theme_item_list

Versions
4.6: theme_item_list($items = array(), $title = NULL)
4.7: theme_item_list($items = array(), $title = NULL, $type = 'ul')
5 – 6: theme_item_list($items = array(), $title = NULL, $type = 'ul', $attributes = NULL)
7: theme_item_list($variables)

Return a themed list of items.

Parameters

$items An array of items to be displayed in the list. If an item is a string, then it is used as is. If an item is an array, then the "data" element of the array is used as the contents of the list item. If an item is an array with a "children" element, those children are displayed in a nested list. All other elements are treated as attributes of the list item element.

$title The title of the list.

$type The type of list to return (e.g. "ul", "ol")

$attributes The attributes applied to the list element.

Return value

A string containing the list output.

▸ 1 function calls theme_item_list()

▾ 1 function calls theme_item_list()

theme_item_list in includes/theme.inc: Return a themed list of items.

Code

includes/theme.inc, line 1461

<?php
function theme_item_list($items = array(), $title = NULL, $type = 'ul', $attributes = NULL) {
  $output = '<div class="item-list">';
  if (isset($title)) {
    $output .= '<h3>'. $title .'</h3>';
  }

  if (!empty($items)) {
    $output .= "<$type". drupal_attributes($attributes) .'>';
    $num_items = count($items);
    foreach ($items as $i => $item) {
      $attributes = array();
      $children = array();
      if (is_array($item)) {
        foreach ($item as $key => $value) {
          if ($key == 'data') {
            $data = $value;
          }
          elseif ($key == 'children') {
            $children = $value;
          }
          else {
            $attributes[$key] = $value;
          }
        }
      }
      else {
        $data = $item;
      }
      if (count($children) > 0) {
        $data .= theme_item_list($children, NULL, $type, $attributes); // Render nested list
      }
      if ($i == 0) {
        $attributes['class'] = empty($attributes['class']) ? 'first' : ($attributes['class'] .' first');
      }
      if ($i == $num_items - 1) {
        $attributes['class'] = empty($attributes['class']) ? 'last' : ($attributes['class'] .' last');
      }
      $output .= '<li'. drupal_attributes($attributes) .'>'. $data ."</li>\n";
    }
    $output .= "</$type>";
  }
  $output .= '</div>';
  return $output;
}
?>

Example

kentr - Wed, 2009-09-09 18:31

Typical usage:

<?php
$title = 'The List Title';
$type = 'ul';
$attributes = array('class' => 'my-list-class');
$items = array(
  /*
   * If an item is a string, then it is used as is.
   */
  'Level 1 Item 1',
  'Level 1 Item 2',
  /*
   * If an item is an array...
   * 
   * If there is no element with a 'data' key, the first element 
   * in the array will be the list item contents.  But for code clarity, 
   * it's better to specify the 'data' element.
   */
  array(
    'data' => 'Level 1 Item 3. This item has a special class and an "id" attribute.',
    'class' => 'level-1-item-class',
    'id' => 'level-1-item-3',
  ),

  /*
   * If an item is an array with a "children" element...
   * 
   * The child lists are rendered with the full theming of single-level
   * item list, but they inherit the $type and $attributes elements
   * from the original function call.
   */
  array(
    'data' => 'Level 1 Item 5. This item has a child.',
    /*
     * The "children" element represents a full list, so it should be
     * an array of items similar to the parent element.
     */
    'children' => array(
        'Level 2 Item 1',
        'Level 2 Item 2',
        /* 
         * Another "array" type item. 
         * 
         * The item has a class attribute.  This also replaces the 
         * $attributes['class'] value used for the nested call
         * to theme_item_list() when rendering the child list.
         */
        array(
          'data' => 'Level 2 Item 3.  This item has a special class and a child.  The child\'s <code>&lt;ul&gt;</code> has inherited the class of this item.',
          'children' => array(
            'Level 3 Item 1',
            'Level 3 Item 3',
          ),
          'class' => 'foo',          
        ),
        /* Back to "string" type items */
        'Level 2 Item 4',
    ),
  ),
);
echo theme_item_list($items, $title, $type, $attributes);
?>

Output:

(assuming theme_item_list() has not been overridden by your theme.)

<div class="item-list">
   <h3>The List Title</h3>
   <ul class="my-list-class">
      <li class="first">Level 1 Item 1</li>
      <li>Level 1 Item 2</li>
      <li class="level-1-item-class" id="level-1-item-3">Level 1 Item 3. This item has a special class and an "id" attribute.</li>
      <li class="last">Level 1 Item 5. This item has a child.
         <div class="item-list">
            <ul>
              <li class="first">Level 2 Item 1</li>
               <li>Level 2 Item 2</li>
               <li class="foo">Level 2 Item 3.  This item has a special class and a child.  The child's <code>&lt;ul&gt;<&#8260;code> has inherited the class of this item.
                  <div class="item-list">
                     <ul class="foo">
                        <li class="first">Level 3 Item 1</li>
                        <li class="last">Level 3 Item 3</li>
                     </ul>
                  </div>
               </li>
               <li class="last">Level 2 Item 4</li>
            </ul>
         </div>
      </li>
   </ul>
</div>