3 * Adds an HTML element and method to trigger audio UAs to read system messages.
5 * Use {@link Drupal.announce} to indicate to screen reader users that an
6 * element on the page has changed state. For instance, if clicking a link
7 * loads 10 more items into a list, one might announce the change like this.
11 * .on('itemInsert', function (event, data) {
12 * // Insert the new items.
13 * $(data.container.el).append(data.items.el);
14 * // Announce the change to the page contents.
15 * Drupal.announce(Drupal.t('@count items added to @container',
16 * {'@count': data.items.length, '@container': data.container.title}
21 (function (Drupal, debounce) {
26 var announcements = [];
29 * Builds a div element with the aria-live attribute and add it to the DOM.
31 * @type {Drupal~behavior}
33 * @prop {Drupal~behaviorAttach} attach
34 * Attaches the behavior for drupalAnnouce.
36 Drupal.behaviors.drupalAnnounce = {
37 attach: function (context) {
38 // Create only one aria-live element.
40 liveElement = document.createElement('div');
41 liveElement.id = 'drupal-live-announce';
42 liveElement.className = 'visually-hidden';
43 liveElement.setAttribute('aria-live', 'polite');
44 liveElement.setAttribute('aria-busy', 'false');
45 document.body.appendChild(liveElement);
51 * Concatenates announcements to a single string; appends to the live region.
55 var priority = 'polite';
58 // Create an array of announcement strings to be joined and appended to the
60 var il = announcements.length;
61 for (var i = 0; i < il; i++) {
62 announcement = announcements.pop();
63 text.unshift(announcement.text);
64 // If any of the announcements has a priority of assertive then the group
65 // of joined announcements will have this priority.
66 if (announcement.priority === 'assertive') {
67 priority = 'assertive';
72 // Clear the liveElement so that repeated strings will be read.
73 liveElement.innerHTML = '';
74 // Set the busy state to true until the node changes are complete.
75 liveElement.setAttribute('aria-busy', 'true');
76 // Set the priority to assertive, or default to polite.
77 liveElement.setAttribute('aria-live', priority);
78 // Print the text to the live region. Text should be run through
79 // Drupal.t() before being passed to Drupal.announce().
80 liveElement.innerHTML = text.join('\n');
81 // The live text area is updated. Allow the AT to announce the text.
82 liveElement.setAttribute('aria-busy', 'false');
87 * Triggers audio UAs to read the supplied text.
89 * The aria-live region will only read the text that currently populates its
90 * text node. Replacing text quickly in rapid calls to announce results in
91 * only the text from the most recent call to {@link Drupal.announce} being
92 * read. By wrapping the call to announce in a debounce function, we allow for
93 * time for multiple calls to {@link Drupal.announce} to queue up their
94 * messages. These messages are then joined and append to the aria-live region
97 * @param {string} text
98 * A string to be read by the UA.
99 * @param {string} [priority='polite']
100 * A string to indicate the priority of the message. Can be either
101 * 'polite' or 'assertive'.
104 * The return of the call to debounce.
106 * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
108 Drupal.announce = function (text, priority) {
109 // Save the text and priority into a closure variable. Multiple simultaneous
110 // announcements will be concatenated and read in sequence.
115 // Immediately invoke the function that debounce returns. 200 ms is right at
116 // the cusp where humans notice a pause, so we will wait
117 // at most this much time before the set of queued announcements is read.
118 return (debounce(announce, 200)());
120 }(Drupal, Drupal.debounce));