Documentation for Converting 6.x modules to 7.x theme_links()

Here is the proposed documentation:

theme_links() has a $heading parameter for accessibility

(issue) theme_links() has a new $heading parameter so that consistent sets of links such as navigation menus will be preceded by a heading, whether visible or invisible.

Drupal 5-6: theme_links($links, $attributes = array('class' => 'links'))

Drupal 7: theme_links($links, $attributes = array('class' => array('links')), $heading = array())

$heading is an optional keyed array for a heading to precede the links:

- text: the heading text

- level: the heading level (e.g. 'h2', 'h3')

- class: (optional) an array of the CSS classes for the heading

Headings should be used on navigation menus and any list of links that consistently appears on multiple pages. To make the heading invisible use class => 'element-invisible'. Do not use 'display:none', which removes it from screen-readers and assistive technology. Headings allow screen-reader and keyboard only users to navigate to or skip the links.

For more info see the Headings page of the Theme Guide at http://drupal.org/node/561750. For more about invisible content, see http://drupal.org/node/472572.

To Upgrade: Search your theme or module for theme('links' or theme_links(. For each occurrence, choose whether the set of links should have a visible or invisible heading or none at all (see Theme Guide links above for guidance). If none, there is no code change needed to upgrade. Otherwise add the $heading param.

Example template.php or MYTHEME_preprocess_page(&$vars)

$vars['primary_nav'] = theme('links', $vars['main_menu'], array('class' => array('links', 'main-menu')), <strong>array('text' => t('Main menu'), 'level' => 'h2', 'class' => array('element-invisible'))</strong>);

Example page.tpl.php

<?php print theme('links', $main_menu, array('id' => 'main-menu', 'class' => array('links')), <strong>array('text' => t('Main menu'), 'level' => 'h2', 'class' => array('element-invisible')),</strong>); ?>

Example overriding theme_links() with MYTHEME_theme_links(), where we recommend you handle the $heading parameter similar to the core theme_links() function:

    if (!empty($heading)) {
      if (is_string($heading)) {
        // Prepare the array that will be used when the passed heading is a string.
        $heading = array(
          'text' => $heading,
          // Set the default level of the heading.
          'level' => 'h2',
        );
      }
      $output .= '<' . $heading['level'];
      if (!empty($heading['class'])) {
        $output .= drupal_attributes(array('class' => $heading['class']));
      }
      $output .= '>' . check_plain($heading['text']) . '</' . $heading['level'] . '>';
    }