Problem/Motivation

Core has several instances of aria-live for announcing UI changes aurally.

  • ckeditor
  • edit
  • file
  • toolbar
  • user

We plan to add more instances of aria-live elements to further exposes state changes to users who interact with Drupal through audio.

Just like string translation, we don't want each individual module developing a scheme to handle audio announcements. This type of functionality should be provided as a utility through Drupal because it is a common method of building aural UIs.

Proposed resolution

We should consolidate the existing aria-live implementations into a Drupal library and provide an API.

Remaining tasks

Review the proposed patch.

User interface changes

No UI changes.

API changes

We will introduce a new API for improving accessibility of page state changes.

CommentFileSizeAuthor
#23 drupal-announce-1915302-23.patch3.86 KBeffulgentsia
#23 interdiff.txt1.07 KBeffulgentsia
#21 drupal-announce-1915302-19.patch3.24 KBeffulgentsia
#19 drupal-announce-1915302-19.patch3.24 KBjessebeach
#19 interdiff_14-to-19.patch2.9 KBjessebeach
#18 drupal-announce-1915302-18.patch3.18 KBjessebeach
#14 drupal-announce-1915302-14.patch3.74 KBjessebeach
#12 drupal-announce-1915302-12.patch3.13 KBjessebeach
#1 drupal-announce-1915302-1.patch3.13 KBjessebeach
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Status: Active » Needs review
FileSize
drupal-announce-1915302-1.patch3.13 KB

Alright! Let's get a patch going!

This patch introduces Drupal.announce. It very simply accepts a string to be read by an audio UA. You can also set a second priority parameter. Here are a couple examples:

Drupal.announce('Entering edit mode');
Drupal.announce('Please fill in your user name', 'assertive');
Drupal.announce('You look beautiful today.');

It's that easy! You can even test it out in the Developer console. It's right there to use once you apply this patch.

There is no dependency on jQuery for this patch. I put the method on the Drupal object in drupal.js and we don't assume jQuery is available in this file.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Issue tags: +Needs JavaScript review
jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Status: Needs review » Needs work

Hmm, the Drupal object isn't available by default to anonymous users. Gonna have to rethink where this code lives and how it gets to the page.

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford commented

Patch applies nicely locally.

I didn't have enough experience getting to the console easily, but with Jesse's help I was able to verify that it worked in Safari with VoiceOver & Chrome with http://www.chromevox.com

With Safari, it's not as obvious where the console is, it's now:
"the speech bubble tab at the top of the sidebar on the left side of the screen and then click on the Current Log entry in the sidebar."

This is definitely something that needs to be available for everyone, but I quite like the centralization of this function.

I like the parameter priority too:

   * @param {String} priority
   *   - A string to indicate the priority of the message. Can be either
   *   'polite' or 'assertive'. Polite is the default.
   * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops

Sometimes ARIA docs are horrible to read, but that looks like a reasonably clear one. Nice choice.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Status: Needs work » Needs review

Regarding #3, the Drupal object not loading on the default front page for an anonymous user is expected. I was being derpy at that moment. If a module needs Drupal.announce, it will declare the drupal library as a dependency. At the moment, there's no need for this library on the front page for an anonymous user, so it isn't loaded.

There's nothing to change here. I'm setting this to needs review to get some eyes on it.

Ideally we'd get this simple API in and then start converting modules that need it during code freeze.

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford commented

Sounds great! This is a very useful step ahead. Centralizing this functionality makes it so much easier for people to implement to ensure that rich internet applications are accessibile.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Title: Consolidate the various uses of the aria-live region into an API that modules developers can leverage » Provide an API for aria-live region update announcements that modules developers can leverage

changing the title a smidge.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Title: Provide an API for aria-live region update announcements that modules developers can leverage » Provide an API for aria-live region update announcements that module developers may leverage

so derpy today :/ Too excited about the possibilities.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Issue tags: +Needs tests
jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Issue tags: +Needs documentation
seutje’s picture

