Web Accessibility Issues

Web Accessibility Issues

The main accessibility concern for the Dojo Toolkit is the widget set.The widgets need to be usable by all users in order to create accessible applications using Dojo.The main issues are with color, device independent interactions and providing semantic information about these user interface (UI) components.

Many widgets were initially implemented with support only for mouse interactions and need keyboard support added.In order to create high performance, easily styled and visually appealing widgets, the toolkit makes use of CSS to create a desktop-like look and feel.These widgets may not work when CSS is turned off.

Color/CSS

There are several issues with color.Some people have vision problems which prevent them from seeing certain colors or may need a high contrast between foreground and background colors. These people may adjust the operating system colors to meet their needs or use the high contrast settings provided by the operating system.In some cases, when a person can not distinguish the colors in an image, he may turn off images in the browser and rely on the description of the image provided via a text alternative. In HTML the text alternative is provided via the alt attribute of the img element.

In order to create high performance, easily styled and visually appealing widgets, the toolkit makes use of CSS to create a desktop-like look and feel.These widgets may not work in high contrast mode.Selecting high contrast mode in the Windows operating system forces all color and image related CSS information to be turned off in the browser.All positioning information is retained but the colors and background images are turned off.Dojo Widgets that create the visual effects using CSS background-images will not be visible in high contrast mode.In order to accommodate high contrast mode, the widgets need to use real img elements to create the visual look. Images are still displayed when high contrast mode is enabled.However, some users still may not be able to distinguish the image due to the colors used. These users may also disable images in the browser and rely on the text alternative to provide the necessary information.

More info about High Contrast Mode and Widgets

Device Independent Interactions

Not all users are able to interact with the computer using a mouse, thus, device independent interaction is important.This means that, at a minimum, keyboard interactions must be supported.The Dojo widgets must not work solely via the mouse.For HTML links and form controls, the keyboard is automatically supported. But, since Dojo is creating custom widgets via DHTML and scripting of elements other than links and form controls, keyboard event handling must be added.Dojo widgets created using technologies other than HTML such as SVG, must also support the keyboard or provide an alternative interface that works with the keyboard.

Detailed information about role and state

Accessibility application programming interfaces (APIs) for desktop graphical user interface (GUI) frameworks define a standard contract between an application component and an assistive technology (AT). The information about the type of component and its current state is provided to the AT via the accessibility programming interface. Examples of accessibility APIs are Java Accessibility API , Microsoft Active Accessibility (MSAA), Apple Accessibility for COCOA, and the Gnome Accessibility Toolkit (ATK). In the browser environment, certain HTML elements have well defined roles and states. Examples include lists, links and form elements. The browser communicates the information about these elements and the current state such as checked, unchecked, readonly, disabled, visited, etc. to assistive technology via the accessibility APIs. Now that user interface components are being created via scripted HTML elements such as div and span, the assistive technology needs additional information about the created component and its behaviors.

The W3C Web Accessibility Initiative Accessible Rich Internet Applications (WAI-ARIA) Roadmap provides specifications which describe how to provide this additional information to the assistive technology.These specifications define a set of roles and states which can be added to the created DHTML user interface components.With the addition of this information and support by the browser and assistive technology, a user of AT can get detailed information about the user interface components create for the Web.For example, a tree component will be identified as a tree and each tree item, its level in the tree, expanded and collapsed state and number of children is now available to a screen reader user.The current ARIA specifications are supported in Firefox 1.5 and later versions as well as the by recent versions of the Window-Eyes and JAWS screen readers. Support from other Windows browsers and assistive technology vendors are expected in the future.To provide the most comprehensible accessibility solution for Dojo, the ARIA techniques are being applied to the widgets.

Dojo Accessibility Strategy

Dojo Accessibility Strategy

Support High Contrast /Images Off

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 separate a11y versions of the widgets will not be necessary. This documentation will be updated when the strategy for creating multiple themes is in place. -Becky

Customizing the Dojo Widgets look and feel is very important, as is performance. The Dojo team uses background images in the creation of the widgets because it allows the look and feel of the widgets to be easily customized by modifying the CSS.In addition, using CSS allows several images to be combined into one file and then the proper subset of the image to displayed using positioning. Thus all of the images for a particular widget element can be retrieved via one HTTP request rather than a separate request for each separate image file.For these reasons, Dojo did not want to require the use of image elements when creating widgets. This presents a problem for users with high contrast mode settings because in this mode, background images are not displayed. The solution is to create an accessible version of each widget which will work in high contrast mode.

The accessible version of each widget will be derived from the original widget.Then, only the necessary methods need to be overridden and the general functionality of the widget is maintained. Dojo already has a mechanism to load a particular widget class based on the technology in use so this has been extended to accessible widgets as well. When high contrast or images mode is detected, the accessible version of a widget will be loaded if it exists.

