WAI-ARIA Best Practices

3.1.1 ARIA Keyboard Bindings and Behaviors

Essential to accessible Web 2.0 widgets is keyboard support to provide full operation and functionality of a widget through keyboard-only events. Unlike traditional HTML form controls, Web 2.0 widgets, typically, have no inherent keyboard support. The developer must enable keyboard support for the widgets they create or use widget libraries with keyboard support. The best practices model for keyboard support for Web 2.0 widgets are graphical user interface (GUI) operating systems like Microsoft Windows®, Apple OSX®; and UNIX Desktops like GNOME and GTK. Two basic accessibility requirements for keyboard focus include:

• Support users who cannot use pointing devices due to physical or visual impairment to access the full functionality of the Web application.
• All major software and web accessibility guidelines for people with disabilities require keyboard-only operation of the interface for accessibility.
• Communicate accessibility information to assistive technologies on the type of widget and its associated state and properties.

3.1.2 Keyboard Navigation between Widgets

The tabindex attribute enables focus to be moved via keyboard to HTML elements used to create Web 2.0 widgets.

• Tab and Shift+Tab key move focus among widgets and standard HTML controls.
• Widgets with tabindex=0 will be added to the tab sequence based on document order
• Widgets with tabindex>0 will be added to the tab sequence based on the TABINDEX value
• Widgets with tabindex<0 will not be added to the tab sequence but are enabled to receive keyboard focus.

Once a widget has keyboard focus, arrow keys, Spacebar, Enter key, or other keyboard commands can be used to navigate the options of the widget, change its state, or trigger an application function associated with the widget.

3.1.3 Keyboard Navigation within Widgets

Each element that receives keyboard focus needs to have a tabindex attribute set to its current active desendant element and itself if an active desdendant does not exist. The element with keyboard focus is essential because it communicates information about the widget to assistive technologies like screen readers and magnifiers through operating specific accessibility APIs like Microsoft Active Accessibility (MSAA), the Apple Universal Accessibility API, and the ATK Accessibility Toolkit. The TAB key moves keyboard focus to the widget, and other keys operate the features of the widget, typically cursor keys, Enter key and Spacebar. The actual keys are up to the developer, but best practices recommend using the same key bindings that are used to control similar widgets in common GUI operating systems like Microsoft Windows®, Apple OSX® and UNIX Desktops like GNOME and GTK.

JavaScript can use either the focus() method to move focus to the appropriate element in the widget, or it can use an ARIA property called "activedescendant" on the actual widget container to indicate which element in the widget must have focus. The following procedure should be followed when focus is completely dependent on the use of tabindex to provice focus in a widget:

• Set tabindex="0" to the current active descendant in the widget while setting tabindex="-1" on all the other child elements of the widget
• As the user navigates (e.g. arrows) away from an item, the old item gets a tabindex="-1" and the new item gets tabindex="0".
• Use the javascript method to set focus, using its JavaScript focus() method, on the item whose tabindex="-1"

This procedure creates a roving tabindex. If you tab away and tab back to the widget the same last active descendant becomes active again. This relieves the author from having to compute and set the focus to the last activedescendant.

Conversely, if you use the WAI-ARI activedescendant property things get a lot easier:

• Set tabindex="0" on the element which represents a widget and set its activedescendant property to the id of the child you wish to be active
• As the user navigates (e.g. arrows) away from an item in the widget refresh the activedescendant property on the containing widget to the id of the new active descendant child.

The browser will then be responsible for managing focus changes for you.

In both scenarious the author must indicate through styling and/or markup which element in the widget has focus or is "active."

3.1.4 Example Keyboard Operation: Radio Group/Radio

See working Radio button examples from the University of Illinois.

In this Radio Group example, the tabindex of the radiogroup element initially has tabindex="0" (assuming none of the radio buttons is checked), the radio elements have tabindex="-1". As soon as one of the radio buttons is checked, the radio group element changes its value of tabindex="-1", the radio element that is checked changes its value to tabindex="0", and all other radio buttons have a tabindex ="-1".

3.1.5 Other Widget Best Practices

For specific keyboard navigation, see the Common Widget Design Patterns section.

3.1.6 Validation Issues

WAI-ARIA markup is currently not included in (X)HTML. The W3C WAI PF working group will be creating DTDs for XHTML 1.0 and HTML 4.01 for those wishing to validate their markup with WAI-ARIA embedded into these host languages.

