Improve entity pager accessibility for screen readers

Created on 31 January 2023, almost 2 years ago
Updated 22 February 2023, over 1 year ago

Problem/Motivation

The University of Minnesota has conducted an accessibility review on the Entity Pager module.

Below are the findings:

The keyboard and visual accessibility of the component are good. There are some screen reader access issues though:

  1. The component is operable with a screen reader, but the text and links are just read as separate elements - there is no landmark, label, or container that ties them together and communicates to a screen reader user that this is part of a navigation pager.

  2. It is also not clear to a screen reader user what part of the page the pager controls - prev/next links could be opening a new page or moving through an embedded image or article carousel.

Overall, screen reader users could probably figure out how the pager works but it would introduce some degree of confusion, especially on a page with complex structure or a lot of links.

This issue has been classified as a bug, instead of a feature request per Drupal's Accessibility statement page :

The Drupal community tries to fix accessibility issues in the development process. Everything is documented in the issue queue, and tagged for accessibility. Our community has decided that accessibility is essential. In Drupal 7, the community decided to see accessibility barriers as bugs, rather than feature requests. This resulted in us raising awareness and changing the culture of the community.

Proposed resolution

  1. Wrap the Twig output in a <nav> element to indicate the proper navigation landmark. Note that, unlike Drupal Core, we're excluding the role="navigation attribute from the <nav>, which is no longer considered to be a best practice as it is redundant.

  2. Provide a label for the navigation, by referencing a heading 4 element via aria-labelledby attribute on the nav element. The heading will be hidden from screen using the .visually-hidden class provided by Drupal core. The aria-labelledby attribute requires a unique {{ header_id }} value, which introduces some minor complexity, but we can mimic Drupal Core's pager.html.twig and template_preprocess_pager for the implementation approach.

  3. Document ways that pages with more complex structure or lots of links can and should reduce confusion by override the Twig template in your theme layer and/or overriding the views token output in order to provide additional context on what the pager's purpose is, and/or how links inside the pagination work, eg with extra explanations wrapped in sr-only or visually-hidden classes.

Note: the approach here will not take the extra steps of adding rel="previous" and rel="next" attributes to the links because there is no evidence that these relationship attributes are used by screen readers. This is therefore out-of-scope.

Remaining tasks

Write patch.
Seek feedback from accessibility team.

User interface changes

The wrapper "<div>" will change to a "<nav>" element. This may affect custom front-end themes that target that div via CSS.

API changes

None.

Data model changes

Not applicable.

🐛 Bug report
Status

Needs review

Version

2.0

Component

Code

Created by

🇪🇨Ecuador jwilson3

Live updates comments and jobs are added and updated live.
  • Accessibility

    It affects the ability of people with disabilities or special needs (such as blindness or color-blindness) to use Drupal.

  • Needs accessibility review

    Used to alert the accessibility topic maintainer(s) that an issue significantly affects (or has the potential to affect) the accessibility of Drupal, and their signoff is needed (see the governance policy draft for more information). Useful links: Drupal's accessibility standards, the Drupal Core accessibility gate.

Sign in to follow issues

Comments & Activities

Production build 0.71.5 2024