The accessible version of a widget may use HTML img elements to replace the CSS background images used in the widget, or in some cases, it may fall back to the HTML default version of the control.The checkbox widget uses CSS background widgets to create a graphical look and feel for the Dojo checkbox.Since that graphical look and feel and coloring will be lost in high contrast mode, the solution for the checkbox is to fall back to the default HTML input type=checkbox element in high contrast or images off mode.The dojo.widget.checkbox.a11y class is defined within checkbox.js and is a subclass of dojo.widget.checkbox. It overrides only the necessary methods to implement the accessible version of the checkbox.

The TabContainer widget uses background images to create the close icon on tabs that can be closed.Since there is no HTML alternative for the TabContainer, the accessible version uses img elements in place of the CSS background images.The TabContainer widget uses a TabButton widget to create the tabs.A dojo.widget.a11y.TabButton widget creates the tabs using an img element rather than a background image.The img element will display when the system is in high contrast mode. There is still a possibility that the user may not be able to discern the colors in the close image and will turn images off.With images turned off, the alt attribute of the image element will display and allow the user to properly interpret and interact with the tab.

The main functionality of the TabContainer is maintained in that module.The section of the TabContainer that needs modification to support high contrast and images off mode, the tabs, have been separated out into a separate widget.Thus the minimal adjustments needed to support high contrast and images off mode accessibility are provided in the helper a11y.TabButton class.

Support Device Independent Interaction

One way of providing keyboard support in HTML is to use form and list elements which can accept keyboard focus by default.The user can use the tab key to navigate to these types of elements.The problem is that building sophisticated widgets using these elements in not practical. And, navigating via only the tab key can be very tedious.The solution is to provide full keyboard support within the widgets using additional keystrokes such as the arrow keys to provide more intuitive navigation.

One of the keys to supporting the keyboard is to allow focus to be set to any element.The tabindex attribute can be used to include additional elements in the tab order and to set programmatic focus to them.This was a feature implemented in Internet Explorer that has been extended to Firefox and Mozilla.The following table outlines the use of the tabindex attribute:

Tabindex Attribute Value	Focusable via mouse or scripting via element.focus()	Tab Navigation
not present	Follow default behavior of element (only form controls and anchors receive focus)	Follows default behavior of element
zero - tabindex="0"	Yes	In tab order relative to element's position in document
positive - tabindex="x" (where x is a positive integer between 1 and 32768)	Yes	tabindex value directly specifies where this element is positioned in the tab order
negative - tabindex="-1"	Yes	Not in tab order, author must focus it with element.focus() as result of a key press.

Adding a tabindex of -1 to an element allows the element to receive focus via JavaScript using the element.focus() method.This is used to allow arrow key navigation to elements.Each element that can be navigated to via arrow keys must have a tabindex of -1 to allow it to receive focus.A keydown event handler can determine the next object to receive focus and call that element's focus() method.In addition, the style of the element may need to be updated in order to show the focus as brower's are inconsistent in displaying focus for items that receive focus programmatically.

In order to assist with key event handling, an onkey event has been added to Dojo to normalize key events. The appropriate key event, either onkeydown or onkeypress, will be used depending upon the browser.The key codes have been normalized as well. See dojo.event.browser class in dojo.event.browser.js.

Device Independent behavior means more than just supporting the keyboard. Where ever possible use the most generic event handler possible. For example, consider a widget where the down arrow key selects an element in the widget.The selection needs to be distinguished with a specific style.Rather than modifying the style of the element when processing the down arrow key event , focus the item from the down arrow key event handler and change the style via a focus event handler. This way, if focus is set from a means other than the keyboard such as a voice input system, the styling is properly set and does not depend solely on keyboard actions.

When implementing keyboard navigation, the ideal solution is to mimic the behavior of the operating system..For example, the right and left arrow keys are used to expand and collapse nodes in a Windows tree control and the up and down arrow keys move between nodes in the control.Unfortunately it is not always possible to mimic the operating system or browser behavior because the widgets may not be able to capture the necessary keys. A group of industry representatives are working to create a style guide to describe the navigation and behaviors of Web widgets. When completed, this Style Guide will be provided to open source and Dojo plans to implement the recommendations.The Style Guide will attempt to normalize the differences between operating systems and provide a generalized solution for Web components

Implement ARIA Specification

ARIA techniques allow creating sophisticated UI components using scripting which can be identified to assistive technology. In the future, user agents can also make use of this information to provide additional visual clues about components as well. For example, client side validation of a text entry component that was marked using the ARIA invalid attribute could be visually identified by the browser rather than requiring the developer to provide a specific style or text identification on the component.



