NOTE: As of February, 2007 the High contrast mode accessibility strategy has changed. Dojo will NOT be using background images to convey information. Since Dojo will use real img elements there is not a high contrast issue and high contrast detection may not be necessary. These a11y apis are very likely to change for the 0.9 release. This documentation will be updated with the final apis are determined and the changes to a11y.js have been completed. -Becky
The dojo.a11y module contains methods to detect high contrast mode and to instruct Dojo to load the accessible versions of widgets (when an accessible version exists).
dojo.a11y.accessible is a private variable that stores the current accessibility state. The value is initialized to null when the a11y module is instantiated. This is used to prevent running the accessibility test more than once during widget instantiation or to force a particular mode. A value of true indicates that accessible versions of the widgets will be loaded. A value of false indicates that the accessible version of widgets will not be loaded. The value of this variable is normally set after running the check for high contrast mode or images off but can also be forced via the dojo.a11y.setAccessible() api.
dojo.a11y.doAccessibleCheck determines whether or not the accessibility check is performed. The default value is true – the check for high contrast mode or images off will be performed for each page load. The dojo.a11y.setCheckAccessible() method is provided to set this variable to false and prevent the accessibility check from being performed. The ability to turn off the check is provided for applications that may provide a mechanism for the user to request the accessible mode for widgets.
dojo.a11y.testAccessible always performs the check for accessibility mode. The check is currently only made for the Internet Explorer and Mozilla browsers as others do not yet support high contrast mode or do not support it in a detectable manner. Additional work is required for operating systems other than Windows. The test is performed by creating a div and assigning it a background-image. A very small image is used for the background image so that the download time is short and performance is not greatly affected. In both IE and Firefox, checking the current / computed style of this div after it has been added to the Document Object Model (DOM) will reveal whether or not the background image is visible. Both browsers will return "none" as the computed value for the background-image when high contrast mode is turned on at the operating system level. In Firefox the value returned is "url(invalid-url:)" when images are turned on. Currently images off mode is not detected in IE but further research is being conducted to find a method for determining images off in IE that does not require waiting for the image's onload or onerror events to fire.
dojo.a11y.checkAccessible will perform the accessibility check if the check has not already been performed and testing for accessibility has not been turned off via dojo.a11y.setCheckAccessible(false).
dojo.a11y.setCheckAccessible provides a mechanism to turn off checking for high contrast mode or images off. A value of true turns on accessibility checking and a value of false turns checking off. Generally an application should not turn off checking for the need to display accessible versions of the widgets as a developer can never be certain that the audience does not contain people with disabilities who rely on accessibility accommodations. However, an application may provide another mechanism for the user to request the accessible versions of the widgets and set accessible mode via the dojo.a11y.setAccessible method. In this case the accessibility check would not be required.
dojo.a11y.setAccessibleMode is used to perform the check for accessibility if it has not yet been performed and based on the results set Dojo to load the accessible version of the widgets if necessary. This method is called from the dojo.widget.buildWidgetFromParseTree method. For performance reasons this method checks whether or not the accessibility mode has been set before making any additional calls to avoid performing the accessibility test for each widget.
dojo.a11y.setAccessible is used to force accessibiliy mode on or off and prevent a check for accessibility. It sets the value of dojo.a11y.accessible variable to the value of the boolean parameter passed into the setAccessible method. Passing in true will force accessible mode on and a value of false will force it off.
dom.widget.wainames encapsulates the type of ARIA information being provided, roles and states, which are represented via waiRole and waiState respectively. The wai prefix is used to represent the W3C Web Accessibility Initiative which is hosting the ARIA specification.
The dom.widget.wai module is provided to normalize setting the roles and states. The ARIA techniques are designed to be used with XHTML via namespaces. Since a content-type of application/xhtml+xml is required to fully support namespaces an alternate solution is needed for the most commonly supported content-type of text/html. The roles and states can be manipulated using the DOM namespace apis: getAttributeNS, setAttributeNS, and removeAttributeNS. In browsers which do not support the namespace apis, the generic attribute apis, getAttribute, setAttribute, removeAttribute, are used and namespaces are simulated.
The dom.widget.wai module provides the necessary mapping of namespace information and attribute apis for each of the dom.widget.wainames. It contains two submodules, waiRole and waiState, each with the following variables.
The dom.widget.wai methods getAttr(), setAttr(), and removeAttr() are wrappers to the appropriate attribute apis for the browser in use. These apis are called with the following parameters:
The following will set a role of treeitem onto a DOM node:
dijit.util.wai.setAttr(nodeObj, "waiRole", "role", "treeitem");
This example sets the state of the treeitem to expanded:
dijit.util.wai.setAttr(nodeObj, "waiState", "expanded","true");
The role and state can also be set via the widget template using the waiRole or waiState prefix. Setting the role in the template is that same as setting it via scripting – the dijit.util.wai.setAttr() method will be called during widget instantiation. Simply add the waiRole="actualrole" or waiState="state-value" parameters into the template markup for the element. The element will be passed as the nodeObj into the dijit.util.wai.setaAttr() method. The state is specified as a state name and value pair, the state is separated from the value using the hyphen character (-): state-value. The state becomes the attribute name when dijit.util.wai.setAttr() is called. This mechanism is useful when templates are used to create the objects requiring the role value or when the state is known at creation time.
Here is an example of setting the role in the tab container template. The containerNode is given the "tabpanel" role.
<div id="${this.widgetId}" class="dojoTabContainer">
<div dojoAttachPoint="tablistNode"></div>
<div class="dojoTabPaneWrapper" dojoAttachPoint="containerNode"
dojoAttachEvent="onKey" waiRole="tabpanel"></div>
</div>
The role or state can also be specified via variables. This example shows an excerpt from the slider template which sets the tabindex, role and state for the slider component. Note that currently only one waiRole and waiState value is allowed per element (trac #2163).
<div class="sliderMain" dojoAttachPoint="focusNode" waiRole="slider"
waiState="valuenow-${this.initialValue}" dojoAttachEvent="onmousedown:_setFocus;
onkey:_handleKeyEvents; onkeyup:_buttonReleased; onmouseup:_buttonReleased;
onmousewheel:_mouseWheeled;"
tabindex="0" cols=3 cellpadding=0 cellspacing=0 style="">