3.2.1 Tabindex

One requirement for supporting the keyboard is to allow focus to be set to any element. The tabindex attribute can be used to include additional elements in the tab order and to set programmatic focus to them. Originally implemented in Internet Explorer 5, the feature has been extended to Opera, Firefox, and Mozilla. The following table outlines the use of the tabindex attribute:

Setting a tabindex value of -1 to an element allows the element to receive focus via JavaScript using the element.focus() method. This method is used to enable arrow key navigation to elements. Each element that can be navigated to via arrow keys must have a tabindex of -1 to enable it to receive focus. Here are just a few additional tips to help you with managing keyboard focus:

• Use onfocus to track the current focus - The events onfocus and onblur can now be used with every element. There is no standard DOM interface to get the current document focus, so if you want to track that you'll have to keep track of it in a JavaScript variable. Don't assume that all focus changes will come via key and mouse events, because assistive technologies such as screen readers can set the focus to any focusable element, and that needs to be handled elegantly by the JavaScript widget.

• Follow keydowns to move focus - A keydown event handler can determine the next object to receive focus and call that element's focus() method.
  
  
• Use onkeydown to trap key events, not onkeypress - Internet Explorer will not fire keypress events for non-alphanumeric keys.
  
  
• Refresh an elements style using onfocus() - An element's style may require an update via an onfocus event handler in order to show the focus, because browsers are inconsistent in displaying focus for items that receive focus programmatically.
  
  
• Dynamically change focusability using the tabIndex property - You may want to do this if a custom control becomes disabled or enabled. Disabled controls should not be in the tab order. However, you can typically arrow to them if they're part of grouped navigation widget.
  
  
• Use setTimeout with element.focus() to set focus - Do not use createEvent(), initEvent() and dispatchEvent() to send focus to an element, because DOM focus events are considered informational only -- generated by the system after something is focused, but not actually used to set focus. The timeout is necessary in both IE and Firefox 1.5, to prevent scripts from doing strange unexpected things as the user clicks on buttons and other controls. The actual code to focus an element will look something like this:
  

  window.setTimeout(function () { focusItem.focus(); },0);  // focusItem must be in scope

• Don't use :focus or attribute selectors to style the focus - You will not be able to use :focus or attribute selectors to style the focus if you want the focus to appear in Internet Explorer. Set the style in an onfocus event handler. For example, in a menu item's focus handler add this.style.backgroundColor = "gray";
  
  
• Always draw the focus for tabindex="-1" items and elements that receive focus programatically - Internet explorer will not automatically draw the focus outline for items that programatically receive focus. Choose between changing the background color via something like this.style.backgroundColor = "gray"; or add a dotted border via this.style.border = "1px dotted invert". In the dotted border case you will need to make sure those elements have an invisible 1px border to start with, so that the element doesn't grow when the border style is applied (borders take up space, and IE doesn't implement CSS outlines).
  
  
• Prevent used key events from performing browser functions - If a key such as an arrow key is used, prevent the browser from using the key to do something (such as scrolling) by using code like the following:

  <span tabindex="-1" onkeydown="return handleKeyDown();">   

  If handleKeyDown() returns false, the event will be consumed, preventing the browser from performing any action based on the keysroke.
  

• Use key event handlers to enable activation of the element - For every mouse event handler, a keyboard event handler is required. For example, if you have an onclick="doSomething()" you may also need onkeydown="return event.keyCode != 13 || doSomething();" in order to allow the Enter key to activate that element.
  

• Consider using a "roving" tabindex for complex widgets if you are not using the activedescendant property.

3.2.2 Using activedescendant vs. tabindex for to manage focus of widget children

ARIA provides two techniques for managing the focus of child elements within a widget. Widgets like grid and tree typically manage their children. The root element of the widget should have a tabindex value greater than or equal to "0" to ensure that the widget is in the document tabbing order. Rather than setting a key event handler on each element within a larger component, the event handler can be set on the parent element such as the tree. It will be job of the parent element to manage the focus of the children.

The parent may use the activedescendant property to indicate the active child. For example, the container element with the role of tree can provide an onkeydown event handler so that each individual tree item within the tree does not need to be focusable and to listen for the keydown event. The container object, in this case the tree, needs to maintain the point of regard and manage which individual child item must be perceived as active.

The key handler on the parent captures the keystrokes and determines what item becomes active next and updates the activedescendant property with the ID of the appropriate, next active child element. The browser takes that ID information and generates the focus event to the assistive technology. Each individual element does not have to be made focusable via a tabindex value of -1, but it must be styled using CSS to indicate the active status

An alternative to using activedescendant is to have the parent element, in response to the same keyboard input, move focus to its children by first removing tabindex from children that do not have focus, which removes them from the tab order. This would be followed by setting the tabindex to "-1" on the element which is to receive focus and then using script to set focus on the element to receive focus. Like with activedescendant this leaves managed children out of the tabbing order. For browsers which do not yet support activedescendant, this allows keyboard navigation to be maintained and it will provide focus notification to many assistive technologies like screen magnifiers to move visual focus and which are not reliant on other ARIA properties. Today, this technique will work in more user agents, but in the long run activedescendant will require less work by the developer.

3.2.3 Author-Defined Keyboard Short-Cuts or Mnemonics

Author-defined keyboard short-cuts or mnemonics present a high risk for assistive technology users. Because they are device-, browser-, and AT-dependent, conflicts among key bindings is highly probable. However if you needed to use one use accesskey. You should be aware that it will behave differently in
different browsers. It also may not work with small devices so it is still advisable to ensure that all features are accessible with the basic keys like Tab/shift+tab, arrow, Enter, space and Escape.

The XHTML 2 Working Group is currently developing a new Access Module to address this issue and we hope to have it or a feature like in future versions of (X)HTML. Refer to Section 9: Implemenation Guidance.

3.4.1 Steps for defining a logical navigational structure

Follow these steps to mark up each logical section:

1. Identify a the logical breakdown structure of your page

   Break up your page into perceivable block areas which contain semantically associated information called "regions". You can further breakdown each region into logical regions as needed. This is a common process undertaken by portal developers who break the page into perceivable regions called portlets. Think about the user wanting to navigate to these logical block areas on your web page. Write down a description of what you believe each region to be.

   Depending on your web application you may then need to break it into sub regions depending on the complexity of your web application. This is a recursive process. A user will look at these perceivable areas like pealing an onion. You might have an outermost collection of perceivable regions or block areas and upon entering each region you may have a collection of regions within it.

2. Implement the logical structure in markup

   Implementing the block structure in markup often involves wrapping elements contained with a "region" such as a <div> or <iframe> with perceivable borders so that each perceivable region or block area is perceivable to the user.

3. Label each region

   Once you have broken up each region you need to label it. The start of each region should have a perceivable header and it should be used to label the region. For details on how to do this see section 3.4.3.1 Header Levels vs. nesting level to create a header to label each region. If you're finding it difficult to come up with a label for the region, make sure at least to use one of the standard roles defined in the following step. The drawback of not providing a label is that users will not know the purpose of the region. By definition, regions would be included in a summary of a page. If an assistive technology were to summarize it would be unable to provide information about the section without a label.

4. Assign landmark roles to each region

   Now that you have your regions labelled you need to assign them semantic navigation landmarks. Landmarks are a vast improvement over the rudimentary "skip to main content" technique employed prior to WAI-ARIA. If possible it is best to use these as landmarks. Skip to main content links impact the layout of applications and only address one main content area. WAI-ARIA provides a collection of landmarks which are applied to each of the regions you identified in step 2.

   The presence of common, semantic, navigation landmarks allows each site to support the same standard and allows your your assistive technology to provide a consistent navigation experience - an important feature for screen readers and alternate input solutions. For users with cognitive and learning disabilites the landmark information could be used to expand and collapse these regions of your page to aid in simplifying the user experience by allowing the user to manage the amount of information processed at any one time.

   There are also mainstream benefits of providing navigation landmarks. Your browser may assign key sequences to move focus to these sections as they can be set on every site. Navigation to these landmarks is device independent. A personal digital assistant (PDA) could assign a device key to get to them in your document. These are the common landmarks included in WAI-ARIA.

   article

   Represents a section of a page consisting of a composition forming an independent part of a document, page, or site.
   
   An article could be a forum post, a magazine or newspaper article, a Web log entry, a user-submitted comment, or any other independent item of content. It is "independent" in that its contents could stand alone, for example in syndication. However, the element is still associated with its ancestors; for instance, contact information that applies to a parent body element still covers the article as well. When nesting articles, the inner articles represent articles that are in principle related to the contents of the outer article. For instance, a Web log entry on a site that accepts user-submitted comments could represent the comments as articles nested within the article for the Web log entry. Author, heading, date or other information associated with an article does not apply to nested articles. Assistive technologies must treat and article like a document in that article must must be processed like an application. Unlike a document, the use of articles allows the user to identify them and follow related articles based on the nesting. region that contains the prime heading or internal title of a page. Most of the content of a banner is site-oriented, rather than being page-specific. Site-oriented content includes things such as the logo of the site sponsor, the main heading for the page, and site-specific search tool. Typically this appears at the top of the page spanning the full width.

   banner

   A region that contains the prime heading or internal title of a page. Most of the content of a banner is site-oriented, rather than being page-specific. Site-oriented content includes things such as the logo of the site sponsor, the main heading for the page, and site-specific search tool. Typically this appears at the top of the page spanning the full width.

   complementary

   Any section of the document that supports but is separable from the main content. There are various types of content that would appropriately have this role. For example, in the case of a portal, this may include but not be limited to show times, current weather, or stocks to watch. The content should be relevant to the main content; if it is completely separable, a more general role should be used instead.

   contentinfo

   Meta information about the content on the page or the page as a whole. For example, footnotes, copyrights, links to privacy statements, etc. would belong here.

   main

   Main content in a document. This marks the content that is directly related to or expands upon the central topic of the page.

   navigation

   A collection of links suitable for use when navigating the document or related documents.

   search

   The search tool of a web document. This is typically a form used to submit search requests about the site or to a more general Internet search service.

   To set the landmark in you page:

   <div role="main"> ... <div role="complementary" title="weather">  
   

5. For the landmarks that just won't fit use the region or specialized region ARIA roles

   If you would like to use create your own custom regional landmarks you can by making use of any one of the following WAI-ARIA regions and labelling them with a title attribute or :

   • log
   • status
   • region (generic)

   It is not essential to label these specialized regions when they are used as a widget such as in the case of log and status but you should provide a title. When using the region role you should label the region with a header so that the name of the region is accessible to all users just as you would the standard regional landmarks. See Header levels versus Nesting levels for directions on how to label the region.

   <div role="log" title="chat log">
   <div role="region" title="Game Statistics">  

   Note: the region role is generic and a more specific role should be used if applicable. should only be used as a last resort. It shall be treated as a complemenatary region by an assistive technology.

6. Indicate to the assistive technology who controls the keyboard navigation

   Today's screen readers for the blind have been designed to give the user a "browsing" experience meaning the screen reader consumes a number of keys to aid in the browsing experience. For example, the "up" and "down" arrow keys are used to read the next and previous line of text on your web page. Accessible Rich Internet Applications will use these keys in an application to navigate within "widgets" like a Tree View.

   Assistive technologies must be able to identify widgets and which implement WAI-ARIA and allow them control use the keyboard. However, if you have used a used numerous widgets to form an application you must set the role on the larger region application and if you need to switch back occassionally to a document role you can. See section 3.4.2 Structural Roles used to facilitate assistive technology navigation.

3.4.2 Structural roles used to facilitate assistive technology navigation

When viewing web content however, screen readers often gather information about all the widgets in an area and present them in a document-like view which the user navigates using keyboard commands provided and controlled by the screen reader. Think of this mode as a virtual environment that presents web content in a way that makes it convenient for adaptive technology users to navigate and read. This is sometimes called browse mode, or virtual mode. We refer to this as "document browse mode."

Because screen readers often provide document mode navigation support using single key mnemonics on the alpha-numeric keyboard, they may provide a third mode, called "forms mode," used to interact with form controls that are encountered in document mode. Behavior in forms mode is similar to that of application mode. The key feature of forms mode is that it can be toggled with document mode to make it easy to both interact with a specific widget, and read virtualized content of which the widget is a part. Since, as described above, a screen readers perception of an area as either a document or an application greatly influences how the user reads and interacts with it, ARIA provides content authors a way to indicate whether their pages must be viewed as applications or documents by assistive technologies.

To set document or application mode follow these steps:

1. Set the Application Role

   After you have divided your web page into regions through the use of role landmarks and custom regions, you must make a decision: Is your web page an application or not? If it is, set the role of application on the body tag as follows:

   <body role="application"> 

   When using application, all static text must be associated with widgets, groups or panes via using the labelledby and describedby properties, otherwise it will not be read by the screen reader when the user navigates to the the related widget or group.
   
   Special Considerations:

   • If you have selected to have a role of application on the body tag it is recommended that a widget have focus after the page is first loaded.
   • If when your page loads and you should have have focus on a widget this is a strong indicator that your web page should have role of application.
   • If your page has only a few isolated widgets, like pop-up calendars located on a web page, it is not necessary to expressly set the role of application on the body. Screen readers, based on widget roles, must be able to provide access to these widgets without recognizing the entire page as an application.
   • Also, browsers make use of a feature called the contenteditable attribute, which will be incorporated into HTML 5. Contenteditable allows an author to turn the browser section into a rich text editor, similar to a word processor. Any section which has contenteditable set to "true" is considered a widget.
   • If the body element has been given the role of application, please follow step 3. Otherwise, the web page is considered a document, and no further action is required in this regard.
     
     
2. Dialogs and Alert Dialogs - special case application roles
   
   WAI-ARIA provides dialog and alertdialog roles which are to be treated as special case application roles. Like application, screen readers will leave the main job of keyboard navigation up the the application.
   
   When using dialog, all static text must be associated with widgets, groups or panes via using the labelledby and describedby properties, otherwise it will not be read by the screen reader when the user navigates to the the related widget or group. Unlike an application, your web page is unlikely to start out as either of these two roles but rather the author is most likely to dynamnically create dialogs or alertdialog sections within the web page.
   
   Unlike dialog, descriptive text of the alert does not need to be associated via a relationship as the contents of alert dialogs will be read automatically by the screen eader when the dialog opens.
   
   
3. Set the Document Role

The default mode for a screen reader to be processing an HTML web page is document browse mode. This is equivalent to having a role of document on the HTML <body> tag. If you have already specified a role of application on the body tag there may be times in which you tell the screen reader to switch into "document browse mode" and start stealing the necessary keys to browse a document section of your web page. These keys are the typical keys used by WAI-ARIA widgets and to provide this level of navigation the keys must be stolen from your browser.

To mark areas of your page to tell the assistive technology when to switch into document browse mode, look at the regions/landmarks you have defined and determine which ones must be browsed as a document or navigated as an application. For each region which must be browsed in document browse mode, embed a div element within it with the role of document as follows:

<div role="document"> 

Now, when a screen reader encounters this region, it will change its interaction model to that of document browsing mode.

3.4.3 Implicit Nesting and Headings

This section discusses the use of the heading role and nesting levels.

<p role="main" aria-labelledby="hdr1">

 <div role="header" id="hdr1">
    Top News Stories

 </div>

</p>

3.4.4 Grouping, Regions, and Directories

<div role="directory">
   <ul>
      <li>Global Warming Causes
          <ul>
             <li>CO2 Buildup</li>
             <li>Auto emissions<li>
             <li>Factory emissions</li>
             <li>Destruction of rainforests</li>
          </ul>

      </li>

      <li>Tailoring CO2 buildup</li>
          <ul>
             <li>Elimination of the incandescent light bulb</li>
             <li>Hydrogen fuel cells</li>
             <li>Solar energy</li>
             <li>Wind power</li>
          </ul>

      </li>  
   </ul>

</div>

<table role="presentation">
  <tr>
    <td>see</td>
    <td>spot</td>
    <td>run</td>
  </tr>  
  <tr>  
    <td>over</td>
    <td>the</td>
    <td>lazy coder</td>
  </tr>
</table>

3.4.5 Remaining structural roles

• columnheader
• description
• directory
• grid
• gridcell
• img
• list
• listitem
• row
• rowheader
• separator
• treegrid

<table role="grid">		

<table role="grid">
   <tr>
      <td role= "columnheader">Apples</td><td role= "columnheader">Oranges</td>
   </tr>
   <tr>
      <td role="gridcell" aria-readonly="false">Macintosh</td><td role="gridcell">Valencia</td>
   </tr>
</table>

<img src="foo" alt="" aria-describedby="prose1">

<div role="description" id="prose1">
   This prose in this div describes in detail the image foo.
</div>

4.1.1 Labelled By

A labelledby section needs to indicate what the object it labels does. For example, you could have a button in a webmail client which will erase a selected message. This button could be constructed out of any kind of HTML but with with the ARIA roles, states and other attributes the user will know it is a button. The button itself should have a basic behavioral explanation, such as "erase mail" but the user might not be familiar with this feature or webmail in general, so providing additional behavioral labeling will reduce fear and make the page more user friendly. The markup could look like this

<div role="button" aria-labelledby="eraseButton" tabindex="0">Erase Message</div> 

and elsewhere in the markup

<div id="eraseButton">Permanently erase the currently selected message titled "Nigerian Lottery"</div> 

This would give the user and any running AT additional information about the expected behavior if the button widget is activated. In this particular case, the <div> content has been updated to reflect the current context to make it more obvious exactly what the effect of the action will be. The section doing the labeling might be referenced by multiple widgets or objects as these need only reference the same id, so contextual description may not always be viable. The labelledby attribute can have multiple ids specified as a space separated list much like applying multiple classes to a single DOM object.

It should be noted that (X)HTML provides a <label for> element which you can use to label form controls. For all visual objects, including (X)HTML form elements, you should may the WAI-ARIA labelledby property for labelling.

4.1.2 Described By

A describedby section provides further information about a given object or widget, which may not be intuitively obvious from the context, content or other attributes. For example, a fake window is a common widget used in web applications and is often constructed using a div absolute positioned in a layer above other content. To simulate common window behavior look and feel there is often an X box in the corner which, when activated, dismisses the window widget. One common way to make this X box is to simply make a link whose content is an X. This doesn't give a non-visual user much to go on and belies the real purpose of the X link. To help we add more descriptive text stored elsewhere in the page like this:

<a role="button" aria-describedby="winClose" href="#" onclick="fakewin.close()">X</a> 

<div id="winClose">Closing this window will discard any information 
  entered and return you back to the main page</div> 

ARIA also defines the description and tooltip roles to which describedby may reference to assign a description (which could span multiple document elements) and an author defined tooltip. The assistive technology can can tell from the type of object describing the document element what the purpose of that element is. For example, a screen reader could announce the tooltip without the user having to waive the mouse over the element by following the describedby relationship to a document area with a tooltip role. The describedby property is also useful for describing groups.

Here is a code snippet showing a set of the tooltip:

...    
  <div class="text">
    <label for="first">First Name:</label>
      <input type="text"               
          id="first"           
          name="first"            
          size="20"           
          onfocus="tooltipShow(tooltip1)"          
          onblur="tooltipHide(tooltip1)"
          onmouseover="tooltipShow(tooltip1)"           
          onmouseout="tooltipHide(tooltip1)"           
          aria-describedby="tp1"
      />
  <div id="tp1" class="tooltip" role="tooltip">Your first name is a optional</div>    
  </div>    
...  

4.2.1 The owns relationship.

Assistive technologies are dependent on knowing the parent, or owner, of an object the person is working on to provide context where the user is operating. Typically, this can can be determined from a parsing of your web page into a DOM, forming of a tree hierarchy, that allows an assistive technology to request the "parent" of the the object they are working on. An example where this is important is a treeitem. Here, the user often asks for the the container parent such as a folder name. In rich internet applications, only a subset of the treeitems may be available at any one time and they may be added dynamically without modification to the DOM tree hierarchy - a common occurence in Ajax applications.

WAI-ARIA allows the the author to identify "adopted" children solution through the use of the owns property. The owns relationship property establishes owernship of an element when applied to an element in the web page.  In these situations, adopted children are visually rendred to be contained in or managed by a "perceived" parent when actually they are not natural children as would be found in a parsed DOM. The owns attribute must appear on any element whose logical contents includes elements nested within it and also other content not found among its syntactic descendants (determined from the DOM). The value of the attribute is a list of 'id' attribute values for the additional logical children that are not syntactic descendants. Let us call the elements whose IDs appear in the 'owns' attribute value as the adoptive children and the children by textual inclusion natural children.

Natural and adopted children must be presented to users in a way such that the user will perceive them to be part(s) of the logical parent and peers of each other. Each child, adopted or natural, should each have the appropriate posinset and setsize properties set consistent with their rendering if the cannot be determined from the DOM from a direct parsing of the host language. Places where direct parsing does not allow the user agent to determine posinset and setsize are long lists where only the currently visible items are loaded (via Ajax). If the children are resorted then the posinset and setsize values should be updated consistent with their visual rendering.

Platform accessibility API must invert this relationship for assistive technologies so that they may determine the owning parent from a child and couple it with posinset and setsize information to provide context information to the user.

4.2.2  Using owns with reuse.

If you are re-using content across different, transient sections of content by restyling it to render it in association with a different object, you need to maintain the owns property as well to match the current use and apparent ancestry of the reused sub-section. A good example of this is a context help menu that resides at the end of the document. When the user wish to launch the context help menu in association with different visual elements, styling is used to render the menu in context with that object. Prior to rendering the visual submenu you should ensure the object to which you have requested help assigns its owns property value to the submenu id. When the menu closes you can remove the owns property.

4.2.3 The controls relationship.

In Rich Internet Applications document elements may control the behavior on another part of web page outside themselves. The controls attribute indicates cause-and-effect relationships between document elements.

An example might be a group of radio buttons that "control" contents of a listbox in another part of the page. Here, you would want the radio group to assign a controls relationship to the listbox which will be updating without a page reload. The user, through their assistive technology can then navigate to the listbox by following the controls relationship, when a different radio is selected, to see how the contents changed in the listbox. The ability to update parts of a page without a page reload is a common practice of applications making use of Ajax. Without the controls attribute, a user would be unable to effectively use these types of web pages as assistive technologies often will not make the user aware of what is happening outside the context of the element the user is currently operating.

With the controls attribute the user may use the assistive technology to follow the relationship to the object it is controlling. It is extremely important for an assistive technology to present changes in the document in response to user input. Therefore, an assistive technology immediately present changes to a live region when the controlling widget is the one which has user keyboard focus. For example, if a tree view controls a help document pane, each time
the tree item changes the new tree item and then the new help contents should also be read. In the case of a screen reader, the amount of information information read in the target live region is dependent on how the live region is configured.

The controls attribute takes one or more ids which refer to the document element. If this relationship is not implied by the host language semantics, then the controlling element must be given a controls attribute with the IDs of the other elements where the changes will show up listed in the attribute value.

5.2.1
5.2.1 Live Region Properties and how to use them

One of the most important concepts behind live regions is politeness. Politeness indicates how much priority a live region has. The following politeness settings are possible: live="off", live="polite", live="assertive", and live="rude".

live="off"

This is the default. Any updates made to this region must not be announced to the user. live="off" would be a sensible setting for things that update very frequently such as GPS coordinates of a moving vehicle.

live="polite"

Any updates made to this region should only be announced if the user is not currently doing anything. live="polite" should be used in most situations involving live regions that present new information to users, such as updating news headlines.

live="assertive"

Any updates made to this region are important enough to be announced to the user as soon as possible, but it is not necessary to immediately interrupt the user. live="assertive" must be used if there is information that a user must know about right away, for example, warning messages in a form that does validation on the fly.

live="rude"

Any updates made to this region are extremely important. In fact, the updates are so important that the user must be interrupted immediately. live="rude" should be used sparingly and only with great consideration as it can be very annoying to users.

There are times to suppress AT presentation changes while a region is updating. For that you can use the busy property.

busy="true"

To suppress presentation of changes until a region is finished updating or until a number of rapidfire changes are finished, set busy="true" and then clear the attribute when the region is finished. While it is busy, the AT will track and collate the changes. It will finally speak the changes once the region is no longer busy

When a live region is updated, the update can often be announced on its own and still make sense. For example, if a news headline is added, it would make sense to simply announce the headline. However, sometimes the entire live region must be read in order to give the user enough context to make sense of the update. For example, it would not make sense to only give the current value of a stock without saying the name of the stock. The atomic setting gives assistive technologies a hint about which of these cases an update falls into.

atomic="false"

This is the default. It means that when there is a change in the region, that change can be presented on its own; the AT should not present the entire region. atomic="false" is generally a good idea as it presents users with only changes and does not cause them to hear repetitive information that has not changed. However, web developers should take care that the changed information, when presented by itself, can still be understood and contextualized by the user.

atomic="true"

If atomic is set to "true", it means that the region must be presented as a whole; when there is a change, the AT should present the entire region, not just the change. atomic="true" can make it harder for users to understand changes as the changed areas are not presented independently. atomic="true" can also be annoying as it can force users to listen to repetitive information that has not changed. However, atomic="true" is necessary in cases where the change, when presented by itself, cannot be understood and contextualized by the user. Note that when aria-atomic="true", the AT will attempt to speak the atomic region only once when multiple changes occur in the same region and it hasn't been spoken yet.

relevant="additions"

relevant="additions" states that the insertion of nodes to the live region should be considered relevant.

relevant="removals"

relevant="removals" states that the removal of nodes to the live region should be considered relevant. Often, removals are not relevant because nodes are removed to make space for new information - e.g. a log implemented as a table where items are taken off the top. However, in the case of something like a bluddylist, it is relevant if a buddy is removed. It doesn't require the screen reader to speak the removal, but it notifies the screen reader that it could be useful to do so.

relevant="text"

relevant="text" states that changes to the textual content of nodes that already exist in the live region should be considered relevant. Textual content includes text equivalents, such as the alt attribute of images.

channel="main"

This is the default. Messages in the main channel can only cancel out other messages in the main channel.

channel="notify"

The notify channel is slightly higher priority than the main channel. If there are two messages of equal politeness waiting in both the notify and main channels and there is only one output channel, the message in the notify channel will be processed first. However, if the politeness values are different, then the message that is less polite will be processed first, regardless of which channel it is in. Messages in the notify channel can only cancel out other messages in the notify channel.

Example 1

1. The user is on an AT that supports only a single hardware channel.
2. Given:

    <div id="liveRegionA" aria-live="polite" aria-channel="main">
    </div>
    <div id="liveRegionB" aria-live="polite" aria-channel="notify">
    </div>          

3. Both live regions get updates that are "polite" simultaneously. liveRegionB should be spoken first since it is on the notify channel.

Example 2

1. The user is on an AT that supports only a single hardware channel.
2. Given:
   

    <div id="liveRegionA" aria-live="assertive" aria-channel="main">
    </div>
    <div id="liveRegionB" aria-live="polite" aria-channel="notify">
    </div>
   

3. Both live regions get updates simultaneously. liveRegionA should be spoken first, because its message has a higher priority than liveRegionB.

See Also Explanation of Live Region Use

11.3.1 Managing Showing and Hiding document sections

11.3.2 Notification of changes to sections

11.3.3 ARIA to Accessibility API Events

11.3.4 Role Mappings

11.3.5 Mapping to platform accessibility APIs

User agents should map ARIA role and property semantics to the closest appropriate matches in their supported accessibility API. When it is not possible to find an exact match for a given role or property, API extensions should be utilized to expose the complete information.

11.5.1 Participants active in the PFWG at the time of publication

• Chris Blouch (AOL)
• Charles Chen (Google)
• Michael Cooper (W3C/MIT)
• Dimitar Denev (FIT)
• Donald Evans (AOL)
• Kentarou Fukuda (IBM)
• Alfred S. Gilman (W3C Invited Expert)
• Jon Gunderson (UIUC)
• Kenny Johar (Vision Australia)
• Diego La Monica (IWA/HWG)
• Aaron Leventhal (IBM)
• Thomas Logan (Invited Expert, BayFirst Solutions)
• Matt May (Adobe)
• Charles McCathieNevile (Opera)
• Lisa Pappas (Invited Expert, SAS)
• Dave Pawson (RNIB)
• David Poehlman (Invited Expert, State of MD)
• Gregory Rosmaita (Invited Expert)
• Janina Sajka (Invited Expert, The Linux Foundation)
• Stefan Schnabel (SAP)
• Richard Schwerdtfeger (IBM)
• Lisa Seeman (UB Access)
• Marc Silbey (Microsoft)
• Mike Squillace (IBM)
• Gottfried Zimmermann (Access Technologies Group)

11.5.2 Other previously active PFWG participants and other contributors to the Accessible Rich Internet Applications specification

Special thanks to Aaron Leventhal for effort and insight as he implemented a working prototype of accessibility API bindings.

Jim Allan (TSBVI), Simon Bates, Judy Brewer (W3C/MIT), Christian Cohrs, Becky Gibson (IBM), Andres Gonzalez (Adobe), Georgios Grigoriadis (SAP AG), Jeff Grimes (Oracle), Barbara Hartel, Sean Hayes (Microsoft), John Hrvatin (Microsoft), Earl Johnson (Sun), Masahiko Kaneko (Microsoft), Jael Kurz, Alex Li (SAP AG), William Loughborough, Linda Mao (Microsoft), Anders Markussen (Opera), Dave Pawson (RNIB), T.V. Raman (Google), Vitaly Sourikov, Ryan Williams (Oracle), Tom Wlodkowski.

11.5.3 Enabling funders

This publication has been funded in part with Federal funds from the U.S. Department of Education under contract number ED05CO0039. The content of this publication does not necessarily reflect the views or policies of the U.S. Department of Education, nor does mention of trade names, commercial products, or organizations imply endorsement by the U.S. Government.