The ARIA information will be added into the base widget modules rather than the accessibility extension to insure that the ARIA information is updated whenever behavior changes are made to the widget. Methods have been added to Dojo to enable setting the ARIA information. The roles and states for a widget can be set via the widget template or within the widget scripting code. The details of these methods are discussed later in this document. In addition to providing the roles and states for each component, there are some architectural considerations as well. For components that represent a hierarchy, such as a tree or menu, it is important to identify parent and child relationships. For items where position or count are important it may be necessary to hierarchically group elements or identify a set of related elements as a group. In some cases there are specific ARIA roles for grouping items such as treegroup for tree items within the same level. If no specific grouping role is provided the generic group role can be used.

Dojo Accessibility Resources

Dojo Accessibility Resources

a11y.js

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

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.

• 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 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:

• node – the DOM node on which to make the appropriate attribute api call
• ns – this selects the appropriate dom.widget.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).

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="">

Creating Accessible Widgets

Creating Accessible Widgets

Add device independent interaction

This is a fairly high level description of how to support device independent interaction. An understanding of general Dojo widget development and event handling within scripting and the Dojo Toolkit is assumed and not described.

Device Independent behavior means more than just supporting the keyboard. Where ever possible use the most generic event handler available. For example, consider a widget where the down arrow key selects an element in the widget. The selection needs to be distinguished with a specific style. Rather than modifying the style of the element when processing the down arrow key event, focus the item from the down arrow key event handler and change the style via a focus event handler. This way, if focus is set from a means other than the keyboard such as a voice input system, the styling is properly set and does not depend solely on keyboard actions.

Determining Key Behavior

When implementing keyboard navigation, the ideal solution is to mimic the behavior of the operating system. For example, the right and left arrow keys are used to expand and collapse nodes in a Windows tree control and the up and down arrow keys move between nodes in the control. Unfortunately it is not always possible to mimic the operating system or browser behavior because the widgets may not be able to capture the necessary keys. A group of industry representatives are working to create a style guide to describe the navigation and behaviors of Web widgets. When completed, this Style Guide will be provided to open source and Dojo plans to implement the recommendations. The Style Guide will attempt to normalize the differences between operating systems and provide a generalized solution for Web components

Within all widgets interaction with both the keyboard and the mouse is important. Users may switch between using the mouse and using the keyboard at any time. A widget author can not assume only keyboard or only mouse interaction. Thus, the widget component will generally need to store information about the current item with focus.

This can also be useful when the keyboard event handler is placed on an owning object in the component hierarchy rather than the actual element generating the event, for example on the table element rather than on each td element. Even though the event handler provides information on exactly what element generated the event, it is often necessary or easier to use the stored point of reference

In order to support both the mouse and the keyboard a component will usually have both onclick and onkey events. The onclick handler must include steps to update the point of regard so that any keyboard actions after the onclick will continue to work. In addition, the point of regard is often needed in order to update the style on the element losing focus before updating the new item irregardless or whether the mouse or the keyboard generated the event that results in a focus change.

Trapping Key Events

When implementing keyboard navigation, first determine where in the hierarchy to trap the key events. It is generally best to trap the key events at as high a level as possible and use the event object to determine that actual source of the event and perform the necessary action. This method prevents having to add a key handler to each individual element thus conserving the amount of markup to be generated. However, there may be cases where the event needs to be trapped at the level of each individual element. The actual source of the event is needed in order to determine how to process the keystroke received.

Once the component handles an event, it will usually stop that event from being propagated to other elements. For example, if the down arrow key is captured and moves focus to the next item in a tree control, the event should not propagate up to the browser where it might be interpreted as a command to scroll the page. Use the dojo.event.browser.stopEvent(event) method to stop the event.

In order to assist with key event handling, an onkey event has been added to Dojo to normalize key events. The appropriate key event, either onkeydown or onkeypress, will be used depending upon the browser. The key codes have been normalized as well. See dojo.event.browser class in dojo.event.browser.js.

Add the dojo onKey event into the widget template or via scripting using one of the dojo event connection apis.

Example using dojo.event.connect to connect the object represented by the node variable to the onKey handler function in the current object:

dojo.event.connect(node, "onkey", this, "onKey");

Example from tab container template to demonstrate adding the onkey handler and waiRole within the template:

<div id="${this.widgetId}" class="dojoTabContainer">
    <div dojoAttachPoint="tablistNode"></div>
    <div class="dojoTabPaneWrapper" dojoAttachPoint="containerNode"  
dojoAttachEvent="onKey" waiRole="tabpanel"></div>
</div>

Tabindex and Focus

When navigating via the keyboard is it essential that the element that is navigated to receives focus. The focus should NOT be simulated via CSS - call the focus() method on the element. Styling can be used to enhance the visual focus or selection but should not replace actually setting focus on an element. A screen reader will only speak information about the element when it receives focus. Screen magnifiers rely on focus to move the zoomed viewport on the screen.