seutje CreditAttribution: seutje commented 
+++ b/core/misc/drupal.jsundefined
@@ -259,6 +259,76 @@ Drupal.t = function (str, args, options) {
+      liveElement.id = "drupal-live-announce";

Any particular reason this is the only line with double quotes?

+++ b/core/misc/drupal.jsundefined
@@ -259,6 +259,76 @@ Drupal.t = function (str, args, options) {
+      liveElement.classList.add('element-invisible');

Does this depend on #1754166: Add classList polyfill for IE?

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
FileSize
drupal-announce-1915302-12.patch3.13 KB

seutje, for this patch, I can just as easily use className instead of classList. I'm not doing anything but assigning a class to an element that was just created.

I fixed the double-quote issue you mentioned and the classList issue.

Is anything blocked on #1754166: Add classList polyfill for IE? I can give it a review if so.

seutje’s picture

seutje CreditAttribution: seutje commented

I don't have any more concerns with it, but it is still marked "Needs Documentation" and "Needs tests".

regarding #1754166: Add classList polyfill for IE, the way #1252178: Add Modernizr to core went in, it's not blocked anymore, but would need to depend on Modernizr and carry its own feature-test, I guess

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Issue tags: -Needs tests, -Needs documentation, -Needs JavaScript review
FileSize
drupal-announce-1915302-14.patch3.74 KB

I added this method to the JavaScript testing plan tracker - http://drupal.org/node/1777342

I've updated the comments to indicate how this function could be used with a simple example.

Removing the tags.

The iron is hot. Let's strike!

dcmouyard’s picture

dcmouyard CreditAttribution: dcmouyard commented
Status: Needs review » Reviewed & tested by the community

The patch in #14 looks good. As long as the tests pass, this is RTBC.

Great work Jesse and seutje!

nod_’s picture

nod_
Primary language French
Location Lille
CreditAttribution: nod_ commented

just want to know why we're not using setAttribute before this gets committed.

Status: Reviewed & tested by the community » Needs work

The last submitted patch, drupal-announce-1915302-14.patch, failed testing.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Status: Needs work » Needs review
FileSize
drupal-announce-1915302-18.patch3.18 KB

I chatted with nod_ and his suggestion to use setAttribute cut the code in half.

I tested back to IE7. All works well.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
FileSize
interdiff_14-to-19.patch2.9 KB
drupal-announce-1915302-19.patch3.24 KB

Small correction to two comments.

Interdiff from #14 to #19 provided.

Status: Needs review » Needs work

The last submitted patch, interdiff_14-to-19.patch, failed testing.

effulgentsia’s picture

effulgentsia CreditAttribution: effulgentsia commented
Status: Needs work » Needs review
FileSize
drupal-announce-1915302-19.patch3.24 KB

Re-uploading #19 so that the interdiff isn't the last bot-tested patch on this issue. Also, seems odd for a JS only patch to cause Simpletest failures, so let's see if bot comes back happier this time.

Status: Needs review » Needs work

The last submitted patch, drupal-announce-1915302-19.patch, failed testing.

effulgentsia’s picture

effulgentsia CreditAttribution: effulgentsia commented
Status: Needs work » Needs review
FileSize
interdiff.txt1.07 KB
drupal-announce-1915302-23.patch3.86 KB

Oh, right, locale scans js files for translatable strings, and this issue adds another one, so the test's use of a magic number broke. This makes that test more robust to such incidental changes.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented

I had a feeling it was the '@count' in the comment. Nice catch!

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented
Status: Needs review » Reviewed & tested by the community

The test fail is fixed. I put in nod_'s recommendation to use setAttribute instead of setAttributeNode. All blockers have been addressed. I'm putting this back to RTBC.

nod_’s picture

nod_
Primary language French
Location Lille
CreditAttribution: nod_ commented

+1 rtbc

Dries’s picture

Dries CreditAttribution: Dries commented
Status: Reviewed & tested by the community » Fixed

Committed to 8.x. Thanks!

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford commented

This is really great! So happy that @Jesse was inspired to do this. Makes so much sense, but I hadn't heard anyone even discuss this before a week ago when this issue got going.

jessebeach’s picture

jessebeach CreditAttribution: jessebeach commented

@mgifford, we talked about it in Toronto. I just finally had time to get around to it! My arc of my todo list is long, but it bends towards getting things done.

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford commented

That's great. Thanks for coming to the sprint and following it up!

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford commented

Hopefully we'll see this implemented here:
#1855036: ARIA and accessibility improvements in entity (content) translation settings page
#1272990: Make tabledrag warning message show when row weights are enabled, and add WAI-ARIA live region

Where else would this be useful?

Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers commented
Status: Closed (fixed) » Active
Issue tags: +Needs change record, +sprint, +Spark

A change record for this should be created; this is a new API that Drupal developers should be aware of!

Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers commented
Title: Provide an API for aria-live region update announcements that module developers may leverage » [Change notice] Provide an API for aria-live region update announcements that module developers may leverage
Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers commented
Status: Active » Closed (fixed)
Issue tags: -Needs change record, -sprint

Change notice created: https://drupal.org/node/2014521.

Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers commented

Change notice created: https://drupal.org/node/2014521.

Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers commented
Title: [Change notice] Provide an API for aria-live region update announcements that module developers may leverage » Provide an API for aria-live region update announcements that module developers may leverage
Wim Leers’s picture

Wim Leers
Location Ghent 🇧🇪🇪🇺
CreditAttribution: Wim Leers commented
Issue summary: View changes

Updated issue summary.

BarisW’s picture

BarisW CreditAttribution: BarisW at LimoenGroen for Gemeente Venlo commented
Issue summary: View changes

Just wondering, could this be backported to D7? Doesn't seem very complex.

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford at OpenConcept Consulting Inc. commented
Version: 8.0.x-dev » 7.x-dev
Status: Closed (fixed) » Needs work
Issue tags: +Needs backport to D7
mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford at OpenConcept Consulting Inc. commented

We can try. We've got a few years of D7 left, so it could be good!

mgifford’s picture

mgifford
he/him
Primary language English
CreditAttribution: mgifford at OpenConcept Consulting Inc. commented
Issue tags: +aria, +aria-live

Adding tags.

andrewmacpherson’s picture

andrewmacpherson CreditAttribution: andrewmacpherson as a volunteer commented
Issue tags: +Drupal.announce

  • Dries committed 4ebb5fd on 8.3.x 
    Issue #1915302 by jessebeach, effulgentsia: Provide an API for aria-live...

  • Dries committed 4ebb5fd on 8.3.x 
    Issue #1915302 by jessebeach, effulgentsia: Provide an API for aria-live...

  • Dries committed 4ebb5fd on 8.4.x 
    Issue #1915302 by jessebeach, effulgentsia: Provide an API for aria-live...

  • Dries committed 4ebb5fd on 8.4.x 
    Issue #1915302 by jessebeach, effulgentsia: Provide an API for aria-live...
klonos’s picture

klonos
he/him
Primary language English
Location 90% Melbourne, Australia - 10% Larissa, Greece
CreditAttribution: klonos at Backdrop CMS commented
Issue tags: -JavaScript +JavaScript

This is what we ended up using in Backdrop: https://patch-diff.githubusercontent.com/raw/backdrop/backdrop/pull/3557...

I hope it helps with the D7 backport. Thanks for everyone that has worked on this issue ❤️