diff --git a/aria-practices.html b/aria-practices.html index e761313cdd..d1155b8261 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -4145,11 +4145,11 @@

Live Region Properties and How to Use Them

Choosing Between Special Case Live Regions

You may wish to use a special live region role instead of applying live region properties. WAI-ARIA contains a number of standard roles which are by default considered "live" sections of your Web page. It is important to know when to use these and when to create a custom live region on your known. Here are some rules of thumb:

-

alert - You must use the alert role for a one-time notification which shows for a period of time and goes away and is intended to alert the user that something has happened. The assistive technology should be notified by the user agent that an alert has occurred, if your operating system supports this type of event notification. When choosing to use alert you should use the alertdialog role instead if something inside the alert is to receive focus. Both alert and alertdialog appear to pop-up to the user to get their attention.

-

status - You must use the status role when you want to mark an area which is updated periodically and provides general status of your Web application. Changes in status are not typically announced automatically by an assistive technology. However, it is possible to configure some assistive technologies, such as a scriptable screen reader, to watch for changes in the status bar and announce them. Using the status role is also important in that the user could always check the status section for changes in status on different Web pages. Many applications provide status widgets and they are often found, visibly, at the bottom of the application and contain a variety of widgets within it to convey status. The use of status does not guarantee how the AT will respond to changes in the status. The author can still put live="off" or live="assertive" to influence the ATs treatment of the status.

-

timer - You must use a timer role when you want to mark an area which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The text encapsulated within the timer indicates the current time measurement, and are updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point.

-

marquee- You must use a marquee role when you need to mark an area with scrolling text such as a stock ticker. The latest text of the scrolled area must be available in the DOM. A marquee behaves like a live region, with an assumed default aria-live property value of "polite."

-

log - You must use log if you have a live area where new information is added, like a scrolling chat log of text. Unlike other regions, implied semantics indicate the arrival of new items and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. If you have a chat text entry area you should indicate that it also controls the aria log aria like so:

+

alert - You may use the alert role for a one-time notification which shows for a period of time and then goes away. It is intended to alert the user that something has happened. The assistive technology should be notified by the user agent that an alert has occurred, if your operating system supports this type of event notification. When choosing to use alert you should use the alertdialog role instead if something inside the alert is to receive focus. Both alert and alertdialog usually appear to pop-up to the user to get their attention. Unless specified otherwise an alert region has an implicit aria-live of "assertive" and aria-atomic of "true".

+

status - You may use the status role when you want to mark an area which is updated periodically and provides a general status of your Web application. Many applications provide status widgets and they are often found, visibly, at the bottom of the application and contain a variety of widgets within it to convey status. Unless specified otherwise a status region has an implicit aria-live of "polite" and aria-atomic of "true".

+

timer - You may use a timer role when you want to mark an area which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The text encapsulated within the timer indicates the current time measurement, and is updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point. The timer role has an impicit aria-live of "off".

+

marquee- You may use a marquee role when you need to mark an area with scrolling text such as a stock ticker. The latest text of the scrolled area must be available in the DOM. A marquee behaves like a live region, with an implicit aria-live property value of "off."

+

log - You may use log if you have a live area where new information is added, like a scrolling chat log of text. Unlike other regions, implied semantics indicate the arrival of new items and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. Log has an implicit aria-live of "polite"If you have a chat text entry area you should indicate that it also controls the aria log aria like so:

<div contenteditable="true" role="log" id="chatlog">
 </div>
 
@@ -4160,7 +4160,7 @@ 

Choosing Between Special Case Live Regions

contenteditable="true" aria-labelledby="gettext"> </div
-

live region - If you have some other live area use case, WAI-ARIA allows you to mark an area using the aria-live attribute. This accompanied by the collection of attributes which support the live property allow you to create your own custom live area on your Web page. For more details regarding live regions refer to the live region section of this guide.

+

live region - If you have some other live area use case, WAI-ARIA allows you to mark an area using the aria-live attribute. This, accompanied by the collection of attributes which support the live property, allows you to create your own custom live area on your Web page. For more details regarding live regions refer to the live region section of this guide.

Live region roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. It is recommended that authors apply live regions to DIV and SPAN containers. For example:

<!-- Live region 'log' role used with TABLE element:  the 'log' role is not consistently mapped to platform AAPI. -->