theme_item_list

5 theme.inc	`theme_item_list($items = array(), $title = NULL, $type = 'ul', $attributes = NULL)`
6 theme.inc	`theme_item_list($items = array(), $title = NULL, $type = 'ul', $attributes = NULL)`
7 theme.inc	`theme_item_list($variables)`
8 theme.inc	`theme_item_list($variables)`

Returns HTML for a list or nested list of items.

Parameters

$variables: An associative array containing:

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.

▸ 1 function calls theme_item_list()

▾ 1 function calls theme_item_list()

theme_item_list in includes/theme.inc: Returns HTML for a list or nested list of items.

File

includes/theme.inc, line 1957: The theme system, which controls the output of Drupal.

Code

<?php
function theme_item_list($variables) {
  $items = $variables['items'];
  $title = $variables['title'];
  $type = $variables['type'];
  $attributes = $variables['attributes'];

  $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();
      $data = '';
      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) {
        // Render nested list.
        $data .= theme_item_list(array('items' => $children, 'title' => NULL, 'type' => $type, 'attributes' => $attributes));
      }
      if ($i == 0) {
        $attributes['class'][] = 'first';
      }
      if ($i == $num_items - 1) {
        $attributes['class'][] = 'last';
      }
      $output .= '<li' . drupal_attributes($attributes) . '>' . $data . "</li>\n";
    }
    $output .= "</$type>";
  }
  $output .= '</div>';
  return $output;
}
?>

Comments

Hard-coding..?

Posted by roper. on January 25, 2011 at 9:59pm

Why are child lists rendered through the hard-coded theme_item_list() instead of theme('item_list', ...)? Same is true of D6.

Please file a bug report

Posted by moshe weitzman on February 4, 2011 at 5:34pm

thanks.

Cause it is derived to this

Posted by lemark on November 17, 2011 at 8:35pm

Cause it is derived to this particular default item_list implementation. So all is OK.

From this, i found how to add

Posted by WilliamB on April 1, 2011 at 11:58am

From this, i found how to add attributes to the UL tag, but it's not clear to me how i can add attributes to the LI tags?

Can someone helps?

Use an associative array for the items element

Posted by dinarcon on April 12, 2011 at 11:12pm

Hi WilliamB,

In order to add attributes to the li tags, each element in the items array ($variables['items']) must be another (associative) array. For the later, the value of the data key will be treated as the content of the li tag, while any other key (expect for children) will be treated as an attribute to be added (using the key's value as the value for the attribute). Since this might sound confusing, I wrote a simple example...

Let's say you want to print a list of authenticated users. For each of them, you want to print his or her username and add an id attribute with the user's id (uid) to the list item, as well as a class attribute with the roles the user has. Then you would have to do following:

<?php
$title = t('My custom listing');
$type = 'ul';
// The following attributes apply to the list tag (e.g., <ol> or <ul>)
$attributes = array(
  'id' => 'my-custom-listing',
  'class' => 'custom-class another-custom-class', // a string or indexed (string) array with the classes for the list tag
);

$uids = retrieve_uids(); // Replace with your own function

$accounts = array();
foreach ($uids as $uid) {
  $accounts[] = user_load($uid);
}

$items = array();
foreach ($accounts as $account) {
  $items[] = array(
    'data' => $account->name,
    'id' => $account->uid, // be careful not to add another id attribute on the page that might be the same as one of the uids or your page will not validate
    'class' => array_keys($account->roles), // value for 'class' key MUST be an (indexed) array. Using a string value like '2 3 4' produces an error
  );
}

theme_item_list(array('items' => $items, 'title' => $title, 'type' => $type, 'attributes' => $attributes));
?>

The preceding code should produce an output similar to:

<div class="item-list">
  <h3>My custom listing</h3>
  <ul id="my-custom-listing" class="custom-class another-custom-class">
    <li id="1" class="2 3 4 first">admin</li>
    <li id="2" class="2 4">john</li>
    <li id="3" class="2 last">doe</li>
  </ul>
</div>

Note that if the function that retrieves the uids returns an empty array, the the resulting html will not have any li element. An if (!empty($uids)) could be used, but that was skipped to keep the example simple. Also, using the array key from $account->roles as classes might not be intuitive (or useful!). The array value might be more useful, but because role names might contain whitespaces, it would require additional processing if you wanted to use them as classes. At least you should replace the whitespaces with dashes.

Hopefully the example clears your doubt. Of course, you can also read the function's implementation to see how it works.

A simpler version

Posted by Siripong on December 14, 2011 at 5:03am

Try this if you don't want to implement retrieve_uids();

<?php
  $items[] = array(
    'data' => '1',
    'class' => array('dummy'=>'category'),
    'children' => array('1.1','1.2',array('data'=>'1.3','class' => array('dummy'=>'category'),'children'=>array('1.3.1','1.3.2')))
  );
?>

This can hang you up at times

Posted by sirkitree on October 2, 2011 at 8:47pm

This can hang you up at times because you need to realize that you need a key called 'items'.

Succinct example:

<?php
  $items['items'] = array(
    l('Configure', 'admin/config'),
    l('Structure', 'admin/structure'),
  );
  return theme('item_list', $items);
?>

D7 always uses $variables as second parameter for theme function

Posted by EvanDonovan on October 26, 2011 at 3:46am

This is because D7 always uses $variables for second parameter of a theme function, where $variables is an array keyed by the names of the variables. This is so they can be overridden in a preprocess function.

Perhaps this makes more sense in the code if you name like so:

<?php
  $items = array(
    l('Batch history', 'admin/reports/salesforce/batch'),
    l('Currently queued items', 'admin/reports/salesforce/current'),
    l('Retry queue', 'admin/reports/salesforce/retries'),
    l('Permanent failures', 'admin/reports/salesforce/permanent-failures'),
  );
  $output .= theme('item_list', array('items' => $items));
?>

How can I implement the multi-level list?

Posted by ninu_ann on January 6, 2012 at 8:58pm

Hi,
Im using drupal 7, I would like to know whether i can use the same function to implement multi-level list items. As below:

If possible can anybody help me with an example?