From 312e04a7700ad2574caf410a980f81c5d1fddb79 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?"J.=20Rene=CC=81e=20Beach"?= <splendidnoise@gmail.com>
Date: Fri, 15 Feb 2013 15:40:35 -0500
Subject: [PATCH] Issue #1915302 by jessebeach: Consolidate the various uses
 of the aria-live region into an API that module developers
 can leverage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: J. Renée Beach <splendidnoise@gmail.com>
---
 core/misc/drupal.js |   62 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)

diff --git a/core/misc/drupal.js b/core/misc/drupal.js
index 627e264..c500766 100644
--- a/core/misc/drupal.js
+++ b/core/misc/drupal.js
@@ -259,6 +259,68 @@ Drupal.t = function (str, args, options) {
 };
 
 /**
+ * Adds an HTML element and method to trigger audio UAs to read system messages.
+ */
+(function (document, Drupal) {
+
+  var liveElement;
+
+  /**
+   * Builds a div element with the aria-live attribute.
+   */
+  Drupal.behaviors.drupalAnnounce = {
+    attach: function (settings, context) {
+      liveElement = document.createElement('div');
+      liveElement.id = 'drupal-live-announce';
+      liveElement.className = 'element-invisible';
+      liveElement.setAttribute('aria-live', 'polite');
+      liveElement.setAttribute('aria-busy', 'false');
+      document.body.appendChild(liveElement);
+    }
+  };
+
+  /**
+   * Triggers audio UAs to read the supplied text.
+   *
+   * @param {String} text
+   *   - A string to be read by the UA.
+   *
+   * @param {String} priority
+   *   - A string to indicate the priority of the message. Can be either
+   *   'polite' or 'assertive'. Polite is the default.
+   *
+   * Use Drupal.announce to indicate to screen reader users that an element on
+   * the page has changed state. For instance, if clicking a link loads 10 more
+   * items into a list, one might announce the change like this.
+   * $('#search-list')
+   *   .on('itemInsert', function (event, data) {
+   *     // Insert the new items.
+   *     $(data.container.el).append(data.items.el);
+   *     // Announce the change to the page contents.
+   *     Drupal.announce(Drupal.t('@count items added to @container',
+   *       {'@count': data.items.length, '@container': data.container.title};
+   *     ));
+   *   });
+   *
+   * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
+   */
+  Drupal.announce = function (text, priority) {
+    if (typeof text === 'string') {
+      // Clear the liveElement so that repeated strings will be read.
+      liveElement.innerHTML = '';
+      // Set the busy state to true until the node changes are complete.
+      liveElement.setAttribute('aria-busy', 'true');
+      // Set the priority to assertive.
+      liveElement.setAttribute('aria-live', (priority === 'assertive') ? 'assertive' : 'polite');
+      // Print the text to the live region.
+      liveElement.innerHTML = Drupal.checkPlain(text);
+      // The live text area is updated. Allow the AT to announce the text.
+      liveElement.setAttribute('aria-busy', 'false');
+    }
+  };
+}(document, Drupal));
+
+/**
  * Returns the URL to a Drupal page.
  */
 Drupal.url = function (path) {
-- 
1.7.10.4