This document is a draft, and is designed to show changes from a previous version. It is presently showing added text,changed text,deleted text,[start]/[end] markers,and Issue Numbers.
Changes are displayed as follows:
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:
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.
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.
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>
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 are for information purposes only, no endorsement implied.
Load the page using a user agent and/or assistive technology that supports Accessible Rich Internet Applications.
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.
Check #2 is true.