Editoria11y for Drupal

Core features

The Drupal module connects the checker library to the editorial backend, and adds many server-side tools for reporting, governance and configuration

Installation and key setup steps

The bundled installer at Drupal.org includes several modules:

• Editoria11y: the core content checker and dashboard.
• Editoria11y CSA: developer tests and dashboard maintenance tools.
• Editoria11y Export: CSV reporting tools.

Install like any other module, and then take these key steps:

1. Check permissions. Trusted authors should have "Mark OK," "Mark as Ignored" and "View the dashboard."
2. Check key pages for repetitive or unhelpful alerts. Either mark them as OK in the tooltip, or adjust the configuration to ignore elements by selector.
3. Look for tips that are hard to see – offscreen, truncated, behind other elements, or on hidden elements. Use the tips in "Fix tip positioning" below to fix.
4. If the site already has content, and you have a CSA subscription, visit the dashboard "recheck" tab, and crawl the site to pre-load the site reports. This is optional, but older pages will not appear in reports until they are crawled or visited by a logged in user.

View a video introduction to the configuration options (v2.4).

Hide unhelpful alerts

Good configurations suppress unhelpful alerts, so content authors can focus on issues they should fix.

While you can turn off tests altogether, it is usually better to hide alerts on specific elements or pages.

During each test run, Editoria11y gathers a single set of elements from the "Check content in these containers" setting, and then filters it several times. This is what a test run looks like:

1. Cancel checking if configuration prevents checking on this page or for this user.
2. Gather elements in specified page regions, e.g.:
   body > *:not('.ed11y-element')
   For Editoria11y CSA users, these are the regions on the Developer tests tab.
3. Drop elements that match ignore selectors, e.g.:
   .widgets, .utility-menu
   For Editoria11y CSA users, these are the selectors on the Developer tests tab.
4. Run tests and sync results to the dashboard.
5. If split configuration is active and the user is a content editor, filter developer results:
   • Drop results from tests set to "Developer only."
   • Drop results on elements from outside specified content regions, e.g.:
     main, footer
   • Drop results on elements that match content ignore selectors.
   Note that there is not a second "gather" phase. The developer page regions must include the content regions.
6. Open the panel and draw alerts if configuration matches an auto-open setting.

Dismiss alerts

Tests can be configured in the library as errors or warnings ("manual checks"). Warnings can be dismissed. There are two types of dismissals available from the footer of each tooltip:

• "Ignore" is stored as a user preference: the alert is now hidden for the current user, but only the current user.
• "Mark OK" hides the alert for all users.

Whether a user is able to dismiss an alert is controlled at the role level in Drupal's user permissions. Most authors should be allowed to dismiss alerts. There is no point in assigning someone a manual check if they cannot mark the item as having been checked.

Ignore elements

These two configuration settings are the most important!

Set the first to include any parts of the page content authors can edit. E.g., if they can edit the main content area, .sidebar and .footer-column-two, set those selectors as your content check area.

Use the second to "knock out" subsections. E.g., if main contains various widgets and embeds that only developers can modify, list those: .widget-1, .social-embed;

If you are using the split configuration, you will see a similar pair of settings on the Developer Tests tab:

The key thing to know about the developer check areas is that they are not independent of the content check areas. In a split configuration, the developer areas are checked, and then those results are filtered to match the content areas. Any areas that are excluded for developers will also be excluded for content editors. Do not exclude editable content areas!

Some tests allow for more precise configuration, to only hide certain alerts on affected elements. Look for them under:

• Content tests: Links to check
• Content tests: Embeds to check
• Content tests: Detecting dynamic and shadow content
• Developer tests: Contrast

Hide for specific pages or users

The easiest way to do this is by passing CSS classes or IDs to these options:

The first will prevent checks from running, and the toolbar will not show.

The second will start the checker minimized, and auto-mark (for the current user) all issues as "Ignored," even if they are errors. This allows the tests to run and update the dashboard without bothering the user.

If you want to use these to control which users see the checker, you may need to adjust your theme to output a class, e.g. .user-247

Manage site-wide results

Fix hidden or offscreen tips

The module provides fields for two of the library's configuration options to change how tips are placed:

Some themes have columns or widgets that hide horizontal or vertical overflow. The library automatically detects when a toggle would fall outside the visible part of the page. Telling the library that certain containers hide overflow means it will also attempt to position tips for elements in those container inside their borders.

Some themes have widgets that toggle the visibility of content, such as accordions, tabs and slideshows. Tips inside these elements will also be hidden. Providing a list of selectors for these widgets means Editoria11y will pause briefly when a user tries to jump to those tips using a next or previous button. Drupal themes and modules can then follow the directions from the library section on dealing with tips on hidden content to reveal the hidden content.

Write your own config

In PHP: the Drupal module provides a hook_editoria11y_alter_config to change the content of drupalSettings.editoria11y in a module or theme. For example:

Modifying drupalSettings only helps if the module JS is already set up to pass that value to the library. To add additional parameters, you need to modify the JS options object directly. The module checks for one global JS variable of editoria11yOptionsOverride. If this is set, it will pass the options object to an editoria11yOptions function you have provided in your module or theme. You can now set any of the library parameters.