Use the tabindex value to provide direct or programmatic keyboard focus to an element. The tabindex attribute can be used to include additional elements in the tab order and to set programmatic focus to them.This was a feature implemented in Internet Explorer that has been extended to Firefox and Mozilla.The following table outlines the use of the tabindex attribute:

Tabindex Attribute Value	Focusable via mouse or scripting via element.focus()	Tab Navigation
not present	Follow default behavior of element (only form controls and anchors receive focus)	Follows default behavior of element
zero - tabindex="0"	Yes	In tab order relative to element's position in document
positive - tabindex="x" (where x is a positive integer between 1 and 32768)	Yes	tabindex value directly specifies where this element is positioned in the tab order
negative - tabindex="-1"	Yes	Not in tab order, author must focus it with element.focus() as result of a key press.

When adding support for keyboard navigation, consider the widget as a component. The tab key can be used to navigate from component to component on a page and then the arrow and other keys should be used to navigate within the component. Only one element in a given component should have a tabindex equal to zero at any one time. This allows the user to navigate into and set focus within in the component using the tab key. Then, trap the onkey events and use the arrow keys to navigate within the elements of the component. All of the elements within the component which can receive focus must have a tabindex equal to -1. When an element is programmatically given focus, its tabindex value is changed from -1 to 0 and the tabindex of the previous element with focus will be changed from 0 to -1. This will insure that only one element within the component is in the tab order of the page and that the element with tabindex = 0 is the most recently focused element in the component. For example, when creating a tree control, each tree item is represented by an element. The first tree item in the control will be given a tabindex of 0. All of the other elements which represent tree items and can receive focus programmatically will have a tabindex value of -1. An onkey handler will trap the keyboard events for the tree control. When a tree item element is given focus via element.focus(), the element’s tabindex will be changed from -1 to 0. and it will be put into the tab order. Now if the user moves focus out of the tree control (either via a mouse click or by tabbing to the next component on the page), when the user sets focus back into the tree control using the tab key, the last focused tree item, which was given a tabindex of 0, will receive focus.

Add ARIA information

The Accessible Rich Internet Applications Roadmap is being developed by the W3C Web Accessibility Initiative (WAI) Protocols and Formats working group. The group is creating specifications for role and state information which can be added to markup to provide semantic information about user interface components.The browsers will translate this role and state information into the accessibility api for the platform in use.Currently Firefox 1.5 and later supports this additional semantic information on the Windows platform where it converts the information into the Microsoft Active Accessibility (MSAA) api.When recent versions of the Window-Eyes and JAWS screen readers are used with Firefox, this additional information is spoken to the user.

Some HTML elements such as links and form elements have well defined roles and behaviors. Interactive controls created from generic elements can now also be identified with roles and states.When an element receives focus the role and state information provided by the developer will be made available to assistive technologies. For example, as a screen reader traverses through a Dojo Tree control using the arrow keys, as each tree item receives focus the title of the tree item will be spoken as well as its expanded or collapsed state if it has children. Likewise, a Dojo checkbox created using <div>and <pan> tags can be identified as a checkbox and its checked or unchecked state can be reported. When creating a new Dojo widget, the role of the widget must be identifed and the state of the widget must be set and updated as it changes.

As of January, 2007, the ARIA specifications are still under development; however a significant portion of the specification has been implemented in Firefox 1.5 and 2.0.

The public drafts of the specifications can be found at http://www.w3.org/wai/pf.

• Roles for Accessible Rich Internet Applications (ARIA Roles) In addition to the listing of roles, this includes valuable information and examples for creating accessible components.
• States and Properties Module for Accessible Rich Internet Applications (ARIA States and Properties)

Accessible DHML in the Mozilla Developer Center provides additional information about using the ARIA specifications and includes a table of roles and states supported in current versions of Firefox.

Assigning Roles

Use the tabindex to provide keyboard focus or to allow programmatic focus to an object. By adding a tabindex to an element, the element will now be included in the accessibility hierarchy of the Firefox browser.Information about elements in the accessibility hierarchy will be provided to assistive technologies. If you use a tabindex attribute on a DIV, SPAN, IMG or any element which has no natural role of its own then you need to provide a role. Any element that can receive focus must have a role, either implied, such as input elements and anchors, or specified via a role attribute. For things with an implied role such as input fields and anchors, you can use tabindex=-1 to remove them from the tab order. You can also specify a different role for elements which already have an implied role.

The role and states are added to Dojo widgets within the widget template or via the dojo.widget.wai APIs as described in the Dojo Accessibility Strategy section.

Providing Hierarchical Information

