Add Navigation Landmarks to Book Navigation [#2864895]

Problem/Motivation

Implementing ARIA landmarks helps screen reader users more easily navigate a page (see ARIA11: Using ARIA landmarks to identify regions of a page). Book Navigation (book-navigation.tpl.php) should functions as a navigation landmark (see WAI-ARIA Authoring Practices 1.1). Doing this will help make core more compliant with WCAG 2.4.1: Bypass Blocks (Level A)

Proposed resolution

Add landmarks to the Book Navigation.

As I see it, there are three issues here:

Whether to create separate navigation landmarks for the $tree and $has_links parts of the navigation or whether to simply wrap both in the same navigation landmark;
How to label the landmark(s);
How to implement the landmarks, either from changing the book-navigation.tpl.php, changing any theme or preprocess functions, and whether to use an nav element, a role attribute, or both. (It seems to me we would want to attach the label by using an aria-label attribute, but I could be wrong about that.)

This doesn't seem to me to be a ton of work, but I'm not completely familiar with the Book module, so I'm not sure what the pros / cons wold be of the above points.

User interface changes

Assistive technologies would announce landmarks to users and allow for navigation. Users who do not use assistive tech would not perceive a difference.

API changes

In book-navigation.tpl.php, adds the new variables $tree_attributes and $page_links_attributes.
In book-navigation.tpl.php, adds a wrapping div around the $tree variable. The $tree_attributes variable is printed out within this div.
In book-navigation.tpl.php, the $page_links_attributes variable is printed out within the class="page-links" div.
In book.module's template_preprocess_book_navigation, adds code for ARIA landmarks and labels to $variables['page_links_attribues_array'] and $variables['tree_attributes_array'].
In book.module, adds template_process_book_navigation in order to flatten the arrays added in template_preprocess_book_navigation.
Updates comments as appropriate.

Comment	File	Size	Author
#6	book-navigation-landmarks-2864895-6.patch	3.08 KB	miwayha
#6	7.x: PHP 5.3 & MySQL 5.5 2,034 pass
#4	book-navigation-landmarks-2864895-4.patch	1.78 KB	miwayha
#4

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

29 March 2017 at 01:58

miwayha created an issue. See original summary.

Comment #2

miwayha CreditAttribution: miwayha as a volunteer commented 29 March 2017 at 18:34

I've done a little digging here...

The $tree variable relies on theme_menu_tree, which doesn't allow for adding attributes. That is, it's hard to target that particular ul to add role="navigation". Assuming we want two separate navigations, one solution is either to create a new theme function (call it, say theme_book_tree or to chance theme_menu_tree directly.

The other option would be to change the book-navigation.tpl.php from

<?php if ($tree || $has_links): ?>
  <div id="book-navigation-<?php print $book_id; ?>" class="book-navigation">
    <?php print $tree; ?>
    ...

to something like

<?php if ($tree || $has_links): ?>
  <div id="book-navigation-<?php print $book_id; ?>" class="book-navigation">
    <div role="navigation" aria-label="Table of Contents">
      <?php print $tree; ?>
    </div>

<?php if ($tree || $has_links): ?>
  <div id="book-navigation-<?php print $book_id; ?>" class="book-navigation">
    <div <?php print $tree_attributes; ?>>
      <?php print $tree; ?>
    </div>

When considering the advantages of these approaches, I'm trying to think both about how much it will disrupt current sites and about how easy it will be to remove the accessibility landmark once it's been implemented.

Changing the tpl to add new elements necessarily changes users' markup, and could consequently break their styles. Adding elements and hard coding accessibility functions makes them brittle to tpl.php overrides that simply don't include them. Adding elements and printing an attributes variable feels a little more robust to me, but still poses the danger of breaking styles.

Changing the theme or adding a new theme, in contrast, feels like a stickier change, but might cause some more disruption with theme overrides people have already built. theme_menu_tree doesn't feel like the kind of theme function we should mess with lightly.

I'm inclined to go with changing the tpl.php file and the preprocess function, but I'm open to others.

Comment #3

mgifford

he/him

English

CreditAttribution: mgifford at OpenConcept Consulting Inc. commented 29 March 2017 at 20:22

Issue tags:

+aria

Comment #4

miwayha CreditAttribution: miwayha as a volunteer commented 31 March 2017 at 15:30

File	Size
book-navigation-landmarks-2864895-4.patch	1.78 KB

Beginnings of a patch based on adding attributes to book-navigation.tpl.php via a preprocess function and a process function. Still needs documentation.