function theme_item_list

Returns HTML for a list or nested list of items.

@since 1.21.0: added the "empty" variable. @since 1.27.0: added the "wrapper_attributes" variable.

Parameters

$variables: An associative array containing:

• items: A list of items to render. String values are rendered as is. Each item can also be an associative array containing:
  • data: The string content of the list item.
  • children: A list of nested child items to render that behave identically to 'items', but any non-numeric string keys are treated as HTML attributes for the child list that wraps 'children'.

  Any other key/value pairs are used as HTML attributes for the list item in 'data'.

• 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.
• wrapper_attributes: Any additional attributes that should be applied to the wrapper DIV around the list element (the "item-list" CSS class is added by default).
• empty: A message to display when there are no items. Allowed value is a string or render array.

Related topics

File

core/includes/theme.inc, line 2408

The theme system, which controls the output of Backdrop.

Code

function theme_item_list($variables) {
  $items = $variables['items'];
  $title = $variables['title'];
  $type = $variables['type'];
  $list_attributes = $variables['attributes'];
  $wrapper_attributes = $variables['wrapper_attributes'];

  $output = '';
  if ($items) {
    $output .= '<' . $type . backdrop_attributes($list_attributes) . '>';

    $num_items = count($items);
    $i = 0;
    foreach ($items as $key => $item) {
      $i++;
      $attributes = array();

      if (is_array($item)) {
        $value = '';
        if (isset($item['data'])) {
          $value .= $item['data'];
        }
        $attributes = array_diff_key($item, array('data' => 0, 'children' => 0));

        // Append nested child list, if any.
        if (isset($item['children'])) {
          // HTML attributes for the outer list are defined in the 'attributes'
          // theme variable, but not inherited by children. For nested lists,
          // all non-numeric keys in 'children' are used as list attributes.
          $child_list_attributes = array();
          foreach ($item['children'] as $child_key => $child_item) {
            if (is_string($child_key)) {
              $child_list_attributes[$child_key] = $child_item;
              unset($item['children'][$child_key]);
            }
          }
          $value .= theme('item_list', array(
            'items' => $item['children'],
            'type' => $type,
            'attributes' => $child_list_attributes,
          ));
        }
      }
      else {
        $value = $item;
      }

      $attributes['class'][] = ($i % 2 ? 'odd' : 'even');
      if ($i == 1) {
        $attributes['class'][] = 'first';
      }
      if ($i == $num_items) {
        $attributes['class'][] = 'last';
      }

      $output .= '<li' . backdrop_attributes($attributes) . '>' . $value . '</li>';
    }
    $output .= "</$type>";
  }
  elseif (!empty($variables['empty'])) {
    $output .= render($variables['empty']);
  }

  // Only output the list container and title if there are any list items.
  if ($output !== '') {
    // Check to see whether the list title exists before adding a header. Empty
    // headers are not semantic and present accessibility challenges.
    if (isset($title) && $title !== '') {
      $title = '<h3>' . $title . '</h3>';
    }

    // Add any attributes specified for the wrapper div tag.
    if (!isset($wrapper_attributes['class'])) {
      // Make sure that the 'class' key exists in the array.
      $wrapper_attributes['class'] = array();
    }
    elseif (is_string($wrapper_attributes['class'])) {
      // Do not choke if 'class' was provided as a string which may include
      // commas, spaces, or semicolons. Convert sub-strings into array items.
      $wrapper_class_items = array_map('trim', preg_split("/[;,]/", $wrapper_attributes['class']));
      $wrapper_attributes['class'] = $wrapper_class_items;
    }
    // Finally, include a default CSS class "item-list".
    $wrapper_attributes['class'][] = 'item-list';

    $output = '<div' . backdrop_attributes($wrapper_attributes) . '>' . $title . $output . '</div>';
  }

  return $output;
}