Web checklist

Scripting, including JavaScript and the standard version ECMAScript, enables Web developers to enhance sites with dynamic content, visual effects, user interaction, and client-side processing. Scripts can update HTML content and perform visual enhancements to a Web site. Scripts can respond to many types of manual and automatic events. Some of these events include: the loading of a Web page, the user selecting an item in a menu, and the submitting of a form. Due to the virtually limitless ability of scripts to affect most any content, discussing the techniques for making the use of JavaScript accessible is complex and sometimes challenging.

The general approach to making scripting accessible is to ensure the functionality of the scripts is accessible from the keyboard, and to ensure the information (content) is available to assistive technologies.

Scripts that provide both of these features are considered directly accessible. If one or both of the above cannot be achieved, then additional techniques are used to reduce the need for scripting, or to provide equivalent content that does not rely on script functionality. This checkpoint provides recommendations and techniques for accessible scripting.

Compliance with this checkpoint requires all of the following techniques be met. These techniques are defined in the WCAG 2.0 Level A Success Criterion for Guideline 2.1.1 (link resides outside of ibm.com).

1. Functions: Use both keyboard and other device-specific functions.

2. JavaScript actions: Make JavaScript actions keyboard accessible.

Examples for Script developers

1. Functions: Use both keyboard and other device-specific functions.

To comply with this technique, all of the following examples must be implemented.

Example 1

In the following example, the developer wants additional text to be displayed when a user with a mouse puts the cursor over the image (onMouseOver). To make this type of functionality accessible, onFocus and onBlur must also be used. In addition, because this is essentially an "image-swap", alt text must be added to the image, so that visually impaired users have access to the content as well. The image-swap below can be executed with a mouse or with a keyboard.

The code for the above example is below:

<a href="webscripts_eventhandlers.html#imageswap" onmouseover="document.images['ex1pic2'].src = ex1on.gif';"
onfocus="document.images['ex1pic2'].src = 'ex1on.gif';"
onmouseout="document.images['ex1pic2'].src = 'ex1off.gif';"
onblur="document.images['ex1pic2'].src = 'ex1off.gif';"><img src="ex1off.gif" width="289" height="79" id="ex1pic2"
alt="Accessibility - The quality of being accessible, or of admitting approach; receptibility." /></a>

The following table suggests keyboard event handlers to pair with mouse event handlers.

Mapping of event handlers for the mouse to the keyboard

Use...	...with
mousedown	keydown
mouseup	keyup
click [1]	keypress [2]
mouseover	focus
mouseout	blur

Example 2

Implement WAI-ARIA keyboard navigation.

Note that WAI-ARIA examples are not supported by all browsers. If your product needs to be accessible in multiple browsers one or more of the required HTML/CSS specific techniques must be implemented as well as a WAI-ARIA technique.

Rich Internet application keyboard navigation should behave like desktop application keyboard navigation. For example, keyboard users tab to Windows Explorer and then use the arrow keys to navigate to elements in the tree. WAI-ARIA provides support for arrow key navigation of complex widgets such as menus, trees and grids via the tabindex attribute or activedescendant property. For more information on how to implement arrow key navigation, see WAI-ARIA Best Practices (link resides outside of ibm.com) and Keyboard navigable JavaScript widgets (link resides outside of ibm.com).

For additional information, refer to WCAG 2.0 examples for using both keyboard and other device-specific functions (link resides outside of ibm.com).

2. JavaScript actions: Make JavaScript actions keyboard accessible.

To comply with this technique, all of the following examples must be implemented.

Example 3

The keyboard tab key must be able to be used to "stop" at the element and then activate it by pressing the Enter key.

Typically only links and form controls are in the keyboard tab order. However, complex widgets such as trees, menus and grids should also receive focus via tabbing, and arrow key navigation should be supported for navigating elements within these widgets. For more information on how to implement arrow key navigation for complex widgets, see WAI-ARIA Best Practices (link resides outside of ibm.com) and Keyboard navigable JavaScript widgets (link resides outside of ibm.com).

