Techniques for WCAG 2.0

Skip to Content (Press Enter)

-

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:

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.

 <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){
	if (typeof document.documentElement.setAttributeNS != 'undefined') {
		elemObj.setAttributeNS("http://www.w3.org/2005/07/aaa", theAttr, theValue);
	}else{
		elemObj.setAttribute("aaa:" + 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.

<?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.

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