In order for Firefox to determine the correct parent child relationships between objects, and to communicate this via an accessibility API to assistive technologies, it is best to create components in a hierarchical fashion. For example, when creating a menubar it is best to have the components that make up the menus and menuitems of the menubar be children of the menubar. Likewise, menuitems should be children of the owning menus. This hierarchy allows Firefox to provide menu information to the assistive technologies, and for a screen reader to speak more information about the menu such as, menu open, File, item 1 of X when the user opens a menu. Here is a simple pseudo code example demonstrating a hierarchical layout of elements for a menu control. This exmaple only shows the addition of role attributes and does not represent a complete menu widget.(Note: Attributes are not quoted in pseudo-code examples to help improve the readability):

<div role=menubar>
 <div role=menuitem>A</div>
  <div role=menu><divole=menuitem>A.1</div>
    <div role=menuitem<A.2</div>
  </div>
  <div role=menuitem>B</div>
  <div role=menu>           
    <div role=menuitem>B.2</div>                
    <div role=menuitem>B.2.1</div>  </div>
</div>

It may not always be practical to create items via HTML in a hierarchical fashion. In that case the group role can help to associate the items properly. This is illustrated in the following simple pseudo code example of a tree hierarchy.

<div role=tree >
  <div role=treeitem>Top>/div>
  <div role=group>
     <div role=treeitem>1>div>
     <div role=group>
       <div role=treeitem>1.1 </div>
       <div role=treeitem<1.2>/div>
       <div role=treeitem>1.3</div>
       <div role=group>
         <div role=treeitem>1.3.1<div>
         <div role=treeitem>1.3.2>/div>
         <div role=treeitem>1.3.3</div>
         <div role=treeitem>1.3.4</div>
       </div>
       <div role=treeitem>1.4</div>
     </div>
     <div role=treeitem>2>/div>
     <div role=treeitem>3</div>
     <div role=group>
       <div role=treeitem>3.1</div>
       <div role=treeitem>3.2</div>
     >/div>
  </div>
</div>

The tree items at the same level in the hierarchy are grouped together within a DIV element identified with role=group. With this organization, the assistive technologies can be provided with the information about what level and item number a particular treeitem represents. For example, in the above tree example, with focus on item 1.3.3 a screen reader might speak, "one dot three dot three item three of four, level four" or something similar.

Other items included in the hierarchy may not be essential to the component. These items can be marked with a role of presentation to eliminate them from consideration when determining information about the component.

Using the Presentation Role

While it is preferable to use CSS for layout, tables are still used to quickly and easily arrange elements on a page. This is especially true of existing widgets which were originally created to work in older browsers. Putting information in tables can easily confuse the hierarchy of the component. If tables must be used, they can be marked with a role of presentation to eliminate them from the hierarchy. Here is a pseudo code example where the presentation role was used on tables within a tree component:

<div role=tree>
  <table role=presentation>           
    <tr><td><div role=treeitem>Top</div>&;lt;/tdgt;</tr>
  </table>
  <div role=group>
    <table role=presentation>
      <tr><td><span role=treeitem>1</span></td></tr>
    </table>
    <div role=group>
      <table role=presentation>
        <tr><td><span role=treeitem>1.1</span&;gt;</td></tr>
      </table>
      <table role=presentation>
        <tr><td><span role=treeitem>1.2</span></td></tr>
      </table>
    </div>
    <table role=presentation>
      <tr><td><span role=treeitem>2</span></td></tr>
    </table>
  </div>
</div>

Since the table is only used for layout it is identified with a role of presentation to remove if from the accessibility hierarchy so that information about the table is not provided to assistive technology.

Other elements may need to be removed from the accessibility hierarchy as well. For example, when creating a DHTML checkbox, an image may be contained within a span element that is marked with a role of checkbox and an appropriate state of checked equals true or false. The image which represents the checkbox is contained within the span and should not contain any alt text since the role and state are managed by the surrounding span. Images are considered important elements and are normally included with the accessibility hierarchy of the browser. In order to ignore this image in the accessibility hierarchy, it is marked with a role of presentation:

Assigning States

In addition to identifying the role of a widget, the state of the widget must be identified and updated. The initial state can be set within the widget template or via scripting when the widget is created. As the state changes during user interaction with the widget, the state must be updated using the dijit.util.wai apis:

dijit.util.wai.setAttr(/*DomNode*/node, /*String*/ ns, /*String*/ attr, 
/*String|Boolean*/value)
dijit.util.wai.getAttr(/*DomNode*/ node, /*String*/ ns, /*String|Boolean*/ attr)
dijit.util.wai.removeAttr(/*DomNode*/ node, /*String*/ ns, /*String|Boolean*/ attr)