In addition, browsers will sometimes map the pressing of the keyboard Enter key to mouse events. Therefore, device-dependent event triggers must be tested to determine if the browser simulates the event with the keyboard as a redundant input mechanism. If it does, then specifying the mouse event is sufficient. Two events might cause a problem when only one is expected. For example, onKeyDown should not be specified with onMouseDown because doing so will cause two browser events: one for the onKeyDown event because the user pressed down the Enter key and a simulated mouse click provided by the browser for onMouseDown.

If the browser does not simulate the mouse event when the keyboard is used, then the keyboard event must also be specified.

OnClick is an example of an event handler that sometimes behaves as a device-independent handler and in other cases as a device dependent handler. Specifying the event handler onClick on a link or form element should cause the browser to evoke the event if either the mouse or the Enter key is used to select it. In this case, onClick acts in a device-independent manner, and is therefore directly accessible because the same action takes place when the link is clicked or the enter key is pressed. In other words, for a link that uses onClick, if tabbing to a link and pressing the Enter key will cause the onClick event to occur - then the script functionality can be operated via the keyboard without requiring the developer to code the second redundant onKeyPress event for the same element.

The example below uses onClick as a device-independent link, which is executed when the Enter Key is used to select the element:

View this device-independent onClick example

The code for the Example 1 is below:

<a href="webscripts.html#postexample" onclick="return confirm('Clicking OK will take you to the next paragraph');">View this device-independent onClick example</a>

When the onClick event is used with elements that are not links or form controls, onClick is device-dependent, therefore you must provide a redundant device-independent event handler (onKeyPress) or an equivalent alternative. In order to gain focus on the text, you will need to implement the tabindex attribute. Once that is done, you can use the onkeypress event handler to provide an alternative to onClick. In Example 2 below, the "View this onClick with onKeyPress example" text has the tabindex set, and has both the onClick and onKeyPress event handlers defined.

Note complex widgets such as trees, menus and grids have a different navigation paradigm. Complex widgets should receive focus via tabbing, and arrow key navigation should be supported for navigating elements within the widgets. For more information on how to implement arrow key navigation for complex widgets, see WAI-ARIA Best Practices (link resides outside of ibm.com) and Key-navigable custom JavaScript widgets (link resides outside of ibm.com).

Example 4

Do not write event handlers that use double-clicking (onDblClick).

There is no keyboard equivalent specified in HTML 4.01. Instead, use one of the keyboard accessible handlers.

Example 5

Do not write event handlers that rely on mouse coordinates.

There is no keyboard equivalent way to perform this function. An example of a script that relies on mouse coordinates is a server-side image map which uses javascript:onmouseover as a precursor to performing an action.

Example 6

Ensure that hidden content that is made visible is "seen" by assistive technologies.

Assume that a blind user is completing a form but forgets to enter a required phone number. Javascript prevents the form from being submitted and renders an error message below the form indicating that a phone number is required.

* Phone number:

* indicates required information must be entered.

Before submiting this form, your phone number must be entered.

The error message is created in the DOM, but unfortunately screen readers don't always read elements created in the DOM, so a blind user doesn't know that an error has occurred.

This problem may be overcome by assigning an alert role to the message container as follows.

function showErrorMsg(msg){
    var msgContainer = document.createElement('div');
    msgContainer.setAttribute('role', 'alert');
    msgContainer.setAttribute('id', 'alert');

    var msg = document.createTextNode(msg);
    msgContainer.appendChild(msg);

    document.body.appendChild(msgContainer);
}

When an error occurs, the Javascript function creates a div element and assigns it a role of alert. A text node containing the error message is created and appended to the div. Finally, the div is appended to the document body. The alert role causes a screen reader to read the error message when it is rendered.

Also see the Dojo examples for providing a text message that identifies a field as mandatory and providing a text message when user input falls outside the required format or values.

