www.aleph1.co.uk Git - yaffs-website/blob - web/core/misc/announce.js

   1 /**
   2  * @file
   3  * Adds an HTML element and method to trigger audio UAs to read system messages.
   4  *
   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.
   8  *
   9  * @example
  10  * $('#search-list')
  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}
  17  *     ));
  18  *   });
  19  */
  20
  21 (function (Drupal, debounce) {
  22
  23   'use strict';
  24
  25   var liveElement;
  26   var announcements = [];
  27
  28   /**
  29    * Builds a div element with the aria-live attribute and add it to the DOM.
  30    *
  31    * @type {Drupal~behavior}
  32    *
  33    * @prop {Drupal~behaviorAttach} attach
  34    *   Attaches the behavior for drupalAnnouce.
  35    */
  36   Drupal.behaviors.drupalAnnounce = {
  37     attach: function (context) {
  38       // Create only one aria-live element.
  39       if (!liveElement) {
  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);
  46       }
  47     }
  48   };
  49
  50   /**
  51    * Concatenates announcements to a single string; appends to the live region.
  52    */
  53   function announce() {
  54     var text = [];
  55     var priority = 'polite';
  56     var announcement;
  57
  58     // Create an array of announcement strings to be joined and appended to the
  59     // aria live region.
  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';
  68       }
  69     }
  70
  71     if (text.length) {
  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');
  83     }
  84   }
  85
  86   /**
  87    * Triggers audio UAs to read the supplied text.
  88    *
  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
  95    * as one text node.
  96    *
  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'.
 102    *
 103    * @return {function}
 104    *   The return of the call to debounce.
 105    *
 106    * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
 107    */
 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.
 111     announcements.push({
 112       text: text,
 113       priority: priority
 114     });
 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)());
 119   };
 120 }(Drupal, Drupal.debounce));