Login Register

Dojo Accessibility Resources

dijit._base.wai.js - 0.9 Version

Functions for dealing with accessibility are found in dijit._base.wai.js. The name of the file and object is derived from the W3C Web Accessibility Initiative which is hosting the ARIA specification. The dijit.wai APIs are used to manipulate ARIA roles and properties. In addition, the onload function to detect high contrast mode is part of dijit.wai.

The dijit.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 dijit.wai module provides the necessary mapping of namespace information and attribute apis for each of the dijit.waiNames. It contains two submodules, waiRole and waiState, each with the following variables.

  • name represents the ARIA type being set, waiRole or waiState.
  • namespace contains the actual namespace for the role or state information.
  • alias is the pseudo namespace to be used when true namespaces are not supported.
  • prefix will be added to the beginning of the value being set.

The dijit.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:

  • node – the DOM node on which to make the appropriate attribute api call
  • ns –this selects the appropriate dijit.wai module to use; waiRole or waiState.
  • attr – the attribute name. This will be “role” when setting a role value and it will be one of the possible ARIA state attributes when specifying a state.
  • value – the actual value to be set; either an ARIA role value (tree, treeitem, checkbox, tab, etc) or the value for the previously specified state name (true, false, mixed, etc).

dijit.wai.setAttr(/*DomNode*/node, /*String*/ ns, /*String*/ attr, /*String|Boolean*/value)
is used to set an ARIA role or state.

The following will set a role of treeitem onto a DOM node:
dijit.wai.setAttr( focusNode, “waiRole”, “role”, “treeitem”);
This example sets the state of the treeitem to expanded:
dijit.wai.setAttr( focusNode, “waiState”, “expanded”, “true);
There are also dijit.wai APIs to get or remove attribute values:
dijit.wai.getAttr(/*DomNode*/node, /*String*/ ns, /*String*/ attr, /*String|Boolean*/value);
dijit.wai.removeAttr(/*DomNode*/node, /*String*/ ns, /*String*/ attr, /*String|Boolean*/value);

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 the same as setting it via scripting – the dijit.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.wai.setAttr() 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.wai.setAttr() is called. Multiple states can be set within the template by separating the state-value pairs with a comma. This mechanism is useful when templates are used to create the objects requiring a role value and when the state is known at creation time.

Here is an example of setting the role in the diijt tree template. The domNode is given the “tree” role.

<div class="dijitTreeContainer" style="" waiRole="tree"
dojoAttachEvent="onclick:_onClick,onkeypress:_onKeyPress"
>
</div>
<div>The role or state can also be specified via variables. This example shows an excerpt from the dijit button template that sets the tabindex, role and state on the button element. </div>
<div class="dijit dijitLeft dijitInline dijitButton" baseClass="${baseClass}"
dojoAttachEvent="onclick:_onButtonClick,onmouseover:_onMouse,onmouseout:_onMouse,onmousedown:_onMouse">

  <div class='dijitRight'>
    <button class="dijitStretch dijitButtonNode dijitButtonContents" dojoAttachPoint="focusNode,titleNode"
     tabIndex="${tabIndex}" type="${type}" id="${id}" name="${name}" waiRole="button"
      waiState="labelledby-${id}_label">

      <div class="dijitInline ${iconClass}"></div>
        <span class="dijitButtonText" id="${id}_label" dojoAttachPoint="containerNode">${label}</span>
    </button>
  </div>
 </div>



dijit._base.wai.js - Updated for 1.0

Functions for dealing with accessibility are found in dijit._base.wai.js. The name of the file and object is derived from the W3C Web Accessibility Initiative which is hosting the ARIA specification. The dijit wai APIs are used to manipulate ARIA roles and properties. In addition, the onload function to detect high contrast mode is part of dijit.wai.

The dijit 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 can be set directly by prefixing the role value with "wairole". 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.

There are separate dijit methods for querying, getting, setting, and removing ARIA roles and states.


Roles

The following dijit methods will set the role onto an element. The role parameter must be one of the possible ARIA role values.

dijit.hasWaiRole(/*Element*/ elem)
is used to determine if a role has been set on the element.

dijit.getWaiRole(/*Element*/ elem)
is used to obtain a role that has been set on the element. It returns an empty string if no role has been set.

diijt.setWaiRole(/*Element*/ elem, /*String*/ role)
assigns an ARIA role to the element.

dijit.removeWaiRole(/*Element*/ elem)
removes the role attribute from the element.


States

These dijit methods set the state values onto an element and are wrappers to the appropriate attribute apis for the browser in use. The state parameter must be a valid ARIA state name and the value the appropriate value for the specified state.

dijit.hasWaiState(/*Element*/ elem, /*String*/ state)
is used to determine if a particular state has been set on the element.

dijit.getWaiState(/*Element*/ elem, /*String*/ state)
is used to obtain the value of a state that has been set on the element. It returns an empty string if the element has no value for the requested state.

diijt.setWaiState(/*Element*/ elem, /*String*/ state, /*String*/ value)
assigns an ARIA state and value to the element.

dijit.removeWaiState(/*Element*/ elem, /*String*/ state)
removes the role attribute from the element.


Examples of setting role and state:

The following will set a role of treeitem onto a DOM node:
dijit.setWaiRole( domNode, “treeitem”);
This example sets the state of the treeitem to expanded:
dijit.setWaiState( focusNode, “expanded”, “true);
This example removes the valuenow property from an indeterminate progress bar.
dijit.removeWaiState(internalProgress, "valuenow");

Setting Role and State in the Widget Template

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 the same as setting it via scripting – the dijit.setWaiRole() 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.setWaiRole() and dijit.setWaiState() methods. The state is specified as a state name and value pair, the state is separated from the value using the hyphen character (-): state-value. Multiple states can be set within the template by separating the state-value pairs with a comma. This mechanism is useful when templates are used to create the objects requiring a role value and when the state is known at creation time.

Here is an example of setting the role in the diijt tree template. The domNode is given the “tree” role.

<div class="dijitTreeContainer" style="" waiRole="tree"
dojoAttachEvent="onclick:_onClick,onkeypress:_onKeyPress"
>
</div>
<div>The role or state can also be specified via variables. This example shows an excerpt from the dijit button template that sets the role and state on the button element. </div>
<div class="dijit dijitLeft dijitInline dijitButton"
        dojoAttachEvent="onclick:_onButtonClick,onmouseenter:_onMouse,onmouseleave:_onMouse,onmousedown:_onMouse"
        >
<div class='dijitRight'
                >
<button class="dijitStretch dijitButtonNode dijitButtonContents" dojoAttachPoint="focusNode,titleNode"
                        type="${type}" waiRole="button" waiState="labelledby-${id}_label"
                        >
<span class="dijitInline ${iconClass}" dojoAttachPoint="iconNode"
                             >
<span class="dijitToggleButtonIconChar">&#10003</span
                        ></span
                        ><span class="dijitButtonText" id="${id}_label" dojoAttachPoint="containerNode">${label}</span
                ></button
        ></div
></div>