Accessibility tools for JavaScript in Drupal 8
This documentation needs work. See "Help improve this page" in the sidebar.
These tools are under active development in Drupal 8. This documentation page may be out of date
Announce page updates aurally
Many page updates are expressed visually through color changes and animations. In order to make page updates apparent in a non-visual way, Drupal provides the Drupal.announce
JavaScript method. This method creates an aria-live
element on the page. Text appended to this node is read by a screen-reading user agent.
Drupal.announce
accepts a string to be read by an audio UA. You can also set a second parameter: the priority. Here are a couple examples:
Drupal.announce('Entering edit mode');
Drupal.announce(
Drupal.t('You look beautiful today.')
);
Drupal.announce(
Drupal.t('Please fill in your user name'),
'assertive'
);
Use of Drupal.t()
is recommended to ensure announcements are translatable.
The two accepted priority values are polite
and assertive
. polite
is the default.
Assertive statements will interrupt any current speech. Polite statements will not interrupt the user agent. There is a chance they will not be read at all if many things on the page change at once. The announce feature will itself concatenate several calls and read several strings at once to ensure that multiple simultaneous updates are expressed to the end user.
Constrain tabbing
For some interactions, you may want to guide a non-visual user to the most important elements on the page. For example, the Contextual module constrains tabbing to the contextual links when the global edit mode is enabled.
These modules achieve this constrained tabbing with the Drupal.tabbingManager
JavaScript feature. To constrain tabbing on the page, invoke the tabbing manager feature like this.
var tabbingContext = Drupal.tabbingManager.constrain($('.contextual-toolbar-tab, .contextual'));
A set of elements is passed to the constrain
method. Pressing the tabbing key will now only move between the tab-able elements in this set of elements.
To remove the tabbing constraint, the release
method must be called on the tabbing context object.
tabbingContext.release();
The Overlay module uses two functions to initiate a tabbing constraint and release the constraint:
/**
* Makes elements outside the overlay unreachable via the tab key.
*/
Drupal.overlay.constrainTabbing = function ($tabbables) {
// If a tabset is already active, return without creating a new one.
if (this.tabset && !this.tabset.isReleased()) {
return;
}
// Leave links inside the overlay and toolbars alone.
this.tabset = Drupal.tabbingManager.constrain($tabbables);
var self = this;
$(document).on('drupalOverlayClose.tabbing', function () {
self.tabset.release();
$(document).off('drupalOverlayClose.tabbing');
});
};
/**
*
*/
Drupal.overlay.releaseTabbing = function () {
if (this.tabset) {
this.tabset.release();
delete this.tabset;
}
};
Only one tabbing constraint may be active at a time. If a tabbing constraint is active and another is invoked, the previously active tabbing constraint will be disabled and the new one applied. You need only worry about the tabbing constraint that your module controls.
If another module overrides your tabbing constraint and then releases this constraint, then your module's tabbing constraint will be reapplied. In this case, if your module releases its tabbing constraint while its tabbing constraint is disabled (meaning another module has an active tabbing constraint), then it will not be reapplied, as you would expect.
Devel accessibility
The Devel accessibility (devel_a11y
) module was created to aid with implementing, understanding and testing the above accessibility functionality.
It provides browser console logging of announcements and visualization of tabbing constraints.
For example, this is how it helps with visualizing tabbing constraints:
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion