Techniques for WCAG 2.0

On this page:

-

# ARIA1: Using Accessible Rich Internet Application describedby property to provide a descriptive, programmatically determined label

## Applicability

HTML and XHTML with scripting and Accessible Rich Internet Applications.

Editorial Note: This technique will be applicable when Accessible Rich Internet Application specifications reach W3C recommendation status.

This technique relates to:

- Success Criterion 1.3.1 (Info and Relationships)
  - How to Meet 1.3.1 (Info and Relationships)
  - Understanding Success Criterion 1.3.1 (Info and Relationships)
- Success Criterion 2.4.4 (Link Purpose (In Context))
  - How to Meet 2.4.4 (Link Purpose (In Context))
  - Understanding Success Criterion 2.4.4 (Link Purpose (In Context))
- Success Criterion 2.4.2 (Page Titled)
  - How to Meet 2.4.2 (Page Titled)
  - Understanding Success Criterion 2.4.2 (Page Titled)
- Success Criterion 3.3.2 (Labels or Instructions)
  - How to Meet 3.3.2 (Labels or Instructions)
  - Understanding Success Criterion 3.3.2 (Labels or Instructions)

## User Agent and Assistive Technology Support Notes

As of October, 2006, Accessible Rich Internet Application techniques are supported in Firefox 1.5 or later on Windows and Window-Eyes version 5.5 or later. Support in other user agents and assistive technologies is in progress. This particular technique relies on updates made to Firefox 2.0 to allow the use of the `describedby` attribute by itself without also defining a role for the element.

## Description

The purpose of this technique is to demonstrate how to use the Accessible Rich Internet Application (ARIA) `descibedby` property to provide descriptive information about a user interface control that can be programmatically determined by user agents. ARIA techniques provide the ability to add programmatically determined information to an element which can provide additional information about the element. The user agent can provide this additional information to assistive technology for presentation to the user. For example, the `describedby` property can be used to provide information that is available in the content surrounding the user interface control but would not normally be available when the user is navigating from control to control using an assistive technology.

## Examples

### Example 1: HTML

This example uses scripting to add the `describedby` property to user interface controls on the page. The use of scripting is necessary because the "describedby" attribute is not in the HTML specification and adding it directly to the markup would prevent the markup from validating. In user agents which support namespaces, the required state is assigned using the `setAttributeNS()` application programming interface (API). For other user agents the required state is assigned using the `setAttribute()` API and the namespace is simulated by adding a static text string to the front of the `describedby` attribute.

In the example below two array variables, `buttonIds` and `linkIds`, are created. Each array holds the ids of the elements that contain the description text. Each array is indexed via the id of the elements which need a `describedby` property. The `setDescribedBy()` function is called from the onload event of window object.

The `setDescribedBy()` function finds all of the button elements on the page. It loops through all of the button elements found and, using the button id as the index, looks in the `buttonIds` array for an associated id value. This id is the `id` attribute of the element which contains the description text to be associated with the button. If an associated id is found, the script assigns the `describedby` property to the button using the `setAttrNS()` function.

The `setDescribedBy()` function also finds all of the anchor elements on the page and performs a similar process. It looks for associated ids in the `linksId` array and assigns the `describedby` property to each link using the `setAttrNS()` function.

The `setAttrNS()` function will call the `setAttributeNS()` API when it is available to set the required attribute. It uses the appropriate namespace URI, "http://www.w3.org/2005/07/aaa", for the States and Properties Module for Accessible Rich Internet Applications (ARIA States and Properties). If the `setAttributeNS()` API is not available in the user agent, a static, simulated namespace of "aaa:" is added to the required attribute name and it is set using the `setAttribute()` API.

Using a user agent and/or assistive technology which supports ARIA, the additional description will be provided when the user interface controls receive focus.