The ns value passed into these function is either "waiState" or "waiRole". The dijit.util.wai functions above are wrappers to the DOM apis to set, get and remove attributes. In browsers where namespaces are supported the setAttributeNS, getAttributeNS, and removeAttributeNS, apis are called. In other browsers the setAttribute, getAttribute and removeAttribute apis are called and the namespace is simulated. The namespace information is stored in the dijit.util.wai class.



It is important to update the state information as it changes so assistive technology users can be made aware of the change. For example, when a treeitem is expanded, the state for the element that has been assigned role=treeitem, must be set to expanded=true. Likewise, when a treeitem is collapsed, the state for the element with the role=treeitem must be updated to expanded=false. Be aware that some of the boolean states imply more than just a dual state. For the state attributes checked, selected and expanded a value of false indicates that the widget is capable of being checked, selected or expanded while no attribute indicates that the element is not capable of that state. For example, a tree node with children will have either a state of expanded=true or expanded=false depending upon whether the child nodes are visible or not. An end node, with no children will have no expanded state value set.



Generally only items which have a role can have a state value. The role may be explicitly set by the author such as a treeitem or may be implicitly defined such as a form element or link. Items which have been added into the accessibility hierarchy via a tabindex attribute may also have states such as desribedby or labelled by.

Create a11y subclass to support high contrast / images off mode

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 separate a11y versions of the widgets will not be necessary. For now, when creating new widgets do NOT use CSS backgound images to convey information - use real img elements. This documentation will be updated when the strategy for creating multiple themes is in place. -Becky

All widgets must be visible and work when the operating system is set to high contrast mode. In this mode, colors and background images set via CSS are turned off. The CSS positioning attributes are still used but any color information is overridden by the colors selected for high contrast mode. The most common high contrast modes are black on white or white on black but any color combination can be set by the user. In addition to high contrast mode, the widgets should generally be usable with the display of images turned off in the browser. When images are turned off, the alt attribute for any images in the widget should provide the same information. There may be cases, such as an analog clock, where the alt attribute information can not substitute for the actual image. In these cases there should be an alternative method of obtaining the same information. In the case of an analog clock, a text display of the time would be appropriate, since it conveys that same information, the current time.

To avoid problems with high contrast mode it is best to create HTML widgets using the img element rather than relying on CSS background images. Since the use of img elements can have a negative affect on performance, many developers prefer to use background images even though they do not display in high contrast mode. In this case, an accessible version of the widget must be created that will work in high contrast mode.

The widget author must create an additional widget that derives from the original widget to support accessibility. This widget will be named with the a11y prefix. If the original widget name is dojo.widget.MyCoolWidget, the accessible version will be named, dojo.widget.a11y.MyCoolWidget. When using namespaces other than dojo, the same naming convention must be followed of appending a11y to the actual widget name. For example, the accessible version of mynamespace.MyCoolWidget becomes mynamespace.a11y.MyCoolWidget. The preferred location for this new class is within the same file as the original widget. This will make it easier to keep the two files in sync. Although, the reason for extending the original widget class to create the accessible version is to reduce the need to make changes in two places. The majority of the behavior and logic for the widget should remain in the original class. All of the keyboard support and role and state information belong in the original widget. The only modifications for the accessible version should be to support high contrast and images off mode.

The appropriate version of the widget will be loaded and used based on a check for accessibility that is performed in dojo.widget.buildWidgetFromParseTree():

// test for accessibility mode

dojo.a11y.setAccessibleMode();

If a check has not already been performed, dojo.a11y.setAccessibleMode will test to determine if high contrast mode is set or images are turned off in the browser. This test is only performed once and the results cached to improve performance. When images are turned off or high contrast mode is enabled, the dojo.a11y.accessible variable is set to true. In addition, the a11y prefix is added to the beginning of the dojo.render.html.prefixes array. This will cause dojo to load the a11y version of a widget if it exists rather than the default version. This is the same mechanism that is used to load an svg version of a widget if the browser supports svg and an svg version of the widget exists.

If the Dojo widget has an HTML equivalent, such button or checkbox, the accessible version can use the basic HTML type. This strategy will likely involving creating a new template for the accessible version of the widget. The new template name should include "a11" in the name to distinguish it from the standard template. For example the templates for the checkbox widget are named Checkbox.html and CheckboxA11y.html. The accessible version of the widget will refer to the accessible template via the templatePath variable.

If there is not an equivalent HTML element, the accessible version of the widget can replace the use of CSS background images with img elements. When using image elements the look and feel of the widget can not easily be changed since changes to the image source are likely to occur within the scripting code and can no longer be changed via style sheets. Since the purpose of the accessible widget is to support high contrast mode and high contrast mode does not support a color theme, the image set used is not critical. Certainly, there are some high contrast uses who may not be able to interpret the images due to the colors used within the images. But, there is no universal color scheme that can be used in the images that will suit all users. Users which can not interpret the images due to color or size will turn the images off and use the alt text. Thus, it is essential that alternative text is provided for all images using the alt attribute of the img elements.

