Get new jQuery plugins just once a week

×

jquery-live-regions

January 1, 2015

jQuery plugin for managing WAI-ARIA Live Regions

jquery-live-regions is a jQuery plugin for managing WAI-ARIA Live Regions.

Created by Karl Groves

Download

jquery-live-regions

ARIA

jQuery Live Regions

This is a simple, easy to use plugin for managing live regions on a page, including adding new content or swapping content in the live region.

Getting Started

Download the production version or the development version.

Install via bower:

bower install jquery-live-regions --save

Creating live region

Primary Use Case

Live Regions allows the user of assistive technologies to be notified of content changes that may occur automatically and may not be explicitly triggered by the user. The content change may exist separate to what object has focus, and so Live Regions facilitate these notifications. Possible examples include:

There are many types of changes that occur in the typical web-based applications and essentially any content that changes dynamically is a candidate for a live region.

Secondary Use Case

Some changes to content on a page should trigger notifications to the user of assistive technologies, but don't. This pluging can be used as a "notifier" of sorts, to add these relevant notifications.

Super simple method

$('#foo').liveRegion();

The above method creates a live region with default values. Modifications to the content within the live region will be announced by assistive technology.

Give it a label

$('#foo').liveRegion({label: 'News Ticker'});

This will create a live region with an aria-label of "New Ticker"

Use it as a notifier

Consider the following use case where a user searches for clothing products. When the user refines their search options, such as size and color, the results list is dynamically updated client-side (or via AJAX).

// Set up the "notifier" as a container for notices
var notifier = $('#notifier');
notifier.liveRegion({
  label: 'Search Status',
  role: 'region', 
  live: 'assertive'
});

Now, the user triggers the search and results are refined

notifier.liveRegion({
  replace: 'true',
  text: 'Search results updated: ' + num + ' results. Size: ' + sSize + ', Color: ' +sColor;
});

The above example shows the live region indicating to the user that search results were updated and lists out the search criteria.

Full list of available properties

Note: You are not required to provide any of these values. They will be set to sensible defaults if they aren't supplied.

Sample use with all available properties:

$('#foo').liveRegion({
    label: 'Chat Log',
    role: 'log',
    atomic: 'false',
    live: 'polite',
    relevant: 'additions text',
    busy: 'false',
    className: 'tblLiveCaption'
    replace: true,
    text: 'User List, assorted by last name descending'
});

Overriding Values

There may be times when you want to override one or more of the existing values. For instance, in the case where you're waiting for new content to arrive from Ajax:

// the default set up
$('#foo').liveRegion({
    label: 'Chat Log',
    role: 'log',
    atomic: 'false',
    live: 'polite',
    relevant: 'additions text',
    busy: 'false'
});

// when waiting for the new content
if(we-are-waiting-for-the-new-content){
    $('#foo').liveRegion({ 
      busy: 'true'
    });
}

In the above scenario, the original settings are retained and only the aria-busy value is modified.

More information:

A complete tutorial on live regions is out of the scope of this README. Browse the following for more info:

jquery-live-regions

Related posts:

Prism
SlickQuiz
gridify
jquery-live-regions

http://jquer.in/wp-content/uploads/2014/12/jquery-live-regions.jpg

jQuery plugin

Sign up for our weekly newsletter.

* We won't spam you ever
Couple Gift Ideas