Example Code:

     <head>
     <meta http-equiv="content-type" content="text/xhtml; charset=utf-8" />
     <title>Demonstration of describedby property</title>
     <style type="text/css">
     div.form p { clear:left; margin: 0.3em 0;}
    .left {
      float:left;
      width:400px;
    }
    .right {
    	width:100px;
    	text-align:right;
    }
     </style>
     <script type="text/javascript">
     //<![CDATA[

     // array entries for each button on the page that associates the button id
     // with the id of the element containing the text which describes the button
     var buttonIds = new Array();
     buttonIds["fontB"]= "fontDesc";
     buttonIds["colorB"] = "colorDesc";
     buttonIds["customB"] = "customDesc";
     // array entries for each link on the page that associates the link id with
     // the id of the element containing the text which describes the link
     var linkIds = new Array();
     linkIds["iceberg"] = "icebergInfo";

     // function that is run after the page has loaded to set the describedBy
     // property on each of the elements referenced by the array of id values
     function setDescribedBy(){
    	if (buttonIds){
    		var buttons = document.getElementsByTagName("button");
    		if (buttons){
    			var buttonId;
    			for(var i=0; i<buttons.length; i++){
    				buttonId = buttons[i].id;
    				if (buttonId && buttonIds[buttonId]){
    					setAttrNS(buttons[i], "describedby", buttonIds[buttonId]);
    				}
    			}
    		}
    	}
    	if (linkIds){
    		var links = document.getElementsByTagName("a");
    		if (links){
    			var linkId;
    			for(var k=0; k<links.length; k++){
    				linkId = links[k].id;
    				if (linkId && linkIds[linkId]){
    					setAttrNS(links[k], "describedby", linkIds[linkId]);
    				}
    			}
    		}
    	}
     }

     // method to set the attribute values based on the capability of the browser.
     // Use setAttributeNS if it is available, otherwise append a namespace
     // indicator string to the attribute and set its value.
     function setAttrNS(elemObj, theAttr, theValue){
             elemObj.setAttribute("aria-" + theAttr, theValue);
     }

     // simulated action function - currently just displays an alert
     function doAction(theAction){
    	alert("Perform the " + theAction + " action");
     }

     window.onload=setDescribedBy;

    //]]>
     </script>
     </head>
     <body>
     <p>The buttons on this page use the Accessible Rich Internet Applications
     describedby property to provide more detailed information
     about the button action
     </p>
     <div class="form">
     <p><span class="left" id="fontDesc" >Select the font faces and sizes to be used on this page</span>
        <span class="right"><button id="fontB" onclick="doAction('Fonts');"> Fonts </button></span>
     </p>
     <p><span class="left" id="colorDesc" >Select the colors to be used on this page</span>
        <span class="right"><button id="colorB" onclick="doAction('Colors');"> Colors </button></span>
     </p>
     <p><span class="left" id="customDesc" >Customize the layout and styles used on this page</span>
        <span class="right"><button id="customB" onclick="doAction('Customize');"> Customize </button></span>
     </p>
     </div>
     <p>The link in this paragraph has been updated with the Accessible Rich
     Internet Applications describedby property to provide more information
     about the link</p>
     <p> <span id="icebergInfo">Alaskan storm cracks iceberg in Antarctica. </span>
     A bad storm in Alaska last October generated an ocean swell that broke apart
     a giant iceberg near Antarctica six days later, U.S. researchers reported on Monday.
     <a href="http://www.sciencemag.com/iceberg.html" id="iceberg">More Info...</a>.
     </p>
     </body>

Working HTML example of use of describedy property

### Example 2: XHTML

This is the same example coded in XHTML with a MIME type of application:xhtml+xml. This MIME type is not supported in all user agents. It declares an xml namespace to access the `describedby` property. The `describedby` information is added directly into the XHTML markup and no additional scripting is needed.

Example Code:

    <?xml version="1.0" encoding="UTF-8"?>
     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
        "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
     <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
     xmlns:waistate="http://www.w3.org/2005/07/aaa" >
     <head>
     <meta http-equiv="content-type" content="application:xhtml+xml; charset=utf-8" />
     <title>Demonstration of describedby property</title>
     <style type="text/css">
     div.form p { clear:left; margin: 0.3em 0;}
     .left {
       float:left;
       width:400px;
     }
     .right {
       width:100px;
       text-align:right;
     }
     </style>
     </head>
     <body>
     <p>The buttons on this page use the Accessible Rich Internet Applications describedby property
     to provide more detailed information about the button action</p>
     <div class="form">
     <p><span class="left" id="fontDesc" >Select the font faces and sizes to be used on this page</span>
     <span class="right"><button id="fontB" onclick="doAction('Fonts');" waistate:describedby="fontDesc">
     Fonts </button></span></p>
     <p><span class="left" id="colorDesc" >Select the colors to be used on this page</span>
     <span class="right"><button id="colorB" onclick="doAction('Colors');" waistate:describedby="colorDesc">
     Colors </button></span></p>
     <p><span class="left" id="customDesc" >Customize the layout and styles used on this page</span>
     <span class="right"><button id="customB" onclick="doAction('Customize');"
     waistate:describedby="customDesc"> Customize </button></span></p>
     </div>
     <p>The link in the next paragraph has been updated with the Accessible Rich Internet Applications
     describedby property to provide more information about the link</p>
     <p> <span id="icebergInfo">Alaskan storm cracks iceberg in Antarctica. </span>
     A bad storm in Alaska last October generated an ocean swell that broke apart a giant
     iceberg near Antarctica six days later, U.S. researchers reported on Monday.
     <a href="http://www.sciencemag.com/iceberg.html" id="iceberg" waistate:describedby="icebergInfo">More Info...</a>.
     </p>
     </body>
     </html>

## Resources

Resources are for information purposes only, no endorsement implied.

- Roadmap for Accessible Rich Internet Applications (WAI-ARIA Roadmap)

- Accessible Rich Internet Applications (WAI-ARIA) Version 1.0

## Related Techniques

- ARIA4: Using Accessible Rich Internet Applications to programmatically identify form fields as required

## Tests

### Procedure

1. Load the page using a user agent and/or assistive technology that supports Accessible Rich Internet Applications.

2. Using a user agent that supports ARIA, navigate to each user interface control modified with a `describedby` property and verify that the description is made available to the user.

### Expected Results

- Check #2 is true.

- Top
- Contents
- Intro
- Previous: Technique T3
- Next: Technique ARIA2