Testing Widgets for Accessibility

Currently the Windows operating system provides the most resources and functionality for testing for accessibility in more than one browser.Also, the majority of assistive technologies run under the Windows operating system.Test with both Firefox and Internet Explorer on at least the Windows operating system to assure at least a minimal level of accessibility.

Test for full keyboard support

All widgets must be tested for use with the keyboard only.The most stringent way to test for keyboard support is to remove the mouse from the system and interact with the widget. This assures that only the keyboard can be used for navigation and interaction. Test that all functionality of the widget can be accomplished using the keyboard only.The functionality does not necessarily have to be performed in exactly the same manner as with the mouse. For example, it is preferred that a slider can be adjusted by dragging with the mouse or focusing the slider and adjusting the value using the arrow keys or plus and minus characters on the keyboard. But if the value and position of a slider can be adjusted by entering a new value in an associated text field, the slider is keyboard accessible.Drag and drop operations are another example of behavior which may need to be supported via an alternative mechanism such as a menu bar or context menu.

After determining that the widget is accessible using only the keyboard, test using both the keyboard and the mouse.There is no guarantee that a user will interact only using the keyboard or only using the mouse.Make certain that both types of interaction can be used within the widget and that the focus and styles are updated appropriately.

Since not all browsers support adding the tabindex to elements to make them focusable and thus keyboard accessible, it may not be possible to provide full keyboard support in all instances.As of January 2007, Opera and Safari do not support adding tabindex to additional elements.

Resources for Navigating via the keyboard

• Mozilla Keyboard Planning FAQ and Cross Reference
• Common keyboard shortcuts in Firefox, and the equivalents in Internet Explorer and Opera
• Windows Keyboard Interface Summary
• Keyboard Shortcuts for Internet Explorer 6
• The Keyboard Lover's Guide to IE7
• Use Opera without a Mouse

Test for focus and role and state

It is important that when an element is clicked on with the mouse or navigated to via the keyboard that the element receives actual focus.Focus must not be simulated via styles since assistive technology relies on the focus event to inform the user about the element and the role and state.Focus can be visually tested since browsers will indicate focus, however the focus border may be difficult to see or have been modified with a different style.

Testing using Microsoft Inspect Objects

The Microsoft Inspect Objects application from the Microsoft Active Accessibility SDK can be used on Windows to test for focus and also to verify the correct ARIA role and state has been set on the element. Test using Firefox version 1.5 or later since Firefox has the most comprehensive support for the ARIA role and state information.

Download Inspect32 from Active Accessibility 2.0 SDK Tools.Basic information on using the tool is provided at Using Inspect Objects.

Run Inspect Objects and test the widget for focus and role and state information. Turn on Highlight Focus tracking via the Inspect Objects Options menu. This mode will display a yellow rectangle around the currently focused element.Use this rectangle to verify that the expected element is actually receiving focus. The Show Information Tooltip option may also be helpful.As you set focus to an item, Inspect Objects will display information about the role and state of the object.You can verify that the object receives focus and that the role and state information is as expected.

Figure 1 is a picture of the Dojo checkbox with Inspect Objects running and the Show Information Tooltip and Turn On Highlight Focus options set.With focus on a checked Dojo checkbox, note the focus rectangle and role and state information displayed within the tooltip. The role is "checkbox" and the state is "focused, checked, marqueed, focusable". This verifies that the role of checkbox has been properly set in the Dojo checkbox code. The state information verifies that the element is focused and the checked state is set. With focus on an unchecked checkbox the state would display, "focused, marqueed, focusable", since the checked state is not set. Note that when the state of an element changes, focus must be removed from the element and then returned in order for Inspect Objects to update the information. Or, rather than change focus use the Inspect Objects Action Refresh command to update the information about the currently focused object.

Figure 1

Testing using a screen reader

For best results, testing with a screen reader is recommended. This section provides a brief introduction to using screen readers. Currently Window-Eyes 5.5 and JAWS 7.10 or later versions of both running with Firefox 1.5 or later will recognize ARIA role and state information. Unfortunately it takes some time and experience to become proficient using a screen reader and these programs are expensive. There are demo versions available which will run for a limited amount of time (usually 30 minutes) before a reboot of the system is required). But, note that often the demo versions are not to be used for commercial purposes.

When testing with a screen reader be careful not to use the mouse when navigating through the widget. Often a tester will miss problems with keyboard navigation or focus by using the mouse to initiate or force interaction within a widget. Not all screen reader users are blind – some may have low vision or use the screen reader to assist with cognitive disabilities, but, in order to catch all problems it is important to interact with the widget in the same manner as someone with no vision.

