At this point you should have a basic understanding of how WAI-ARIA is used to support interoperability with assistive technologies. If you are not reusing a WAI-ARIA-enabled widget library and wish to create your own the following steps will guide you through the thought process for creating an accessible widget using WAI-ARIA.
-
Pick the widget type (role) from the WAI-ARIA taxonomy
WAI-ARIA provides a role taxonomy ([ARIA], Section 3.4) constituting the most common UI component types. Choose the role type from the provided table. If your desire was to create a toolbar set the role to toolbar:
<div role="toolbar">
- From the role, get the list of supported states and properties
Once you have chosen the role of your widget, consult the WAI-ARIA specification [ARIA] for an in-depth definition for the role to find the supported states, properties, and other attributes. For example, the toolbar role definition includes:
- parent role
- In the taxonomy the widget you selected inherits states and properties from this role. In the case of a toolbar you will see that a toolbar is a subclass of a group. This makes sense given that a toolbar is a collection of commonly used functions.
- related concept
- This is really more informative to state what other concepts are similar to this role. These may exist in different host languages outside WAI-ARIA.
The keyboard model
for the control should emulate that of the related concept control.
- supported states and properties
- These are unique states and properties that this widget supports and that were not inherited from its ancestors in the taxonomy. In the case of a
toolbar there are no such states or properties. However, in the case of a listbox, you may choose to set the property of aria-multiselectable to true if you were to have more than one item in the listitem selected at a time. This indicates to the assistive technology that the listbox manages a collection of selectable options. - inherited states and properties
- These are all the states and properties which are inherited from the roles's ancestors and which you may use.
- global states and properties
- These are states and properties which apply to all host language components regardless of whether a role is set or not. You may use these as well.
Once you have chosen the states and properties that apply to your widget you must set those properties you will use to set their initial values. Note: You do not need to use all the states and properties available for your role. In our case we shall use:
<div role="toolbar" tabindex="0" id="customToolbar"
onkeydown="return optionKeyEvent(event);"
onkeypress="return optionKeyEvent(event);"
onblur="hideFocus()"
onfocus="showFocus()"
>
<img src="img/btn1.gif" tabindex="0" title="Home"
role="button" id="b1" alt="Home"
onClick="updateText('Home was invoked');">
<img src="img/btn2.gif" tabindex="-1" title="Refresh"
role="button" id="b2" alt="Refresh"
onClick="updateText('Refresh was invoked');">
<img src="img/btn3.gif" tabindex="-1" title="Help"
role="button" id="b3" alt="Help"
onClick="updateText('Help was invoked');">
</div>
By avoiding tabindex on the toolbar and setting tabindex=0 on the first button, but tabindex=-1 on the others, we have specified that the first button in the toolbar will receive focus in the document order. It is then necessary to use script to change the focus amongst the buttons from there.
Important: When embedding WAI-ARIA markup in (X) HTML, all WAI-ARIA states and properties must be preceded with the characters aria- with the exception of the role and tabindex attributes. Otherwise, the user agent will not map the WAI-ARIA information, resulting in it not being recognized by assistive technologies.
When embedding WAI-ARIA into other host languages, tabindex does not carry over. The WAI-ARIA tabindex extensions are specific to (X)HTML to repair deficiencies in keyboard support.
- Establish the widget structure in the markup (parent/child)
Assistive technologies are very dependent on the structure of widgets as well as general document structure. Structure provides context to the user. A toolbar is a collection of common functions made available to the user. Therefore, all functions you would like in the toolbar must be contained within it. This can be determined by using the Document Object Model [DOM] tree structure created by the browser when parsing the host language. By using the parent child relationship of the DOM, an assistive technology can determine all the related toolbar widgets associated with the toolbar. The toolbar widgets would be DOM children of the "toolbar" container. For our purposes we will define three image buttons for cut, copy, and paste.
<div role="toolbar" tabindex="0" aria-activedescendant="button1">
<img src="buttoncut.png" alt="cut" id="button1">
<img src="buttoncopy.png" alt="copy" id="button1">
<img src="buttonpaste.png" alt="paste" id="button1">
</div>
- Repeat steps 1-3 for the children of the parent
We now need to assign the roles and states for each of the children. However, we shall save the detailed navigation for step 5.
<div role="toolbar" tabindex="0" aria-activedescendant="button1">
<img src="buttoncut.png" alt="cut" role="button" id="button1">
<img src="buttoncopy.png" alt="copy" role="button" id="button2">
<img src="buttonpaste.png" alt="paste" role="button" id="button3">
</div>
The process of setting roles and states may be a recursive procedure if the children themselves have children, such as in the case of an expandable/collapsible tree widget.
-
Establish keyboard navigation of the widget and plan for how it will be navigated to within the document
It is very important that your widget be keyboard accessible. In fact, there must be a keyboard equivalent for every mouse operation. Where possible you should refer to the WAI-ARIA examples in this guide for tips on how to implement keyboard navigation for your widget. If you find that an example is not provided, you should follow standard keyboard bindings for UI components such as those used for the Java Foundation Classes for Windows 95/NT.
For our toolbar, we have chosen to have the toolbar manage the focus for its children and through the use of the aria-activedescendant property. We have also chosen to have the toolbar receive focus based on the tab order by using tabindex. In order to use aria-activedescendant, each focusable descendant must have an assigned ID.
<head>
<script>
...
function optionKeyEvent(event)
{
var tb = event.target;
var buttonid;
DOM_VK_ENTER = 13;
// Partial sample code for processing arrow keys
if (event.type == "keydown") {
if (event.altKey) {
return true; // Browser should use this, the menu view doesn't need alt-modified keys
}
// XXX Implement circular keyboard navigation within the toolbar buttons
if (event.keyCode == DOM_VK_ENTER) {
ExecuteButtonAction(getCurrentButtonID()); // This is an author defined function
}
else if (event.keyCode == event.DOM_VK_RIGHT) {
// Change the active toolbar button to the one to the right (circular) by
var buttonid = getNextButtonID(); // This is an author defined function
tb.setAttribute("aria-activedescendant", buttonid);
}
else if (event.keyCode == event.DOM_VK_LEFT) {
// Change the active toolbar button to the one to the left (circular) by
var buttonid = getPrevButtonID(); // This is an author defined function
tb.setAttribute("aria-activedescendant", buttonid);
}
else {
return true;
}
return false;
}
else if (event.type == "keypress") {
...
}
}
</script>
<div role="toolbar" tabindex="0" aria-activedescendant="button1" id="tb1"
onkeydown="return optionKeyEvent(event);"
onkeypress="return optionKeyEvent(event);">
<img src="buttoncut.png" alt="cut" role="button" id="button1">
<img src="buttoncopy.png" alt="copy" role="button" id="button2">
<img src="buttonpaste.png" alt="paste" role="button" id="button3">
</div>
The details of implementing keyboard navigation are described in Keyboard and Structural Navigation section of this document.
Note: You must also show the visual focus for each element that has focus.
-
Apply and manage needed WAI-ARIA states in response to user input events
Similar to the processing of aria-activedescendant in Step 5, as author you must set any additional WAI-ARIA states and properties on document elements.
-
Synchronize the visual UI with accessibility states and properties for supporting user agents
You should consider binding user interface changes directly to changes in WAI-ARIA states and properties, such as through the use of CSS attribute selectors. For example, the setting of the aria-selected (state) state may change the background of a selected treeitem in a tree. This may also be done with JavaScript.
.treeitem[role="treeitem"][aria-selected="true"] {color: white; background-color: #222222;}
.treeitem[role="treeitem"][aria-selected="false"] {color: white; background-color: beige;}
Authors should be aware that CSS attribute selectors are not supported in some browsers, such as Internet Explorer 6. A consistent way to apply styling to reflect WAI-ARIA semantics would be to assign an element a class name based on the WAI-ARIA attribute being set using script as shown here:
function setSelectedOption(menuItem)
{
if (menuItem.getAttribute("role") != "menuitem") {
return;
}
var menu = getMenu(menuItem);
var oldMenuItem = getSelectedOption(menu);
// Set class so that we show selection appearance
oldMenuItem.className="unselected";
menu.setAttribute("aria-activedescendant", menuItem.id);
menuItem.className= "selected";
}
- Showing and Hiding Sections in a Widget
The proper synchronization of showing and hiding sections in a widget with the WAI-ARIA display state is also critical. Some platform accessibility APIs provide events for applications to notify the assistive technology when pop-ups such as menus, alerts, and dialogs come into view or go away. Rich Internet applications can assist browsers which support these conventions by:
-
Creating an entire section and then insert it into the Document Object Model [DOM], as a subtree of the parent element activated to show the pop-up, and then removing the section from the inserted area when the pop-up goes away.
OR
-
Using the following style sheet properties to show and hide document sections being used to represent the pop-up items, menus or dialogs:
display:blockdisplay:nonevisibility:visiblevisibility:hidden
By monitoring these behaviors a user agent may use this information to notify assistive technology that the pop-up has occurred by generating the appropriate accessibility API event.
Some assistive technologies may use the DOM directly to determine these when pop-up occurs. In this case, the first mechanism of writing a section to the DOM would work using the DOM events as demonstrated here.
// create new table row with table cell and div
var newTr = document.createElement('TR');
var newTd = document.createElement('TD');
var newDiv = document.createElement('DIV');
newTr.appendChild(newTd);
newTd.appendChild(newDiv);
//insert this new table row before the Node selected
var container = theNode.parentNode;
container.insertBefore(newTr, theNode);
//remove theNode selected
container.removeChild(theNode);"
However, if you are using CSS to show and hide sections of the DOM (2) it is essential that you set the corresponding WAI-ARIA aria-hidden (state) property to indicate that the section is visible or hidden and synchronize it with your CSS styling as shown here:
[aria-hidden=true] {visibility: hidden;}
...
<div role="button" aria-haspopup="true" aria-owns="mypopupmenu">
<div role="menu" aria-hidden="true" id="mypopupmenu">...</div>
- Support basic accessibility, such as alternative text on images
When an image is used to represent information within a component, such as image buttons, you need to set the alternative text on those images. This is then mapped by the user agent to the accessible name in the platform accessibility API. Using our example:
<div role="toolbar" tabindex="0" aria-activedescendant="button1" id="tb1"
onkeydown="return optionKeyEvent(event);"
onkeypress="return optionKeyEvent(event);">
<img src="buttoncut" role="button" id="button1" alt="cut">
<img src="buttoncopy" role="button" id="button2" alt="copy">
<img src="buttonpaste" role="button" id="button3" alt="paste">
</div>
- Establish WAI-ARIA relationships between this widget and others
Once you have made the basic widget accessible you may then need to establish its relationship to other widgets. Examples of this are aria-labelledby, aria-controls, aria-describedby and aria-flowto. The details of using these relationships are described in the Relationships section of this document.
Other relationships which should be considered are more declarative and provide context to the widget within a set. For these, aria-level, aria-posinset, and aria-setsize are provided. If you structure your Document Object Model appropriately so that the user agent can determine this information from it using the DOM hierarchy directly, you do not need to set these properties. There are, however, situations in rich internet applications where all the elements in a container are not in the DOM at one time, such as when you can only render the ten of fifty items in a subtree. In this case the user agent cannot determine the number of tree items (aria-setsize) for the position in the set (aria-posinset), and potentially the tree depth (aria-level) from the DOM. In these situations you will need to provide these WAI-ARIA properties.
-
Review widget to ensure that you have not hard coded sizes
The ability for applications to respond to system font settings is a requirement. Most user agents are designed to meet this requirement. This also means your Web application running within your browser is impacted when the user agent changes the font sizes to meet the need. If you have hard coded your font size in pixels an increase in system fonts will not be reflected in your Web application. You must also not hard code the size of your widgets in pixels either. If the fonts are scalable, but the widget they are encapsulated in is not, then the text could flow outside your widget.
Follow these rules to allow your application to respond to system font settings:
- Establish a base set of font sizes used in widgets based on percentage of the container element font size.
- Use CSS width, borders, margin, padding, background, and positioning properties to specify the graphical rendering of widgets and their sub-components, use percentage units or em units to specify widths of widget components (An em is a the font unit of measure between the top and bottom of an upper case letter M.). Border widths, padding, and margins can use PX units.
- Use scripting for run time CSS positioning of widget sub-components in relation to other sub components.
- Make sure all widgets use consistent height and width units of measure.
Percentages are the most reliable way to consistently specify proportional text sizes in widgets. The use of percentages and em should be used for specifying widths of a widget and the widget sub components. The use of percentages for text size and percentages and em units for widths support browser zoom capabilities to make widgets larger or smaller.
Pixels can be used for specifying line widths, padding and margins.
Important: Most browsers today have a zoom feature which allow the user to magnify the entire Web page. Most legislation today requires that your application respond to system font and color settings and therefore you will want to consider the fact the system settings could adversely affect your Web page should you decide to hard code pixel sizes.
- Test with User agent, Assistive Technology, and People with disabilities
To ensure you have set your WAI-ARIA semantics correctly, test your application with your user agent, an assistive technology, and a person with disability. Example assistive technologies are screen readers and screen magnifiers. Ensure that your user agent is designed to support WAI-ARIA and their your assistive technology is designed to support WAI-ARIA in the selected user agent.
Finding people with disabilities to do testing may be difficult but many companies employ people with disabilities, including your customers, and you should reach out to them to ask for help. Other places to look are advocacy groups like the National Federation of the Blind or your local schools for the blind, reading and learning centers, and so on. The people you reach out to may someday need to use what you produce.