Upgrading to Drupal 7 theme_links

Below is draft information for the Upgrading section of the Drupal Handbook. Please provide any feedback or suggestions in Issue #364219.

API Change

Drupal 7 added a new $heading parameter to the theme_links() function.

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

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

$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) space-separated 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. See http://juicystudio.com/article/screen-readers-display-none.php and http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.

Steps 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.

Visible

Visible headings are appropriate when:

• The heading will provide visual information to sighted users about the links that follow. Remember, you can style the heading with CSS to appear however you want as long as you don't use display:none.
• The heading should be present for everyone including sighted users, screen-reader users, and all assistive technology users.

Invisible

Invisible headings are appropriate when:

• The set of links is apparent visually to sighted users. For example, a Main navigation menu may be visually positioned and styled such that it is clear that it is the site-wide main menu with links that users can click on. However, if this is not apparent visually, the links should have a visible heading.
• The set of links contains a navigation menu or appears consistently on multiple pages. Otherwise, this set of links may not need a heading.

No Heading

Using no heading before the links is appropriate when:

• The set of links is not a menu. However, if it is a menu, it should have a visible or invisible heading.
• The set of links is not consistently used on multiple pages. However, if it is a consistently-used set of links, such as footer links, it should have a visible or invisible heading.
• Users would not want to easily find or skip over this set of links. However, if users would want to find or skip over these links, it should have a visible or invisible heading.

If all three of those are true, upgrade your code to send a NULL $heading value and output no heading.

Example Code

Existing Drupal 5-6 page.tpl.php code


<?php print theme('links', $main_menu, array('id' => 'main-menu', 'class' => 'links')); ?>


Example Drupal 7 page.tpl.php code with an invisible h2 heading


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


Existing Drupal 5-6 template.php or MYTHEME_preprocess_page(&$vars) code:


$vars['primary_nav'] = isset($vars['main_menu']) ? theme('links', $vars['main_menu'], array('class' => 'links main-menu')) : FALSE;


Example Drupal 7 template.php or MYTHEME_preprocess_page(&$vars) code


$vars['primary_nav'] = isset($vars['main_menu']) ? theme('links', $vars['main_menu'], array('text' => t('Main menu'), 'level' => 'h2', class => 'element-invisible'), array('class' => 'links main-menu')) : FALSE;


Use Headings in Order

Headings should be used in order (h1, h2, h3) without skipping a level. The W3C recommends using h2 for navigation menus. The h2 may precede the h1 tag which contains the site title or page title. See http://www.w3.org/TR/WCAG-TECHS/H42.html for more information.

Overriding theme_links with MYTHEME_theme_links

We recommend you handle the $heading parameter similar to the core theme_links() function:

if (!empty($heading['text']) && !empty($heading['level'])) {
  $output .= '<' . $heading['level'] . (!empty($heading['class']) ?
    drupal_attributes(array('class' => $heading['class'])) : '') . '>';
  $output .= check_plain($heading['text']);
  $output .= '';
}

• Do not print out an empty heading.
• Do not print out a heading if there are zero links.
• The heading should immediately precede the ul or similar element that contains the links.

For more information see the Accessibility section of the Drupal Theming Guide.