Screen readers work by storing the contents of the entire page into a virtual buffer. The user can move through this buffer and have the contents spoken by the screen reader. There are many mechanisms to move through the virtual buffer, by character, word, line, or from object to object. Both JAWS and Window-Eyes have different terminology for this buffer.Window-Eyes refers to it as "browse mode" and JAWS as "forms mode&quo; or via the navigation mode, "virtual PC cursor on/off". When interacting with a Web page, the screen reader can no longer rely on the virtual buffer. In Window-Eyes the user must turn browse mode off to interact with form elements and interactive widgets. In JAWS the user must enter forms mode on or virtual PC cursor mode off tointeract with form controls and interactive widgets.

When testing fully keyboard accessible Dojo widgets the screen readers must be in the "interactive mode" to announce the role and state of an element as the element receives focus. In Window-Eyes this is "browse mode off" which is toggled using the ctrl-shift-a keys.< In JAWS this is "forms mode on" which is turned on by pressing enter on a focusable element and is turned off by pressing the numpad plus key. You can also turn off the virtual PC cursor in JAWS. This setting is toggled via the ins–z key combination.

If the role and state information have been applied correctly the screen reader will hear information about the role and stated of widget elements as well as information about child objects.Figure 2 is a simple tree control with three main nodes with titles Node1 , Node 2, and Node 3. Node 1 has no children. Node 2 is expanded and has two childe nodes titled Node 2.1 and Node 2.2. Node 3 has children but is not expanded. Here is a brief example of what is spoken by Window-Eyes with focus on the Node 2 tree item within the tree control displayed in figure 2, "Node 2 expanded two items, 2 of 3"

Figure 2

The user knows which node currently has focus, Node 2; that the state of the node is expanded, it has two children and that Node 2 is the second node in a group of three nodes at the same level in the tree hierarchy. This type of information is critical for screen reader users to interact and navigate with complex widgets. The title of the Node is spoken when it receives focus. Because the tree control developer has properly set the state of Node 2 to expanded=true, that information is spoken by the screen reader. All of the nodes in the tree control have been properly organized into hierarchies and identified using the role="group" so the browser is able to provide the screen reader with information about the number of children and the position of the current node within its siblings.

When testing widgets with a screen reader interact with each element and verify that the proper role and state and grouping information is spoken by the screen reader and all functionality is accessible via only the keyboard. In addition, make certain that elements which do not provide information to the screen reader user are marked with a role="presentation" so they are ignored. In Figure 2, each tree item node which has children is preceded by an image of a plus or minus to indicate the expanded state of the item. This plus or minus image can not receive focus and it does not need focus since the keyboard user can expand and collapse the tree item using the arrow keys and the screen reader will speak the expanded or collapsed information based on the state value.

See the videos linked from Adventures in Accessibility - What is a screen reader? for more in depth information about screen readers.

Test for high contrast mode support

Windows comes configured with default high contrast mode settings. Turn on high contrast mode in Windows XP via the Accessibility Options dialog available from the Control Panel. From the Diplay panel check the high contrast checkbox. Press the settings button to modify the display colors and font sizes. Checking the Use shortcut checkbox from the settings dialog allows toggling high contrast mode on and off using the shift-alt-printscreen key combination. Press OK to confirm the settings and then OK again to close the dialog and turn on high contrast mode. Note, putting your system in high contrast mode will likely rearrange the desktop icons on the system due to the changes in font size.

After turning on high contrast mode, test the widget in Firefox or Internet Explorer. If the widget test page was already loaded in the browser, you may need to refresh the page for the high contrast mode to take affect. Verify that all components within the widget are visible. Any components or visual effects which are improperly created via background images or color will no longer be visible in high contrast mode. Verify that the user is able to determine where current focus is within the widget. If focus is not visually evident the widget developer may have used a background color change to indicate focus (or the browser provided focus rectangle may be hard to distinguish). Fix this by using a different styled border or other mechanism to indicate focus if the browser differentiation is not sufficient. When testing in high contrast mode it is fairly evident where the problems occur since any visual effects which rely on color or images will no longer be visible.

Test for usable operation with images off

In addition to testing for support of high contrast mode, the widgets should also work with images are turned off in the browser. Test in Firefox by turning images off via the Tools Options dialog. Note that only images loaded via http will no longer display. Changing this settig in Firefox does not prevent loading of images from the file system. Test in Internet Explorer by turning off images in the Advanced tab of the Tools Internet Options dialog.

With images turned off the widgets should still be usable. Since no images are loaded, bythe browser the alt attribute of the image elements will be displayed. Verify that the alt attribute provides sufficient information for the user to interact with the widget.