Example 7

Use document.write in an accessible manner.

When using document.write, the content should be written to the same page, or the user must be notified if document.write creates content in new page/window, and then set focus to the new window.

The techniques above are required; the following techniques are recommended to enhance accessibility:

See WCAG 2.0 Additional Techniques (Advisory) for 2.1.1 (link resides outside of ibm.com) for a list of keyboard related techniques and examples.

1. Don't use scripts that constantly refresh visible content.

Scripts that change content continuously, such as a real time clock, create accessibility problems for assistive technologies. Try not to use any scripts that constantly refresh visible content. Rather, give the user an option to press a device-independent button that will display the "refreshed" content only the when the button is pressed. The clock example below uses a global script to continually update a hidden element with the correct time. When a user clicks on the "Display current time" button, the time is then shown on the screen in a dialog box:

The code for the above example is:

<form action=""> <input type="hidden" id="face" size="13" value="" /> <input type="button" value="Display the current time" onclick="alert('The current time is ' + document.getElementById('face').value);" />

With the advent of WAI-ARIA live regions, Web application developers can easily make dynamic content accessible to screen reader users. However, when live region information is auto-updating, a mechanism must be provided to stop and restart the flow of information so as not to overwhelm a screen reader user. For example, the following stock ticker widget provides a "pause ticker" checkbox to pause the flow of stock quotes displayed by the ticker.

The HTML to render the ticker follows. The aria-live attribute on the fieldset element.enables a screen reader to announce quotes as they appear in the ticker.

<input type="button" id="startQuotes" name="startQuotes" value="Start stock
ticker"
onclick="showQuotes();">
<input type="checkbox" id="tickerOff" name="tickerOff"
onclick="toggleTicker(this)">
<label for="startQuotes">Pause ticker</label>
<fieldset id="quote" aria-live="polite"><legend>Stock
Quotes</legend></fieldset>

The showQuote() function starts the flow of quotes into the ticker box. When the "pause ticker" checkbox is checked, toggleTicker() is called which stops the flow of quotes. When the checkbox is unchecked, the ticker resumes displaying quotes.

<script type="text/javascript">
var t;

/* Start quotes */
function showQuotes(){

/* Simulate a stock ticker */
    var quotes = new Array("IBM 97.75", "GLW 7.87", "C 8.75", "WB 5.98",
"SUN 3.65", "RIG 72.25");

var quoteStr =
document.createTextNode(quotes[Math.floor(Math.random()*6)]);
var msgContainer = document.createElement('div');
    msgContainer.appendChild(quoteStr);

    document.getElementById('quote').appendChild(msgContainer);

    /* Show a quote every second */
    t=setTimeout("showQuotes()",1000);

}

/* Pause/resume quotes */
function toggleTicker(obj){
    if (obj.checked == true){
      clearTimeout(t);
    } else {
      showQuote();
    }
} </script>

For more information on WAI-ARIA live regions see the WAI-ARIA specification (link resides outside of ibm.com) and WAI-ARIA Best Practices (link resides outside of ibm.com).

Note that WAI-ARIA examples are not supported by all browsers. If your product needs to be accessible in multiple browsers one or more of the required HTML/CSS specific techniques must be implemented as well as a WAI-ARIA technique.

2. Inform the user that the page will be reloaded when a specific action/event is taken, what will be changed, and how to get back to where they where. For example, if by selecting a menu item, a second select menu item is changed by reloading the page- then the user needs to know that before selecting the first menu item. If a skip link is provided to quickly navigate to the changed content, then the users can efficiently change and navigate the content.

3. Review placement of content in document order.

4. When content is added, (>3 items) update the tab order if needed.

5. When possible, content that is modified should be after current cursor location.

6. Do not turn off scroll-bars.

The following test tools and techniques are required to test this checkpoint.

1. Test tools
2. Required accessibility verification test techniques