From 572cdf388c8aee4b1c829fb4d1ab9a6dac6a2343 Mon Sep 17 00:00:00 2001 From: Matt King Date: Sat, 13 Aug 2016 17:56:05 -0700 Subject: [PATCH] Removed sections that require major rework to fix incorrect guidance. In addition to the below, This commit also moves the landmark section after the example section. Moved each of the following sections from aria-practices.html to aria-practices-DeletedSectionsArchive.html and created associated issues for drafting new versions. 1. Section "General Steps for Building an Accessible Widget with WAI-ARIA" and created issue #73. 2. Section "Other Widget Authoring Practices"., primarily about aria-valuenow, there is no specific need to raise an issue for this section. 3. Section "Relationships" and raised issues #74, #75, #76, and #77. 4. Section "Managing Dynamic Changes" and created issue #78. 5. Section "Presentation Role" and created issue #79. 6. Section "Form Properties" and created issue #80. 7. Section "Drag-and-Drop Support" and created issue #81 8. Section "Math" and created issue #82. 9. Section "Reusable Component Libraries" and created issue #83. 10. The following 4 Appendix sections related to background on ARIA and created issue #84 A. Background on WAI-ARIA B. Filling the Gaps for Content Delivered to Desktop Browsers c. Building Accessible Applications with WAI-ARIA D. Reasons for Adopting WAI-ARIA 11. The following design patterns: A. Accordion and updated issue #53. B. Autocomplete and updated issue #31. C. Combobox and updated issue #31. D. Datepicker and updated issue #57 E. Dialog (Non-Modal) and updated issue 59. F. Dialog (Tooltip) and added issue #85. G. Landmarks and added issue #86. H. Popup Help (aka Bubble Help) and added issue #87. I. Rich Text Editor and added issue #88. j. Site Navigator - General and added issue #89. K. Site Navigator - Tree and added it to issue #89. L. Site Navigator - Tabbed Style and added it to issue #89. M. Tree Grid and added issue #91. N. Wizard and added issue #92. --- aria-practices-DeletedSectionsArchive.html | 3040 ++++++++++++++ aria-practices.html | 4367 ++++---------------- 2 files changed, 3801 insertions(+), 3606 deletions(-) diff --git a/aria-practices-DeletedSectionsArchive.html b/aria-practices-DeletedSectionsArchive.html index 3a7019efaf..35148fa7dd 100644 --- a/aria-practices-DeletedSectionsArchive.html +++ b/aria-practices-DeletedSectionsArchive.html @@ -165,6 +165,1449 @@ It allows reviewers to more easily see what was removed, and makes it easier to restore content.

+ +
+

Design Patterns and Widgets

+ +
+

Accordion

+ +

This section has not been updated since it was integrated from the WAI-ARIA Authoring Practices Guide (APG) version 1.0 -- an APG task force review is pending.

+ +

+ An accordion component is a collection of expandable panels associated with a common outer container. + Panels consist of a header and an associated content region or panel. + The primary use of an Accordion is to present multiple sections of content on a single page without scrolling, where all of the sections are peers in the application or object hierarchy. + The general look is similar to a tree where each root tree node is an expandable accordion header. + The user navigates and makes the contents of each panel visible (or not) by interacting with the Accordion Header. + Terms for understanding accordions include: +

+ +
+
accordion component:
+
Collection of panels within a common outer pane.
+
accordion header:
+
Label area of an accordion panel. This is where you find the control to expand or collapse the panels.
+
accordion panel:
+
Contents area associated with an accordion header.
+
+ +
+

Keyboard Interaction

+ +
    +
  • + Tab - When focus is on an accordion header, pressing the Tab key moves focus in the following manner: +
      +
    1. If interactive glyphs or menus are present in the accordion header, focus moves to each in order.
      2. +
    2. When the corresponding panel is expanded (its aria-expanded state is 'true'), then focus moves to the first focusable element in the panel.
      3. +
    3. If the panel is collapsed (its aria-expanded state is 'false' or missing), OR, when the last interactive element of a panel is reached, the next Tab key press moves focus as follows: +
        +
      • If a subsequent accordion panel is already expanded, focus moves to the first focusable element in this subsequent panel.
        • +
      • If no subsequent accordion panel is expanded, focus moves to the first focusable element outside the accordion component.
        • +
      +
      4. +
    +
    • +
  • + Left arrow +
      +
    • When focus is on the accordion header, a press of up/left arrow keys moves focus to the previous logical accordion header.
      • +
    • When focus reaches the first header, further up/left arrow key presses optionally wrap to the first header.
      • +
    +
    • +
  • + Right arrow +
      +
    • When focus is on the accordion header, a press of down/right moves focus to the next logical accordion header.
      • +
    • When focus reaches the last header, further down/right arrow key presses optionally wrap to the first header.
      • +
    +
    • +
  • + Up arrow - behaves the same as left arrow +
    • +
  • + Down arrow - behaves the same as right arrow +
    • +
  • + Control + Up Arrow - Moves focus from anywhere in the accordion content to its associated accordion header or tab respectively. +
    • +
  • + Control + Page Up - +
      +
    • When focus is inside of an accordion pane, pressing Control + Page Up moves focus to the accordion header of the previous accordion pane.
      • +
    • When focus is in the first accordion header content, pressing Control + Page Up optionally moves focus to the last accordion header.
      • +
    • Focus will simply move to the header and will require Enter/Space to expand/collapse the accordion pane.
      • +
    +
    • +
  • + Control + Page Down - +
      +
    • When focus is inside of an accordion pane, pressing Control + Page Down moves focus to the header of the accordion pane.
      • +
    • When focus is in the last accordion header content, pressing Control + Page Down optionally moves focus to the first accordion header.
      • +
    • In the case of an accordion, focus simply moves to the header and requires Enter/Space to expand/collapse the accordion pane.
      • +
    +
    • +
  • + End - When focus is on the accordion header, an End key press moves focus to the last accordion header. +
    • +
  • + Home - When focus is on the accordion header, a Home key press moves focus to the first accordion header. +
    • +
  • + Enter/Space - When focus is on an accordion header, pressing Enter/Space toggles the expansion of the corresponding panel. +
      +
    • If collapsed, the panel is expanded, and its aria-expanded state is set to 'true'.
      • +
    • If expanded, the panel is collapsed and its aria-expanded state is set to 'false'.
      • +
    +
    • +
  • + Shift + Tab - Generally the reverse of Tab. +
    • +
  • + Alt + Delete - +
      +
    • + When deletion is allowed, with focus anywhere within the tab panel or tab, pressing Alt + Delete will delete the current tab and tab panel from the tabbed interface control. + If additional tabs remain in the tabbed interface, focus goes to the next tab in the tab list. + If no additional tabs remain, then focus moves to the last place that held focus in the previous tab panel. +
      • +
    • + An alternative to providing a keystroke to close a tab is to provide a context menu that is associated with the tab title. + When focus is on the tab, pressing Shift + F10 or pressing the right mouse button will open a context menu with the close choice. +
      • +
    • A warning should be given to the user before allowing the delete to occur.
      • +
    +
    • +
+

+ In Firefox, pressing Control + Page Up / Control + Page Down moves between browser tabs. + Firefox also supports Control + Tab and Control + Shift + Tab to move between tabs. + Internet Explorer 7 also uses Control + Tab and Control + Shift + Tab. + There may be advantages to using Control + Page Up/Page Down as the keys to change tabs; it is a recognizable keystroke to at least Firefox users and it is also supported by the Windows operating system to move between panels in a tabbed dialog. +

+

You should be aware of two issues with using Control + Page Up/Page Down:

+
    +
  • + The first arises when the user is within a tabbed interface control on a Web page. + Here they can not easily switch browser tabs without first moving focus outside of the tabbed interface control. + This may be acceptable. +
    • +
  • + The second arises when the entire web page is a tabbed interface control. + In this case the user could not switch browser tabs unless the control on the web page ignored the Control + Page Up/Page Down keypress (and thus letting the browser access it) when the first or last tab was reached. +
    • +
+
+ +
+

WAI-ARIA Roles, States, and Properties:

+ +
    +
  • + The accordion component must have a role of tablist and have aria-multiselectable="true" + This will enable an assistive technology, such as screen reader, to convey that the tablist is an accordion or a multi selectable tablist. + This will also tell the user that the keyboard navigation matches an accordion and not a tablist. +
    • +
  • Contained within the tablist is a set of tab/tabpanel pairs.
    • +
  • Each header tab in the tablist has a role of tab.
    • +
  • The accordion panel uses the role tabpanel and should have an aria-labelledby relationship referencing the corresponding header having a role of tab
    • +
  • The tabpanel is considered a grouping for all content consisting of that tabpanel.
    • +
  • An accordion should manage the expanded/collapsed state of each tab by maintaining its aria-expanded state.
    • +
  • An accordion should manage the selected state of each tab by maintaining its aria-selected state.
    • +
  • An accordion should convey the visibility of each tabpanel by maintaining its aria-hidden state.
    • +
+
+ +
+

Example

+ +

+ Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. + The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. +

+ +

Open Ajax Alliance Accordion

+
+
+ +
+

Auto Complete

+

This section has not been updated since it was integrated from APG + version 1.0 -- an APG task force review is pending.

+ +

A text box and an associated drop-down list of choices where the choices offered + are filtered based on the information typed into the box. Typically, an icon + associated with the text box triggers the display of the drop-down list of choices. + An editable auto-complete accepts text entry of choices that are not in the list. An + example of an editable auto-complete is the URL field in the browsers.

+ +
+

Keyboard Interaction

+
    +
  • With focus in an empty text box, press Down Arrow, Up + Arrow, Alt + Down Arrow, or Alt + Up Arrow to + display the entire list of choices. Focus remains in the text box and no + choice is highlighted. +
      +
    • Press the Down Arrow to highlight the first choice + in the list. +
      • +
    • Press the Down Arrow and Up Arrow keys to + highlight the desired choice in the list. +
      • +
    • Note that the arrows will wrap through the text box when the + top or bottom of the list is reached. For example, pressing the down + arrow when the last choice is highlighted will move focus back to + the text box, pressing down again will move focus to the first item + in the list. Likewise, with focus in the text box and the list + displayed, pressing up arrow will move focus to the last item in the + list.
      • +
    • When a choice is highlighted using the arrow keys, the + highlighted choice is displayed in the text box.
      • +
    • Press Enter to select the highlighted choice and + close the drop-down list. This mimics the behavior of the HTML + select element. +
      • +
    +
    • +
  • With the drop-down list of choices displayed, move the mouse pointer + over an item in the list to highlight it. The text box value is not modified + when the mouse is used to highlight a choice. Clicking on the highlighted + choice will close the drop-down and update the text box with the selected + choice. This mimics the behavior of the HTML select element.
    • +
  • With focus in an empty text box, type any letter. If + any of the available choices begin with the letter typed, those choices are + displayed in a drop down. If the letter typed does not match any of the + available choices the drop-down list is not displayed. +
    • +
  • With focus in text box with an existing value type additional + letters. As the user types letters the list of choices is filtered so + that only those that begin with the typed letters are displayed. +
      +
    • Until the user presses the arrow keys to highlight a particular + choice, only the typed letters are displayed in the text box.
      • +
    • In an editable auto-complete, if no choices match the letter(s) + typed, the drop down list closes.
      • +
    • In a non-editable auto-complete, any letters that do not result + in a match from the list are ignored. The drop down list of choices + remains static until the user presses: +
        +
      • Escape to clear the text field
        • +
      • Backspace to remove some of the letters + previously typed
        • +
      • an additional letter that results in a valid list of + choices.
        • +
      +
      • +
    • Navigation through the list of choices and display of the + highlighted choice in the text box works as described above.
      + Optional: When a choice is highlighted via arrow key + navigation, the input cursor is left at the end of the typed + entry and the highlighted choice is displayed in the text box + with the characters after the input cursor selected. Typing an + additional character will remove the auto-completed portion and + append the newly typed character to the end of the previously + typed characters. The list will be filtered based on the + additional character(s) typed. +
      • +
    +
    • +
  • With focus in a text box, press Escape +
      +
    • If there is no text in the text box, pressing Escape + closes the drop-down if it is displayed. +
      • +
    • For an editable autocomplete that has text in the text box that + was both typed by the user and auto-completed by highlighting a + choice using the keyboard, the auto-completed portion of the text is + cleared and the user typed characters remain in the text box. The + drop-down list is closed. To completely clear the text box contents + the user must use the backspace key to remove the typed characters. + This is how the Google search box in the Firefox UI works. Recommend + that pressing the Escape key again completely clears + the text box rather than relying on only the backspace key. + +
      • +
    • For a non-editable auto-complete that has text in the text box + that was both typed by the user and auto-completed by highlighting a + choice using the keyboard, pressing Escape closes the + drop-down list and leaves the current choice in the text box. +
      • +
    • For an editable or non-editable auto complete with text in the + text box that was typed by the user and the mouse is highlighting a + choice in the drop down (keyboard navigation was NOT used), pressing + Escape closes the drop down and leaves the typed text + displayed in the text box. Need to consider if pressing Escape + again should clear the typed text. The user must press the Down + arrow or Alt + Down arrow or click the associated icon to + invoke the drop-down list of choices again. +
      • +
    +
    • +
  • Moving focus out of an empty auto complete field where a value is + required should either invoke an error or if a default value was initially + assigned, reset the value to the default value.
    • +
  • Moving focus out of an auto complete field that does not contain a + valid entry should either invoke an error or if a default value was + initially assigned, reset the value to the default value.
    • +
+

It is good practice to limit the number of matching items in the + drop down to a reasonable number. The reasonable number is determined by the + task at hand. A list of the 50 US States is probably reasonable, but a list + containing all of the office numbers in a building is probably not appropriate. +

+
+ +
+

WAI-ARIA Roles, States, and Properties

+
    +
  • The widget has a role of combobox. +
    • +
  • The combobox has an aria-autocomplete property set to one of 'inline', + 'list', or 'both'. +
    • +
  • For more information, see the combobox design + pattern. +
    • +
+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org + may have changed and may not accurately exemplify the guidance in this section. + The APG task force is developing examples for APG version 1.1 that will be + directly incorporated into the guide.

+

+ Dojo autocomplete +

+
+
+ +
+

Combo Box

+

This section has not been updated since it was integrated from APG + version 1.0 -- an APG task force review is pending.

+ +

A combo box enables the user to type in a field and at the same time chose a + predefined value from a list. By using the keyboard the user can select an item from + the list. After selection she will be able to type further characters in the field. +

+ +
+

Keyboard Interaction

+
    +
  • Left Arrow or Right Arrow move the caret within + the edit field.
    • +
  • Alt + Up/Down Arrow opens and closes the list.
    • +
  • Up Arrow and Down Arrow moves focus up and down + the list. As focus moves inside the dropdown list, the edit field is + updated.
    • +
  • Page Up / Page Down selects the next/previous pages item + depending on the lists size.
    • +
  • Escape closes the dropdown list, returns focus to the edit + field, and does not change the current selection.
    • +
  • Enter selects the current item on the list, updates the edit + field, highlights the selected item in the dropdown list, closes the + dropdown list, and returns focus to the input field.
    • +
  • Typing a letter (printable character) key moves focus to the + next instance of a visible node whose title begins with that printable + letter.
    • +
+

+ For combo boxes that implement aria-autocomplete, see the autocomplete design pattern. +

+
+ +
+

WAI-ARIA Roles, States, and Properties

+

A combobox can be implemented using either of two design patterns:

+
    +
  1. As a combination of text field, which may be editable, a displayable + list of items, and a drop button to toggle the display of that list; all + wrapped in the form of a single widget with role of combobox.
    2. +
  2. As a combobox, which behaves like a textfield and may be editable, with + a displayable list of items, and a drop button to toggle the display of that + list;
    3. +
+

Like text fields a combobox should be labeled to convey the purpose of the + widget. Keyboard focus within the widget must be managed by the widget. + Comboboxes are used extensively in graphical user interfaces and the design + pattern for the widget should be semantically correct.

+

For the first combobox design pattern:

+
    +
  • The container element that wraps the combobox has a role of combobox. +
    • +
  • The first element within the combobox is an input text + field and is responsible for managing the keyboard focus between the text + field and the list as well as displaying the list. The text field is in the + tab order. If you create a text field without using a standard HTML text + field form control then ensure that it is in the tab order. +
    • +
  • If the text field is not editable it must have have aria-readonly = true. +
    • +
  • The combobox must have aria-expanded = true if the list + is displayed or aria-expanded + = false when it is not. +
    • +
  • The next element is an html <button>, or another + element with a role of button. + This element is used to toggle the display of the combobox's drop down list. +
    • +
  • The next element has a listbox + role and represents the drop down list. It manages keyboard navigation among + list items and navigating back to the text field if necessary. +
    • +
  • Each item in the listbox is an option. + Options are not in the tab order. +
    • +
  • Provide a label for the combobox by referencing the text field in the + combobox. You can use an aria-label + to associate this label with the combobox or you may use the HTML <label> + element and its for attribute to reference the text field. +
    • +
+

For the second combobox design pattern:

+
    +
  • The first element for the combobox has a role of combobox and behaves + like an input text field and is responsible for managing the keyboard focus + between the combobox and the list as well as displaying the list. The text + field is in the tab order. If you create a text field without using a + standard HTML text field form control then ensure that it is in the tab + order.
    • +
  • If the combobox is not editable it must have have aria-readonly = true. +
    • +
  • The combobox must have aria-expanded = true if the list + is displayed or aria-expanded + = false when it is not. +
    • +
  • The next element is an html <button>, or another + element with a role of button. + This element is used to toggle the display of the combobox's drop down list. +
    • +
  • The next element has a listbox + role and represents the drop down list. It manages keyboard navigation among + list items and navigating back to the text field if necessary. +
    • +
  • Each item in the listbox is an option. + Options are not in the tab order. +
    • +
  • Provide a label for the combobox by referencing the text field in the + combobox. You can use an aria-label + to associate this label with the combobox or you may use the HTML <label> + element and its for attribute to reference the text field. +
    • +
+

+ For each combobox pattern the button need not be in the tab order if + there is an appropriate keystroke associated with the + input + element such that when focus is on the + input + , the keystroke triggers display of the associated drop down list. In this case, + a + Tab + to focus the button is unnecessary. This is the same behavior as the + select + element. +

+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org + may have changed and may not accurately exemplify the guidance in this section. + The APG task force is developing examples for APG version 1.1 that will be + directly incorporated into the guide.

+

+ First design pattern -- container element with role combobox: +

+ +

+ Second pattern -- text field with role combobox: +

+ +
+
+ +
+

Date Picker

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+ +

+ The date picker widget allows the user to select a date or date ranges. + The date picker shows one month at least. All navigation that is described below depends on the application. + If no range selection is possible, the relevant keystroke interaction can be ignored. + Also navigation to the past might be optional. + Each week might be labeled with the corresponding calendar week number. +

+

+ As a general rule the actual calendar portion of the date picker follows a table structure where days of the week and calendar day numbers are laid out in table cells. + This provides context so an assistive technology can render the day of the week; its corresponding numeric calendar day, and week number if necessary. + Consequently, it is best to start with an HTML table and apply WAI-ARIA semantics for a grid. + However, should the author wish to uses a div or span to represent the cells then the DOM structure for a table is duplicated with rows marked with role="row". +

+

The calendar portion can be displayed in a numbers of ways, including as a popup associated with another widget, or as a static region of a page.

+ +
+

Keyboard Interaction

+

Keyboard navigation on days that are not included the currently displayed month should move to the month automatically and lead to the day in the next or previous month.

+
    +
  • + Tab - Like other widgets, the date picker widget receives focus by tabbing into it. + Once focus is received, focus is repositioned on today's date in a grid of days and weeks. + A second tab will take the user out of the date picker widget. + Focus initially is placed on today's date. +
    • +
  • + Shift + Tab - reverses the direction of the tab order. + Once in the widget, a Shift+Tab will take the user to the previous focusable element in the tab order. +
    • +
  • + Up Arrow and Down Arrow - goes to the same day of the week in the previous or next week respectively. + If the user advances past the end of the month they continue into the next or previous month as appropriate. +
    • +
  • + Left Arrow and Right Arrow - advances one day to the next, also in a continuum. + Visually focus is moved from day to day and wraps from row to row in a grid of days and weeks. +
    • +
  • Control + Page Up - Moves to the same date in the previous year.
    • +
  • Control + Page Down - Moves to the same date in the next year.
    • +
  • + Space - +
      +
    • Singleton Mode: acts as a toggle either selecting or deselecting the date.
      • +
    • + Contiguous Mode: Similar to selecting a range of text. + Space selects the first date. + Shift + Arrows add to the selection. + Pressing Space again deselects the previous selections and selects the current focused date. +
      • +
    +
    • +
  • Home - Moves to the first day of the current month.
    • +
  • End - Moves to the last day of the current month.
    • +
  • Page Up - Moves to the same date in the previous month.
    • +
  • Page Down - Moves to the same date in the next month.
    • +
  • + Enter - +
      +
    • If the the calendar is a popup attached to some other widget (e.g., a text field), then Enter dismisses the popup, and the selected date(s) are shown in the associated widget.
      • +
    • If the calendar is a static region on the page, then Enter confirms the selected date(s).
      • +
    +
    • +
  • Escape - in the case of a popup date picker, closes the widget without any action.
    • +
+

Navigation into the past is optional

+

+ Do not implement keyboard navigation schemes that would place more than one calendar day in the tab order at any time as this impacts the usability of keyboard navigation. + For example, using HTML anchors for the gridcells places them all in the tab order impacting the usability of keyboard navigation. +

+
+ +
+

WAI-ARIA Roles, States, and Properties

+
    +
  • + The current month has a label representing the month and year. + It is advisable to use a role heading but is not essential. + This "label" should have a unique ID. +
    • +
  • If the author would like to ensure that a label is announced by a screen reader, as the label changes, include live region properties with the label element: aria-live="assertive" and aria-atomic="true".
    • +
  • The container for the day of week headers and numeric days of the week has a role of grid.
    • +
  • The grid has an aria-labelledby property with a value equivalent to the id of the label for the grid.
    • +
  • Each name for the day of the week has a role columnheader and is not navigable via the keyboard.
    • +
  • Each numeric day of the week has the role gridcell.
    • +
  • When a day is selected its aria-selected is set to true, otherwise it is set to false or removed.
    • +
  • Changes in aria states, identified here, as well as focus, are clearly styled to show the user where their point of regard is and what days are selected.
    • +
+

+ When the date picker is active a calendar day of the week always has focus. + This can be achieved by setting the tabindex on that day as appropriate and then using script to give it focus. + Alternatively, the grid container could set aria-activedescendant to the id of the currently focused gridcell. + Keep in mind that older browsers may not support aria-activedescendant. +

+
+ +
+

Example

+

+ Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. + The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. +

+ +
+
+ +
+

Dialog (Non-Modal)

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+ +

A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response (dialog).

+ +

+ A non-modal dialog is one which is displayed and focusable at the same time as the application which invoked it. + Also like the modal dialog, focus via the tab and shift-tab key must be maintained within the dialog. + However, a non-modal dialog should have a keyboard mechanism to return focus to the application while leaving the dialog open. +

+ +
+

Keyboard Interaction

+
    +
  • Escape cancels the dialog without taking any action.
    • +
  • Enter submits any data gathered in the dialog.
    • +
  • F6 is the recommended key to move focus between the application and an open non-model dialog.
    • +
+

Notes:

+
    +
  • The mouse user may click on either the application or the dialog to change focus between the two.
    • +
  • In a Web application the non-modal dialog is usually always displayed above the application page, rather than in a separate browser window but that is not a requirement.
    • + +
  • + Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. + Authors should ensure that Enter activates only the widget they intend. +
    • +
+
+ +
+

WAI-ARIA Roles, States, and Properties

+

See Dialog (Modal).

+
+ +
+

Example

+ +

+ Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. + The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. +

+

Experimental dojo floating non-modal pane

+
+
+ +
+

Dialog (Tooltip)

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+ +

A tooltip dialog is a modal dialog that is rendered near the invoking element and visually connected via a cartoon bubble-like protrusion. It is displayed when the mouse passes over or rests on that element.

+ +
+

Keyboard Interaction:

+
    +
  • Escape The tooltip dialog is closed by pressing the escape key when focus is within the dialog, mouse clicking on a close icon, or mouse clicking outside of the dialog onto the application.
    • +
  • Tab Focus must be held within the dialog until it is cancelled or submitted. As the user presses tab to move within items in the dialog, pressing tab with focus on the last focusable item in the dialog will move focus back to the first focusable item in the dialog.
    • +
  • Shift + Tab Likewise, if the user is shift-tabbing through elements in the dialog, pressing shift-tab with focus on the first focusable item in the dialog will move focus to the last item in the dialog.
    • +
+

It is modal because focus is trapped within the dialog as the user navigates via the Tab and Shift + Tab key.

+

Unlike a true modal dialog, the user can click outside of the dialog, however in that case the tooltip dialog is immediately closed.

+

A tooltip dialog can not be moved/dragged.

+

Other than the close and move behavior, all other behaviors of a modal dialog are implemented by the tooltip dialog.

+
+ +
+

WAI-ARIA Roles, States, and Properties

+

See Dialog (Modal).

+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

+

Dojo nightly

+
+
+ +
+

Landmark Navigation

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+ +
+

Keyboard Interaction

+
+ +
+

WAI-ARIA Roles, States, and Properties

+

Provide the appropriate landmark for the role attribute. See the section describing landmark use.

+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

+ +
+
+ +
+

Popup Help (aka Bubble Help)

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+ +

+ Popup Help contains more descriptive, or actionable, help-like text and elements. + It may contain, and was designed to handle, interactive elements such as a button, link, or text field. + It is essentially a Popup Menu with un-necessary keystrokes turned off. + The key sequence for posting Popup Help was to take advantage of F1's tie to the Help paradigm (F1 calls up application Help for example). +

+ +
+

Keyboard Interaction

+
    +
  • Control + F1 +
      +
    • Posts the Popup Help widget.
      • +
    • Input focus is placed on the first interactive element in the Popup Help.
      • +
    • Control F1 is used by IE to "Display a help dialog box". In IE7 and IE8 event.cancelBubble=true; and event.returnValue=false; will allow the re-purposing of keys used by the browser. In the case of IE6, you can not stop the bubble up of keys used by the browser, but can stop the bubble up to the OS. In the case of Firefox and other standard compliant browsers, event.stopPropagation(); and event.preventDefault(); will re-purpose the keys.
      • +
    • With the exception of Control F1 to bring up Popup Help this widget is very similar to Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip) described elsewhere in this document.
      • +
    +
    • +
  • Esc +
      +
    • Causes no menu action and dismisses Popup Help.
      • +
    • Input focus is returned to the element, or widget the Popup Help was invoked from.
      • +
    • Pressing Enter when input focus is on the "X" glyph acts the same as pressing Esc.
      • +
    +
    • +
  • Tab +
      +
    • One of the following occurs: +
        +
      • Modal behavior +
          +
        • Moves input focus between elements in the Popup Help's tabbing order. +
            +
          • Input focus stays in the Popup Help until one of the following occurs: +
              +
            • Esc is pressed.
              • +
            • Enter is pressed when input focus is on an interactive widget/element.
              • +
            +
            • +
          +
          • +
        +
        • +
      • Non-Modal behavior +
          +
        • Moves input focus to the next tabbable element in the tabbing order if the following applies: +
            +
          • Popup Help is posted.
            • +
          • It contains no tab navigable elements in it.
            • +
          +
          • +
        +
        • +
      +
      • +
    +
    • +
  • Shift + Tab +
      +
    • As with other keyboard conventions described here, the Shift + Tab has the effect of moving the focus up rather than down and follows the same conventions as described for the modal and non-modal Tab key above.
      • +
    +
    • +
  • Enter +
      +
    • Activates the element in the Popup Help that has input focus, if applicable, then dismisses the popup. +
        +
      • Input focus should be placed on the appropriate element after the user presses the Enter key. +
          +
        • The appropriate place to move input focus to will not always be the parent element the Popup Help was invoked from.
          • +
        +
        • +
      • Nothing occurs if input focus is on an element that has no associated action.
        • +
      +
      • +
    +
    • +
  • F6 +
      +
    • In the non-modal instance, the F6 key can be used to move focus between the application and the open non-modal window. This is also the behavior described in Dialog (Non-Modal) above.
      • +
    +
    • +
+
+ +
+

WAI-ARIA Roles, States, and Properties

+

See Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip).

+
+ +
+

Example

+

Add link to example.

+
+
+ +
+

Rich Text Editor

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

Input control that accepts free-form text as its value.

+ +
+

Keyboard Interaction

+ +
    +
  • The edit control is provided by the browser; it provides the keyboard support for navigating, adding, removing and selecting text, so that behavior is not defined by the rich internet application.
    • +
  • The browser should also provide a keyboard mechanism for navigating into and out of the edit control. Within most browsers the edit control is put into the tab order of the page and can be navigated into, out of, and through using the tab and shift-tab keys like any standard form control.
    • +
  • A rich text editor widget needs to provide a user interface for interacting with the browser provided edit control. Interaction between the user interface and editor is defined here assuming that a toolbar is used.
    • +
  • Tab and Shift + Tab - If not provided by the browser, the rich text editor widget provides a keyboard mechanism to move into and out of the edit control. Tab and shift-tab are the recommended keystrokes. The toolbar or other user interface component associated with the editor is placed in the tab order immediately before the editor. To set an attribute on text within the edit control the user sets focus into the edit control, moves the insertion point, selects text and presses shift-tab to move focus from the editor back to the toolbar. The user navigates through the toolbar (see toolbar behavior) to a desired attribute and invokes that attribute. When an attribute is invoked, that attribute is applied to the selected text in the editor and focus moves back into the editor at the previous insertion point with the selection intact.
    • +
  • Options: +
      +
    • Rather than using Shift + Tab to move focus from within the editor to the toolbar, another key combination could be used (Alt + Up Arrow, Control + Shift + Letter, etc.). This would eliminate the need to put the user interface control (in this example a toolbar) into the tab order immediately before the editor component. However, there are drawbacks to using a different keystroke to navigate to the user interface: +
        +
      1. It is not as "discoverable" as relying on the standard Tab/Shift + Tab behavior;
        2. +
      2. It is difficult to find key combinations which are not already captured by the browser or assistive technology.
        3. +
      3. Focus could stay within the toolbar after the user invokes an attribute. The user would then have to press an additional key to move focus back into the editor. This would allow multiple attributes to be set on the current selection without having to return back to the user interface but it would add an extra key sequence after setting just a single attribute. Requiring a keystroke to move focus back into the editor would also require modifying the toolbar behavior to intercept this keystroke and to know how to set focus back to the component (the editor) that the toolbar is associated with.
        4. +
      +
      • +
    +
    • +
+ +

Optionally, if the developer wishes to provide the ability to insert a tab into the document, it is recommended one of the following methods be used.

+
    +
  • Provide indent and outdent buttons in the menu. Keyboard shortcuts to the buttons should be Control + M for indent and Control + Shift + M for outdent.
    • +
  • Provide a button in the menu to toggle the use of Tab between the two modes. If this button is used, then Control + M is recommended as a keyboard shortcut to toggle the button.
    • +
+
+ +
+

WAI-ARIA Roles, States, and Properties

+

Authors are advised to not use ARIA for rich text editors, but to rely on native HTML markup. Current rich text editors typically use an iframe element for editable content. As a result, the editable content is implicitly mapped to a document role in accessibility APIs. If using HTML5, it is recommended that authors use the designMode or contentEditable attributes.

+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

+ +
+
+ + + + + + + +
+

Tree Grid

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

+ A grid whose rows can be expanded and collapsed in the same manner as for a tree. + A Tree Grid is a combination of a Treeview and a Table with rows that are expandable. +

+ +
+

Keyboard Interaction

+

There are two modes of keyboard interaction:

+
    +
  • Navigation Mode (Read-Only) is the default mode, and allows quick and intuitive navigation around the grid. +
      +
    • Tab +
        +
      • The initial tab enters the grid with focus on the first cell of the first row, often a header.
        • +
      • Once in the grid a second tab moves out of the grid to the next tab stop.
        • +
      • Once focus is established in the grid, a Tab into or a Shift + Tab into the grid will return to the cell which last had focus.
        • +
      +
      • +
    • Left Arrow and Right Arrow keys navigate between columns. If the next cell in the row is empty, focus should not move.
      • +
    • Up Arrow and Down Arrow The down arrow moves focus to the first column of a child row, if expanded. Otherwise focus is moved to the same column in the next row. Up arrow performs the same navigation but in reverse.
      • +
    • Control + Left and Control + Right Arrows expand or collapse rows.
      • +
    • If the cell contains an editable field, the Enter key starts edit mode and the Escape key exits edit mode.
      • +
    • Selecting Cells +
        +
      • Control + Space selects the current column.
        • +
      • Shift + Space selects the current row.
        • +
      • Control + A selects the entire grid.
        • +
      • Shift + Arrow selects contiguous cells.
        • +
      • Shift + F8 Allows additional cells to be added to a previous selection to accomplish non-contiguous selection.
        • +
      +

      See Global Recommendations for information on cut, copy and paste.

      +
      • +
    +
    • +
+ +

The author may choose to indent child nodes visually. This should be done with an appropriate number of spacer cells marked as presentation in order to keep the headers aligned.

+ +

If cells are used for padding or layout of the hierarchy, navigation to those presentational cells should be prevented.

+ +
    +
  • Actionable Mode (Interactive) allows the interaction with other objects that might be found in the grid cells such as edit fields, links, etc. +
      +
    • F2 pressed anywhere inside the grid will enter Actionable Mode. Focus will not be moved.
      • +
    • Enter pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
      • +
    • Optionally, alphanumeric keys pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
      • +
    • Tab will move to the next actionable (tabbable) item in the grid and stay within the grid wrapping at the bottom. In this mode each tabbable object in each cell of the grid can be reached with the tab key. If multiple tabbable items are located inside a single grid cell, the tab will stop at each one. When the last tabbable item in a cell is reached the next tab will move to the next tabbable item in the grid, wrapping at the last tabbable item in the grid.
      • +
    • Shift + Tab moves to the previous actionable (tabbable) item in the grid and stays within the grid, wrapping at the top.
      • +
    • Escape exits Actionable mode (by which the user may enter text or perform an action to complete a operation) and returns to Navigation Mode (where the user is allowed to move focus among elements). If a widget is in the current grid cell that also uses the Escape key, then it should cancel the event propagation. A subsequent press of the Escape key will return focus to the parent widget.
      • +
    +
    • +
+
+ +
+

WAI-ARIA Roles, States, and Properties

+

+ Uses the WAI-ARIA role treegrid, and requires the child element row. + By default a treegrid is considered to be editable, meaning all gridcells are editable. +

+
    +
  • To make a treegrid read-only, set aria-readonly="true" on the document element having a role="treegrid." This will make all gridcells read-only.
    • +
  • To override the read-only status on an individual gridcell, set its aria-readonly property to false.
    • +
+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

+
    +
  • For a visual (not accessible) example of where padding cells have been implemented see: dojo's TreeGrid example.
    • +
  • An example where padding cells have not been used (also not accessible): Oracle's Tree Grid.
    • +
+
+
+ +
+

Wizard

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

A sequence of dialogs or panels guiding the user through performing a task.

+ +
+

Keyboard Interaction

+

A Wizard can be done in several ways. Either is valid.

+
    +
  • Method 1: Like a Toolbar
    • +
  • Method 2: Controls as Default Actions +
      +
    • Escape cancels the wizard.
      • +
    • Enter invokes the "next" action; If the last page, it invokes "finish"
      • +
    +
    • +
  • Method 3: Hot Keys +
      +
    • Control + Alt + N next, finish
      • +
    • Control + Alt + P previous
      • +
    • Escape cancel, exit without saving
      • +
    • Control + Alt + R reset current page to default settings
      • +
    • Control + Alt + S save and exit
      • +
    +
    • +
  • Method 4: Like a Dialog
    • +
+

Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. Authors should ensure that Enter activates only the widget they intend.

+
+ +
+

WAI-ARIA Roles, States, and Properties

+
+ +
+

Example

+

Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

+

Dojo nightly

+
+
+ +
+ +
+

General Steps for Building an Accessible Widget with WAI-ARIA

+

This content could be useful when working on issue 73.

+

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.

+
    +
  1. +

    Pick the widget type (role) from the WAI-ARIA taxonomy

    +

    WAI-ARIA provides a role taxonomy ([[WAI-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">
    +
    2. +
  2. From the role, get the list of supported states and properties +

    Once you have chosen the role of your widget, consult the [[WAI-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:

    +
    +
    superclass 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" id="customToolbar" tabindex="0" aria-activedescendant="button1"
+      onkeydown="return optionKeyEvent(event);"
+      onkeypress="return optionKeyEvent(event);"
+      onblur="hideFocus();"
+      onfocus="showFocus();"
+      >
+      <img src="img/btn1.gif" title="Home" alt="Home" role="button" id="button1"
+           onclick="updateText('Home was invoked');">
+      <img src="img/btn2.gif" title="Refresh" alt="Refresh" role="button" id="button2"
+           onclick="updateText('Refresh was invoked');">
+      <img src="img/btn3.gif" title="Help" alt="Help" role="button" id="button3"
+           onclick="updateText('Help was invoked');">
+</div>
+
    +

    By setting tabindex=0 on the toolbar, the toolbar will receive focus in the document order. It is necessary then to use script and the aria-activedescendant property to manage virtual focus among the buttons. The details are given in step five, below.

    +
    +

    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.

    +
    +
    3. +
  3. 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 [[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="button2">
+  <img src="buttonpaste.png" alt="paste" id="button3">
+</div>
    +
    4. +
  4. 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.

    +
    5. +
  5. +

    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.

    +

    Commented out link to conference paper, which a) was broken, and b) we should have more canonical references than conference papers for things like this.

    +

    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.

    +

    You must also show the visual focus for each element that has focus.

    +
    6. +
  6. +

    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.

    +
    7. +
  7. +

    Synchronize the visual UI with accessibility states and properties for supporting user agents

    +

    Thomas comment: is confusing that the example switches from toolbar to treeitem. Maybe the best overall sample is to do a tree because it demonstrates each of the points you want to make?

    +

    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 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";
+      }
    +
    8. +
  8. 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:

    +
      +
    1. +

      Creating an entire section and then insert it into the [[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

      +
      2. +
    2. +

      Using the following style sheet properties to show and hide document sections being used to represent the pop-up items, menus or dialogs:

      +
        +
      • display:block
        • +
      • display:none
        • +
      • visibility:visible
        • +
      • visibility: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.

      +
      3. +
    +

    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 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>
    +
    9. +
  9. 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>
    +
    10. +
  10. 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.

    +
    11. +
  11. +

    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.

    +
    12. +
  12. Compensate for Background Images when in High Contrast Mode +

    Authors use background images when styling their widgets, including situations where the background image is not merely decorative, but informative. An example is a horizontal progress bar that it is filled by gradually revealing more of a background image. This is accomplished by initially setting the width of the element to zero, and then incrementing its width in accordance with the degree of progress.

    +

    High contrast mode is an operating system display modification that makes the screen easier to see for low vision users. Some operating systems (e.g., Windows), do not display background images when in high contrast mode. Consequently, the progress bar described above appears empty regardless of the progress. It is recommended that authors not use background images as the sole method to convey important information, and to compensate with alternative or additional style rules.

    +

    In the case of the progress bar example, a technique that works when in high contrast mode is to style the element with a border. Since the width of the element is updated as progress increases, its border gradually expands horizontally forming an ever wider unfilled rectangle. This provides alternative visual feedback as to the extent of the progress.

    +

    Another technique is to replace a background image with text. Consider a dialog that uses a background image for its close box. To compensate for the missing close box when in high contrast mode, a lower case 'x' is used instead. The compensation technique used depends on the context, particularly the purpose of the background image.

    +

    There are two general approaches with respect to detecting high contrast mode. They are (1) executing a script to determine if the system is in high contrast mode, or (2) providing a preference to use alternative styles. The advantage of automatic detection is that some operating systems simply apply a different color palette when in high contrast mode and do not turn off background images. In that case, authors need not compensate for missing background images. However, detection of high contrast mode by script is relatively expensive compared to a preference that users can set, and, presumably, users can see whether background images are displayed in high contrast mode on their system. It is up to individual authors to decide which method they find acceptable for their particular situation.

    +

    The following code fragment outlines how to detect high contrast mode.

    + 
    +/* Define styles for the high contrast test element */
+#hiContrastTestEl {
+    border: 1px solid;
+    border-color:red green;
+    position: absolute;
+    height: 5px;
+    top: -999px;
+    background-image: url('resources/blank.gif');
+}
+…
+// An onload event handler that inserts the high contrast test element and
+// then tests its computed styles.
+function detectHiContrast() {
+    var div = document.createElement('div');
+    div.setAttribute ('id', 'hiContrastTestEl');
+    // … append <div#hiContrastTestEl> to the <body> element …
+    var cs = window.getComputedStyle(div);
+    var bki = cs.backgroundImage;
+    var hiContrast = false;
+
+    // The CSS sets the top and right borders of the test element to red and
+    // green, respectively.  In high contrast mode either the borders are
+    // the same color, or there is no legitimate url to the background image.
+    hiContrast =    (cs.borderTopColor == cs.borderRightColor) ||
+                    (bki != null && (bki == 'none' || bki == 'url (invalid-url:)'));
+
+    if (hiContrast) {
+        // apply hi contrast styles to compensate for missing background images.
+    }
+    // … remove the test element from the document …
+}
    +
    13. +
  13. 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.

    +
    14. +
+
+

Providing Navigable Structure within Web Pages

@@ -492,5 +1935,1602 @@

Miscellaneous XHTML Section Roles

</div>
+ +
+

Other Widget Authoring Practices

+

+ MCK: Setting this content aside to determine whether we will remove or rewrite it. +

+

+ The Common Widget Design Patterns section of this document contains best practices, such as keyboard navigation, for creating common widgets found on the Web. + This section contains miscellaneous authoring practices that you should also consider. +

+
+
Maintain a valid format for aria-valuenow
+

It is essential that application vendors maintain a valid format for +aria-valuenow, and aria-valuenow should +accurately represent the value of the widget.The value must be within range of aria-valuemax and aria-valuemin, where the value of aria-valuemin is less than or equal to the value of aria-valuemax, throughout the life cycle of your widget. If aria-valuemin is not less than or equal to the value of aria-valuemax, or if the aria-valuemax is indeterminate, this creates an error condition that will be handled by +the assistive technology, resulting in undesirable results. Should an alternative text + equivalent be needed to properly represent the aria-valuenow, such as a day + of the week, then you should accompany the aria-valuenow with an appropriate + aria-valuetext equivalent such as in this example:

+
+<div role="slider"
+  aria-valuenow="1"
+  aria-valuemin="1"
+  aria-valuemax="7"
+  aria-valuetext="Sunday">
+
+

+Here the values 1 through 7 represent the days of the week and + aria-valuenow of 1 is equivalent to the first day of the week or Sunday. When aria-valuetext is made available aria-valuenow should also be treated as an index which is 1 based.

+
+
+ +
+

Relationships

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+
+

Labeling and Describing

+

Marked up content or widgets will often need additional context to make clear what the meaning or purpose is. It is also reasonable that some content media types will need additional descriptions in another format to give clarity to those who are unable to consume the origin format. These additional meta-content sections are linked together by tagging them as labels or descriptions. WAI-ARIA provides the aria-labelledby and aria-describedby attributes to signal the browser to feed these relationships into the accessibility layer. This layer is then used by screen readers and other accessibility technology (AT) to gain awareness of how disparate regions are actually contextually connected to each other. With this awareness the AT can then present a meaningful navigation model for discovery and presentation of these additional content sections. The user agent itself can also choose to present these insights in a meaningful way. Generally you should always add these attributes to any widgets on your site as they are often merely a construct of HTML and JavaScript which provides no obvious insight as to what the widget's behavior or interactivity is.

+
+

Labeling

+ When using one element to label another use the aria-labelledby by attribute. A label should provide the user with the essence of what the object does. For example, you could have a dialog box erected from HTML <div> and you need to associate a label for the dialog. With a WAI-ARIA role of dialog, you can indicate its widget type and define a label using an HTML header and then associate that label with the dialog using the aria-labelledby relationship. + 
+  <div role="dialog" aria-labelledby="dialogheader">
+  <h2 id="dialogheader">Choose a File</h2>
+  … Dialog contents
+  </div>
+
+

The section doing the labeling might be referenced by multiple widgets or objects as these need only reference the same id, so contextual description may not always be viable. The labelledby attribute can have multiple ids specified as a space separated list much like applying multiple classes to a single DOM object.

+

The aria-labelledby property can be used to label all visual objects, however it should be noted that (X)HTML provides a @for attribute on the label element which is used to label form controls. Use this attribute where possible and valid. Because the aria-labelledby attribute accepts multiple IDREFs, it is recommended that authors use aria-labelledby for labeling elements that require more than one label string.

+

Some elements receive their label for embedded text content, but that is the exception.

+

Often user agents will operate with images turned off for network performance reasons. In these situations, alt text is provided in the place of the image. When the host language provides alternative text capability it is recommended that authors use the alternative text to support these situations and not use separate labeling as a replacement.

+
+
+

Describing

+
+

Using aria-describedby

+

When one element describes another, use the aria-describedby attribute. An aria-describedby section provides further information about a given object or widget, which may not be intuitively obvious from the context, content or other attributes. For example, a fake window is a common widget used in Web applications and is often constructed using a div absolute positioned in a layer above other content. To simulate common window behavior look and feel there is often an X box in the corner which, when activated, dismisses the window widget. One common way to make this X box is to simply make a link whose content is an X. This doesn't give a non-visual user much to go on and belies the real purpose of the X link. To help we add more descriptive text stored elsewhere in the page like this:

+ 
<button aria-label="Close" aria-describedby="descriptionClose"
+    onclick="myDialog.close();">X</button>
+ and then elsewhere in the HTML + 
<div id="descriptionClose">Closing this window will discard any information entered and
+return you back to the main page</div>
+ Like labelledby, describedby can accept multiple ids to point to other regions of the page using a space separated list. It is also limited to ids for defining these sets. In our contrived example we would also want a good labelledby section to fully explain what the window does and how closing will effect the task being worked on. If an object or widget lacks describedby the user agent or AT may try to extract information from the label or th tags, if present. The label and th tags have limited use in that they can only be applied to forms or tables, respectively. +
+
+

Using a tooltip as a description

+

WAI-ARIA also defines the tooltip role to which aria-describedby may reference an author defined tooltip. The assistive technology can tell from the type of object describing the document element what the purpose of that element is. For example, a screen reader could announce the tooltip without the user having to wave the mouse over the element by following the describedby relationship to a document area with a tooltip role. The aria-describedby property is also useful for describing groups.

+

Here is a code snippet showing a set of the tooltip:

+ 
…
+  <div class="text">
+    <label for="first">First Name:</label>
+      <input type="text"
+          id="first"
+          name="first"
+          size="20"
+          onfocus="tooltipShow(tooltip1);"
+          onblur="tooltipHide(tooltip1);"
+          onmouseover="tooltipShow(tooltip1);"
+          onmouseout="tooltipHide(tooltip1);"
+          aria-describedby="tp1"
+      />
+  <div id="tp1" class="tooltip" role="tooltip">Your first name is optional</div>
+  </div>
+…
+
+
+

Descriptions on external pages

+

The aria-describedby property is not designed to reference descriptions on an external resource—since it is an IDREF, it must reference an element in the same DOM document. This is different from the HTML longdesc attribute, which accepts any URI. In general, the preferred pattern for WAI-ARIA applications is to include all relevant resources in the same DOM, But if you wish to reference an external resource with aria-describedby, you can reference a link that in turn references the external resource. This requires the user to follow two steps, first following the aria-describedby arc, then following the link, but does address the use case. The following example demonstrates this:

+ 
<p>
+   <img
+       src="images/histogram.png"
+       alt="Histogram of Blackberry tree heights"
+       width="40%"
+       aria-describedby="longdesc1"
+   />
+</p>
+
+<p>
+    <a id="longdesc1" href="blackberry-description.html" target="_description">Data for Blackberry Histogram</a>
+</p>
+
+
+

It is not good practice to use the above pattern when the describing element—the <a> tag with @id='longdesc1'—is hidden, since there is no way for a user to navigate to and activate the link. Use the technique only when the description is not hidden.

+
+
+

Owning and Controlling

+

Two relationships expand the logical structure of a WAI-ARIA Web application. These are aria-owns and aria-controls .  The aria-owns relationship completes the parent/child relationship when it cannot be completely determined from the DOM created from the parsing of the markup. The aria-controls relationship defines a cause-and-effect relationship so that assistive technologies may navigate to content effected by and changes to the content where the user is operating.

+
+

The Owns Relationship

+

In addition to WAI-ARIA role and state information, for a document element, +an assistive technology needs to convey its context. In +the case of a treeitem, it is important to know the parent (container), + which may provide a folder depth and the number of siblings in the folder. This containment hierarchy can often be determined by +the DOM tree, as it provides parent, siblings, and children for a given +document element. That said, the DOM hierarchy is rigid and non cyclical in +that each node may only have one parent. In some situations, a child +is reused by multiple parents or a child is separated from its +siblings or parent in the DOM tree. One example is when a radio button +appears in a table but it is not a DOM child of the radiogroup, due to the +authors use of a table for formatting and the placement of the radio buttons +placing them outside the radiogroup container. To solve this problem +WAI-ARIA provides the aria-owns property.

+

+The aria-owns property is set on a document element, and its values are the +unique IDs of all the adopted children. These elements may appear anywhere +in the DOM, yet they are treated as siblings of each owning parent. This +example illustrates a radiogroup that first uses the DOM hierarchy to +convey context and then aria-owns:

+

First, consider the preferred method for using the W3C DOM to describe the relationship between + radiogroup and radio roles for HTML:

+
+<div id="radio_label">My radio label</div>
+<ul role="radiogroup" aria-labelledby="radio_label">
+<li role="radio">Item #1</li>
+<li role="radio">Item #2</li>
+<li role="radio">Item #3</li>
+</ul>
+
+

+In this example, the elements with role="radio" are child nodes of the parent role="radiogroup" element node. + +

+

+Now, consider an alternative method using the aria-owns property to describe the parent-child +role relationship between radiogroup and radio roles for HTML:

+
+<table>
+<tr>
+<td role="radiogroup" aria-owns="myradio1 myradio2 myradio3" rowspan="3" >
+My Radio Label
+</td>
+<td id="myradio1" role="radio">Item #1</td>
+</tr>
+<tr>
+<td id="myradio2" role="radio">Item #2</td>
+</tr>
+<tr>
+<td id="myradio3" role="radio">Item #3</td>
+</tr>
+</table>
+
+

+The aria-owns property should be used sparingly, since it +increases the computational load on assistive technology to provide +alternative renderings. Also, when accessing the DOM and enumerating +children of a DOM node, an AT should then enumerate the adopted children +using the aria-owns property. At that instance of walking the DOM, the +parent of the adopted children is the adopted parent and not the DOM +parent. This will avoid recursion problems.

+

+Each child, adopted or natural, should have the appropriate + aria-posinset and aria-setsize properties set consistent with their +rendering, if these cannot be determined from the DOM from a direct parsing of +the host language. Places where direct parsing does not allow the user +agent to determine + aria-posinset and aria-setsize are long lists where only +the currently visible items are loaded (via Ajax). If the children are +re-sorted then the + aria-posinset and aria-setsize values should be updated +consistent with their visual rendering. Rather than setting size only on a container, content authors should specify aria-setsize on each member of a set to avoid performance issues.  If this property is not set, the user agent must compute and set the property on supporting roles.

+

Platform accessibility API mappings must invert this relationship for + assistive technologies, so that they may determine the owning parent from a + child and couple it with aria-posinset and aria-setsize information to + provide context information to the user.

+
+
+

 Using Owns with Reusable Content

+

If you are re-using content across different, transient sections of content by restyling it to render it in association with a different object, you need to maintain the aria-owns property as well to match the current use and apparent ancestry of the reused sub-section. A good example of this is a context help menu that resides at the end of the document. When the user wishes to launch the context help menu in association with different visual elements, styling is used to render the menu in context with that object. Prior to rendering the visual submenu you should ensure the object to which you have requested help assigns its aria-owns property value to the submenu ID. When the menu closes you can remove the aria-owns property.

+
+
+

The Controls Relationship

+

In rich internet applications document elements may control the behavior on another part of Web page outside themselves. The aria-controls attribute indicates cause-and-effect relationships between document elements.

+

An example might be a group of radio buttons that "control" contents of a listbox in another part of the page. Here, you would want the radio group to assign a aria-controls relationship to the listbox which will be updating without a page reload. The user, through their assistive technology, can then navigate to the listbox by following the aria-controls relationship when a different radio is selected, to see how the contents changed in the listbox. The ability to update parts of a page without a page reload is a common practice of applications making use of Ajax. Without the aria-controls attribute, a user would be unable to effectively use these types of Web pages as assistive technologies often will not make the user aware of what is happening outside the context of the element the user is currently operating.

+

With the aria-controls attribute the user may use the assistive technology to follow the relationship to the object it is controlling. It is extremely important for an assistive technology to present changes in the document in response to user input. Therefore, an assistive technology immediately presents changes to a live region when the controlling widget is the one which has user keyboard focus. For example, if a tree view controls a help document pane, each time
+ the tree item changes the new tree item and then the new help contents should also be read. In the case of a screen reader, the amount of information read in the target live region is dependent on how the live region is configured.

+

The aria-controls attribute takes one or more ids which refer to the document element. If this relationship is not implied by the host language semantics, then the controlling element must be given a controls attribute with the IDs of the other elements where the changes will show up listed in the attribute value.

+
+
+
+

Changing the Reading Flow

+

(X)HTML suffers from a number of disadvantages in keyboard navigation today. One such example is the restriction of navigation to the tabbing order. This is a common problem with presentations in office suites where the logical, perceivable, navigation order of a slide may not match the tabbing order. Sighted users may see a logical navigation process (such as visual steps in the process for assembling a lawn mower). This "flow" is not conveyed by the tab order. The user might tab from step 1 and land on step 4. Another problem is the construction of model-based authoring tools on a Web page. In a model-based authoring tool, a visual object may provide a number of paths that the user can take, such as a multiplexor, which may have output that logically flows to a number of optional electronic components in a drawing. In Web 2.0, developers are actually creating drawings like this to perform tasks such as visually model a work flow. In this scenario, the user will want to decide which object they will navigate their screen reader or alternate input device to next.

+

Although it is recommended that Tab order follow the reading flow, there may be instances where this is not possible. For these reasons, WAI-ARIA provides a relationship property, called aria-flowto. This allows the author to provide an assistive technology with alternative navigation flows through the document that best represents the author's intent and which is more logical for people with disabilities. aria-flowto establishes the recommended reading order of content, so that the an assistive may overriding the default of reading in document order to its user. aria-flowto does not change the keyboard navigation order of the browser.

+

Consider the first case of changing a basic reading flow to circumvent (X)HTML tabbing. A good example of this is a logical reading flow in a portal with landmarks. In the future, the user may wish to change the reading flow based on the order of priority with which they navigate a personalized Web application. In the following example, the navigation would follow the order of "Top News Stories", "television listings", "stock quotes", and "messages from friends" by following (X)HTML document reading order. However, the author or end user may determine that the main content is most important, followed by "stock quotes", "messages from friends", and then "TV listings." The end user can change the order if the web page or assistive technology provides an interface for such personalization.

+ 
<html>
+…
+<div role="main" title="Top News Stories" id="main" aria-flowto="stock"></div>
+<div role="complementary" title="television listings" id="tv"></div>
+<div role="complementary" title="stock quotes" id="stock" aria-flowto="messages"></div>
+<div role="complementary" title="messages from friends" id="messages" aria-flowto="tv"></div>
+

The second use case is such that the Web developer may wish to circumvent the flow by branching to multiple paths in the Web page, requiring the assistive technology to present a collection of options where the user could go next. This is important for work flows or business process management applications. More of these applications are becoming Web based, and a vehicle is required to tell the user how to get through the work flow. The flowto property takes multiple idrefs, allowing the author to define each object the user could flow to. To implement this technique do the following.

+
    +
  • +

    Make each object in the work flow accessible

    +

    This will require assigning a title or WAI-ARIA label for each object and a unique HTML id. Also, if the html element is repurposed assign it a WAI-ARIA role.

    + 
    <html>
+
+…
+<img src="foo.jpg" id="331" title="What is the Invoice Value?">
+<img src="foo.jpg" id="333" title="Finance Manager Approval">
+<img src="foo.jpg" id="334" title="Sales Manager Approval">
+…
    +
    • +
  • Assign the flowto properties +

    For each visual object that will flow to one or more other objects assign the flowto property the list of IDs to which it flows.

    + 
    <html>
+…
+<img src="foo.jpg" id="331" title="What is the Invoice Value?" aria-flowto="333 334">
+<img src="foo.jpg" id="333" title="Finance Manager Approval">
+<img src="foo.jpg" id="334" title="Sales Manager Approval">
+…
    +

    Each element referenced by the flowto must have have a unique id. The combination of the unique id and the name allow the assistive technology to adequately assist the user in retracing their steps backward through a flow to reference or moving forward to it. Since the author sets only the target the user agent is responsible for mapping the backward reference relationship. Therefore, neither the user agent nor the user can get lost. The host user agent does not provide an alternative navigation order; this is an assistive technology function.

    +
    • +
  • Make sure visual objects are keyboard accessible +

    Use tabindex to enable objects to receive focus. Actually setting focus to them may be performed by an assistive technology, such as an alternative input device. This example places each drawing object in document order with respect to the tab sequence.

    + 
    <img src="foo.jpg" id="331" title="What is the Invoice Value?"
+    aria-flowto="333 334" tabindex="0">
+<img src="foo.jpg" id="333"  title="Finance Manager Approval" tabindex="0">
+<img src="foo.jpg" id="334" title="Sales Manager Approval" tabindex="0">
+…
    +

    When an assistive technology encounters "What is the Invoice Value?," it will know to tell the user that they may choose to navigate either to the "Financial Manager Approval" or to the "Sales Manager Approval" object. The options may be provided through a menu for the What is the Invoice Value object by the assistive technology. After a choice is made, then the AT can move focus to the target object; or in the case of a screen reader, it may just move the user to that location in the screen reader's virtual buffer.

    +

    Note: WAI-ARIA does not specify backward flowto properties for the same reason that we do not have the reverse of relationships like labelledby. The author may incorrectly do the reversal, creating a whole set of new problems. Rather, the task of the reversal relationships may be handled by the user agent through its accessibility API mapping or in the assistive technology itself.

    +
    • +
+
+
+

Popups and drop-downs

+

In order for menus, menubars, and menuitems to indicate that it opens a menu, set its aria-haspopup property to "true." The type of menu being launched (submenu, context help, etc.) is not explicitly indicated with WAI-ARIA but is based on the operational characteristics (keyboard and mouse commands).

+

Combo boxes, or drop down lists, work differently. Controls with the role combobox must contain a list of items that can be opened, usually as a drop-down. Because this is intrinsic to the functionality of a combo box, it does not need to be explicitly indicated with aria-haspopup.

+ +

The following html fragment shows the use of aria-haspopup with a menubar, its menus, and submenus. All of the menuitems associated with the menubar have aria-haspopup set to 'true'. Also, the "Zoom" menuitem of the "View" menu has an aria-haspopup property as it leads to a submenu.

+ + 
<div role="menubar">
+  <!--
+    File menu: File menuitem has an aria-haspopup attribute set to 'true'.
+    That popup div follows immediately below.
+  -->
+  <div role="menuitem" aria-haspopup="true" id="fileMenu">File</div>
+  <div role="menu" aria-labelledby="fileMenu">
+    <div role="menuitem">Open</div>
+    <div role="menuitem">Save</div>
+    <div role="menuitem">Save as …</div>
+    …
+  </div>
+  <!--
+    View menu:
+  -->
+  <div role="menuitem" aria-haspopup="true" id="viewMenu">View</div>
+  <div role="menu" aria-labelledby="viewMenu">
+    <div role="menuitem">Normal</div>
+    <div role="menuitem">Outline</div>
+    <!--
+      The View's Zoom menuitem has aria-haspopup='true' as it leads to a
+      submenu.
+    -->
+    <div role="menuitem" aria-haspopup="true" id="zoomSubMenu">Zoom</div>
+    <div role="menu" aria-labelledby="zoomSubMenu">
+      <div role="menuitem">50%</div>
+      <div role="menuitem">75%</div>
+      <div role="menuitem">100%</div>
+      <div role="menuitem">150%</div>
+      <div role="menuitem">200%</div>
+    </div>
+  </div>
+</div>
+
+
+ +
+

Managing Dynamic Changes

+

This section has had only minor edits since it was integrated from APG version 1.0 -- a complete APG task force review is pending.

+
+

Managing Content and Presentational Changes

+

General rules for managing content and displaying information

+
    +
  • Do not change an element's role once it has been set. If you need to change the role of an object, first remove the element from the DOM tree and then add the new element to the tree with the new role set.
    • +
  • For supporting browsers, tie CSS attribute selectors to WAI-ARIA properties to reduce script (browser issue with refresh).
    • +
  • Tie CSS display property to WAI-ARIA hidden state. This is important for assistive technologies who communicate directly with the user agent's DOM versus a platform accessibility API supported by the user agent. You can also tie CSS visibility:hidden or visibility:collapse to the WAI-ARIA hidden state but the use of visibility:hidden will affect layout in that content will continue to flow around the hidden area even though the content to be hidden is invisible.
    • +
+

If you are refreshing areas asynchronously, then you need to designate live regions. The following sections explain how to implement live regions and when to use roles that are considered "live" sections by default, including alert, status, or log.

+
+
+

Implementing Live Regions

+

Live regions are parts of a Web page that the author expects to change. Examples of live regions include dynamically updated content (sports stats, stock information), logs where new information is being added (chat transcript logs), notification areas (status, alerts), etc.

+

Live regions enable assistive technologies, such as screen readers, to be informed of updates without losing the users' place in the content. Live region settings provide hints to assistive technologies about how to process updates. Note that the assistive technology is responsible for handling these updates and enabling users to override these hints.

+

The section on Live Region Properties and how to use them gives the details of how to apply live region properties. This process will help rich internet application (RIA) developers to set live region settings that will provide a good user experience for most assistive technology users with little configuration on their part. When applying these live region properties, it is recommended that you conduct user testing. If the AT supports scripting of the response to live regions you may wish to customize the response, such as through a screen reader script for your Web page.

+
    +
  1. +

    Identify the live regions

    +

    Live regions are any region on a page that receives dynamic updates through client-side scripting. Note the regions of your page that will be live.

    +
    2. +
  2. +

    See if any of the special case live regions meet your needs

    +

    WAI-ARIA provides a number of special case live region roles whose live region properties are pre-defined and which you may use. If one of these live region roles meet your needs just apply the specific role to the region of the Web page.

    +
    3. +
  3. +

    Decide the priority of each live region

    +

    When a live region changes, should the user be notified of the change? Notifications could include a sound for a screen reader user. (For simplicity, we will use the case of an audio notification in this discussion.) The shorter the interval between changes and the less important the information, the less likely that the user needs to hear every change. A simple example of changes that should not be heard are changes to time; a sound for every second would be very annoying.

    +

    If the user should hear the change, should the change be announced immediately, as soon as possible, or only when the user is idle? Announcing a change immediately can be disorienting for users, so that should be done sparingly. Most updates should probably only be announced when the user is idle.

    +

    After you have decided the priority for each live region, then decide the live property value:

    + +
    4. +
  4. +

    Decide how much context is needed for each update

    +

    When part of a live region changes, how much context is needed to understand the change. Does the user need to hear the entire live region or just the change by itself?

    +

    If the user needs to hear the entire live region, then mark the entire live region with aria-atomic="true".

    +
    5. +
  5. +

    Decide what types of changes are relevant for each live region

    +

    Three possible types of changes are: additions, removals, and text. Additions means new nodes are added to the DOM; removals means nodes are removed from the DOM; and text means changes are solely to the textual content. Should the user hear all types of changes or only certain types?

    +

    By default, the user will hear additions and text type changes. If you wish to explicitly define the types of changes, you need to set relevant="THE_TYPES_OF_CHANGES". If more than one type of change is relevant, the types are separated by a space. For example, to define additions and removals as relevant but not text, set relevant="additions removals".

    +
    6. +
+
+

Live Region Properties and How to Use Them

+

One of the most important concepts behind live regions is politeness. Politeness indicates how much priority a live region has. The following politeness values are available for aria-live: off, polite, and assertive.

+
+
aria-live="off"
+
This is the default. Any updates made to this region must not be announced to the user. live="off" would be a sensible setting for things that update very frequently such as GPS coordinates of a moving vehicle.
+
aria-live="polite"
+
Any updates made to this region should only be announced if the user is not currently doing anything. live="polite" should be used in most situations involving live regions that present new information to users, such as updating news headlines.
+
aria-live="assertive"
+
Any updates made to this region are important enough to be announced to the user as soon as possible, but it is not necessary to immediately interrupt the user. live="assertive" must be used if there is information that a user must know about right away, for example, warning messages in a form that does validation on the fly.
+
+

There are times to suppress AT presentation changes while a region is updating. For that you can use the aria-busy property.

+
+
aria-busy="true"
+
+

To suppress presentation of changes until a region is finished updating or until a number of rapid-fire changes are finished, set aria-busy="true" and then clear the attribute when the region is finished. While it is busy, the AT will track and collate the changes. It will finally speak the changes once the region is no longer busy.

+
+
+

When a live region is updated, the update can often be announced on its own and still make sense. For example, if a news headline is added, it would make sense to simply announce the headline. However, sometimes the entire live region must be read in order to give the user enough context to make sense of the update. For example, it would not make sense to only give the current value of a stock without saying the name of the stock. The atomic setting gives assistive technologies a hint about which of these cases an update falls into.

+
+
aria-atomic="false"
+
This is the default. It means that when there is a change in the region, that change can be presented on its own; the AT should not present the entire region. atomic="false" is generally a good idea as it presents users with only changes and does not cause them to hear repetitive information that has not changed. However, Web developers should take care that the changed information, when presented by itself, can still be understood and contextualized by the user.
+
aria-atomic="true"
+
If atomic is set to "true", it means that the region must be presented as a whole; when there is a change, the AT should present the entire region, not just the change. atomic="true" can make it harder for users to understand changes as the changed areas are not presented independently. atomic="true" can also be annoying as it can force users to listen to repetitive information that has not changed. However, atomic="true" is necessary in cases where the change, when presented by itself, cannot be understood and contextualized by the user. Note that when aria-atomic="true", the AT will attempt to speak the atomic region only once when multiple changes occur in the same region and it hasn't been spoken yet.
+
+ Not all updates to a live region are relevant. For example, if the oldest headline in a list of headlines is removed and a new headline is added, the removal of the oldest headline is probably not important enough to announce to the user. However, in a chat application, when a user leaves the chat and their username is removed from the list of users, that removal may be important enough to announce. The relevant setting gives a hint about what types of changes are relevant and should be announced. Any change which is not relevant will be treated as if the region had live="off" and will not be announced. Multiple types of changes can be listed as relevant; the types are separated by a space. The default is relevant="additions text" and this is the most common use case. If the default is applicable to your application, you do not need to provide the relevant property explicitly. +
+
aria-relevant="additions"
+
Insertion of nodes to the live region should be considered relevant.
+
aria-relevant="removals"
+
Removal of nodes to the live region should be considered relevant. + Often, removals are not relevant because nodes are removed to make space for new information - e.g. a log implemented as a table where items are taken off the top. However, in the case of something like a buddy list, it is relevant if a buddy is removed. It doesn't require the screen reader to speak the removal, but it notifies the screen reader that it could be useful to do so. Use of aria-relevant="removals" or aria-relevant="all" should be used sparingly. Notification of an assistive technology when content is removed may cause an unwarranted number of changes to be notified to the user.
+
aria-relevant="text"
+
Changes to the textual content of nodes that already exist in the live region should be considered relevant. Textual content includes text equivalents, such as the alt attribute of images.
+
+

This example shows two live regions. If both regions update simultaneously, liveRegionA should be spoken first because its message has a higher priority than liveRegionB.

+
+ 
<div id="liveRegionA" aria-live="assertive">
+</div>
+<div id="liveRegionB" aria-live="polite>
+</div>
+
+
+
+
+

Choosing Between Special Case Live Regions

+

You may wish to use a special live region role instead of applying live region properties. WAI-ARIA contains a number of standard roles which are by default considered "live" sections of your Web page. It is important to know when to use these and when to create a custom live region on your known. Here are some rules of thumb:

+
+

alert - You may use the alert role for a one-time notification which shows for a period of time and then goes away. It is intended to alert the user that something has happened. The assistive technology should be notified by the user agent that an alert has occurred, if your operating system supports this type of event notification. When choosing to use alert you should use the alertdialog role instead if something inside the alert is to receive focus. Both alert and alertdialog usually appear to pop-up to the user to get their attention. Unless specified otherwise an alert region has an implicit aria-live of "assertive" and aria-atomic of "true".

+

status - You may use the status role when you want to mark an area which is updated periodically and provides a general status of your Web application. Many applications provide status widgets and they are often found, visibly, at the bottom of the application and contain a variety of widgets within it to convey status. Unless specified otherwise a status region has an implicit aria-live of "polite" and aria-atomic of "true".

+

timer - You may use a timer role when you want to mark an area which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The text encapsulated within the timer indicates the current time measurement, and is updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point. The timer role has an impicit aria-live of "off".

+

marquee- You may use a marquee role when you need to mark an area with scrolling text such as a stock ticker. The latest text of the scrolled area must be available in the DOM. A marquee behaves like a live region, with an implicit aria-live property value of "off."

+

log - You may use log if you have a live area where new information is added, like a scrolling chat log of text. Unlike other regions, implied semantics indicate the arrival of new items and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. Log has an implicit aria-live of "polite"If you have a chat text entry area you should indicate that it also controls the aria log aria like so:

+ 
<div contenteditable="true" role="log" id="chatlog">
+</div>
+
+
+<label id="gettext">Send Text</label>
+<div aria-controls="chatlog"
+     role="textbox"
+     contenteditable="true"
+     aria-labelledby="gettext">
+</div
+

live region - If you have some other live area use case, WAI-ARIA allows you to mark an area using the aria-live attribute. This, accompanied by the collection of attributes which support the live property, allows you to create your own custom live area on your Web page. For more details regarding live regions refer to the live region section of this guide.

+
+

Live region roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. It is recommended that authors apply live regions to DIV and SPAN containers. For example:

+ 
<!-- Live region 'log' role used with TABLE element:  the 'log' role is not consistently mapped to platform AAPI. -->
+<!-- Do not use. -->
+<table role="log" … >
+  …
+</table>
+
+<!-- Wrap the TABLE element in a DIV with role 'log' instead: -->
+<div role="log" … >
+  <table … >
+    …
+  </table>
+</div>
+
+ +
+
+ +
+

Presentation Role

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

This section describes the presentation role, including the conditions under which it is inherited by an element's children.

+
+

Rationale

+

Authors devote a good deal of effort to the appearance of their web pages, and this is especially true in the case of scripted web applications. To this end authors employ various elements purely for visual presentation. For example, <img> elements are used for spacing and decoration; and <table>s are used to create a column based layout. Elements used strictly for presentation are semantically neutral and irrelevant in terms of accessibility. It is necessary to mark such elements as presentational so that they do not appear in the accessible tree created by the user agent. For example, a current technique used with spacer images is to provide blank alt text to indicate that the image is not meaningful. User agents will not publish any information about images with blank alt text to the platform accessibility API.

+

There are elements other than <img> and <table> that are used solely for visual presentation. Any element is a potential candidate for presentation, and, if so used, these elements also need to be marked as semantically neutral.

+

It is important to separate content and presentation. CSS 3 has introduced new table layout functionality to allow a user agent to layout content using CSS. There are many advantages to using this feature of CSS such as browser style sheet caching and improved adaptability to mobile devices with limited screen real estate. There are, however, cases where presentational markup cannot be avoided. In such instances, authors are counseled to consult WCAG 2.0 for more detailed guidance.

+

WAI-ARIA introduces the presentation role as a general device for marking elements as presentational. The presentation role overrides the element's native implicit role, and informs the user agent to not publish the element to the accessibility API. In fact, the preferred way to mark <img> elements as decorative is to use a role="presentation" attribute instead of (or in addition to) an empty alt attribute. Here is a code fragment sample:

+ +
<!-- [role="presentation"] informs the user agent that the spacer images are for layout only. -->
+…
+<h2>Other Histories of Architecture</h1>
+<p>
+  <a href="www.somewhere.com">Ancient Roman Architecture</a>
+  <img src="spacer.png" role="presentation">
+  <a href="somewhere.else.com">19th Century Italian Architecture</a>
+  <img src="spacer.png" role="presentation">
+  <a href="www.elsewhere.com">Modern Buildings more than 100 Years Old</a>
+</p>
+
+<h2>Modern Building Design</h1>
+…
+
+

The resulting accessible tree is shown below. Note that none of the spacer <img> elements are present:

+
    +
  • root +
      +
    • …
      • +
    • h2 +
        +
      • [text] Other Histories of Architecture
        • +
      +
      • +
    • p +
        +
      • a +
          +
        • [text] Ancient Roman Architecture
          • +
        +
        • +
      • a +
          +
        • [text] 19th Century Italian Architecture
          • +
        +
        • +
      • a +
          +
        • [text] Modern Buildings more than 100 Years Old
          • +
        +
        • +
      +
      • +
    • h2 +
        +
      • [text] Modern Building Design
        • +
      +
      • +
    • …
      • +
    +
    • +
+
+
+

Inheritance of Presentation by Parent Element's Children

+

In general, the presentation role is not inherited by an element's children. The exceptions are elements whose role entails that the element has required owned children. Examples include the <table> element and list role, and these exceptions are discussed further below. For all other elements, only the element marked presentational is eliminated from the accessible tree. Note, however, that its contents are published; in particular, the element's textual content is published, but any attributes of the element that may form a text-equivalent are not. For example, a header element with a presentation role would not appear in the accessible tree, but its text does. An image with a role of presentation is not exposed in the accessible tree, nor is the contents of its alt attribute. This is shown in the following code fragment:

+ +
<!-- 1. [role="presentation"] negates the implicit 'heading' role semantics but does not affect the contents. -->
+
+<h1 role="presentation">Presentation role overrides Header role</h1>
+<h1>Another header</h1>
+
+<!-- 2. [role="presentation"] hides the image from the accessibility API and does not publish the alt attribute contents. -->
+
+<img role="presentation" alt="This text will not appear in the Accessibility API" src="…">
+
+
+

The first header element is absent from the accessible tree for the above example, but its text appears. The second header element is present as a heading. The img element is not exposed at all:

+
    +
  • root +
      +
    • …
      • +
    • [text] Presentation role overrides Header role
      • +
    • h1 +
        +
      • [text] Another header
        • +
      +
      • +
    • …
      • +
    +
    • +
+

Be aware that the markup <img role="presentation" alt="non-empty alt text"…> is in fact contradictory: Declaring a role of presentation says that the image is for layout, is decorative and meaningless, whereas the non-empty alt text implies that the image is meaningful. It is recommended that authors instead use empty alt text (alt="") where they use role="presentation".

+

Earlier it was noted that the presentation role is not generally inherited by an element's children. The exception are roles that have required owned elements. Examples include the <table> element, and the list and tree roles. A list is required to have listitem children; a tree, treeitem children. The <table> element's child components are <tbody>, <thead>, <tfoot>, <th>, <tr>, <td>, and <caption>. These component elements would not appear in the markup without the enclosing <table> root element. Thus, when a table is used for layout, it follows that all of its component elements are present in the markup for layout as well. Since annotating all the required child elements with role="presentation" is error prone and difficult to maintain, it is sufficient to mark the table root element as presentational. The presentation role propagates to all the table component elements. However, as before, the contents of the table elements do appear in the accessible tree. Here is an example:

+ +
<!-- Layout table marked with [role="presentation"]. -->
+
+<table role="presentation">
+  <tbody>
+    <tr> <td>Some text</td> <td><p>Paragraph</p></td> </tr>
+    <tr> <td><a href="www.somewhere.com">Link text</a></td> <td><img src="meaningful.jpg" alt="meaningful image"></td> </tr>
+  </tbody>
+</table>
+
+

All table specific elements (table, tr, td, etc.) are eliminated from the tree by inheriting the presentation role, but other elements and textual content in the table cells are exposed:

+
    +
  • root +
      +
    • …
      • +
    • [text] Some text
      • +
    • p +
        +
      • [text] Paragraph
        • +
      +
      • +
    • a +
        +
      • Link text
        • +
      +
      • +
    • img +
        +
      • [name] meaningful image
        • +
      +
      • +
    • …
      • +
    +
    • +
+

The same logic applies to other roles that have required owned children, such as a list. If the list's root element is declared presentational using role="presentation", all of its listitem elements inherit the presentation role, and none of the list item elements appear in the accessible tree. However, the contents of each list item, that is, other elements and textual content, are included in the tree.

+
+
+

Overriding Presentation

+

The presentation role is overridden in some circumstances. Recall that the presentation role informs user agents that certain elements are semantically neutral, and are irrelevant for accessibility. If, however, there is an aspect of an element that makes it meaningful, it is no longer neutral, and cannot simultaneously be presentational. The Core Accessibility API Mappings describes the cases where this occurs:

+
    +
  • element is focusable.
    • +
  • element has a global WAI-ARIA attribute, other than aria-hidden.
    • +
  • element is referenced by another element's aria-controls, aria-describedby, aria-flowto, aria-labelledby, or aria-owns property.
    • +
  • element normally inherits presentation from a parent, but the element explicitly declares a role other than presentation. +
      +
    • E.g., a table cell, <td>, within a <table role="presentation">, where that cell is marked with a button role: <td role="button" …> -- the cell has a role of button, not presentation. +
      • +
    +
    • +
+

These situations entail that the given element is semantically relevant and will appear in the accessible tree. Marking the element with a role="presentation" is an error, and user agents will ignore the presentation role in these cases. Authors are advised to not mark an element with a role of presentation when it has any of the above properties; rather, to use a role that reflects the element's purpose.

+
+
+ +
+

Form Properties

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

+This section identifies authoring practices for elements used as form elements. +

+
+

Use aria-invalid and aria-required To Improve Access to Forms

+

+Until the introduction of WAI-ARIA's aria-invalid state and aria-required property, only presentational strategies have been available to Web content authors to indicate that certain form fields and controls are required or invalid. In applications, these states are only available through styling or varying markup, which is inconsistent, and therefore is inconclusive. In Web-based forms, fields required may be marked by an asterisk. Forms submitted with required data missing or improperly specified may be redisplayed with the unacceptable elements highlighted in red. The assistive technology user is poorly served by such imprecise methods, and all users confront inconsistent indicators for consistent situations. +

+

+The WAI-ARIA invalid state and required property provide: +

+
    +
  • +A programmatic aria-required property that can be applied to a form element to indicate to an AT that it is required to complete the form. +
    • +
  • +A programmatic aria-invalid state that can be used to indicate which data fields have incorrect data to an AT so that the user knows they have entered invalid data. Invalid data is often rendered in red by HTML form developers. +
    • +
+

Alert the User When Maximum Length Value Is Reached

+

When a text input field that has a maximum length value (or the host markup language's equivalent) receives focus, the value defined for +"maximum length" should be communicated to the user. When text entry reaches that maximum length (or the markup language's equivalent), an alert (expressed in accordance with user preferences and capabilities) should inform the user that the maximum length for a given field has been reached. Such an alert can be expressed programmatically or, using as an aural icon, by using a WAI-ARIA alert; the user agent may alert the user through a system beep and by triggering the operating systems' "show sounds" facility. When maximum length (or the markup language's equivalent) is reached, the user must then be able to move to another form field in a manner consistent with tab-navigation for that document.

+
+
+

Automatic Focus Changes

+

Having a user agent automatically change focus in a form in response to user input can be advantageous in situations where that change saves the user keystrokes or on-screen keyboard interaction in order to manually move the focus from one field to another. However, as with form auto-completion, this type of text input event must be firmly under user control because this may not have been the user's intention and some users with disabilities may become disoriented such as those with sight impairments. Consider these cases:

+
    +
  • For a text input field that automatically moves focus to a new +field when the value defined for "maximum length" (or the markup language's +equivalent) is reached, the user must have the ability to suppress the change in focus. Otherwise, the user's assistive +technology may not be able to make the user aware of the error.
    • +
  • +A textarea field that has a scripted counter to display the number +of characters entered or the number of characters available for input; +in this case, the dynamic content (the character count) must be owned +by the textarea as a live region, so that the user can keep either a +running (real-time) account of how many characters are left for him +to input or can obtain such information on user query.
    • +
+
+
+

Form Auto-submit

+

Use caution when using automatic submission of a form without explicit user command or +in response to a user-defined setting that permits such behavior, as +expressed by the Priority 1 UAAG 1.0 Checkpoints + 7.1, + 7.2 and + 11.1. +Unless the user has specifically chosen to set the user agent to allow auto-submission, authors are advised not to set onChange or onFocus events either to trigger submission of a form or to provide an auto-submission event upon +completion of all or all required fields of a form or input +field.

+ +
+ +
+ +
+

Math

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

Editors' note: This section was added as part of disposition of comment 4, but is very incomplete. The section needs to be reordered, so that instructions on how to use the math role properly appear before considerations of legacy content and negative examples (such as the use of generic HTML to approximate a visual representation of a mathematical expression). It needs more introductory text about how to use math. The examples need better introductions, and the positive examples should preceded the negative examples, which need to be explained more fully.

+

There exists significant amounts of legacy content that uses images + and/or textual approximations to represent mathematical expressions. + Examples of this include the use of ASCII art and/or the misuse of + HTML tags -- in particular, SUB and SUP -- to achieve a visual + approximation of a mathematical expression, one which is void of + the structure needed to render mathematical expressions inherently + meaningful.

+

Use of generic HTML to approximate a visual rendering + of a mathematical expression:

+

<i>a</i><i>x</i><sup>2</sup> + <i>b</i><i>x</i> + <i>c</i> = 0

+

Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

+ 
<div role="math" aria-label="a times x squared plus b times x plus c equals 0">
+  <math xmlns='http://www.w3.org/1998/Math/MathML'>
+    <mrow>
+      <mrow>
+         <mrow>
+            <mi>a</mi>
+            <mo>&#x2062; <!-- invisible times --></mo>
+            <msup>
+              <mi>x</mi>
+              <mn>2</mn>
+            </msup>
+         </mrow>
+         <mo>+</mo>
+         <mrow>
+            <mi>b</mi>
+            <mo>&#x2062; <!-- invisible times --></mo>
+            <mi>x</mi>
+         </mrow>
+         <mo>+</mo>
+         <mi>c</mi>
+      </mrow>
+      <mo>=</mo>
+      <mn>0</mn>
+    </mrow>
+  </math>
+</div>
+

Similarly:

+

+<i>f</i>(<i>x</i>) + = <i>x</i><sup>2</sup> + <i>x</i> - 2 +

+

Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

+

Todo: add aria-label here also

+ 
<div role="math">
+  <math xmlns='http://www.w3.org/1998/Math/MathML'>
+    <mrow>
+      <mrow>
+         <mi>f</mi>
+         <mo>&#x2061;</mo>
+         <mrow>
+            <mo>(</mo>
+            <mrow>
+               <mi>x</mi>
+            </mrow>
+            <mo>)</mo>
+         </mrow>
+      </mrow>
+      <mo>=</mo>
+      <mrow>
+         <msup>
+           <mi>x</mi>
+           <mn>2</mn>
+         </msup>
+         <mo>+</mo>
+         <mi>x</mi>
+         <mo>&#x2212;</mo>
+         <mn>2</mn>
+      </mrow>
+    </mrow>
+  </math>
+</div>
+
+ +
+

Drag-and-Drop Support

+

aria-grabbed and aria-dropeffect have been deprecated in ARIA 1.1 - as such this section has been removed. Advice for implementing drag and drop will be added to a future version of the Authoring Practices Guide.

+ +
+ +
+

Reusable Component Libraries

+

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

+

Rich internet applications are complex to author. To save time, it is often faster to use existing widget libraries that implement WAI-ARIA and that have already gone through:

+ +

Some publicly available UI component libraries have already implemented WAI-ARIA. Authors can reuse such libraries to start developing accessible rich internet applications.

+
+ +
+

Appendices

+ +
+

Background on WAI-ARIA

+

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

+

According to the SecuritySpace Technology Penetration Report, more than 55% of all Web sites today contain JavaScript, dramatically affecting the ability for persons with disabilities to access Web content. New Rich Internet Applications (RIAs) render custom widgets, modeling rich desktop components to perform UI updates without having to reload the entire page - much like a graphical user interface (GUI). Legacy GUI accessibility frameworks address these issues through a comprehensive accessibility application programming interface (API) and infrastructure to foster interoperability with assistive technologies. These APIs constitute a contract between applications and assistive technologies, such as screen readers, to enable them to access rich dynamic content with the appropriate semantics needed to produce a usable alternative. No such contract exists between modern RIAs and assistive technologies, creating an accessibility gap for persons with disabilities.

+

Unfortunately, HTML and other markup languages do not provide adequate + support for accessible dynamic content. Until now, the W3C WAI has discouraged the use of JavaScript per [[WAI-WEBCONTENT]], Checkpoint 6.1). + A + number of W3C initiatives underway address this problem using + a declarative markup approach. This primer describes a means to + bridge the interoperability problem with assistive + technologies now by incorporating the appropriate metadata into + current HTML and XHTML markup to support today's accessibility APIs. Moreover, the primer provides web developers with a conceptual understanding of WAI-ARIA as a prelude to using the [[WAI-ARIA]]. WAI-ARIA brings advanced accessibility features of the desktop to the web through the creation of cross-cutting technologies that + (X)HTML authors can incorporate in their markup. WAI-ARIA defines roles, states, and properties, where those roles reflect standard GUI elements that are recognized by accessibility Application Programming Interfaces (APIs). These metadata that describes these + GUI widgets and document structures aides assistive technology + vendors in providing accessible, usable solutions. The W3C WAI PF working group is working with User Agent manufacturers, assistive + technology vendors, and accessibility tool providers, to ensure an end-to-end working solution.

+

For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Primer is part of a set of resources that support the WAI-ARIA specification. The Primer provides a basic introduction to the concepts behind and reason for WAI-ARIA, and the WAI-ARIA Authoring Practices describe recommended usage patterns for Web content developers. The WAI-ARIA Suite fills gaps identified by the [[WAI-ARIA-ROADMAP]]. These documents serve as important places of clarification where topics appear to be unclear.

+
+

The Problem

+

Aspects of traditional Hypertext Markup Language (HTML) make accessible support of dynamic content difficult:

+
    +
  1. Accessibility of dynamic content relies on abstracting semantics from both content and presentational information. Extracting semantic cues from current HTML content is typically unreliable as the cues are limited to tag elements names.
    2. +
  2. While HTML allows content to be repurposed for presentational formatting, it lacks the ability to attach meaningful metadata about document structure and to convey semantic information. A common example of this is content formatted with tables rather than style sheets.
    3. +
  3. When combined with script and cascading style sheets (CSS), HTML can be repurposed to create dynamic custom components without providing a means to convey semantic information to native accessibility architectures designed to support dynamic graphical user interface (GUI) content.
    4. +
  4. Custom components built from common HTML elements often are not keyboard accessible.
    5. +
+

Authors of JavaScript-generated content do not want to limit themselves to using standard tag elements that define the actual user interface element such as tables, ordered lists, etc. Rather, they make extensive use of elements such as DIV tags in which they dynamically apply a user interface (UI) through the use of style sheets and dynamic content changes. HTML DIV tags provide no semantic information. For example, authors may define a DIV as the start of a pop-up menu or even an ordered list. However, no HTML mechanism exists to:

+
    +
  • Identify the role of the DIV as a pop-up menu
    • +
  • Alert assistive technology when these elements have focus
    • +
  • Convey accessibility property information, such as whether the pop-up menu is collapsed or expanded
    • +
  • Define what actions can be formed on the element other than through a device-dependent means through the event handler type (onmouseover, onclick, etc.)
    • +
+

In short, JavaScript needs an accessibility architecture to write to such that a solution can be mapped to the accessibility + frameworks on the native platform by the user agent.

+

The following diagram illustrates a typical document object model (DOM) node in + a Model-View-Controller architecture. Accessibility information surfaced to assistive technologies is provided only by the HTML element's tag name, with only the accessibility attributes that tag can provide.

+

shows that on the node, data, or the + "Model", which should include semantic information, is separated + from the user interface presentation, the "View." Here, the + document element is managed by the user agent based on the default + behavior of the element. The user agent's default behavior at the + document element forms the controller.

+
+ Accessibility information mapped to a DOM element in the Document Object Model +
Accessibility Interoperability at a DOM Node without JavaScript
+
+

The box between the DOM node + and the assistive technology contains the contract + provided by the user agent to the assistive technology. This data + includes typical accessibility information found in the + accessibility API for many accessible platforms for GUIs + (role, state, caret, selection, text, hypertext, name + description, parent/child information, parent/child + information, and relations). For HTML and other W3C markup, the + accessibility information provided solely depends upon what the element's tag name and any accessibility attributes that map to that tag provides. For example, the accessible role of a table is table. The author provides an accessible description by assigning a title attribute.

+

In contrast, with JavaScript, user actions can trigger updates in the data and presentation, but the default accessibility information available in the element tags is no longer valid.

+
DOM Element with JavaScript controller +
Accessibility + Interoperability at a DOM Node with JavaScript
+

shows the same DOM node provided + in Figure 1.0 but with JavaScript acting as the new controller. + JavaScript overrides the default user agent behavior at the DOM + node. It manipulates the data, content, and style in response to + events caused by user interaction to produce custom widgets. In + this situation, the default accessibility information is no longer + valid and, therefore, the contract is now invalid. Figure 2.0 shows + the contract with asterisks in front of role, state, actions, + value, event changes, and relations. These asterisks represent + potential accessibility errors and gaps in the base markup. These + gaps result from the author's inability to provide the new semantic + data needed to support the contract.

+
+
+

Requirements

+

Any solution to facilitate the creation of accessible rich Internet applications (RIAs) must:

+
+
Allow for discovery of custom UI components + through the use of Semantic Web technologies
+
Web ontologies allow for storage of semantic information about + objects and how they relate to others in the ontology.
+
Support today's accessibility + architectures
+
Accessibility architecture today is centered around object + technology. Each object in an application or document exposes + its accessible properties to an assistive + technology.
+
Allow for separation of content and + presentation
+
Dynamic content authors must be able to store the accessible + meta data in the document independent of how it is rendered.
+
Allow for passive monitoring of the application + by an assistive technology
+
Assistive technology vendors should not be required to poll an + application for changes in accessibility information.
+
Leverage new W3C efforts to solve the + problem
+
This problem needs to be solved quickly. A number of + efforts are underway, such that minimal changes may be required to + bring them to the level needed.
+
Be light weight
+
The solution needs to be light-weight in order to promote adoption by Web authors.
+
Scaleable
+
The solution needs to be scalable; it must make simple things + easy while making complex things possible.
+
Internationalizable
+
Like other Web solutions, our solutions must be + internationalizable.
+
Guarantee user agent support up front
+
User agent manufacturers must be involved up front to ensure support for the solution when the specification is complete.
+
Involve assistive technology vendors up + front
+
To ensure interoperability, assistive technology vendors need to be involved from day one. + The effort must leverage support by AT vendors to ensure that a + total solution is available when the specification is complete.
+
Produce Developer Guidelines during the + process
+
This is a critical mistake made by people creating a new + accessibility model. Developers must be engaged early on so that + they can contribute feedback and start producing workable solutions + early.
+
+
+
+

Solution

+

What is clear from the problem statement is that developers of dynamic web content cannot provide the appropriate accessibility information in the markup to support the accessibility APIs on the target platform. This problem is not limited to HTML. It extends to other markup, including Scaleable Vector Graphics [SVG]. This primer addresses the problem for web content delivered to desktop browsers and introduces you to common extensions to both HTML and XHTML called [[WAI-ARIA]]. The goal is to make these standard features in HTML 5.

+
+
+

HTML Accessibility API Support Analysis

+

Using as a template for addressing the + problem and U.S. Section 508 accessibility standards, Table 1.0 illustrates gaps + in the infrastructure and identifies W3C standards that should be used to + address the problem. In the right column, table cells that are empty + or that indicate a limitation represent accessibility gaps in HTML + and XHTML.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Table 1.0 Platform Gap Analysis + for Accessible Dynamic Web Content for HTML and XHTML +
Required ComponentsWho does what today? (HTML)
Events: 
FocusChangeDOM 2, 3 events
ActivationUser Agent API
Caret ChangeUser Agent API
Value Change 
State Change 
Selection ChangeUser Agent API
MutationDOM Events
Accessible + Actions: 
Event Handler functional information to label the actions 
Access to the available event + handlers for enumerating the actions 
State Information: 
Role Information:Limited to standard HTML tag names. (Mix + Content/presentation)
Relationships: Parent/childLimited DOM (affected by style) (Mix Content/presentation)
Relationships: (Label, MemberOf - Group, + ControllerFor)Limited to HTML (Title, alt, label)
TextCore DOM from parsed HTML
Content selection:Browser-dependent (incomplete)
Font/Font Style Information:Can set but can't get final format
Description/Help:Limited to HTML 4.0 - Alt Text, title text
Accessible value:Limited to form elements
Coordinates (Bounding rectangle, etc.):User Agents. platform accessibility API
Accessible Name: 
Respond Desktop Font/Color + Changes:Partial (conflicts with CSS and JavaScript)
Device independent navigation: 
Accessibility API Mapping:Partial - User Agents
Provide focus to all active elements (important for + equivalent keyboard access on desktops)Limited to forms and anchors
+
+
+ +
+

Filling the Gaps for Content Delivered to Desktop Browsers

+

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

+

At this time,W3C WAI Protocols and + Formats working group's primary focus is on extensions to HTML 4.01 and XHTML 1.X by extending the host language to include WAI-ARIA with a migration path to HTML 5. This will require the creation of new hybrid document type definitions (DTDs) that incorporate the extensions. This work will be in the [[WAI-ARIA]] specification. WAI-ARIA will constitute + extensions to fill most of the gaps needed to support + accessibility API infrastructures and dynamic (X)HTML content. The comprehensive gap analysis of (X)HTML, used to form WAI-ARIA is found in Table 1.0 and how WAI-ARIA fills those gaps. In the future we hope to incorporate WAI-ARIA into many host languages to improve their accessibility. The critical extensions needed to make accessible dynamic Web content accessible, through rich interoperability with assistive technologies, + are summarized here:

+
+

States, and Property attributes - This is the set of attribute modifications to (X)HTML necessary to provide full keyboard focus and states and properties that may be mapped directly or indirectly to platform accessibility APIs to ensure full interoperability with assistive technologies for WAI-ARIA.

+

Role attribute - The role attribute, borrowed from the, [[ROLE-ATTRIBUTE]], allows the author to annotate host languages with machine-extractable semantic information about the purpose of an element. It is targeted for accessibility, device adaptation, server-side processing, and complex data description. WAI-ARIA uses the role attribute to provides the role information, in to an assistive technology.

+

Role document landmark values - These values, borrowed from the [[ROLE-ATTRIBUTE]] provides a standard set of role attribute values designed to define pertinent parts of a document (landmarks) for the purpose of accessibility. User agents may incorporate device equivalents, such as key mappings in the case of a desktop user agent, to navigate to these sections of a document.

+

Taxonomy of WAI-ARIA role values - The necessary core roles found in Accessibility API sets + for Windows and Linux as well as roles representative of document structure, such as banner or treegrid. Use of document + structure is necessary for assistive technologies to navigate + complex documents and to know when they have entered active areas + of a Web page such as in the case of a dynamic scripted Web + application. The taxonomy is designed to help user agents or + authoring tools determine what properties a given role supports and to assist with accessibility API mapping of these + properties. The taxonomy will is like a class hierarchy used to + convey semantics and structure and includes knowledge about each + role. At this time, that taxonomy is modeled using [[RDF-CONCEPTS]] and [[OWL-FEATURES]].

+
+

In short, WAI-ARIA will be used to fix the dynamic accessibility of scripted Web content, + in particular the use of JavaScript with (X)HTML markup. They are meant to be + cross-cutting and should apply to other markup like SVG. Less + critical for (X)HTML but helpful for accessibility + will be the descriptive extensions to XML events and the new [[XHTML Access]]. Web Content Accessibility Guidelines 2.0 calls for the WAI-ARIA properties in guideline 4.1 Maximize compatibility with current and future agents, including assistive technologies (roles, states, properties, and values) and section guideline 1.3 Create content that can be presented in different ways (for example spoken aloud, simpler layout, etc.) without losing information or structure (relationships).

+

The + next section describes how the specifications are used together as well as how they will be implemented in HTML 4.

+
+

Use of New Provisions for Keyboard Focus and Semantics to Support Platform Accessibility APIs

+

Adaptive technologies, which need to provide alternative access to + complex user interfaces authored via HTML, are often left guessing + at the semantics behind specific portions of HTML document. As an + example, an XHTML document might use a certain HTML construct, such + as a collection of DIV tags, to create navigation bars, a + site-navigation menu, and other GUI-like user interface widgets. To + fix the problem, we incorporate the role + attribute, assign the accessible state properties, and give the object + focus using the new TABINDEX feature. Addition of this information + helps authors to provide the necessary information to + enable the user agent to support the accessibility API accessed by + the adaptive technology.

+
+

Provision of the Role Attribute: "What is the Object?"

+

Each platform accessibility API has the notion of a "role" for a + GUI object. This is the case for [[JAPI]], [[MSAA]]], [[AXAPI]], and the [[ATK]], or [[UI-AUTOMATION]] (called content type in UI Automation). The WAI-ARIA specifications are based on XHTML 1.X and include the role attribute. The "role" attribute takes a qname, enabling authors to reference the role attribute from the WAI-ARIA Roles. In + the following example, we use qname to reference the menu role in the WAI-ARIA specification.

+
+

Example: Use of WAI-ARIA to incorporate + role information into XHTML 1.x

+ 
+<?xml version="1.1" encoding="us-ascii"?>
+<!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml"
+>
+    <body>
+        <div role="menu">
+            File
+        </div>
+    </body>
+</html>
+
+
+

WAI used RDF/OWL to model our taxonomy for WAI-ARIA. In fact, if a host language sought to use namespaces or qnames, they could do so to reference the WAI-ARIA role taxonomy. The WAI-ARIA role taxonomy could be used by authoring tool developers to ensure that states and properties assigned to a given role are accurate.

+
+
+

Provision of the Accessibility State Information: "What meaningful properties does this object have at this time?"

+

Since this is dynamic content, the state of these new repurposed + objects will change. The WAI-ARIA specification shall provide the common + accessible properties needed to support the accessible state or + property information provided by the platform accessibility API + defined previously. This specification was created based on an + analysis of the accessibility properties defined in MSAA and ATK. + The following example extends the previous approach by adding the aria-haspopup accessibility property.

+
+

Example: Use of WAI-ARIA to incorporate accessible state information information into XHTML 1.x

+ 
+<?xml version="1.1" encoding="us-ascii"?>
+<!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
+    http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+
+
+>
+        <body>
+            <div role="menu" aria-haspopup="true">
+                File
+        </div>
+    </body>
+</html>
+
+
+

A Windows user agent may now map this property to the Microsoft + Active Accessibility state of STATE_SYSTEM_HASPOPUP. Adding or + removing this state would result in the Windows user agent sending + an EVENT_OBJECT_STATECHANGE event to the assistive technology. The + task of the JavaScript page author would be to maintain this state + attribute, which can easily be done through the use of Document + Object Model calls.

+
+
+

Provision of the Keyboard or Input Focus: "What object am I working on?"

+

Virtually all adaptive technology solutions, such as screen + readers and onscreen keyboards, must know which object currently + has focus. For example, an author might want to insert text into the + current object with focus or to announce information + about the object that has focus. With today's HTML 4.01 and XHTML 1.x, script authors can only provide focus to form + and anchor elements yet the Document Object Model Specification + allows all elements to receive events including keyboard events. + This means that HTML, by design prohibits script authors from + making all HTML elements keyboard accessible. This single problem + effects usability of Web pages where one gains access to + elements by using the Tab key on desktop browsers. This slow, + unproductive, approach makes portal navigation difficult because all active elements must be tabbed through to put focus on an + active element in the last portlet in a document. To solve this + problem in XHTML 1.x, we are incorporating a feature in Firefox and + Internet Explorer to define the tabindex for -1. This allows a script author to + give an element focus without placing it in the tab order: The + following table describes these changes that will be incorporated + into the new Accessible Adaptive Application specification.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Accessible Adaptive Application Changes to Support Use of tabindex to give Element Focus +
tabindex attributeFocusable with mouse or JavaScript via element.focus()Tab navigable
not presentFollows default behavior of element (yes for form controls, + links, etc.)Follows default behavior of element
Negative, e.g. tabindex="-1" YesNo, author must focus it with element.focus() as a + result of arrow or other key press
Zero, e.g. tabindex="0" YesIn tab order relative to element's position in document
Positive, e.g. tabindex="33" YesTabindex value directly specifies where this element is + positioned in the tab order. These elements will be positioned in + the tab order before elements that have tabindex="0" or that are + naturally included in the tab order (form elements and links)
+

The following example shows the introduction of TABINDEX to + provide focus to a DIV having the new accessibility meta data:

+
+

Example: Use of tabindex to give non-form + and anchor elements focus in XHTML 1.x

+ 
+<?xml version="1.1" encoding="us-ascii"?>
+   <!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
+    http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+
+
+>
+    <body>
+        <div role="menu" aria-haspopup="true" tabindex=-1>
+            File
+        </div>
+    </body>
+</html>
+
+
+
+
+

Supporting WAI-ARIA in XHTML and HTML 4.01

+

Unlike XHTML, HTML 4.01 is non-extensible in that it is not possible to extend HTML 4 through the use of namespaces. That said, members of the working group have worked with the HTML working group to agree on a vehicle that does not use namespaces, which at this time is supported by XHTML and HTML which will be supported in HTML 5 when it becomes recommendation. Firefox 3 is leading the way to implement this, and other browser manufacturers are working to support it as well. The technique allows all role values specified in WAI-ARIA (including those specified by the XHTML Role attribute module) to be specified without a namespace prefix. Additionally, WAI-ARIA states and properties shall be represented as aria- followed by the concatenated WAI-ARIA state or property.

+
+

Example: Browser supported HTML technique for the tabindex example in section 5.1.3

+ 
+
+<html lang="en">
+  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  </head>
+    <body>
+        <div role="menu" aria-haspopup="true" tabindex=-1>
+            File
+        </div>
+    </body>
+</html>
+
+
+

In order to validate these extended attributes for HTML and XHTML the WAI-PF working group will investigate the creation of an enhanced schema or DTD for each host language.
+

+
+
+
+

Use of XHTML Role Landmarks to Improve Document Navigation

+

In addition to the common roles which will reside in WAI-ARIA Roles, both XHTML 2.0, and the XHTML Role attribute module ([[ROLE-ATTRIBUTE]], Section 4) defines a collection of common role, regional, landmarks that define pertinent parts of a + document for the purpose of accessibility. User agents may + incorporate device equivalents, such as key mappings in the case of + a desktop user agent, to navigate to these sections of a document + independent of the Web site. The addition of these semantics allows + the user agent to provide standardized navigation to common + document sections. This is especially important for portals to + improve the usability. These may be used as attributes in XHTML 1.x + by applying them to sections of the document as shown in this + example. Note: since these roles are a part of XHTML they do not need to be namespace qualified.

+
+

Example: Use of XHTML navigation role to define a landmark for the + navigation section in an XHTML 1.X document

+ 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
+<head>
+  <title>application/xhtml+xml: Navigation Roles Example 1</title>
+  <link rel="stylesheet" href="css/nav1_xhtml.css"  type="text/css" ></link>
+  <script type="text/javascript" src="../js/globals.js"></script>
+  <script type="text/javascript" src="../js/widgets_xhtml.js"></script>  <link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon" />
+  <link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon" />
+</head>
+<body onload="widgets.init()">
+.
+.
+.
+<div id="leftnav">
+<h2 class="nav" id="leftnav_label">Career Center Services</h2>
+ <ul title="Career Center Services" role="navigation" aria-labelledby="leftnav_label">
+   <li><a href="http://www.uiuc.edu/">Career Home</a></li>
+   <li><a href="http://www.uiuc.edu/">Career Counseling</a></li>
+   <li><a href="http://www.uiuc.edu/">Pre-Health Advising</a></li>
+   <li><a href="http://www.uiuc.edu/">Services</a></li>
+   <li><a href="http://www.uiuc.edu/">Workshops</a></li>
+   <li><a href="http://www.uiuc.edu/">Resource Center</a></li>
+   <li><a href="http://www.uiuc.edu/">Question Board/FAQ</a></li>
+ </ul>
+
+...
+
+</body>
+
+

The example above was taken from the header from the Career Center Web page at the University of Illinois at + Urbana-Champaign. Students from this university, under Jon + Gunderson's guidance created Accessibility + extensions for Mozilla/Firefox, in part, to allow a page author or + user to view a list of navigation landmarks. + This tool, shown in , lists the navigation sections on the page. Keyboard navigation of the list of navigation bars causes the + corresponding document section to be highlighted. The title for each navigation region displays in the list.

+
Table of Contents from Landmarks +
Table of Contents generated from navigation landmarks in the header
+
+

shows the accessibility + extensions for Mozilla/Firefox from the University of Illinois at + Urbana-Champaign to render the document landmarks. This picture + shows the Firefox browser rendering the University of Illinois + Career Career Center home page. In this example. The "List of Navigation Bars" viewer is shown, launched from the extension on the + toolbar. The viewer shows that the secondary "Career Center Services" is selected resulting + in that section of the document being highlighted in yellow. The + Navigation Bar Lists Viewer lists the following list of titles corresponding to the navigation sections:

+
    +
  • Career Counseling Resources
    • +
  • Resources by Audience
    • +
  • Career Center Services
    • +
  • Quick Links
    • +
+
+
+

WAI-ARIA Role Taxonomy - Extensible Semantic Role Model, using RDF/OWL

+

The WAI-ARIA role taxonomy was modeled using semantic web technology, in the form of [[RDF-CONCEPTS]] and the [[OWL-FEATURES]], as a vehicle to define a knowledge-based class hierarchy for roles. This model shows what states and properties are supported, by each role in the taxonomy. The role in the class hierarchy inherits properties from its ancestors and defines its own properties. Where applicable, semantic web technology is used to define related concepts within other namespaces. This information is critical in determining how to choose a role and how to interact with it. The role taxonomy uses RDF as a way for using data to describe data and provides a + W3C standards-based approach to represent this information.

+
+ + Sample Semantic Map for Taxonomy +
Example, Partial RDF Map for a possible ButtonUndo role as an extended role to WAI-ARIA
+
+

shows a basic RDF mapping that + defines a set of terms and relationships defining an object. At the + center is a Widget object that defines common states and properties + for all GUI widgets. The Button object extends Widget and inherits + defined accessibility properties from the superclass Widget. It + also defines a relatedConcept property to a Link object. + The ButtonUndo role extends Button. It has a relatedConcept of an HTML input object. + ButtonUndo will introduce Dublin Core meta data such as the + description of the object. The terms relatedConcept and + requiredState are terms that will be defined as part of the + corresponding RDF schema. Each role instance will represent + standard Roles found in the platform accessibility APIs of platforms like + Windows and Gnome as well as content structure. These roles will + form the taxonomy. Although host language browser implementations may reference WAI-ARIA roles without namespaces, the RDF representation for a given role may be referenced using a + qname from a Host XML markup language. This examples shows an XHTML reference to a grid role in the RDF representation of the WAI-ARIA taxonomy:

+

<div + role="grid"> whereby grid expands to: + http://www.w3.org/2005/01/wai-rdf/GUIRoleTaxonomy#grid in the + button markup.

+

The power of this design is that it enables a web authoring tool to go back + into the corresponding RDF/OWL markup and determine what properties it + supports for Accessibility API mapping. Additional, middleware solutions can now make intelligent + transformations of Web Content by processing the semantics behind + rich browser and rich structured frameworks to adapt accessible + solutions for a broader user base. Our immediate goal is to fix the + accessibility problem with scripted Web content. Assistive + technologies will use the standard roles to determine how to render + most content.

+
+

Interoperability Example: Grid Role

+

To understand the power of this approach, consider the case of a Grid Role, analogous to a table. shows a DHTML example using + XHTML, JavaScript, and CSS to produce a GUI-like application. This + example developed in IBM shows a notebook + tab with a data grid that behaves like a traditional desktop GUI. + The user uses arrow keys to navigates the data grid and among the page tabs. + Using the Tab key, a user navigates between the notebook tab, the edit fields, buttons, and + the data grid.

+
DHTML example of GUI-like notebook tab with a data grid +
DHTML Example
+
+

Accessible role and state + meta data from the WAI-WAI-ARIA Roles, States, and Properties specification, are added as attributes to + each of the XHTML elements repurposed as GUI widgets dynamically. + The user agent, in this case Firefox, maps this information to the + platform accessibility API. shows + the Microsoft Active Accessibility rendering of the new + accessibility markup provided on the DataGrid page tab which has + focus.

+
MSAA Inspect Tool diagnostics for Notebook page tab +
Microsoft Inspect Tool rendering of the page tab + DataGrid
+
+

show a Microsoft Inspect 32 + rendering of the DataGrid Page page tab in Figure 5.0. Inspect32 + provides Microsoft Active Accessibility information; here it shows the + accessible role of "page tab" and accessible state information of + focused, focusable, and linked. There are no page tab elements in + XHTML. Here, an XHTML DIV element is repurposed by a + JavaScript controller to look like a notebook tab. It is now able + to receive focus, unlike in standard XHTML 1.X, and it does so without + requiring tabbing. With these specifications, the script + author can now add the accessibility properties to support platform + accessibility API. Accessible state properties for the DataGrid + page tab are shown as focused, focusable, and linked. Unlike a GUI + application, authors need only enable their applications once for + multiple operating system platforms.

+

Beyond scripted Web content, the working group intends to extend + the use of roles to enable other user cases. These may include:

+
    +
  • Structured Textual Markup - enhancing + structure of the markup of a document, including Data Tables , or + translating the structure of an XML document to a markup structure + that user agents are used to dealing with (e.g. myXML to XHTML) + Binding sections of a document to a common role. This allows for + different navigation techniques though a document
    • +
  • Knowledge representation of Web content - As a + secondary benefit, roles improve compatibility with Knowledge-Based + Services and the Semantic Web. By integrating accessibility and the + semantic Web, accessibility can be moved forward, paving the way + for customized accessible searches and intelligent user agents with + additional applications.
    • +
  • Adding concepts in the type of content for adaptation + to the user scenario - The more that is understood about + content, the better it can be adapted for the end user. For example: +
      +
    1. If it is known that a page hyperlink has the role of taking the + user to the site's home page, then that knowledge can be used to + create enhanced accessibility in different ways in many different + scenarios, such as icons or access keys.
      2. +
    2. If it is known that a text box is for the user email address, + then the user agent can support users filling in the form by + labeling it with an icon or symbol, automatically validating it, or + even form filling.
      3. +
    3. If it is known that a paragraph is complex, then a simple equivalent + can be shown in its place
      4. +
    4. If a word is ambiguous, then a role of a concept can be given, + providing clarity An example of this may be : <span + role="role:nonliteral" aria:hasAlternate="no">
      5. +
    +
    • +
+ +
+
+
+

Accessibility Events and Event Handling

+

Interoperability between applications and assistive technologies + requires event notification for accessibility. The events will be fired via the user + agent. The accessible value and state property changes will be + generated in response to changes in the DOM attributes as defined + by the WCAG 1.0 AAA specification. User agents supporting the platform + accessibility API, will support event notification such as the state change or value change events.

+
+
+
+

Building Accessible Applications with WAI-ARIA

+

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

+

This section provides a brief introduction to the process of making applications accessible using WAI-ARIA. The choice and usage of roles can be complex and context dependent. It is beyond the scope of this document to explain implementations for all the possible WAI-ARIA use cases. WAI-ARIA Authoring Practices provides detailed guidance on WAI-ARIA implementation methodology as well as references to sample code.

+

First steps to making an application accessible:

+
    +
  1. Each element or widget has correct and complete semantics that fully describe its behavior (using element names or roles);
    2. +
  2. The relationships between elements and groups are defined;
    3. +
  3. States, properties, and container relationships are valid for each element's behavior and are accessible via the [[dom]] and the platform accessibility API; and
    4. +
  4. Keyboard focus should be maintained for the duration of the user's interaction with the application.
    5. +
  5. All interactive components should be keyboard operable.
    6. +
+

WAI-ARIA provides authors with the means to make the different elements in a web application semantically rich. User agents use the role semantics to understand how to handle each element. Roles convey additional information that the assistive technologies need to anticipate the behavior of the elements inside the application such as how to present the corresponding WAI-ARIA states and properties to the user. The user agent will use the accessibility semantics from the host language and WAI-ARIA accessibility semantics (which may augment or override those of the host language) and present them to assistive technologies through the Document Object Model or the platform accessibility API. The user agent will create an accessible representation of each element in the web page, and will use the appropriate accessibility API to notify assistive technologies of changes to the semantics of those elements.

+

The following steps are recommended when WAI-ARIA is applied to content:

+
    +
  1. +

    Use native markup when possible.

    +

    Use the semantic elements that are defined in the host markup language. For example, with HTML or XHTML, it is better to use the native checkbox than to use a div element with role checkbox as these should already be accessible through your browser. There may also be cases where WAI-ARIA can augment an existing element in the host language. For example, a grid and gridcell elements can reuse the functionality of a table when overlaying it. WAI-ARIA roles, states, and properties are best used when the markup language does not support all the semantics required. When a role attribute is added to an element, the semantics and behavior of the element are augmented or overridden by the role behavior.

    +
    2. +
  2. +

    Apply the appropriate roles.

    +

    Set roles to make sure elements behave predictably and correctly describe the behavior of each element within the application, unless element behaviors are fully described by the native markup language. Roles for interactive elements should support all the attributes that the element could use. Once a role attribute is set it should not be changed as this may confuse the end user. This does not preclude an element being removed which has the role attribute set, but only states and properties (aria-* attributes) should be changed for a given element.

    +
    3. +
  3. +

    Preserve semantic structure.

    +

    Structural information is critical to providing context to persons with disabilities. Preserve DOM hierarchy within structural elements and widgets:

    +
      +
    • Form logical groups within user interface widgets, such as treeitem elements in a group.
      • +
    • Identify large perceivable regions and apply a landmark role to those areas. This will facilitate keyboard navigation. It will also facilitate content management by assistive technologies by providing semantics to manage how much information is rendered at a given time. The use of WAI-ARIA landmarks helps everyone, including vision-impaired users, dexterity-impaired users, and even users with cognitive or learning impairments.
      • +
    • For areas of the page that contain a group of elements that are likely to change through an Ajax application it may be specified as a live region, through the use of the aria-live attribute or it may be marked with pre-defined roles, such as log, which has assumed behavior of a live region.
      • +
    +
    4. +
  4. +

    Build relationships.

    +

    Look for relationships between elements, and mark them using the most appropriate property or attribute. For example, if a page contains both a search form and search results region, mark each container as a region and set the aria-controls attribute of the search form to reference the search results. See relationships in WAI-ARIA.

    +

    Some relationships are determined automatically from the host language, like label elements associated with input elements in HTML.

    +
    5. +
  5. +

    Set states and properties in response to events.

    +

    Once the role for an element has been set, change states and properties as appropriate during the element's life cycle, usually in response to user input events. Only use attributes supported for the chosen role or element.

    +

    User agents should notify assistive technologies of state changes. Conversely, assistive technologies' notification of property changes depends on the method by which assistive technologies communicate with the user agent. For example, the aria-multiline attribute (a property) is not something that changes frequently, whereas the aria-checked attribute (a state) changes frequently in response to user input.

    +
    6. +
  6. +

    Support full, usable keyboard navigation.

    +

    Usable keyboard navigation in a rich internet application is different from the tabbing paradigm in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant widgets and uses the arrow keys to navigate within a complex widget, such as a menu or spreadsheet. The changes that WAI-ARIA introduces in keyboard navigation make this enhanced accessibility possible. Tabbing in the document should follow a logical navigation structure. Authors implementing arrow key navigation should, where possible, follow the design patterns in the WAI-ARIA Authoring Practices Guide. When using these features, it is important as always to ensure keyboard navigation is logical.

    +
    7. +
  7. +

    Synchronize the visual interface with the accessible interface.

    +

    This will allow the state of your UI to be perceivable to the user as well as assistive technologies. For example, the author should use the appropriate WAI-ARIA attribute on a form element that is visually styled to appear required (aria-required) or a gridcell that is visually styled to appear selected (aria-selected). Authors may choose to achieve visual synchronization of these interface elements by using a script or by using CSS attribute selectors.

    +
    8. +
+
+

Example: Building a Tree Widget

+ Graphic of an example tree view. +

A basic tree view allows the user to select different list items and expand and collapse embedded lists. Arrow keys are used to navigate through a tree, including left/right to collapse/expand sub trees. Clicking the visible expander button with the mouse also toggles expansion. Further keyboard implementation details for tree widgets may found in the .

+

To make this feature accessible we need to:

+
    +
  • Inform assistive technologies about the role of each element;
    • +
  • Inform assistive technologies about the relationships between tree items;
    • +
  • Give a clear keyboard focus that will not confuse users with disabilities; and
    • +
  • Expose the changing states (expanded and collapsed) of the tree items.
    • +
+

Following the steps below:

+
    +
  1. +

    Look at the native markup language

    +

    Although standard list behavior is supported by the native ul and li elements in HTML, there is no element that natively supports list expansion and selection. Since there is not, we will need to use roles.

    +
    2. +
  2. +

    Finding the right roles

    +

    Since there is no native tree element in HTML, we need to add roles from the taxonomy that support the additional states and properties needed. The roles that support tree behavior are:

    +
      +
    • tree: A tree is the main container element for our tree. It is a form of a select where sub-level groups of treeitems may be collapsed and expanded.
      • +
    • treeitem: A treeitem is an option item of a tree. This is an element within a tree; sub-level groups of treeitems may be expanded or collapsed.
      • +
    • group: A group encloses a set of sub-level treeitems.
      • +
    +
    3. +
  3. +

    Look for groups and build relationships

    +

    Tree relationships can be made simply via the DOM and logical structure of the page. A tree element will be the main container encompassing all other elements in the tree. Each selectable item in the tree will be a treeitem.

    +

    When a treeitem contains an embedded list of treeitems they will be all be embedded in a group. A group should be contained inside the tree item that is the parent item.

    + 
    <h1 id="treelabel">WAI-ARIA Tree Example</h1>
+<ul role="tree" aria-labelledby="treelabel" aria-activedescendant="example_id" tabindex="0">
+  <li role="treeitem" aria-expanded="true">Animals
+    <ul role="group">
+      <li role="treeitem">Birds</li>
+      <li role="treeitem" aria-expanded="false">Cats
+        <ul role="group">
+          <li role="treeitem">Siamese</li>
+          <li role="treeitem">Tabby</li>
+        </ul>
+      </li>
+      <li role="treeitem" aria-expanded="true">Dogs
+        <ul role="group">
+          <li role="treeitem" aria-expanded="true">Small Breeds
+            <ul role="group">
+              <li role="treeitem">Chihuahua</li>
+              <li role="treeitem" id="example_id">Italian Greyhound</li>
+              <li role="treeitem">Japanese Chin</li>
+            </ul>
+          </li>
+          <li role="treeitem" aria-expanded="false">Medium Breeds
+            <ul role="group">
+              <li role="treeitem">Beagle</li>
+              <li role="treeitem">Cocker Spaniel</li>
+              <li role="treeitem">Pit Bull</li>
+            </ul>
+          </li>
+          <li role="treeitem" aria-expanded="false">Large Breeds
+            <ul role="group">
+              <li role="treeitem">Afghan</li>
+              <li role="treeitem">Great Dane</li>
+              <li role="treeitem">Mastiff</li>
+            </ul>
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li role="treeitem" aria-expanded="true">Minerals
+    <ul role="group">
+      <li role="treeitem">Zinc</li>
+      <li role="treeitem" aria-expanded="false">Gold
+        <ul role="group">
+          <li role="treeitem">Yellow Gold</li>
+          <li role="treeitem">White Gold</li>
+        </ul>
+      </li>
+      <li role="treeitem">Silver</li>
+    </ul>
+  </li>
+  <li role="treeitem" aria-expanded="true">Vegetables
+    <ul role="group">
+      <li role="treeitem">Carrot</li>
+      <li role="treeitem">Tomato</li>
+      <li role="treeitem">Lettuce</li>
+    </ul>
+  </li>
+</ul>
    +

    The use of aria-expanded should mirror that which is visibly expanded on screen, so authors may wish to use CSS attribute selectors to toggle visibility or style of an item based on the value of an WAI-ARIA state or property. The following example would hide the sub-level groups of a collapsed tree node.

    + 
    [aria-expanded="false"] [role="group"] { display: none; }
    +

    + + At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise force the browser to redraw the styles properly.

    +

    Sometimes a tree structure is not explicit via the DOM and logical structure of a page. In such cases the relationships must still be made explicit using the states and properties. In the following example, the aria-owns attribute indicates that the div with id "external_treeitem" should be considered a child of the ul element with the attribute, even though it is not a child in the DOM.

    + 
    ...
+<li role="treeitem" aria-expanded="true" aria-owns="external_group">Vegetables</li>
+...
+<ul role="group" id="external_group">
+  <li role="treeitem">Carrot</li>
+  <li role="treeitem">Tomato</li>
+  <li role="treeitem">Lettuce</li>
+</ul>
+...
    +

    Sometimes trees (and other lists or grids) cannot be completed represented in the DOM due to performance limitations of the browser. For example, an application interface may only need to display 100 items out of a set of 100,000. Including all 100,000 items in the DOM could cause performance problems on both the client and server machines.

    +

    If items in a managed widget are loaded, for example, via the XMLHttpRequest object, and not present in the DOM at all times, authors should use aria-level, aria-posinset and aria-setsize, and ensure that aria-owns is not required to convey membership with the widget.

    + 
    ...
+<li role="treeitem" aria-level="1" aria-posinset="3" aria-expanded="true" aria-setsize="3">
+  Vegetables
+  <ul role="group">
+    <li role="treeitem" aria-level="2" aria-posinset="6" aria-setsize="8">Carrot</li>
+    <li role="treeitem" aria-level="2" aria-posinset="7" aria-setsize="8">Tomato</li>
+    <li role="treeitem" aria-level="2" aria-posinset="8" aria-setsize="8">Lettuce</li>
+  </ul>
+<li>
+...
    +
    4. +
  4. +

    Use states and properties in response to events

    +

    Control the behavior of the element in response to user input events such as from the keyboard and the mouse, which includes maintaining the current states and properties for that element. For example, a tree control will need to respond to click events on the expand/collapse triggers, and key events on the currently active descendant. Use device-independent events with supporting JavaScript to handle user interaction. For detailed examples of this please refer to the Design Patterns section.

    +
    5. +
+
+
+
+

Reasons for Adopting WAI-ARIA

+

This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

+

By adopting WAI-ARIA, both developers of static web sites and of dynamic Internet applications can improve the usability, accessibility, and scalability of their products. Developers of static web content can continue to follow the 1999 WCAG 1.0 standards, while improving usability and accessibility through the use of WAI-ARIA landmark roles, aria-labelledby relationships, and properties like aria-invalid and aria-required that can apply to HTML form controls. In richer, dynamic content, developers create custom widgets like calendars and spreadsheets based on technologies such as Ajax and CSS; to achieve accessibility, they need to use WCAG 2.0. Previously, when delivering rich Internet applications to users, to comply with WCAG 1.0, developers resorted to providing alternative, static content. While such measures met the WCAG 1.0 requirements, people using assistive technologies were not provided the richer user experience. When tables are used for layout, rather than CSS absolute positioning, historically, they have been problematic for assistive technologies to interpret. When the WAI-ARIA role of presentation is used on such tables, the assistive technology ignores the table structure, providing a more accessible experience without requiring major recoding.

+
+

Technical Benefits

+

Consider a rich Internet application where developers attempt to achieve keyboard accessibility using markup language. Without WAI-ARIA, results may be keyboard accessible but not highly usable; consider a user having to press Tab thirty times to put focus on a checkbox. To achieve keyboard accessibility in HTML without WAI-ARIA, developers must code active elements either as a link or as a form element. Accordingly, this means that no additional semantics are required or provided, other than that provided by the host language. In addition, WCAG 1.0 requires that content be renderable with Cascading Style Sheets turned off in the browser. This approach creates the following general usability problems:

+
    +
  • All keyboard-accessible controls must be either forms or anchors, forcing the user to tab through all focusable elements on the web page to navigate. If you need to navigate from the first link on the page to the last link on the page, that could be a very long trip and takes usability a step back.
    • +
  • Without WAI-ARIA semantics, you cannot provide contextual information to the user.
    • +
  • If you repurpose HTML elements you cannot provide the appropriate role and context information for the new widget. Lack of context is a serious usability problem. WAI-ARIA semantics results in providing contextual information to the user.
    • +
  • CSS is used for absolute positioning. If you remove that capability, usability features of widgets like pop-up menus disappear. Imagine activating the file menu and the menu showing up at the bottom of the page.
    • +
+

WAI-ARIA and WCAG 2.0 coding techniques are useful for developing content and applications that can scale across a variety of user agents, including those on mobile devices.

+

For all these reasons, adopting WAI-ARIA makes good technical as well as business sense. For a further illustration, compare how accessibility is achieved with WCAG techniques without and with WAI-ARIA, as shown in .

+
+ +

Editor's Note: Figure 7, described as WAI-ARIA tree widget usability comparison, refers to a resource that has not yet been found.

+
Usability of Tree Widget Using WAI-ARIA Semantics to Implement WCAG 2.0 Guidelines Compared to WCAG 1.0 Without WAI-ARIA
+
+ +

+ + shows an "accessible" widget for a tree item, within a tree widget, using WCAG 1.0 without WAI-ARIA, which ,when supplied to a screen reader, may say "link folder Year." There is no information to indicate that the folder is closed (aria-expanded = "false"). There is no information to indicate its depth (aria-level="2"), position in the set and the set size at the level, all of which provides the user with context something sighted users may take for granted. The role is used to indicate that it is a treeitem which indicates that the item should behave and navigate with the keyboard like a tree item. A screen reader using the WAI-ARIA version might say "Closed Folder Year, Closed Folder one of two, Depth two, unchecked." Furthermore, the WAI-ARIA version can allow the tree items to be navigated with arrow keys and without requiring they be navigated as part of a global web page tabbing scheme. This is not what any user would expect of a tree widget. Finally, if you were told all widgets were links on the web page, consider how usable -- or not -- that would be.

+
+
+

Business Benefits

+

If, as described above, coding techniques to achieve accessibility compliance do not promote overall usability, then business strategists must ask "Why invest in accessibility?" With WAI-ARIA, businesses can invest in accessible development and reap benefits for all users, not just those with disabilities or using assistive technologies. Some benefits include:

+
    +
  • Because WAI-ARIA is being developed through the PFWG with cooperation from browser and assistive technology vendors, accessibility and interoperability with those technologies will be easier to achieve, reducing or eliminating the need for per-browser and per-screenreader coding to achieve accessibility.
    • +
  • In addition to people with disabilities, all users benefit from WAI-ARIA because it establishes a Web-standard for keyboard interaction, easing the learning curve for users moving among applications, sites, and browsers.
    • +
  • Implementing WAI-ARIA can facilitate test automation. Test engines require semantic information about user interface elements, unique names, exposure of state, specific properties in order to run automated test scripts. WAI-ARIA provides that semantic information needed for efficient test automation.
    • +
+
+
+ +
+ diff --git a/aria-practices.html b/aria-practices.html index 615779591d..c977b9175c 100644 --- a/aria-practices.html +++ b/aria-practices.html @@ -208,415 +208,7 @@

Introduction

It includes guidance on dynamic document management, use of WAI-ARIA Form properties, and the creation of WAI-ARIA-enabled alerts and dialogs.

- -
-

Landmark Roles Design Patterns

- -

- Landmarks provide a powerful way to identify the organization and structure of a web page. - The structural information conveyed visually to users should be represented programmatically in the markup using landmark roles. - The use of landmark roles supports keyboard navigation to the structure of a web page for screen reader users, and can be used as targets for author supplied "skip links" and browser extensions for enhanced keyboard navigation. -

- -

This section is intended to assist designers, developers and quality assurance staff in defining and understanding the importance of logical, usable, and accessible layout for assistive technologies using HTML5 sectioning elements and ARIA landmark roles.

- -
-

HTML5 Sectioning Elements

- -

- It is important to understand that many HTML5 sectioning elements by default define ARIA landmarks. - If HTML5 sectioning elements are used without understanding the associated landmark structure, assistive technology users will most likely be confused and less efficient in accessing content and interacting with web pages. - More information on HTML5 element role mapping. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Default landmark roles for HTML5 sectioning elements
HTML5 ElementDefault Landmark Role
asidecomplementary
footercontentinfo when in context of the body element
headerbanner when in context of the body element
mainmain
navnavigation
sectionregion when it has an accessible name using aria-labelledby or aria-label
-
- -
-

General Principles of Landmark Design

- -

Due to the complexity of todays web content, if using landmarks, all content should reside in a semantically meaningful landmark in order that content is not missed by the user.

- -

Step 1: Identify the logical structure

- -
    -
  • Break the page into perceivable areas of content which designers typically indicate visually using alignment and spacing.
    • - -
  • Areas can be further defined into logical sub-areas as needed.
    • - -
  • An example of a sub-area is a portlet in a portal application.
    • -
- -

Step 2: Assign landmark roles to each area

- -
    -
  • Assign landmark roles based on the type of content in the area.
    • - -
  • banner, main, complementary and contentinfo landmarks should be top level landmarks.
    • - -
  • Landmark roles can be nested to identify parent/child relationships of the information being presented.
    • -
- -

Step 3: Label areas

- -
    -
  • If a specific landmark role is used more than once on a web page, it should have a unique label.
    • - -
  • If a landmark is only used once on the page it may not require a label. See Landmark Roles section below.
    • - -
  • If an area begins with a heading element (e.g. h1-h6) it can be used as the label for the area using the - aria-labelledby attribute.
    • - -
  • If an area requires a label and does not have a heading element, provide a label using the aria-label attribute.
    • - -
  • - Do not use the landmark role as part of the label. - For example, a navigation landmark with a label "Site Navigation" will be announced by a screen reader as "Site Navigation Navigation". - The label should simply be "Site". -
    • -
-
- -
-

Landmark Roles

- -
-

Banner

- -

- A banner landmark identifies site-oriented content at the beginning of each page within a website. - Site-oriented content typically includes things such as the logo or identity of the site sponsor, and site-specific search tool. - A banner usually appears at the top of the page and typically spans the full width. -

- -
    -
  • Each page may have one banner landmark.
    • - -
  • The banner landmark should be a top-level landmark.
    • - -
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one banner landmark.
    • - -
  • If a page includes more than one banner landmark, each should have a unique label (see Step 3 above).
    • -
- -
-
HTML5 Techniques
-
    -
  • The HTML5 header element defines a banner landmark when its context is the body element.
    • - -
  • - The HTML5 header element is not considered a banner landmark when it is descendant of any of following elements (see HTML Accessibility Mappings): -
      -
    • article
      • -
    • aside
      • -
    • main
      • -
    • nav
      • -
    • section
      • -
    -
    • -
- -
ARIA Techniques
- -

If the HTML5 header element technique is not being used, a role="banner" attribute should be used to define a banner landmark.

-
- -
-
Examples
- -

Banner Landmark Example

-
- -
- -
-

Complementary

- -

A complementary landmark is a supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.

- -
    -
  • complementary landmarks should be top level landmarks (e.g. not contained within any other landmarks).
    • - -
  • If the complementary content is not related to the main content, a more general role should be assigned (e.g. region).
    • - -
  • If a page includes more than one complementary landmark, each should have a unique label (see Step 3 above).
    • -
- -
-
HTML5 Technique
- -

Use the HTML5 aside element to define a complementary landmark.

- -
ARIA Technique
- -

If the HTML5 aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.

-
- -
-
Examples
- -

Complementary Landmark Example

-
-
- -
-

Contentinfo

- -

A contentinfo landmark is a way to identify common information at the bottom of each page within a website, typically called the "footer" of the page, including information such as copyrights and links to privacy and accessibility statements.

- -
    -
  • Each page may have one contentinfo landmark.
    • - -
  • The contentinfo landmark should be a top-level landmark.
    • - -
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one contentinfo landmark.
    • - -
  • If a page includes more than one contentinfo landmark, each should have a unique label (see Step 3 above).
    • -
- -
- -
HTML5 Techniques
- -
    -
  • The HTML5 footer element defines a contentinfo landmark when its context is the body element.
    • - -
  • - The HTML5 footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings): -
      -
    • article
      • -
    • aside
      • -
    • main
      • -
    • nav
      • -
    • section
      • -
    -
    • -
- -
ARIA Technique
- -

If the HTML5 footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.

-
- -
-
Examples
-

Contentinfo Landmark Example

-
-
- -
-

Form

- -

A form landmark identifies a region that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main or search).

- -
    -
  • Use the search landmark instead of the form landmark when the form is used for search functionality.
    • - -
  • A form landmark should have a label to help users understand the purpose of the form.
    • - -
  • A label for the form landmark should be visible to all users (e.g. an h1-h6 element).
    • - -
  • If a page includes more than one form landmark, each should have a unique label (see Step 3 above).
    • - -
  • - Whenever possible, controls contained in a form landmark in an HTML document should use native host semantics: -
      -
    • button
      • - -
    • input
      • - -
    • select
      • - -
    • textarea
      • -
    -
    • -
- -
-
HTML5 Techniques
- -

The HTML5 form element that defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).

- -
ARIA Technique
- -

Use the role="form" to identify a region of the page; do not use it to identify every form field.

-
- -
-
Examples
- -

Form Landmark Example

-
-
- -
-

Main

- -

A main landmark identifies the primary content of the page.

- -
    -
  • Each page should have one main landmark.
    • - -
  • The main landmark should be a top-level landmark.
    • - -
  • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one main landmark.
    • - -
  • If a page includes more than one main landmark, each should have a unique label (see Step 3 above).
    • -
- -
-
HTML5 Technique
- -

Use the HTML5 main element to define a main landmark.

- -
ARIA Technique
- -

If the HTML5 main element technique is not being used, use a role="main" attribute to define a main landmark.

-
- -
-
Examples
- -

Main Landmark Example

-
-
- -
-

Navigation

- -

Navigation landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation.

- -
    -
  • If a page includes more than one navigation landmark, each should have a unique label (see Step 3 above).
    • - -
  • If a navigation landmark has an identical set of links as another navigation landmark on the page, use the same label for each navigation landmark.
    • -
- -
-
HTML5 Technique
- -

Use the HTML5 nav element to define a navigation landmark.

- -
ARIA Technique
- -

If the HTML5 nav element technique is not being used, use a role="navigation" attribute to define a navigation landmark.

- -
- -
-
Examples
- -

Navigation Landmark Example

-
-
- -
-

Region

- -

A region landmark is a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section.

- -
    -
  • A region landmark must have a label.
    • - -
  • If a page includes more than one region landmark, each should have a unique label (see Step 3 above).
    • - -
  • The region landmark can be used identify content that named landmarks do not appropriately describe.
    • -
- -
-
HTML5 Technique
- -

Use the HTML5 section element to define a region landmark.

- -
ARIA Technique
- -

If the HTML5 section element technique is not being used, use a role="region" attribute to define a region landmark.

-
- -
-
Examples
- -

Region Landmark Example

-
-
- - -
-
- +

Design Patterns and Widgets

@@ -652,168 +244,11 @@

Generally Applicable Keyboard Recommendations

-
-

Accordion

- -

This section has not been updated since it was integrated from the WAI-ARIA Authoring Practices Guide (APG) version 1.0 -- an APG task force review is pending.

- -

- An accordion component is a collection of expandable panels associated with a common outer container. - Panels consist of a header and an associated content region or panel. - The primary use of an Accordion is to present multiple sections of content on a single page without scrolling, where all of the sections are peers in the application or object hierarchy. - The general look is similar to a tree where each root tree node is an expandable accordion header. - The user navigates and makes the contents of each panel visible (or not) by interacting with the Accordion Header. - Terms for understanding accordions include: -

- -
-
accordion component:
-
Collection of panels within a common outer pane.
-
accordion header:
-
Label area of an accordion panel. This is where you find the control to expand or collapse the panels.
-
accordion panel:
-
Contents area associated with an accordion header.
-
- -
-

Keyboard Interaction

- -
    -
  • - Tab - When focus is on an accordion header, pressing the Tab key moves focus in the following manner: -
      -
    1. If interactive glyphs or menus are present in the accordion header, focus moves to each in order.
      2. -
    2. When the corresponding panel is expanded (its aria-expanded state is 'true'), then focus moves to the first focusable element in the panel.
      3. -
    3. If the panel is collapsed (its aria-expanded state is 'false' or missing), OR, when the last interactive element of a panel is reached, the next Tab key press moves focus as follows: -
        -
      • If a subsequent accordion panel is already expanded, focus moves to the first focusable element in this subsequent panel.
        • -
      • If no subsequent accordion panel is expanded, focus moves to the first focusable element outside the accordion component.
        • -
      -
      4. -
    -
    • -
  • - Left arrow -
      -
    • When focus is on the accordion header, a press of up/left arrow keys moves focus to the previous logical accordion header.
      • -
    • When focus reaches the first header, further up/left arrow key presses optionally wrap to the first header.
      • -
    -
    • -
  • - Right arrow -
      -
    • When focus is on the accordion header, a press of down/right moves focus to the next logical accordion header.
      • -
    • When focus reaches the last header, further down/right arrow key presses optionally wrap to the first header.
      • -
    -
    • -
  • - Up arrow - behaves the same as left arrow -
    • -
  • - Down arrow - behaves the same as right arrow -
    • -
  • - Control + Up Arrow - Moves focus from anywhere in the accordion content to its associated accordion header or tab respectively. -
    • -
  • - Control + Page Up - -
      -
    • When focus is inside of an accordion pane, pressing Control + Page Up moves focus to the accordion header of the previous accordion pane.
      • -
    • When focus is in the first accordion header content, pressing Control + Page Up optionally moves focus to the last accordion header.
      • -
    • Focus will simply move to the header and will require Enter/Space to expand/collapse the accordion pane.
      • -
    -
    • -
  • - Control + Page Down - -
      -
    • When focus is inside of an accordion pane, pressing Control + Page Down moves focus to the header of the accordion pane.
      • -
    • When focus is in the last accordion header content, pressing Control + Page Down optionally moves focus to the first accordion header.
      • -
    • In the case of an accordion, focus simply moves to the header and requires Enter/Space to expand/collapse the accordion pane.
      • -
    -
    • -
  • - End - When focus is on the accordion header, an End key press moves focus to the last accordion header. -
    • -
  • - Home - When focus is on the accordion header, a Home key press moves focus to the first accordion header. -
    • -
  • - Enter/Space - When focus is on an accordion header, pressing Enter/Space toggles the expansion of the corresponding panel. -
      -
    • If collapsed, the panel is expanded, and its aria-expanded state is set to 'true'.
      • -
    • If expanded, the panel is collapsed and its aria-expanded state is set to 'false'.
      • -
    -
    • -
  • - Shift + Tab - Generally the reverse of Tab. -
    • -
  • - Alt + Delete - -
      -
    • - When deletion is allowed, with focus anywhere within the tab panel or tab, pressing Alt + Delete will delete the current tab and tab panel from the tabbed interface control. - If additional tabs remain in the tabbed interface, focus goes to the next tab in the tab list. - If no additional tabs remain, then focus moves to the last place that held focus in the previous tab panel. -
      • -
    • - An alternative to providing a keystroke to close a tab is to provide a context menu that is associated with the tab title. - When focus is on the tab, pressing Shift + F10 or pressing the right mouse button will open a context menu with the close choice. -
      • -
    • A warning should be given to the user before allowing the delete to occur.
      • -
    -
    • -
-

- In Firefox, pressing Control + Page Up / Control + Page Down moves between browser tabs. - Firefox also supports Control + Tab and Control + Shift + Tab to move between tabs. - Internet Explorer 7 also uses Control + Tab and Control + Shift + Tab. - There may be advantages to using Control + Page Up/Page Down as the keys to change tabs; it is a recognizable keystroke to at least Firefox users and it is also supported by the Windows operating system to move between panels in a tabbed dialog. -

-

You should be aware of two issues with using Control + Page Up/Page Down:

-
    -
  • - The first arises when the user is within a tabbed interface control on a Web page. - Here they can not easily switch browser tabs without first moving focus outside of the tabbed interface control. - This may be acceptable. -
    • -
  • - The second arises when the entire web page is a tabbed interface control. - In this case the user could not switch browser tabs unless the control on the web page ignored the Control + Page Up/Page Down keypress (and thus letting the browser access it) when the first or last tab was reached. -
    • -
-
- -
-

WAI-ARIA Roles, States, and Properties:

- -
    -
  • - The accordion component must have a role of tablist and have aria-multiselectable="true" - This will enable an assistive technology, such as screen reader, to convey that the tablist is an accordion or a multi selectable tablist. - This will also tell the user that the keyboard navigation matches an accordion and not a tablist. -
    • -
  • Contained within the tablist is a set of tab/tabpanel pairs.
    • -
  • Each header tab in the tablist has a role of tab.
    • -
  • The accordion panel uses the role tabpanel and should have an aria-labelledby relationship referencing the corresponding header having a role of tab
    • -
  • The tabpanel is considered a grouping for all content consisting of that tabpanel.
    • -
  • An accordion should manage the expanded/collapsed state of each tab by maintaining its aria-expanded state.
    • -
  • An accordion should manage the selected state of each tab by maintaining its aria-selected state.
    • -
  • An accordion should convey the visibility of each tabpanel by maintaining its aria-hidden state.
    • -
-
- -
-

Example

- -

- Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

- -

Open Ajax Alliance Accordion

-
-
- +
+

Accordion

+

Drafting this section is issue 53.

+
+

Alert

@@ -851,8 +286,7 @@

Example

Alert Dialog or Message Dialog

- -

This section has had only minor edits since it was integrated from APG version 1.0 -- a complete APG task force review is pending.

+

This section is partially revised. Planned changes are being discussed in issue 54.

A dialog with the primary purpose of communicating a message and acquiring a user response to that message. @@ -905,121 +339,6 @@

Example

-
-

Auto Complete

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

- A text box and an associated drop-down list of choices where the choices offered are filtered based on the information typed into the box. - Typically, an icon associated with the text box triggers the display of the drop-down list of choices. - An editable auto-complete accepts text entry of choices that are not in the list. - An example of an editable auto-complete is the URL field in the browsers. -

- -
-

Keyboard Interaction

-
    -
  • - With focus in an empty text box, press Down Arrow, Up Arrow, Alt + Down Arrow, or Alt + Up Arrow to display the entire list of choices. - Focus remains in the text box and no choice is highlighted. -
      -
    • Press the Down Arrow to highlight the first choice in the list.
      • -
    • Press the Down Arrow and Up Arrow keys to highlight the desired choice in the list.
      • -
    • - Note that the arrows will wrap through the text box when the top or bottom of the list is reached. - For example, pressing the down arrow when the last choice is highlighted will move focus back to the text box, pressing down again will move focus to the first item in the list. - Likewise, with focus in the text box and the list displayed, pressing up arrow will move focus to the last item in the list. -
      • -
    • When a choice is highlighted using the arrow keys, the highlighted choice is displayed in the text box.
      • -
    • - Press Enter to select the highlighted choice and close the drop-down list. - This mimics the behavior of the HTML select element. -
      • -
    -
    • -
  • - With the drop-down list of choices displayed, move the mouse pointer over an item in the list to highlight it. - The text box value is not modified when the mouse is used to highlight a choice. - Clicking on the highlighted choice will close the drop-down and update the text box with the selected choice. - This mimics the behavior of the HTML select element. -
    • -
  • - With focus in an empty text box, type any letter. - If any of the available choices begin with the letter typed, those choices are displayed in a drop down. - If the letter typed does not match any of the available choices the drop-down list is not displayed. -
    • -
  • - With focus in text box with an existing value type additional letters. - As the user types letters the list of choices is filtered so that only those that begin with the typed letters are displayed. -
      -
    • Until the user presses the arrow keys to highlight a particular choice, only the typed letters are displayed in the text box.
      • -
    • In an editable auto-complete, if no choices match the letter(s) typed, the drop down list closes.
      • -
    • - In a non-editable auto-complete, any letters that do not result in a match from the list are ignored. - The drop down list of choices remains static until the user presses: -
        -
      • Escape to clear the text field
        • -
      • Backspace to remove some of the letters previously typed
        • -
      • an additional letter that results in a valid list of choices.
        • -
      -
      • -
    • - Navigation through the list of choices and display of the highlighted choice in the text box works as described above.
      - - Optional: When a choice is highlighted via arrow key navigation, the input cursor is left at the end of the typed entry and the highlighted choice is displayed in the text box with the characters after the input cursor selected. - Typing an additional character will remove the auto-completed portion and append the newly typed character to the end of the previously typed characters. - The list will be filtered based on the additional character(s) typed. - -
      • -
    -
    • -
  • With focus in a text box, press Escape -
      -
    • If there is no text in the text box, pressing Escape closes the drop-down if it is displayed.
      • -
    • - For an editable autocomplete that has text in the text box that was both typed by the user and auto-completed by highlighting a choice using the keyboard, the auto-completed portion of the text is cleared and the user typed characters remain in the text box. - The drop-down list is closed. - To completely clear the text box contents the user must use the backspace key to remove the typed characters. - This is how the Google search box in the Firefox UI works. - Recommend that pressing the Escape key again completely clears the text box rather than relying on only the backspace key. -
      • -
    • For a non-editable auto-complete that has text in the text box that was both typed by the user and auto-completed by highlighting a choice using the keyboard, pressing Escape closes the drop-down list and leaves the current choice in the text box.
      • -
    • - For an editable or non-editable auto complete with text in the text box that was typed by the user and the mouse is highlighting a choice in the drop down (keyboard navigation was NOT used), pressing Escape closes the drop down and leaves the typed text displayed in the text box. - Need to consider if pressing Escape again should clear the typed text. - The user must press the Down arrow or Alt + Down arrow or click the associated icon to invoke the drop-down list of choices again. -
      • -
    -
    • -
  • Moving focus out of an empty auto complete field where a value is required should either invoke an error or if a default value was initially assigned, reset the value to the default value.
    • -
  • Moving focus out of an auto complete field that does not contain a valid entry should either invoke an error or if a default value was initially assigned, reset the value to the default value.
    • -
-

- It is good practice to limit the number of matching items in the drop down to a reasonable number. - The reasonable number is determined by the task at hand. - A list of the 50 US States is probably reasonable, but a list containing all of the office numbers in a building is probably not appropriate. -

-
- -
-

WAI-ARIA Roles, States, and Properties

-
    -
  • The widget has a role of combobox.
    • -
  • The combobox has an aria-autocomplete property set to one of 'inline', 'list', or 'both'.
    • -
  • For more information, see the combobox design pattern.
    • -
-
- -
-

Example

-

- Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

-

Dojo autocomplete

-
-
- -
-

Combo Box

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

- A combo box enables the user to type in a field and at the same time chose a predefined value from a list. - By using the keyboard the user can select an item from the list. - After selection she will be able to type further characters in the field. -

- -
-

Keyboard Interaction

-
    -
  • Left Arrow or Right Arrow move the caret within the edit field.
    • -
  • Alt + Up/Down Arrow opens and closes the list.
    • -
  • - Up Arrow and Down Arrow moves focus up and down the list. - As focus moves inside the dropdown list, the edit field is updated. -
    • -
  • Page Up / Page Down selects the next/previous pages item depending on the lists size.
    • -
  • Escape closes the dropdown list, returns focus to the edit field, and does not change the current selection.
    • -
  • Enter selects the current item on the list, updates the edit field, highlights the selected item in the dropdown list, closes the dropdown list, and returns focus to the input field.
    • -
  • Typing a letter (printable character) key moves focus to the next instance of a visible node whose title begins with that printable letter.
    • -
-

For combo boxes that implement aria-autocomplete, see the autocomplete design pattern.

-
- -
-

WAI-ARIA Roles, States, and Properties

-

A combobox can be implemented using either of two design patterns:

-
    -
  1. As a combination of text field, which may be editable, a displayable list of items, and a drop button to toggle the display of that list; all wrapped in the form of a single widget with role of combobox.
    2. -
  2. As a combobox, which behaves like a textfield and may be editable, with a displayable list of items, and a drop button to toggle the display of that list;
    3. -
-

- Like text fields a combobox should be labeled to convey the purpose of the widget. - Keyboard focus within the widget must be managed by the widget. - Comboboxes are used extensively in graphical user interfaces and the design pattern for the widget should be semantically correct. -

-

For the first combobox design pattern:

-
    -
  • The container element that wraps the combobox has a role of combobox.
    • -
  • - The first element within the combobox is an input text field and is responsible for managing the keyboard focus between the text field and the list as well as displaying the list. - The text field is in the tab order. If you create a text field without using a standard HTML text field form control then ensure that it is in the tab order. -
    • -
  • If the text field is not editable it must have have aria-readonly = true.
    • -
  • The combobox must have aria-expanded = true if the list is displayed or aria-expanded = false when it is not.
    • -
  • - The next element is an html <button>, or another element with a role of button. - This element is used to toggle the display of the combobox's drop down list. -
    • -
  • - The next element has a listbox role and represents the drop down list. - It manages keyboard navigation among list items and navigating back to the text field if necessary. -
    • -
  • - Each item in the listbox is an option. - Options are not in the tab order. -
    • -
  • - Provide a label for the combobox by referencing the text field in the combobox. - You can use an aria-label to associate this label with the combobox or you may use the HTML <label> element and its for attribute to reference the text field. -
    • -
-

For the second combobox design pattern:

-
    -
  • - The first element for the combobox has a role of combobox and behaves like an input text field and is responsible for managing the keyboard focus between the combobox and the list as well as displaying the list. - The text field is in the tab order. - If you create a text field without using a standard HTML text field form control then ensure that it is in the tab order. -
    • -
  • If the combobox is not editable it must have have aria-readonly = true.
    • -
  • The combobox must have aria-expanded = true if the list is displayed or aria-expanded = false when it is not.
    • -
  • - The next element is an html <button>, or another element with a role of button. - This element is used to toggle the display of the combobox's drop down list. -
    • -
  • - The next element has a listbox role and represents the drop down list. - It manages keyboard navigation among list items and navigating back to the text field if necessary. -
    • -
  • - Each item in the listbox is an option. - Options are not in the tab order. -
    • -
  • - Provide a label for the combobox by referencing the text field in the combobox. - You can use an aria-label to associate this label with the combobox or you may use the HTML <label> element and its for attribute to reference the text field. -
    • -
-

- For each combobox pattern the button need not be in the tab order if there is an appropriate keystroke associated with the input element such that when focus is on the input, the keystroke triggers display of the associated drop down list. - In this case, a Tab to focus the button is unnecessary. - This is the same behavior as the select element. -

-
- -
-

Example

-

- Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

-

First design pattern -- container element with role combobox:

- -

Second pattern -- text field with role combobox:

- -
-
- -
-

Date Picker

-

This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

- -

- The date picker widget allows the user to select a date or date ranges. - The date picker shows one month at least. All navigation that is described below depends on the application. - If no range selection is possible, the relevant keystroke interaction can be ignored. - Also navigation to the past might be optional. - Each week might be labeled with the corresponding calendar week number. -

-

- As a general rule the actual calendar portion of the date picker follows a table structure where days of the week and calendar day numbers are laid out in table cells. - This provides context so an assistive technology can render the day of the week; its corresponding numeric calendar day, and week number if necessary. - Consequently, it is best to start with an HTML table and apply WAI-ARIA semantics for a grid. - However, should the author wish to uses a div or span to represent the cells then the DOM structure for a table is duplicated with rows marked with role="row". -

-

The calendar portion can be displayed in a numbers of ways, including as a popup associated with another widget, or as a static region of a page.

- -
-

Keyboard Interaction

-

Keyboard navigation on days that are not included the currently displayed month should move to the month automatically and lead to the day in the next or previous month.

-
    -
  • - Tab - Like other widgets, the date picker widget receives focus by tabbing into it. - Once focus is received, focus is repositioned on today's date in a grid of days and weeks. - A second tab will take the user out of the date picker widget. - Focus initially is placed on today's date. -
    • -
  • - Shift + Tab - reverses the direction of the tab order. - Once in the widget, a Shift+Tab will take the user to the previous focusable element in the tab order. -
    • -
  • - Up Arrow and Down Arrow - goes to the same day of the week in the previous or next week respectively. - If the user advances past the end of the month they continue into the next or previous month as appropriate. -
    • -
  • - Left Arrow and Right Arrow - advances one day to the next, also in a continuum. - Visually focus is moved from day to day and wraps from row to row in a grid of days and weeks. -
    • -
  • Control + Page Up - Moves to the same date in the previous year.
    • -
  • Control + Page Down - Moves to the same date in the next year.
    • -
  • - Space - +
    +

    Combo Box

    +

    Drafting this section is issue 31.

    +
    + +
    +

    Dialog (Modal)

    +

    This section is partially revised. Planned changes are being discussed in issue 42.

    +

    A dialog is a window overlayed on the primary window. + A modal dialog is designed to interrupt the user to, for example, prompt the user to confirm an action or enter information, and it traps or contains keyboard focus until the dialog is closed. + ARIA has a special role for modal dialogs that convey a brief, important message to the user -- the alertdialog ( See the Alert Dialog design pattern). +

    +
    +

    Keyboard Interaction

      -
    • Singleton Mode: acts as a toggle either selecting or deselecting the date.
      • -
    • - Contiguous Mode: Similar to selecting a range of text. - Space selects the first date. - Shift + Arrows add to the selection. - Pressing Space again deselects the previous selections and selects the current focused date. -
      • +
    • Tab: Moves focus to the next focusable element inside the dialog. Pressing tab with focus on the last focusable element in the dialog moves focus to the first focusable element in the dialog.
      • +
    • Shift + Tab: Moves focus to the previous focusable element inside the dialog. Pressing shift-tab with focus on the first focusable element in the dialog moves focus to the last focusable element in the dialog.
      • +
    • Escape: Closes the dialog without taking any action.
      • +
    • Enter: Serves as the default submit action key if if the primary purpose of the dialog is to gather information
    -
    • -
  • Home - Moves to the first day of the current month.
    • -
  • End - Moves to the last day of the current month.
    • -
  • Page Up - Moves to the same date in the previous month.
    • -
  • Page Down - Moves to the same date in the next month.
    • -
  • - Enter - +
      +
    • If the current focus item has Escape key behavior, the press of the Escape will be handled by the current item and the user may have to press Escape an additional time to close the dialog.
      • +
    • When the dialog is closed or cancelled focus should return to the element in the application which had focus before the dialog is invoked. This is usually the control which opened the dialog.
      • +
    • When a modal dialog opens focus goes to the first focusable item in the dialog. Determining the first focusable item must take into account elements which receive focus by default (form fields and links) as well as items which may have a tabindex attribute with a positive value.
      • +
    +
+ +
+

WAI-ARIA Roles, States, and Properties

    -
  • If the the calendar is a popup attached to some other widget (e.g., a text field), then Enter dismisses the popup, and the selected date(s) are shown in the associated widget.
    • -
  • If the calendar is a static region on the page, then Enter confirms the selected date(s).
    • +
  • The element containing the dialog has a role of dialog.
    • +
  • The dialog box title is provided by either the aria-label or the aria-labelledby property.
    • +
  • The aria-describedby property may be set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Screen readers may automatically announce the specified description along with the dialog title and initially focused element when the dialog opens.
- -
  • Escape - in the case of a popup date picker, closes the widget without any action.
    • - -

    Navigation into the past is optional

    -

    - Do not implement keyboard navigation schemes that would place more than one calendar day in the tab order at any time as this impacts the usability of keyboard navigation. - For example, using HTML anchors for the gridcells places them all in the tab order impacting the usability of keyboard navigation. -

    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -
      -
    • - The current month has a label representing the month and year. - It is advisable to use a role heading but is not essential. - This "label" should have a unique ID. -
      • -
    • If the author would like to ensure that a label is announced by a screen reader, as the label changes, include live region properties with the label element: aria-live="assertive" and aria-atomic="true".
      • -
    • The container for the day of week headers and numeric days of the week has a role of grid.
      • -
    • The grid has an aria-labelledby property with a value equivalent to the id of the label for the grid.
      • -
    • Each name for the day of the week has a role columnheader and is not navigable via the keyboard.
      • -
    • Each numeric day of the week has the role gridcell.
      • -
    • When a day is selected its aria-selected is set to true, otherwise it is set to false or removed.
      • -
    • Changes in aria states, identified here, as well as focus, are clearly styled to show the user where their point of regard is and what days are selected.
      • -
    -

    - When the date picker is active a calendar day of the week always has focus. - This can be achieved by setting the tabindex on that day as appropriate and then using script to give it focus. - Alternatively, the grid container could set aria-activedescendant to the id of the currently focused gridcell. - Keep in mind that older browsers may not support aria-activedescendant. -

    -
    - -
    -

    Example

    -

    - Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

    - -
    -
    - -
    -

    Dialog (Modal)

    -

    A dialog is a window overlayed on the primary window. - A modal dialog is designed to interrupt the user to, for example, prompt the user to confirm an action or enter information, and it traps or contains keyboard focus until the dialog is closed. - ARIA has a special role for modal dialogs that convey a brief, important message to the user -- the alertdialog ( See the Alert Dialog design pattern). -

    -
    -

    Keyboard Interaction

    -
      -
    • Tab: Moves focus to the next focusable element inside the dialog. Pressing tab with focus on the last focusable element in the dialog moves focus to the first focusable element in the dialog.
      • -
    • Shift + Tab: Moves focus to the previous focusable element inside the dialog. Pressing shift-tab with focus on the first focusable element in the dialog moves focus to the last focusable element in the dialog.
      • -
    • Escape: Closes the dialog without taking any action.
      • -
    • Enter: Serves as the default submit action key if if the primary purpose of the dialog is to gather information
      • -
    -
      -
    • If the current focus item has Escape key behavior, the press of the Escape will be handled by the current item and the user may have to press Escape an additional time to close the dialog.
      • -
    • When the dialog is closed or cancelled focus should return to the element in the application which had focus before the dialog is invoked. This is usually the control which opened the dialog.
      • -
    • When a modal dialog opens focus goes to the first focusable item in the dialog. Determining the first focusable item must take into account elements which receive focus by default (form fields and links) as well as items which may have a tabindex attribute with a positive value.
      • -
    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -
      -
    • The element containing the dialog has a role of dialog.
      • -
    • The dialog box title is provided by either the aria-label or the aria-labelledby property.
      • -
    • The aria-describedby property may be set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Screen readers may automatically announce the specified description along with the dialog title and initially focused element when the dialog opens.
      • -
    -
    - -
    -

    Example

    -

    - Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

    - -
    -
    - -
    -

    Dialog (Non-Modal)

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    - -

    A dialog is a small application window that sits above the application and is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response (dialog).

    - -

    - A non-modal dialog is one which is displayed and focusable at the same time as the application which invoked it. - Also like the modal dialog, focus via the tab and shift-tab key must be maintained within the dialog. - However, a non-modal dialog should have a keyboard mechanism to return focus to the application while leaving the dialog open. -

    - -
    -

    Keyboard Interaction

    -
      -
    • Escape cancels the dialog without taking any action.
      • -
    • Enter submits any data gathered in the dialog.
      • -
    • F6 is the recommended key to move focus between the application and an open non-model dialog.
      • -
    -

    Notes:

    -
      -
    • The mouse user may click on either the application or the dialog to change focus between the two.
      • -
    • In a Web application the non-modal dialog is usually always displayed above the application page, rather than in a separate browser window but that is not a requirement.
      • - -
    • - Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. - Authors should ensure that Enter activates only the widget they intend. -
      • -
    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -

    See Dialog (Modal).

    -
    - -
    -

    Example

    - -

    - Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. - The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. -

    -

    Experimental dojo floating non-modal pane

    -
    -
    - -
    -

    Dialog (Tooltip)

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    - -

    A tooltip dialog is a modal dialog that is rendered near the invoking element and visually connected via a cartoon bubble-like protrusion. It is displayed when the mouse passes over or rests on that element.

    - -
    -

    Keyboard Interaction:

    -
      -
    • Escape The tooltip dialog is closed by pressing the escape key when focus is within the dialog, mouse clicking on a close icon, or mouse clicking outside of the dialog onto the application.
      • -
    • Tab Focus must be held within the dialog until it is cancelled or submitted. As the user presses tab to move within items in the dialog, pressing tab with focus on the last focusable item in the dialog will move focus back to the first focusable item in the dialog.
      • -
    • Shift + Tab Likewise, if the user is shift-tabbing through elements in the dialog, pressing shift-tab with focus on the first focusable item in the dialog will move focus to the last item in the dialog.
      • -
    -

    It is modal because focus is trapped within the dialog as the user navigates via the Tab and Shift + Tab key.

    -

    Unlike a true modal dialog, the user can click outside of the dialog, however in that case the tooltip dialog is immediately closed.

    -

    A tooltip dialog can not be moved/dragged.

    -

    Other than the close and move behavior, all other behaviors of a modal dialog are implemented by the tooltip dialog.

    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -

    See Dialog (Modal).

    -
    - -
    -

    Example

    -

    Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

    -

    Dojo nightly

    -
    -
    + + +
    +

    Example

    +

    + Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. + The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide. +

    + +
    + + +
    +

    Dialog (Non-Modal)

    +

    Drafting this section is issue 59.

    +

    Grids : Interactive Tabular Data and Layout Containers

    @@ -1910,29 +928,6 @@

    Examples

    -
    -

    Landmark Navigation

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    - -
    -

    Keyboard Interaction

    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -

    Provide the appropriate landmark for the role attribute. See the section describing landmark use.

    -
    - -
    -

    Example

    -

    Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

    - -
    -
    - -
    -

    Popup Help (aka Bubble Help)

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    - -

    - Popup Help contains more descriptive, or actionable, help-like text and elements. - It may contain, and was designed to handle, interactive elements such as a button, link, or text field. - It is essentially a Popup Menu with un-necessary keystrokes turned off. - The key sequence for posting Popup Help was to take advantage of F1's tie to the Help paradigm (F1 calls up application Help for example). -

    +
    +

    Radio Group

    +

    An option in single-select list

    Keyboard Interaction

    +

    The Tab behavior below differs from some native browser behaviors where Shift+Tab sometimes moves to the last button in the group, if none are selected.

      -
    • Control + F1 -
        -
      • Posts the Popup Help widget.
        • -
      • Input focus is placed on the first interactive element in the Popup Help.
        • -
      • Control F1 is used by IE to "Display a help dialog box". In IE7 and IE8 event.cancelBubble=true; and event.returnValue=false; will allow the re-purposing of keys used by the browser. In the case of IE6, you can not stop the bubble up of keys used by the browser, but can stop the bubble up to the OS. In the case of Firefox and other standard compliant browsers, event.stopPropagation(); and event.preventDefault(); will re-purpose the keys.
        • -
      • With the exception of Control F1 to bring up Popup Help this widget is very similar to Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip) described elsewhere in this document.
        • -
      -
      • -
    • Esc -
        -
      • Causes no menu action and dismisses Popup Help.
        • -
      • Input focus is returned to the element, or widget the Popup Help was invoked from.
        • -
      • Pressing Enter when input focus is on the "X" glyph acts the same as pressing Esc.
        • -
      -
      • -
    • Tab -
        -
      • One of the following occurs: -
          -
        • Modal behavior -
            -
          • Moves input focus between elements in the Popup Help's tabbing order. -
              -
            • Input focus stays in the Popup Help until one of the following occurs: -
                -
              • Esc is pressed.
                • -
              • Enter is pressed when input focus is on an interactive widget/element.
                • -
              -
              • -
            -
            • -
          -
          • -
        • Non-Modal behavior -
            -
          • Moves input focus to the next tabbable element in the tabbing order if the following applies: -
              -
            • Popup Help is posted.
              • -
            • It contains no tab navigable elements in it.
              • -
            -
            • -
          -
          • -
        -
        • -
      -
      • -
    • Shift + Tab -
        -
      • As with other keyboard conventions described here, the Shift + Tab has the effect of moving the focus up rather than down and follows the same conventions as described for the modal and non-modal Tab key above.
        • -
      -
      • -
    • Enter -
        -
      • Activates the element in the Popup Help that has input focus, if applicable, then dismisses the popup. -
          -
        • Input focus should be placed on the appropriate element after the user presses the Enter key. -
            -
          • The appropriate place to move input focus to will not always be the parent element the Popup Help was invoked from.
            • -
          -
          • -
        • Nothing occurs if input focus is on an element that has no associated action.
          • -
        -
        • -
      -
      • -
    • F6 +
    • Tab key will enter the radio group.
        -
      • In the non-modal instance, the F6 key can be used to move focus between the application and the open non-modal window. This is also the behavior described in Dialog (Non-Modal) above.
        • +
      • When Tab or Shift + Tab into a radio group, focus goes to the selected radio button. If none is selected, focus goes to the first radio button.
        • +
      • When focus is on any radio button, Tab or Shift + Tab will exit the radio group.
      • -
    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -

    See Dialog (Modal) and/or Dialog (Non-Modal) and/or Dialog (tooltip).

    -
    - -
    -

    Example

    -

    Add link to example.

    -
    -
    - -
    -

    Radio Group

    -

    An option in single-select list

    - -
    -

    Keyboard Interaction

    -

    The Tab behavior below differs from some native browser behaviors where Shift+Tab sometimes moves to the last button in the group, if none are selected.

    -
      -
    • Tab key will enter the radio group. -
        -
      • When Tab or Shift + Tab into a radio group, focus goes to the selected radio button. If none is selected, focus goes to the first radio button.
        • -
      • When focus is on any radio button, Tab or Shift + Tab will exit the radio group.
        • -
      -
      • -
    • Up Arrow and Left Arrow moves focus to the previous radio button in the group, and selects that button. If focus is on the first item, then focus wraps to last item.
      • -
    • Down Arrow and Right Arrow moves focus to the next radio button in the group, and selects that button. If focus is on the last item, then focus wraps to first item.
      • -
    • Space selects the radio button with focus and de-selects other radio buttons in the group.
      • +
    • Up Arrow and Left Arrow moves focus to the previous radio button in the group, and selects that button. If focus is on the first item, then focus wraps to last item.
      • +
    • Down Arrow and Right Arrow moves focus to the next radio button in the group, and selects that button. If focus is on the last item, then focus wraps to first item.
      • +
    • Space selects the radio button with focus and de-selects other radio buttons in the group.
    @@ -2336,243 +1232,6 @@

    Example

    -
    -

    Rich Text Editor

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    Input control that accepts free-form text as its value.

    - -
    -

    Keyboard Interaction

    - -
      -
    • The edit control is provided by the browser; it provides the keyboard support for navigating, adding, removing and selecting text, so that behavior is not defined by the rich internet application.
      • -
    • The browser should also provide a keyboard mechanism for navigating into and out of the edit control. Within most browsers the edit control is put into the tab order of the page and can be navigated into, out of, and through using the tab and shift-tab keys like any standard form control.
      • -
    • A rich text editor widget needs to provide a user interface for interacting with the browser provided edit control. Interaction between the user interface and editor is defined here assuming that a toolbar is used.
      • -
    • Tab and Shift + Tab - If not provided by the browser, the rich text editor widget provides a keyboard mechanism to move into and out of the edit control. Tab and shift-tab are the recommended keystrokes. The toolbar or other user interface component associated with the editor is placed in the tab order immediately before the editor. To set an attribute on text within the edit control the user sets focus into the edit control, moves the insertion point, selects text and presses shift-tab to move focus from the editor back to the toolbar. The user navigates through the toolbar (see toolbar behavior) to a desired attribute and invokes that attribute. When an attribute is invoked, that attribute is applied to the selected text in the editor and focus moves back into the editor at the previous insertion point with the selection intact.
      • -
    • Options: -
        -
      • Rather than using Shift + Tab to move focus from within the editor to the toolbar, another key combination could be used (Alt + Up Arrow, Control + Shift + Letter, etc.). This would eliminate the need to put the user interface control (in this example a toolbar) into the tab order immediately before the editor component. However, there are drawbacks to using a different keystroke to navigate to the user interface: -
          -
        1. It is not as "discoverable" as relying on the standard Tab/Shift + Tab behavior;
          2. -
        2. It is difficult to find key combinations which are not already captured by the browser or assistive technology.
          3. -
        3. Focus could stay within the toolbar after the user invokes an attribute. The user would then have to press an additional key to move focus back into the editor. This would allow multiple attributes to be set on the current selection without having to return back to the user interface but it would add an extra key sequence after setting just a single attribute. Requiring a keystroke to move focus back into the editor would also require modifying the toolbar behavior to intercept this keystroke and to know how to set focus back to the component (the editor) that the toolbar is associated with.
          4. -
        -
        • -
      -
      • -
    - -

    Optionally, if the developer wishes to provide the ability to insert a tab into the document, it is recommended one of the following methods be used.

    -
      -
    • Provide indent and outdent buttons in the menu. Keyboard shortcuts to the buttons should be Control + M for indent and Control + Shift + M for outdent.
      • -
    • Provide a button in the menu to toggle the use of Tab between the two modes. If this button is used, then Control + M is recommended as a keyboard shortcut to toggle the button.
      • -
    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -

    Authors are advised to not use ARIA for rich text editors, but to rely on native HTML markup. Current rich text editors typically use an iframe element for editable content. As a result, the editable content is implicitly mapped to a document role in accessibility APIs. If using HTML5, it is recommended that authors use the designMode or contentEditable attributes.

    -
    - -
    -

    Example

    -

    Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

    - -
    -
    - - - - - - -

    Slider

    @@ -2712,6 +1371,7 @@

    Example

    Table

    +

    Drafting this section is issue 90.

    [Place holder for a to-be-written section about data tables] While writing the grid pattern, the topic of data tables came up because the grid pattern has text clarifying when to use grid verses when to use table. @@ -2719,7 +1379,6 @@

    Table

    That made the grid pattern section feel overwhelming so adding a placeholder for a potential table section here. The grid pattern links to this section.

    -
    @@ -2895,85 +1554,6 @@

    Example

    -
    -

    Tree Grid

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    - A grid whose rows can be expanded and collapsed in the same manner as for a tree. - A Tree Grid is a combination of a Treeview and a Table with rows that are expandable. -

    - -
    -

    Keyboard Interaction

    -

    There are two modes of keyboard interaction:

    -
      -
    • Navigation Mode (Read-Only) is the default mode, and allows quick and intuitive navigation around the grid. -
        -
      • Tab -
          -
        • The initial tab enters the grid with focus on the first cell of the first row, often a header.
          • -
        • Once in the grid a second tab moves out of the grid to the next tab stop.
          • -
        • Once focus is established in the grid, a Tab into or a Shift + Tab into the grid will return to the cell which last had focus.
          • -
        -
        • -
      • Left Arrow and Right Arrow keys navigate between columns. If the next cell in the row is empty, focus should not move.
        • -
      • Up Arrow and Down Arrow The down arrow moves focus to the first column of a child row, if expanded. Otherwise focus is moved to the same column in the next row. Up arrow performs the same navigation but in reverse.
        • -
      • Control + Left and Control + Right Arrows expand or collapse rows.
        • -
      • If the cell contains an editable field, the Enter key starts edit mode and the Escape key exits edit mode.
        • -
      • Selecting Cells -
          -
        • Control + Space selects the current column.
          • -
        • Shift + Space selects the current row.
          • -
        • Control + A selects the entire grid.
          • -
        • Shift + Arrow selects contiguous cells.
          • -
        • Shift + F8 Allows additional cells to be added to a previous selection to accomplish non-contiguous selection.
          • -
        -

        See Global Recommendations for information on cut, copy and paste.

        -
        • -
      -
      • -
    - -

    The author may choose to indent child nodes visually. This should be done with an appropriate number of spacer cells marked as presentation in order to keep the headers aligned.

    - -

    If cells are used for padding or layout of the hierarchy, navigation to those presentational cells should be prevented.

    - -
      -
    • Actionable Mode (Interactive) allows the interaction with other objects that might be found in the grid cells such as edit fields, links, etc. -
        -
      • F2 pressed anywhere inside the grid will enter Actionable Mode. Focus will not be moved.
        • -
      • Enter pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
        • -
      • Optionally, alphanumeric keys pressed while focus is on an actionable item will enter Actionable Mode. Focus will remain on the actionable item that has focus.
        • -
      • Tab will move to the next actionable (tabbable) item in the grid and stay within the grid wrapping at the bottom. In this mode each tabbable object in each cell of the grid can be reached with the tab key. If multiple tabbable items are located inside a single grid cell, the tab will stop at each one. When the last tabbable item in a cell is reached the next tab will move to the next tabbable item in the grid, wrapping at the last tabbable item in the grid.
        • -
      • Shift + Tab moves to the previous actionable (tabbable) item in the grid and stays within the grid, wrapping at the top.
        • -
      • Escape exits Actionable mode (by which the user may enter text or perform an action to complete a operation) and returns to Navigation Mode (where the user is allowed to move focus among elements). If a widget is in the current grid cell that also uses the Escape key, then it should cancel the event propagation. A subsequent press of the Escape key will return focus to the parent widget.
        • -
      -
      • -
    -
    - -
    -

    WAI-ARIA Roles, States, and Properties

    -

    - Uses the WAI-ARIA role treegrid, and requires the child element row. - By default a treegrid is considered to be editable, meaning all gridcells are editable. -

    -
      -
    • To make a treegrid read-only, set aria-readonly="true" on the document element having a role="treegrid." This will make all gridcells read-only.
      • -
    • To override the read-only status on an individual gridcell, set its aria-readonly property to false.
      • -
    -
    - -
    -

    Example

    -

    Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

    -
      -
    • For a visual (not accessible) example of where padding cells have been implemented see: dojo's TreeGrid example.
      • -
    • An example where padding cells have not been used (also not accessible): Oracle's Tree Grid.
      • -
    -
    -
    -

    Tree View

    @@ -3097,489 +1677,660 @@

    Example

    -
    -

    Wizard

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    A sequence of dialogs or panels guiding the user through performing a task.

    +
    -
    -

    Keyboard Interaction

    -

    A Wizard can be done in several ways. Either is valid.

    - -

    Authors should take care when using Enter to trigger default actions since Enter might be connected to and trigger some other user interface element, or it might trigger the focused element. Authors should ensure that Enter activates only the widget they intend.

    -
    +
    +

    Landmark Roles Design Patterns

    -
    -

    WAI-ARIA Roles, States, and Properties

    -
    +

    + Landmarks provide a powerful way to identify the organization and structure of a web page. + The structural information conveyed visually to users should be represented programmatically in the markup using landmark roles. + The use of landmark roles supports keyboard navigation to the structure of a web page for screen reader users, and can be used as targets for author supplied "skip links" and browser extensions for enhanced keyboard navigation. +

    -
    -

    Example

    -

    Any examples referenced here that are hosted outside www.w3.org may have changed and may not accurately exemplify the guidance in this section. The APG task force is developing examples for APG version 1.1 that will be directly incorporated into the guide.

    -

    Dojo nightly

    -
    -
    - +

    This section is intended to assist designers, developers and quality assurance staff in defining and understanding the importance of logical, usable, and accessible layout for assistive technologies using HTML5 sectioning elements and ARIA landmark roles.

    -
    -

    General Steps for Building an Accessible Widget with WAI-ARIA

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    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.

    -
      -
    1. -

      Pick the widget type (role) from the WAI-ARIA taxonomy

      -

      WAI-ARIA provides a role taxonomy ([[WAI-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">
      -
      2. -
    2. From the role, get the list of supported states and properties -

      Once you have chosen the role of your widget, consult the [[WAI-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:

      -
      -
      superclass 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" id="customToolbar" tabindex="0" aria-activedescendant="button1"
-      onkeydown="return optionKeyEvent(event);"
-      onkeypress="return optionKeyEvent(event);"
-      onblur="hideFocus();"
-      onfocus="showFocus();"
-      >
-      <img src="img/btn1.gif" title="Home" alt="Home" role="button" id="button1"
-           onclick="updateText('Home was invoked');">
-      <img src="img/btn2.gif" title="Refresh" alt="Refresh" role="button" id="button2"
-           onclick="updateText('Refresh was invoked');">
-      <img src="img/btn3.gif" title="Help" alt="Help" role="button" id="button3"
-           onclick="updateText('Help was invoked');">
-</div>
-
      -

      By setting tabindex=0 on the toolbar, the toolbar will receive focus in the document order. It is necessary then to use script and the aria-activedescendant property to manage virtual focus among the buttons. The details are given in step five, below.

      -
      -

      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.

      -
      -
      3. -
    3. 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 [[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="button2">
-  <img src="buttonpaste.png" alt="paste" id="button3">
-</div>
      -
      4. -
    4. 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.

      -
      5. -
    5. -

      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.

      -

      Commented out link to conference paper, which a) was broken, and b) we should have more canonical references than conference papers for things like this.

      -

      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.

      -

      You must also show the visual focus for each element that has focus.

      -
      6. -
    6. -

      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.

      -
      7. -
    7. -

      Synchronize the visual UI with accessibility states and properties for supporting user agents

      -

      Thomas comment: is confusing that the example switches from toolbar to treeitem. Maybe the best overall sample is to do a tree because it demonstrates each of the points you want to make?

      -

      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 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";
-      }
      -
      8. -
    8. 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:

      -
        -
      1. -

        Creating an entire section and then insert it into the [[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

        -
        2. -
      2. -

        Using the following style sheet properties to show and hide document sections being used to represent the pop-up items, menus or dialogs:

        -
          -
        • display:block
          • -
        • display:none
          • -
        • visibility:visible
          • -
        • visibility: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.

        -
        3. -
      -

      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);
+        
      
+            
      HTML5 Sectioning Elements
      
 
+            
      
+                It is important to understand that many HTML5 sectioning elements by default define ARIA landmarks.
+                If HTML5 sectioning elements are used without understanding the associated landmark structure, assistive technology users will most likely be confused and less efficient in accessing content and interacting with web pages.
+                More information on HTML5 element role mapping.
+            
      
 
-    //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 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>
-    
-    
    9. 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>
      
-    
      10. 
-    
    10. 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.
      
-    
      11. 
-    
    11. 
-      
      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.
+                
      12. 
+                    
+                        
 
-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. 
      
-    
-    
    12.  Compensate for Background Images when in High Contrast Mode
-      
      Authors use background images when styling their widgets, including situations where the background image is not merely decorative, but informative.  An example is a horizontal progress bar that it is filled by gradually revealing more of a background image.  This is accomplished by initially setting the width of the element to zero, and then incrementing its width in accordance with the degree of progress.
      
-      
      High contrast mode is an operating system display modification that makes the screen easier to see for low vision users.  Some operating systems (e.g., Windows), do not display background images when in high contrast mode.  Consequently, the progress bar described above appears empty regardless of the progress.  It is recommended that authors not use background images as the sole method to convey important information, and to compensate with alternative or additional style rules. 
      
-      
      In the case of the progress bar example, a technique that works when in high contrast mode is to style the element with a border.  Since the width of the element is updated as progress increases, its border gradually expands horizontally forming an ever wider unfilled rectangle.  This provides alternative visual feedback as to the extent of the progress.
      
-      
      Another technique is to replace a background image with text.  Consider a dialog that uses a background image for its close box.  To compensate for the missing close box when in high contrast mode, a lower case 'x' is used instead.  The compensation technique used depends on the context, particularly the purpose of the background image.
      
-      
      There are two general approaches with respect to detecting high contrast mode.  They are (1) executing a script to determine if the system is in high contrast mode, or (2) providing a preference to use alternative styles.  The advantage of automatic detection is that some operating systems simply apply a different color palette when in high contrast mode and do not turn off background images.  In that case, authors need not compensate for missing background images.  However, detection of high contrast mode by script is relatively expensive compared to a preference that users can set, and, presumably, users can see whether background images are displayed in high contrast mode on their system.  It is up to individual authors to decide which method they find acceptable for their particular situation.
      
-      
      The following code fragment outlines how to detect high contrast mode. 
      
-      
      -/* Define styles for the high contrast test element */
-#hiContrastTestEl {
-    border: 1px solid;
-    border-color:red green;
-    position: absolute;
-    height: 5px;
-    top: -999px;
-    background-image: url('resources/blank.gif');
-}
-…
-// An onload event handler that inserts the high contrast test element and
-// then tests its computed styles.
-function detectHiContrast() {
-    var div = document.createElement('div');
-    div.setAttribute ('id', 'hiContrastTestEl');
-    // … append <div#hiContrastTestEl> to the <body> element …
-    var cs = window.getComputedStyle(div);
-    var bki = cs.backgroundImage;
-    var hiContrast = false;
-
-    // The CSS sets the top and right borders of the test element to red and
-    // green, respectively.  In high contrast mode either the borders are
-    // the same color, or there is no legitimate url to the background image.
-    hiContrast =    (cs.borderTopColor == cs.borderRightColor) ||
-                    (bki != null && (bki == 'none' || bki == 'url (invalid-url:)'));
-
-    if (hiContrast) {
-        // apply hi contrast styles to compensate for missing background images.
-    }
-    // … remove the test element from the document …
-}
      
-    
      13. 
-    
    13.  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.
      
-    
      14. 
-  
-
-  
      
-  
       Developing a Keyboard Interface
      
-  
      
-  Unlike native HTML form elements, browsers do not provide keyboard support for graphical user interface (GUI) components that are made accessible with ARIA; authors have to provide the keyboard support in their code.
-  This section describes the principles and methods for making the functionality of a web page that includes ARIA widgets, such as menus and grids,  as well as interactive components, such as toolbars and dialogs, operable with a keyboard. 
-  Along with the basics of focus management, this section offers guidance toward the objective of providing experiences to people who rely on a keyboard that are as efficient and enjoyable as the experiences available to others. 
-  It covers:
-  
      
-  
        
-  
      1. Understanding fundamental principles of focus movement conventions used in ARIA design patterns.
        2. 
-  
      2. Maintaining visible focus, predictable focus movement, and distinguishing between keyboard focus and the selected state.
        3. 
-  
      3. Managing movement of keyboard focus between components, e.g., how the focus moves when the Tab and Shift+Tab keys are pressed.
        4. 
-  
      4. Managing movement of keyboard focus inside components that contain multiple focusable elements, e.g., two different methods for programatically exposing focus inside widgets like radio groups, menus, listboxes, trees, and grids.
        5. 
-  
      5. Managing focus for modal and non-modal dialogs.
        6. 
-  
      6. Determining when to make disabled interactive elements focusable. 
        7. 
-  
      7. Assigning and revealing keyboard shortcuts, including guidance on how to avoid problematic conflicts with keyboard commands of assistive technologies, browsers, and operating systems.
        8. 
-  
      8. Addressing macro navigation concerns, i.e., methods for enabling efficient keyboard access to different sections of a page or site.
        9. 
-  
      
-    
      
-    
      Fundamental Keyboard Navigation Conventions
      
-      
      
-      ARIA roles, states, and properties model accessibility behaviors and features shared among GUI components of popular desktop GUIs, including Microsoft Windows, Mac OS X, and GNOME.
-      Similarly, ARIA design patterns borrow user expectations and keyboard conventions from those platforms, consistently incorporating common conventions with the aim of facilitating easy learning and efficient operation of keyboard interfaces across the web.
-      
      
-      
      
-      For a web page to be accessible, all interactive elements must be operable via the keyboard.
-      In addition, consistent application of the common GUI keyboard interface conventions described in the ARIA design patterns is important, especially  for assistive technology users. 
-      Consider, for example, a screen reader user operating a tree.
-      Just as familiar visual styling helps users discover how to expand a tree branch with a mouse, ARIA attributes give the tree the sound and feel of a tree in a desktop application.
-      So, screen reader users will commonly expect that pressing the right arrow key will expand  a collapsed node. 
-      Because the screen reader knows the element is a tree, it also has the ability to instruct a novice user how to operate it. 
-      Similarly, voice recognition software can implement commands for expanding and collapsing branches because it recognizes the element as a tree and can execute appropriate keyboard commands.
-      All this is only possible if the tree implements the GUI keyboard conventions as described in the ARIA tree pattern.
-      
      
-      
      
-      A primary keyboard navigation convention common across all platforms is that the tab and shift+tab keys move focus from one UI component to another while other keys, primarily the arrow keys, move focus inside of components that include multiple focusable elements.
-      The path that the focus follows when pressing the tab key is known as the tab sequence or tab ring.
-      
      
-      
      
-      Common examples of UI components that contain multiple focusable elements are radio groups, tablists, menus, and grids.
-      A radio group, for example, contains multiple radio buttons, each of which is focusable. 
-      However, only one of the radio buttons is included in the tab sequence. 
-      After pressing the Tab key moves focus to a radio button in the group, pressing arrow keys moves focus among the radio buttons in the group, and pressing the Tab key moves focus out of the radio group to the next element in the tab sequence.
-      
      
-      
      
-      The ARIA specification refers to a discrete UI component that contains multiple focusable elements as a composite widget.
-      The process of controlling focus movement inside a composite is called managing focus. 
-      Following are some ARIA design patterns with example implementations that demonstrate focus management:
-      
      
-      
      
+                    
+
+                    
+                        
+
+                        
+                    
+
+                    
+                        
+
+                        
+                    
+
+                    
+                        
+
+                        
+                    
+
+                    
+                        
+
+                        
+                    
+
+                    
+                        
+
+                        
+                    
+                
+            
      Default landmark roles for HTML5 sectioning elements
      HTML5 ElementDefault Landmark Role
      asidecomplementary
      footercontentinfo when in context of the body element
      headerbanner when in context of the body element
      mainmain
      navnavigation
      sectionregion when it has an accessible name using aria-labelledby or aria-label
      
+        
      
+
+        
      
+            
      General Principles of Landmark Design
      
+
+            
      Due to the complexity of todays web content, if using landmarks, all content should reside in a semantically meaningful landmark in order that content is not missed by the user.
      
+
+            
      Step 1: Identify the logical structure
      
+
+            
        
+                
      • Break the page into perceivable areas of content which designers typically indicate visually using alignment and spacing.
        • 
+
+                
      • Areas can be further defined into logical sub-areas as needed.
        • 
+
+                
      • An example of a sub-area is a portlet in a portal application.
        • 
             
      
-      
      
-      
      
-      
      Discernable and Predictable Keyboard Focus 
      
-      
      
-      When operating with a keyboard, two essentials of a good experience are the abilities to easily discern the location of the keyboard focus and to discover where focus landed after a navigation key has been pressed.
-      The following factors affect to what extent a web page affords users these capabilities.
-      
      
-      
        
-      
      1. Visibility of the focus indicator: Users need to be able to easily distinguish the keyboard focus indicator from other features of the visual design. 
-      Just as a mouse user may move the mouse to help find the mouse pointer, a keyboard user may press a navigation key to watch for movement. 
-      If visual changes in response to focus movement are subtle, many users will lose track of focus and be unable to operate.
-      Authors are advised to rely on the default focus indicators provided by browsers. 
-      If overriding the default, consider:
-      
          
-      
        • something about ... Colors and gradients can disappear in high contrast modes.
          • 
-      
        • Users need to be able to easily distinguish between focus and selection as described in , especially when a component that contains selected elements does not contain the focus. 
          • 
-      
        • ... other considerations to be added ... 
          • 
-      
        
-      
        2. 
-      
      2. Persistence of focus: It is essential that there is always a component within the user interface that is active (document.activeElement is not null or is not the body element) 
-      and that the active element has a visual focus indicator. 
-      Authors need to manage events that effect the currently active element so focus remains visible and moves logically.
-      For example, if the user closes a dialog or performs a destructive operation like deleting an item from a list, the active element may be hidden or removed from the DOM.
-      If such events are not managed to set focus on the button that triggered the dialog or on the list item following the deleted item, browsers move focus to the body element, affectively causing a loss of focus within the user interface.
-      
        3. 
-      
      3. Predictability of movement: Usability of a keyboard interface is heavily influenced by how readily users can guess where focus will land after a navigation key is pressed. 
-      Some possible approaches to optimizing predictability include:
-      
          
-      
        • 
-      Move focus in a pattern that matches the reading order of the page's language. 
-      In left to right languages, for example, create a tab sequence that moves focus left to right and then top to bottom. 
-      
          • 
-      
        • 
-      Incorporate all elements of a section of the page in the tab sequence before moving focus to another section. 
-      For instance, in a page with multiple columns that has content in a left side bar, center region, and right side bar, build a tab sequence that covers all elements in the left sidebar before focus moves to the first focusable element in the center column. 
-      
          • 
-      
        • 
-      When the distance between two consecutive elements in the tab sequence is significant, avoid movement that would be perceived as backward. 
-      For example, on a page with a left to right language, a jump from the last element in the bottom right of the main content to the top element in a left-hand sidebar is likely to be less predictable and more difficult to follow, especially for users with a narrow field of view. 
-      
          • 
-      
        • 
-      Follow consistent patterns across a site.
-      The keyboard experience is more predictable when similar pages have similar focus movement patterns.
-      
          • 
-      
        •  Do not set initial focus when the page loads except in cases where:
-      
            
-      
          • The page offers a single, primary function that nearly all users employ immediately after page load.
            • 
-      
          • Any given user is likely to use the page often.
            • 
-      
          
-      
          • 
-      
        
-      
      
-      
      
-      
      
-      
      Focus VS Selection and the Perception of Dual Focus
      
-      
      
-      Occasionally, it may appear as if two elements on the page have focus at the same time.
-      For example, in a multi-select list box, when an option is selected it may be greyed.
-      Yet, the focus indicator can still be moved to other options, which may also be selected.
-      Similarly, when a user activates a tab in a tablist, the selected state is set on the tab and its visual appearance changes.
-      However, the user can still navigate, moving the focus indicator elsewhere on the page while the tab retains its selected appearance and state.
-      
      
-      
      
-      Focus and selection are quite different.
-      From the keyboard user's perspective, focus is a pointer, like a mouse pointer; it tracks the path of navigation.
-      There is only one point of focus at any time and all operations take place at the point of focus.
-      On the other hand, selection is an operation that can be performed in some widgets, such as list boxes, trees, and tablists. 
-      If a widget supports only single selection, then only one item can be selected and very often the selected state will simply follow the focus when focus is moved inside of the widget.
-      That is, in some widgets, moving focus may also perform the select operation.
-      However, if the widget supports multiple selection, then more than one item can be in a selected state, and keys for moving focus do not perform selection.
-      Some multi-select widgets do support key commands that both move focus and change selection, but those keys are different from the normal navigation keys.
-      Finally, when focus leaves a widget that includes a selected element, the selected state persists.
-      
      
-      
      
-      From the developer's perspective, the difference is simple -- the focused element is the active element (document.activeElement).
-      Selected elements are elements that have aria-selected="true".
-      
      
-      
      With respect to focus and the selected state, the most important considerations for designers and developers are: 
      
-      
        
-      
      • The visual focus indicator must always be visible.
        • 
-      
      • The selected state must be visually distinct from the the focus indicator. 
        • 
-      
      
+
+            
      Step 2: Assign landmark roles to each area
      
+
+            
        
+                
      • Assign landmark roles based on the type of content in the area.
        • 
+
+                
      • banner, main, complementary and contentinfo landmarks should be top level landmarks.
        • 
+
+                
      • Landmark roles can be nested to identify parent/child relationships of the information being presented.
        • 
+            
      
+
+            
      Step 3: Label areas
      
+
+            
        
+                
      • If a specific landmark role is used more than once on a web page, it should have a unique label.
        • 
+
+                
      • If a landmark is only used once on the page it may not require a label. See Landmark Roles section below. 
        • 
+
+                
      • If an area begins with a heading element (e.g. h1-h6) it can be used as the label for the area using the
+                aria-labelledby attribute.
        • 
+
+                
      • If an area requires a label and does not have a heading element, provide a label using the aria-label attribute.
        • 
+
+                
      • 
+                    Do not use the landmark role as part of the label.
+                    For example, a navigation landmark with a label "Site Navigation" will be announced by a screen reader as "Site Navigation Navigation".
+                    The label should simply be "Site".
+                
        • 
+            
      
+        
      
+
+        
      
+            
      Landmark Roles
      
+
+            
      
+                
      Banner
      
+
+                
      
+                    A banner landmark identifies site-oriented content at the beginning of each page within a website.
+                    Site-oriented content typically includes things such as the logo or identity of the site sponsor, and site-specific search tool.
+                    A banner usually appears at the top of the page and typically spans the full width.
+                
      
+
+                
        
+                    
      • Each page may have one banner landmark.
        • 
+
+                    
      • The banner landmark should be a top-level landmark.
        • 
+
+                    
      • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one banner landmark.
        • 
+
+                    
      • If a page includes more than one banner landmark, each should have a unique label (see Step 3 above).
        • 
+                
      
+
+                
      
+                    
      HTML5 Techniques
      
+                    
        
+                        
      • The HTML5 header element defines a banner landmark when its context is the body element.
        • 
+
+                        
      • 
+                            The HTML5 header element is not considered a banner landmark when it is descendant of any of following elements (see HTML Accessibility Mappings):
+                            
          
+                                
        • article
          • 
+                                
        • aside
          • 
+                                
        • main
          • 
+                                
        • nav
          • 
+                                
        • section
          • 
+                            
        
+                        
        • 
+                    
      
+
+                    
      ARIA Techniques
      
+
+                    
      If the HTML5 header element technique is not being used, a role="banner" attribute should be used to define a banner landmark.
      
+                
      
+
+                
      
+                    
      Examples
      
+
+                    
      Banner Landmark Example
      
+                
      
+
+            
      
+
+            
      
+                
      Complementary
      
+
+                
      A complementary landmark is a supporting section of the document, designed to be complementary to the main content at a similar level in the DOM hierarchy, but remains meaningful when separated from the main content.
      
+
+                
        
+                    
      • complementary landmarks should be top level landmarks (e.g. not contained within any other landmarks).
        • 
+
+                    
      • If the complementary content is not related to the main content, a more general role should be assigned (e.g. region).
        • 
+
+                    
      • If a page includes more than one complementary landmark, each should have a unique label (see Step 3 above).
        • 
+                
      
+
+                
      
+                    
      HTML5 Technique
      
+
+                    
      Use the HTML5 aside element to define a complementary landmark.
      
+
+                    
      ARIA Technique
      
+
+                    
      If the HTML5 aside element technique is not being used, use a role="complementary" attribute to define a complementary landmark.
      
+                
      
+
+                
      
+                    
      Examples
      
+
+                    
      Complementary Landmark Example
      
+                
      
+            
      
+
+            
      
+                
      Contentinfo
      
+
+                
      A contentinfo landmark is a way to identify common information at the bottom of each page within a website, typically called the "footer" of the page, including information such as copyrights and links to privacy and accessibility statements.
      
+
+                
        
+                    
      • Each page may have one contentinfo landmark.
        • 
+
+                    
      • The contentinfo landmark should be a top-level landmark.
        • 
+
+                    
      • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one contentinfo landmark.
        • 
+
+                    
      • If a page includes more than one contentinfo landmark, each should have a unique label (see Step 3 above).
        • 
+                
      
+
+                
      
+
+                    
      HTML5 Techniques
      
+
+                    
        
+                        
      • The HTML5 footer element defines a contentinfo landmark when its context is the body element.
        • 
+
+                        
      • 
+                            The HTML5 footer element is not considered a contentinfo landmark when it is descendant of any of following elements (see HTML Accessibility Mappings):
+                            
          
+                                
        • article
          • 
+                                
        • aside
          • 
+                                
        • main
          • 
+                                
        • nav
          • 
+                                
        • section
          • 
+                            
        
+                        
        • 
+                    
      
+
+                    
      ARIA Technique
      
+
+                    
      If the HTML5 footer element technique is not being used, a role="contentinfo" attribute should be used to define a contentinfo landmark.
      
+                
      
+
+                
      
+                    
      Examples
      
+                    
      Contentinfo Landmark Example
      
+                
      
+            
      
+
+            
      
+                
      Form
      
+
+                
      A form landmark identifies a region that contains a collection of items and objects that, as a whole, combine to create a form when no other named landmark is appropriate (e.g. main or search).
      
+
+                
        
+                    
      • Use the search landmark instead of the form landmark when the form is used for search functionality.
        • 
+
+                    
      • A form landmark should have a label to help users understand the purpose of the form.
        • 
+
+                    
      • A label for the form landmark should be visible to all users (e.g. an h1-h6 element).
        • 
+
+                    
      • If a page includes more than one form landmark, each should have a unique label (see Step 3 above).
        • 
+
+                    
      • 
+                        Whenever possible, controls contained in a form landmark in an HTML document should use native host semantics:
+                        
          
+                            
        • button
          • 
+
+                            
        • input
          • 
+
+                            
        • select
          • 
+
+                            
        • textarea
          • 
+                        
        
+                    
        • 
+                
      
+
+                
      
+                    
      HTML5 Techniques
      
+
+                    
      The HTML5 form element that defines a form landmark when it has an accessible name (e.g. aria-labelledby, aria-label or title).
      
+
+                    
      ARIA Technique
      
+
+                    
      Use the role="form" to identify a region of the page; do not use it to identify every form field.
      
+                
      
+
+                
      
+                    
      Examples
      
+
+                    
      Form Landmark Example
      
+                
      
+            
      
+
+            
      
+                
      Main
      
+
+                
      A main landmark identifies the primary content of the page.
      
+
+                
        
+                    
      • Each page should have one main landmark.
        • 
+
+                    
      • The main landmark should be a top-level landmark.
        • 
+
+                    
      • When a page contains nested document and/or application roles (e.g. typically through the use of iframe and frame elements), each document or application role may have one main landmark.
        • 
+
+                    
      • If a page includes more than one main landmark, each should have a unique label (see Step 3 above).
        • 
+                
      
+
+                
      
+                    
      HTML5 Technique
      
+
+                    
      Use the HTML5 main element to define a main landmark.
      
+
+                    
      ARIA Technique
      
+
+                    
      If the HTML5 main element technique is not being used, use a role="main" attribute to define a main landmark.
      
+                
      
+
+                
      
+                    
      Examples
      
+
+                    
      Main Landmark Example
      
+                
      
+            
      
+
+            
      
+                
      Navigation
      
+
+                
      Navigation landmarks provide a way to identify groups (e.g. lists) of links that are intended to be used for website or page content navigation.
      
+
+                
        
+                    
      • If a page includes more than one navigation landmark, each should have a unique label (see Step 3 above).
        • 
+
+                    
      • If a navigation landmark has an identical set of links as another navigation landmark on the page, use the same label for each navigation landmark.
        • 
+                
      
+
+                
      
+                    
      HTML5 Technique
      
+
+                    
      Use the HTML5 nav element to define a navigation landmark.
      
+
+                    
      ARIA Technique
      
+
+                    
      If the HTML5 nav element technique is not being used, use a role="navigation" attribute to define a navigation landmark.
      
+
+                
      
+
+                
      
+                    
      Examples
      
+
+                    
      Navigation Landmark Example
      
+                
      
+            
      
+
+            
      
+                
      Region
      
+
+                
      A region landmark is a perceivable section of the page containing content that is sufficiently important for users to be able to navigate to the section.
      
+
+                
        
+                    
      • A region landmark must have a label.
        • 
+
+                    
      • If a page includes more than one region landmark, each should have a unique label (see Step 3 above).
        • 
+
+                    
      • The region landmark can be used identify content that named landmarks do not appropriately describe.
        • 
+                
      
+
+                
      
+                    
      HTML5 Technique
      
+
+                    
      Use the HTML5 section element to define a region landmark.
      
+
+                    
      ARIA Technique
      
+
+                    
      If the HTML5 section element technique is not being used, use a role="region" attribute to define a region landmark.
      
+                
      
+
+                
      
+                    
      Examples
      
+
+                    
      Region Landmark Example
      
+                
      
+            
      
+
+            
+
    -
    -

    Keyboard Navigation Between Components (The Tab Sequence)

    -

    - As explained in section , all interactive UI components need to be reachable vai the keyboard. - This is best achieved by either including them in the tab sequence or by making them accessible from a component that is in the tab sequence, e.g., as part of a composite component. - This section addresses building and managing the tab sequence, and subsequent sections cover making focusable elements that are contained within components keyboard accessible. -

    -

    - The HTML tabindex - and SVG tabindex - attributes can be used to add and remove elements from the tab sequence. - The value of tabindex can also influence the order of the tab sequence, although authors are strongly advised not to use tabindex for that purpose. -

    -

    - In HTML, the default tab sequence of a web page includes only links and HTML form elements, except In Mac OS, where it includes only form elements. - Mac OS system preferences include a keyboard setting that enables the tab key to move focus to all focusable elements. -

    -

    - The default order of elements in the tab sequence is the order of elements in the DOM. - The DOM order also determines screen reader reading order. - It is important to keep the keyboard tab sequence and the screen reader reading order aligned, logical, and predictable as described in . - The most robust method of manipulating the order of the tab sequence while also maintaining alignment with the reading order that is currently available in all browsers is rearranging elements in the DOM. -

    -

    The values of the tabindex attribute have the following effects.

    -
    -
    tabindex is not present or does not have a valid value
    -
    The element has its default focus behavior. In HTML, only form controls and anchors with an HREF attribute are included in the tab sequence.
    -
    tabindex="0"
    -
    The element is included in the tab sequence based on its position in the DOM.
    -
    tabindex="-1"
    -
    The element is not included in the tab sequence but is focusable with element.focus().
    -
    tabindex="X" where X is an integer in the range 1 <= X <= 32767 + +
    +

    Developing a Keyboard Interface

    +

    Unlike native HTML form elements, browsers do not provide keyboard support for + graphical user interface (GUI) components that are made accessible with ARIA; authors + have to provide the keyboard support in their code. This section describes the + principles and methods for making the functionality of a web page that includes ARIA + widgets, such as menus and grids, as well as interactive components, such as toolbars + and dialogs, operable with a keyboard. Along with the basics of focus management, this + section offers guidance toward the objective of providing experiences to people who rely + on a keyboard that are as efficient and enjoyable as the experiences available to + others. It covers:

    +
      +
    1. Understanding fundamental principles of focus movement conventions used in ARIA + design patterns.
      2. +
    2. Maintaining visible focus, predictable focus movement, and distinguishing + between keyboard focus and the selected state.
      3. +
    3. Managing movement of keyboard focus between components, e.g., how the focus + moves when the Tab and Shift+Tab keys are pressed. +
      4. +
    4. Managing movement of keyboard focus inside components that contain multiple + focusable elements, e.g., two different methods for programatically exposing focus + inside widgets like radio groups, menus, listboxes, trees, and grids.
      5. +
    5. Managing focus for modal and non-modal dialogs.
      6. +
    6. Determining when to make disabled interactive elements focusable.
      7. +
    7. Assigning and revealing keyboard shortcuts, including guidance on how to avoid + problematic conflicts with keyboard commands of assistive technologies, browsers, + and operating systems.
      8. +
    8. Addressing macro navigation concerns, i.e., methods for enabling efficient + keyboard access to different sections of a page or site.
      9. +
    +
    +

    Fundamental Keyboard Navigation Conventions

    +

    ARIA roles, states, and properties model accessibility behaviors and features + shared among GUI components of popular desktop GUIs, including Microsoft Windows, + Mac OS X, and GNOME. Similarly, ARIA design patterns borrow user expectations and + keyboard conventions from those platforms, consistently incorporating common + conventions with the aim of facilitating easy learning and efficient operation of + keyboard interfaces across the web.

    +

    + For a web page to be accessible, all interactive elements must be operable via the + keyboard. In addition, consistent application of the common GUI keyboard interface + conventions described in the ARIA design patterns is + important, especially for assistive technology users. Consider, for example, a + screen reader user operating a tree. Just as familiar visual styling helps users + discover how to expand a tree branch with a mouse, ARIA attributes give the tree the + sound and feel of a tree in a desktop application. So, screen reader users will + commonly expect that pressing the right arrow key will expand a collapsed node. + Because the screen reader knows the element is a tree, it also has the ability to + instruct a novice user how to operate it. Similarly, voice recognition software can + implement commands for expanding and collapsing branches because it recognizes the + element as a tree and can execute appropriate keyboard commands. All this is only + possible if the tree implements the GUI keyboard conventions as described in the ARIA tree pattern. +

    +

    + A primary keyboard navigation convention common across all platforms is that the + tab + and + shift+tab + keys move focus from one UI component to another while other keys, primarily the + arrow keys, move focus inside of components that include multiple focusable + elements. The path that the focus follows when pressing the + tab + key is known as the tab sequence or tab ring. +

    +

    + Common examples of UI components that contain multiple focusable elements are radio + groups, tablists, menus, and grids. A radio group, for example, contains multiple + radio buttons, each of which is focusable. However, only one of the radio buttons is + included in the tab sequence. After pressing the + Tab + key moves focus to a radio button in the group, pressing arrow keys moves focus + among the radio buttons in the group, and pressing the + Tab + key moves focus out of the radio group to the next element in the tab sequence. +

    +

    + The ARIA specification refers to a discrete UI component that contains multiple + focusable elements as a composite + widget. The process of controlling focus movement inside a composite is called + managing focus. Following are some ARIA design patterns with example implementations + that demonstrate focus management: +

    + +
    +
    +

    Discernable and Predictable Keyboard Focus

    +

    When operating with a keyboard, two essentials of a good experience are the + abilities to easily discern the location of the keyboard focus and to discover where + focus landed after a navigation key has been pressed. The following factors affect + to what extent a web page affords users these capabilities.

    +
      +
    1. Visibility of the focus indicator: Users need to be able to easily + distinguish the keyboard focus indicator from other features of the visual + design. Just as a mouse user may move the mouse to help find the mouse pointer, + a keyboard user may press a navigation key to watch for movement. If visual + changes in response to focus movement are subtle, many users will lose track of + focus and be unable to operate. Authors are advised to rely on the default focus + indicators provided by browsers. If overriding the default, consider: +
        +
      • something about ... Colors and gradients can disappear in high + contrast modes.
        • +
      • Users need to be able to easily distinguish between focus and + selection as described in , + especially when a component that contains selected elements does not + contain the focus. +
        • +
      • ... other considerations to be added ...
        • +
      +
      2. +
    2. Persistence of focus: It is essential that there is always a component + within the user interface that is active (document.activeElement is not null or + is not the body element) and that the active element has a visual focus + indicator. Authors need to manage events that effect the currently active + element so focus remains visible and moves logically. For example, if the user + closes a dialog or performs a destructive operation like deleting an item from a + list, the active element may be hidden or removed from the DOM. If such events + are not managed to set focus on the button that triggered the dialog or on the + list item following the deleted item, browsers move focus to the body element, + affectively causing a loss of focus within the user interface.
      3. +
    3. Predictability of movement: Usability of a keyboard interface is heavily + influenced by how readily users can guess where focus will land after a + navigation key is pressed. Some possible approaches to optimizing predictability + include: +
        +
      • Move focus in a pattern that matches the reading order of the + page's language. In left to right languages, for example, create a tab + sequence that moves focus left to right and then top to bottom.
        • +
      • Incorporate all elements of a section of the page in the tab + sequence before moving focus to another section. For instance, in a page + with multiple columns that has content in a left side bar, center + region, and right side bar, build a tab sequence that covers all + elements in the left sidebar before focus moves to the first focusable + element in the center column.
        • +
      • When the distance between two consecutive elements in the tab + sequence is significant, avoid movement that would be perceived as + backward. For example, on a page with a left to right language, a jump + from the last element in the bottom right of the main content to the top + element in a left-hand sidebar is likely to be less predictable and more + difficult to follow, especially for users with a narrow field of view.
        • +
      • Follow consistent patterns across a site. The keyboard experience + is more predictable when similar pages have similar focus movement + patterns.
        • +
      • Do not set initial focus when the page loads except in cases where: +
          +
        • The page offers a single, primary function that nearly all + users employ immediately after page load.
          • +
        • Any given user is likely to use the page often.
          • +
        +
        • +
      +
    +
    +
    +

    Focus VS Selection and the Perception of Dual Focus

    +

    Occasionally, it may appear as if two elements on the page have focus at the same + time. For example, in a multi-select list box, when an option is selected it may be + greyed. Yet, the focus indicator can still be moved to other options, which may also + be selected. Similarly, when a user activates a tab in a tablist, the selected state + is set on the tab and its visual appearance changes. However, the user can still + navigate, moving the focus indicator elsewhere on the page while the tab retains its + selected appearance and state.

    +

    Focus and selection are quite different. From the keyboard user's perspective, + focus is a pointer, like a mouse pointer; it tracks the path of navigation. There is + only one point of focus at any time and all operations take place at the point of + focus. On the other hand, selection is an operation that can be performed in some + widgets, such as list boxes, trees, and tablists. If a widget supports only single + selection, then only one item can be selected and very often the selected state will + simply follow the focus when focus is moved inside of the widget. That is, in some + widgets, moving focus may also perform the select operation. However, if the widget + supports multiple selection, then more than one item can be in a selected state, and + keys for moving focus do not perform selection. Some multi-select widgets do support + key commands that both move focus and change selection, but those keys are different + from the normal navigation keys. Finally, when focus leaves a widget that includes a + selected element, the selected state persists.

    +

    + From the developer's perspective, the difference is simple -- the focused element is + the active element (document.activeElement). Selected elements are elements that + have + aria-selected="true" + . +

    +

    With respect to focus and the selected state, the most important considerations + for designers and developers are:

    +
      +
    • The visual focus indicator must always be visible.
      • +
    • The selected state must be visually distinct from the the focus indicator. +
      • +
    +
    +
    +

    Keyboard Navigation Between Components (The Tab Sequence)

    +

    + As explained in section , all interactive UI + components need to be reachable vai the keyboard. This is best achieved by either + including them in the tab sequence or by making them accessible from a component + that is in the tab sequence, e.g., as part of a composite component. This section + addresses building and managing the tab sequence, and subsequent sections cover + making focusable elements that are contained within components keyboard accessible. +

    +

    + The HTML + tabindex and SVG + tabindex attributes can be used to add and remove elements from the tab + sequence. The value of tabindex can also influence the order of the tab sequence, + although authors are strongly advised not to use tabindex for that purpose. +

    +

    In HTML, the default tab sequence of a web page includes only links and HTML form + elements, except In Mac OS, where it includes only form elements. Mac OS system + preferences include a keyboard setting that enables the tab key to move focus to all + focusable elements.

    +

    + The default order of elements in the tab sequence is the order of elements in the + DOM. The DOM order also determines screen reader reading order. It is important to + keep the keyboard tab sequence and the screen reader reading order aligned, logical, + and predictable as described in . + The most robust method of manipulating the order of the tab sequence while also + maintaining alignment with the reading order that is currently available in all + browsers is rearranging elements in the DOM. +

    +

    The values of the tabindex attribute have the following effects.

    +
    +
    tabindex is not present or does not have a valid value
    +
    The element has its default focus behavior. In HTML, only form controls and + anchors with an HREF attribute are included in the tab sequence.
    +
    tabindex="0"
    +
    The element is included in the tab sequence based on its position in the + DOM.
    +
    tabindex="-1"
    +
    The element is not included in the tab sequence but is focusable with + element.focus().
    +
    + tabindex="X" where X is an integer in the range 1 <= X <= 32767 +
    Authors are strongly advised NOT to use these values. The element is placed in the tab sequence based on the value of tabindex. Elements with a tabindex value of 0 and elements that are focusable by default will be in the sequence after elements with a tabindex value of 1 or greater.
    @@ -3588,7 +2339,8 @@

    Keyboard Navigation Inside Components

    As described in section , the tab sequence should include only one focusable element of a composite UI component. Once a composite contains focus, keys other than Tab and Shift+Tab enable the user to move focus among its focusable elements. - Authors are free to choose which keys move focus inside of a composite, but they are strongly advised to use the same key bindings as similar components in common GUI operating systems as demonstrated in . + Authors are free to choose which keys move focus inside of a composite, but they are strongly advised to use the same key bindings as similar components in common GUI operating systems as demonstrated in .

    The convention for where focus lands in a composite when it recieves focus as a result of a Tab key event depends on the type of composite. @@ -3640,7 +2392,8 @@

    Managing Focus Within Components Using a Roving tabindex

    Managing Focus in Composites Using aria-activedescendant

    - If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. + If a component container has an ARIA role that supports the aria-activedescendant property, it is not necessary to manipulate the tabindex attribute and move DOM focus among focusable elements within the container. Instead, only the container element needs to be included in the tab sequence. When the container has DOM focus, the value of aria-activedescendant on the container tells assistive technologies which element is active within the widget. Assistive technologies will consider the element referred to as active to be the focused element even though DOM focus is on the element that has the aria-activedescendant property. And, when the value of aria-activedescendant is changed, assistive technologies will receive focus change events equivalent to those received when DOM focus actually moves. @@ -3651,11 +2404,14 @@

    Managing Focus in Composites Using aria-activedescendant

    • When the container element that has a role that supports aria-activedescendant is loaded or created, ensure that:
        -
      • The container element is included in the tab sequence as described in or it is otherwise focusable as described in .
        • +
      • The container element is included in the tab sequence as described in or it is otherwise focusable as described in .
      • It has aria-activedescendant="IDREF" where IDREF is the ID of the element within the container that should be identified as active when the widget receives focus. The referenced element needs to meet the DOM relationship requirements described below.
      • -
    • When the container element receives DOM focus, draw a visual focus indicator on the active element and ensure the active element is scrolled into view. See section Managing Focus with Scroll below for more information. +
    • When the container element receives DOM focus, draw a visual focus indicator on the active element and ensure the active element is scrolled into view. See section Managing Focus with Scroll below for more information.
    • When the composite widget contains focus and the user presses a navigation key that moves focus within the widget, such as an arrow key:
        @@ -3674,11 +2430,14 @@

        Managing Focus in Composites Using aria-activedescendant

        1. The element referenced as active is a DOM descendant of the focused referencing element.
          2. -
        2. The focused referencing element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
          3. -
        3. The focused referencing element has role of textbox and has aria-controls property referring to an element with a role that supports aria-activedescendant and either: +
        4. The focused referencing element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
          5. +
        5. The focused referencing element has role of textbox and has aria-controls property referring to an element with a role that supports aria-activedescendant and either:
          1. The element referenced as active is a descendant of the controlled element.
            2. -
          2. The controlled element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
            3. +
          3. The controlled element has a value specified for the aria-owns property that includes the ID of the element referenced as active.
        @@ -3697,7 +2456,8 @@
        Managing Focus with Scroll
        using available measurements such as scroll+offset+clientWidth/Height/Left/Top. It's important to note that you have to adjust a node so that it's viewable within the context of its parent node.  Then you have to move up the DOM tree and make each parent node visible.

        -

        For example, create a custom scrollIntoView() method that is called at various times, including coincidence with the setting of the aria-activedescendant property. The method takes a DOM node argument, say "n". Here is the high level algorithm:

        +

        For example, create a custom scrollIntoView() method that is called at various times, including coincidence with the setting of the aria-activedescendant property. The method takes a DOM node argument, say "n". Here is the high level algorithm:

        1. If n is already in view, stop; otherwise, continue.
        2. adjust n.scrollTop and n.scrollLeft such that it is in view.
          3. @@ -3847,7 +2607,8 @@

          Focusability of disabled controls

        - One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in . + One design technique for mitigating the impact of including disabled elements in the path of keyboard focus is employing appropriate keyboard shortcuts as described in .

    @@ -4076,14 +2837,17 @@

    Miscelaneous stuff we might or might not keep

    Always draw the focus for tabindex="-1" items and elements that receive focus programmatically when supporting versions of Internet Explorer older than 8 - Choose between changing the background color via something like this.style.backgroundColor = "gray"; or add a dotted border via this.style.border = "1px dotted invert". In the dotted border case, you will need to make sure those elements have an invisible 1px border to start with, so that the element doesn't grow when the border style is applied (borders take up space, and IE doesn't implement CSS outlines).
  • -

    Prevent used key events from performing browser functions - If a key such as an arrow key is used, prevent the browser from using the key to do something (such as scrolling) by using code like the following:

    +

    + Prevent used key events from performing browser functions - If a key such as an arrow key is used, prevent the browser from using the key to do something (such as scrolling) by using code like the following:

    <span tabindex="-1" onkeypress="return  handleKeyPress();">

    If handleKeyDown() returns false, the event will be consumed, preventing the browser from performing any action based on the keystroke. In addition to the return value the browser must call the event methods that will prevent the default action, for IE this is setting the event property "returnValue=false", and for other browsers supporting the W3C event model this means calling the "preventDefault" method of the event object.

  • Use key event handlers to enable activation of the element - For every mouse event handler, a keyboard event handler is required. For example, if you have an onclick="doSomething()" you may also need onkeydown="return event.keyCode != 13 || doSomething();" in order to allow the Enter key to activate that element. - There are user agent-specific considerations for key event handling. + There are user agent-specific considerations for key event handling.
    • @@ -4091,14 +2855,19 @@

    Miscelaneous stuff we might or might not keep

    Supporting Tooltips with the Keyboard

    A tooltip is a popup messages typically triggered by moving a mouse over a control or widget causing a small popup window to appear with additional information about the control. - To provide simple text tooltips, the HTML title attribute should more than suffice because the user agent will render it for tooltips. + To provide simple text tooltips, the HTML title attribute should more than suffice because the user agent will render it for tooltips. When creating a tooltip, it is essential that the user be able to activate it using the keyboard. - When a form control or widget receives keyboard focus, the tooltip must display. + When a form control or widget receives keyboard focus, the tooltip must display. When the form control or widget loses focus, the tooltip must disappear. Browsers do not currently support this functionality.

    - The following code snippet from the iCITA site shows the use of a onfocus="tooltipShow();" function to display the tooltip when focus is placed on an element. + The following code snippet from the iCITA site shows the use of a onfocus="tooltipShow();" function to display the tooltip when focus is placed on an element. 

    <html lang="en-us"">
 <head>
@@ -4134,1647 +2903,33 @@ 
     Supporting Tooltips with the Keyboard
    -
    -

    Other Widget Authoring Practices

    -

    - MCK: Setting this content aside to determine whether we will remove or rewrite it. -

    -

    - The Common Widget Design Patterns section of this document contains best practices, such as keyboard navigation, for creating common widgets found on the Web. - This section contains miscellaneous authoring practices that you should also consider. -

    -
    -
    Maintain a valid format for aria-valuenow
    -

    It is essential that application vendors maintain a valid format for -aria-valuenow, and aria-valuenow should -accurately represent the value of the widget.The value must be within range of aria-valuemax and aria-valuemin, where the value of aria-valuemin is less than or equal to the value of aria-valuemax, throughout the life cycle of your widget. If aria-valuemin is not less than or equal to the value of aria-valuemax, or if the aria-valuemax is indeterminate, this creates an error condition that will be handled by -the assistive technology, resulting in undesirable results. Should an alternative text - equivalent be needed to properly represent the aria-valuenow, such as a day - of the week, then you should accompany the aria-valuenow with an appropriate - aria-valuetext equivalent such as in this example:

    -
    -<div role="slider"
-  aria-valuenow="1"
-  aria-valuemin="1"
-  aria-valuemax="7"
-  aria-valuetext="Sunday">
-
    -

    -Here the values 1 through 7 represent the days of the week and - aria-valuenow of 1 is equivalent to the first day of the week or Sunday. When aria-valuetext is made available aria-valuenow should also be treated as an index which is 1 based.

    -
    -
    +
    -

    Grid and Table Properties

    +

    Grid and Table Properties

    [placeholder ]. This section will cover colcount, rowcount, colindex, rowindex, colspan, rowspan, and sort. It will explain when they are useful and how to use them. It is referenced by the grid and table design patterns. This section will refer readers to the grid and table design patterns for the basics of grid and table.

    -
    -

    Relationships

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -
    -

    Labeling and Describing

    -

    Marked up content or widgets will often need additional context to make clear what the meaning or purpose is. It is also reasonable that some content media types will need additional descriptions in another format to give clarity to those who are unable to consume the origin format. These additional meta-content sections are linked together by tagging them as labels or descriptions. WAI-ARIA provides the aria-labelledby and aria-describedby attributes to signal the browser to feed these relationships into the accessibility layer. This layer is then used by screen readers and other accessibility technology (AT) to gain awareness of how disparate regions are actually contextually connected to each other. With this awareness the AT can then present a meaningful navigation model for discovery and presentation of these additional content sections. The user agent itself can also choose to present these insights in a meaningful way. Generally you should always add these attributes to any widgets on your site as they are often merely a construct of HTML and JavaScript which provides no obvious insight as to what the widget's behavior or interactivity is.

    -
    -

    Labeling

    - When using one element to label another use the aria-labelledby by attribute. A label should provide the user with the essence of what the object does. For example, you could have a dialog box erected from HTML <div> and you need to associate a label for the dialog. With a WAI-ARIA role of dialog, you can indicate its widget type and define a label using an HTML header and then associate that label with the dialog using the aria-labelledby relationship. - 
    -  <div role="dialog" aria-labelledby="dialogheader">
-  <h2 id="dialogheader">Choose a File</h2>
-  … Dialog contents
-  </div>
-
    -

    The section doing the labeling might be referenced by multiple widgets or objects as these need only reference the same id, so contextual description may not always be viable. The labelledby attribute can have multiple ids specified as a space separated list much like applying multiple classes to a single DOM object.

    -

    The aria-labelledby property can be used to label all visual objects, however it should be noted that (X)HTML provides a @for attribute on the label element which is used to label form controls. Use this attribute where possible and valid. Because the aria-labelledby attribute accepts multiple IDREFs, it is recommended that authors use aria-labelledby for labeling elements that require more than one label string.

    -

    Some elements receive their label for embedded text content, but that is the exception.

    -

    Often user agents will operate with images turned off for network performance reasons. In these situations, alt text is provided in the place of the image. When the host language provides alternative text capability it is recommended that authors use the alternative text to support these situations and not use separate labeling as a replacement.

    -
    -
    -

    Describing

    -
    -

    Using aria-describedby

    -

    When one element describes another, use the aria-describedby attribute. An aria-describedby section provides further information about a given object or widget, which may not be intuitively obvious from the context, content or other attributes. For example, a fake window is a common widget used in Web applications and is often constructed using a div absolute positioned in a layer above other content. To simulate common window behavior look and feel there is often an X box in the corner which, when activated, dismisses the window widget. One common way to make this X box is to simply make a link whose content is an X. This doesn't give a non-visual user much to go on and belies the real purpose of the X link. To help we add more descriptive text stored elsewhere in the page like this:

    - 
    <button aria-label="Close" aria-describedby="descriptionClose"
-    onclick="myDialog.close();">X</button>
    - and then elsewhere in the HTML - 
    <div id="descriptionClose">Closing this window will discard any information entered and
-return you back to the main page</div>
    - Like labelledby, describedby can accept multiple ids to point to other regions of the page using a space separated list. It is also limited to ids for defining these sets. In our contrived example we would also want a good labelledby section to fully explain what the window does and how closing will effect the task being worked on. If an object or widget lacks describedby the user agent or AT may try to extract information from the label or th tags, if present. The label and th tags have limited use in that they can only be applied to forms or tables, respectively. + +
    +

    Appendices

    + +
    +

    Understanding Screen Reader Document Reading and Application Reading Modes

    +

    Placeholder for a section covering this topic that is yet to be written.

    -
    -

    Using a tooltip as a description

    -

    WAI-ARIA also defines the tooltip role to which aria-describedby may reference an author defined tooltip. The assistive technology can tell from the type of object describing the document element what the purpose of that element is. For example, a screen reader could announce the tooltip without the user having to wave the mouse over the element by following the describedby relationship to a document area with a tooltip role. The aria-describedby property is also useful for describing groups.

    -

    Here is a code snippet showing a set of the tooltip:

    - 
    …
-  <div class="text">
-    <label for="first">First Name:</label>
-      <input type="text"
-          id="first"
-          name="first"
-          size="20"
-          onfocus="tooltipShow(tooltip1);"
-          onblur="tooltipHide(tooltip1);"
-          onmouseover="tooltipShow(tooltip1);"
-          onmouseout="tooltipHide(tooltip1);"
-          aria-describedby="tp1"
-      />
-  <div id="tp1" class="tooltip" role="tooltip">Your first name is optional</div>
-  </div>
-…
    -
    -
    -

    Descriptions on external pages

    -

    The aria-describedby property is not designed to reference descriptions on an external resource—since it is an IDREF, it must reference an element in the same DOM document. This is different from the HTML longdesc attribute, which accepts any URI. In general, the preferred pattern for WAI-ARIA applications is to include all relevant resources in the same DOM, But if you wish to reference an external resource with aria-describedby, you can reference a link that in turn references the external resource. This requires the user to follow two steps, first following the aria-describedby arc, then following the link, but does address the use case. The following example demonstrates this:

    - 
    <p>
-   <img
-       src="images/histogram.png"
-       alt="Histogram of Blackberry tree heights"
-       width="40%"
-       aria-describedby="longdesc1"
-   />
-</p>
-
-<p>
-    <a id="longdesc1" href="blackberry-description.html" target="_description">Data for Blackberry Histogram</a>
-</p>
    -
    -
    -

    It is not good practice to use the above pattern when the describing element—the <a> tag with @id='longdesc1'—is hidden, since there is no way for a user to navigate to and activate the link. Use the technique only when the description is not hidden.

    -
    -
    -

    Owning and Controlling

    -

    Two relationships expand the logical structure of a WAI-ARIA Web application. These are aria-owns and aria-controls .  The aria-owns relationship completes the parent/child relationship when it cannot be completely determined from the DOM created from the parsing of the markup. The aria-controls relationship defines a cause-and-effect relationship so that assistive technologies may navigate to content effected by and changes to the content where the user is operating.

    -
    -

    The Owns Relationship

    -

    In addition to WAI-ARIA role and state information, for a document element, -an assistive technology needs to convey its context. In -the case of a treeitem, it is important to know the parent (container), - which may provide a folder depth and the number of siblings in the folder. This containment hierarchy can often be determined by -the DOM tree, as it provides parent, siblings, and children for a given -document element. That said, the DOM hierarchy is rigid and non cyclical in -that each node may only have one parent. In some situations, a child -is reused by multiple parents or a child is separated from its -siblings or parent in the DOM tree. One example is when a radio button -appears in a table but it is not a DOM child of the radiogroup, due to the -authors use of a table for formatting and the placement of the radio buttons -placing them outside the radiogroup container. To solve this problem -WAI-ARIA provides the aria-owns property.

    -

    -The aria-owns property is set on a document element, and its values are the -unique IDs of all the adopted children. These elements may appear anywhere -in the DOM, yet they are treated as siblings of each owning parent. This -example illustrates a radiogroup that first uses the DOM hierarchy to -convey context and then aria-owns:

    -

    First, consider the preferred method for using the W3C DOM to describe the relationship between - radiogroup and radio roles for HTML:

    -
    -<div id="radio_label">My radio label</div>
-<ul role="radiogroup" aria-labelledby="radio_label">
-<li role="radio">Item #1</li>
-<li role="radio">Item #2</li>
-<li role="radio">Item #3</li>
-</ul>
-
    -

    -In this example, the elements with role="radio" are child nodes of the parent role="radiogroup" element node. - -

    -

    -Now, consider an alternative method using the aria-owns property to describe the parent-child -role relationship between radiogroup and radio roles for HTML:

    -
    -<table>
-<tr>
-<td role="radiogroup" aria-owns="myradio1 myradio2 myradio3" rowspan="3" >
-My Radio Label
-</td>
-<td id="myradio1" role="radio">Item #1</td>
-</tr>
-<tr>
-<td id="myradio2" role="radio">Item #2</td>
-</tr>
-<tr>
-<td id="myradio3" role="radio">Item #3</td>
-</tr>
-</table>
-
    -

    -The aria-owns property should be used sparingly, since it -increases the computational load on assistive technology to provide -alternative renderings. Also, when accessing the DOM and enumerating -children of a DOM node, an AT should then enumerate the adopted children -using the aria-owns property. At that instance of walking the DOM, the -parent of the adopted children is the adopted parent and not the DOM -parent. This will avoid recursion problems.

    -

    -Each child, adopted or natural, should have the appropriate - aria-posinset and aria-setsize properties set consistent with their -rendering, if these cannot be determined from the DOM from a direct parsing of -the host language. Places where direct parsing does not allow the user -agent to determine - aria-posinset and aria-setsize are long lists where only -the currently visible items are loaded (via Ajax). If the children are -re-sorted then the - aria-posinset and aria-setsize values should be updated -consistent with their visual rendering. Rather than setting size only on a container, content authors should specify aria-setsize on each member of a set to avoid performance issues.  If this property is not set, the user agent must compute and set the property on supporting roles.

    -

    Platform accessibility API mappings must invert this relationship for - assistive technologies, so that they may determine the owning parent from a - child and couple it with aria-posinset and aria-setsize information to - provide context information to the user.

    -
    -
    -

     Using Owns with Reusable Content

    -

    If you are re-using content across different, transient sections of content by restyling it to render it in association with a different object, you need to maintain the aria-owns property as well to match the current use and apparent ancestry of the reused sub-section. A good example of this is a context help menu that resides at the end of the document. When the user wishes to launch the context help menu in association with different visual elements, styling is used to render the menu in context with that object. Prior to rendering the visual submenu you should ensure the object to which you have requested help assigns its aria-owns property value to the submenu ID. When the menu closes you can remove the aria-owns property.

    -
    -
    -

    The Controls Relationship

    -

    In rich internet applications document elements may control the behavior on another part of Web page outside themselves. The aria-controls attribute indicates cause-and-effect relationships between document elements.

    -

    An example might be a group of radio buttons that "control" contents of a listbox in another part of the page. Here, you would want the radio group to assign a aria-controls relationship to the listbox which will be updating without a page reload. The user, through their assistive technology, can then navigate to the listbox by following the aria-controls relationship when a different radio is selected, to see how the contents changed in the listbox. The ability to update parts of a page without a page reload is a common practice of applications making use of Ajax. Without the aria-controls attribute, a user would be unable to effectively use these types of Web pages as assistive technologies often will not make the user aware of what is happening outside the context of the element the user is currently operating.

    -

    With the aria-controls attribute the user may use the assistive technology to follow the relationship to the object it is controlling. It is extremely important for an assistive technology to present changes in the document in response to user input. Therefore, an assistive technology immediately presents changes to a live region when the controlling widget is the one which has user keyboard focus. For example, if a tree view controls a help document pane, each time
    - the tree item changes the new tree item and then the new help contents should also be read. In the case of a screen reader, the amount of information read in the target live region is dependent on how the live region is configured.

    -

    The aria-controls attribute takes one or more ids which refer to the document element. If this relationship is not implied by the host language semantics, then the controlling element must be given a controls attribute with the IDs of the other elements where the changes will show up listed in the attribute value.

    -
    -
    -
    -

    Changing the Reading Flow

    -

    (X)HTML suffers from a number of disadvantages in keyboard navigation today. One such example is the restriction of navigation to the tabbing order. This is a common problem with presentations in office suites where the logical, perceivable, navigation order of a slide may not match the tabbing order. Sighted users may see a logical navigation process (such as visual steps in the process for assembling a lawn mower). This "flow" is not conveyed by the tab order. The user might tab from step 1 and land on step 4. Another problem is the construction of model-based authoring tools on a Web page. In a model-based authoring tool, a visual object may provide a number of paths that the user can take, such as a multiplexor, which may have output that logically flows to a number of optional electronic components in a drawing. In Web 2.0, developers are actually creating drawings like this to perform tasks such as visually model a work flow. In this scenario, the user will want to decide which object they will navigate their screen reader or alternate input device to next.

    -

    Although it is recommended that Tab order follow the reading flow, there may be instances where this is not possible. For these reasons, WAI-ARIA provides a relationship property, called aria-flowto. This allows the author to provide an assistive technology with alternative navigation flows through the document that best represents the author's intent and which is more logical for people with disabilities. aria-flowto establishes the recommended reading order of content, so that the an assistive may overriding the default of reading in document order to its user. aria-flowto does not change the keyboard navigation order of the browser.

    -

    Consider the first case of changing a basic reading flow to circumvent (X)HTML tabbing. A good example of this is a logical reading flow in a portal with landmarks. In the future, the user may wish to change the reading flow based on the order of priority with which they navigate a personalized Web application. In the following example, the navigation would follow the order of "Top News Stories", "television listings", "stock quotes", and "messages from friends" by following (X)HTML document reading order. However, the author or end user may determine that the main content is most important, followed by "stock quotes", "messages from friends", and then "TV listings." The end user can change the order if the web page or assistive technology provides an interface for such personalization.

    - 
    <html>
-…
-<div role="main" title="Top News Stories" id="main" aria-flowto="stock"></div>
-<div role="complementary" title="television listings" id="tv"></div>
-<div role="complementary" title="stock quotes" id="stock" aria-flowto="messages"></div>
-<div role="complementary" title="messages from friends" id="messages" aria-flowto="tv"></div>
    -

    The second use case is such that the Web developer may wish to circumvent the flow by branching to multiple paths in the Web page, requiring the assistive technology to present a collection of options where the user could go next. This is important for work flows or business process management applications. More of these applications are becoming Web based, and a vehicle is required to tell the user how to get through the work flow. The flowto property takes multiple idrefs, allowing the author to define each object the user could flow to. To implement this technique do the following.

    -
      -
    • -

      Make each object in the work flow accessible

      -

      This will require assigning a title or WAI-ARIA label for each object and a unique HTML id. Also, if the html element is repurposed assign it a WAI-ARIA role.

      - 
      <html>
-
-…
-<img src="foo.jpg" id="331" title="What is the Invoice Value?">
-<img src="foo.jpg" id="333" title="Finance Manager Approval">
-<img src="foo.jpg" id="334" title="Sales Manager Approval">
-…
      -
      • -
    • Assign the flowto properties -

      For each visual object that will flow to one or more other objects assign the flowto property the list of IDs to which it flows.

      - 
      <html>
-…
-<img src="foo.jpg" id="331" title="What is the Invoice Value?" aria-flowto="333 334">
-<img src="foo.jpg" id="333" title="Finance Manager Approval">
-<img src="foo.jpg" id="334" title="Sales Manager Approval">
-…
      -

      Each element referenced by the flowto must have have a unique id. The combination of the unique id and the name allow the assistive technology to adequately assist the user in retracing their steps backward through a flow to reference or moving forward to it. Since the author sets only the target the user agent is responsible for mapping the backward reference relationship. Therefore, neither the user agent nor the user can get lost. The host user agent does not provide an alternative navigation order; this is an assistive technology function.

      -
      • -
    • Make sure visual objects are keyboard accessible -

      Use tabindex to enable objects to receive focus. Actually setting focus to them may be performed by an assistive technology, such as an alternative input device. This example places each drawing object in document order with respect to the tab sequence.

      - 
      <img src="foo.jpg" id="331" title="What is the Invoice Value?"
-    aria-flowto="333 334" tabindex="0">
-<img src="foo.jpg" id="333"  title="Finance Manager Approval" tabindex="0">
-<img src="foo.jpg" id="334" title="Sales Manager Approval" tabindex="0">
-…
      -

      When an assistive technology encounters "What is the Invoice Value?," it will know to tell the user that they may choose to navigate either to the "Financial Manager Approval" or to the "Sales Manager Approval" object. The options may be provided through a menu for the What is the Invoice Value object by the assistive technology. After a choice is made, then the AT can move focus to the target object; or in the case of a screen reader, it may just move the user to that location in the screen reader's virtual buffer.

      -

      Note: WAI-ARIA does not specify backward flowto properties for the same reason that we do not have the reverse of relationships like labelledby. The author may incorrectly do the reversal, creating a whole set of new problems. Rather, the task of the reversal relationships may be handled by the user agent through its accessibility API mapping or in the assistive technology itself.

      -
      • -
    -
    -
    -

    Popups and drop-downs

    -

    In order for menus, menubars, and menuitems to indicate that it opens a menu, set its aria-haspopup property to "true." The type of menu being launched (submenu, context help, etc.) is not explicitly indicated with WAI-ARIA but is based on the operational characteristics (keyboard and mouse commands).

    -

    Combo boxes, or drop down lists, work differently. Controls with the role combobox must contain a list of items that can be opened, usually as a drop-down. Because this is intrinsic to the functionality of a combo box, it does not need to be explicitly indicated with aria-haspopup.

    - -

    The following html fragment shows the use of aria-haspopup with a menubar, its menus, and submenus. All of the menuitems associated with the menubar have aria-haspopup set to 'true'. Also, the "Zoom" menuitem of the "View" menu has an aria-haspopup property as it leads to a submenu.

    - - 
    <div role="menubar">
-  <!--
-    File menu: File menuitem has an aria-haspopup attribute set to 'true'.
-    That popup div follows immediately below.
-  -->
-  <div role="menuitem" aria-haspopup="true" id="fileMenu">File</div>
-  <div role="menu" aria-labelledby="fileMenu">
-    <div role="menuitem">Open</div>
-    <div role="menuitem">Save</div>
-    <div role="menuitem">Save as …</div>
-    …
-  </div>
-  <!--
-    View menu:
-  -->
-  <div role="menuitem" aria-haspopup="true" id="viewMenu">View</div>
-  <div role="menu" aria-labelledby="viewMenu">
-    <div role="menuitem">Normal</div>
-    <div role="menuitem">Outline</div>
-    <!--
-      The View's Zoom menuitem has aria-haspopup='true' as it leads to a
-      submenu.
-    -->
-    <div role="menuitem" aria-haspopup="true" id="zoomSubMenu">Zoom</div>
-    <div role="menu" aria-labelledby="zoomSubMenu">
-      <div role="menuitem">50%</div>
-      <div role="menuitem">75%</div>
-      <div role="menuitem">100%</div>
-      <div role="menuitem">150%</div>
-      <div role="menuitem">200%</div>
-    </div>
-  </div>
-</div>
    -
    -
    -
    -

    Managing Dynamic Changes

    -

    This section has had only minor edits since it was integrated from APG version 1.0 -- a complete APG task force review is pending.

    -
    -

    Managing Content and Presentational Changes

    -

    General rules for managing content and displaying information

    -
      -
    • Do not change an element's role once it has been set. If you need to change the role of an object, first remove the element from the DOM tree and then add the new element to the tree with the new role set.
      • -
    • For supporting browsers, tie CSS attribute selectors to WAI-ARIA properties to reduce script (browser issue with refresh).
      • -
    • Tie CSS display property to WAI-ARIA hidden state. This is important for assistive technologies who communicate directly with the user agent's DOM versus a platform accessibility API supported by the user agent. You can also tie CSS visibility:hidden or visibility:collapse to the WAI-ARIA hidden state but the use of visibility:hidden will affect layout in that content will continue to flow around the hidden area even though the content to be hidden is invisible.
      • -
    -

    If you are refreshing areas asynchronously, then you need to designate live regions. The following sections explain how to implement live regions and when to use roles that are considered "live" sections by default, including alert, status, or log.

    -
    -
    -

    Implementing Live Regions

    -

    Live regions are parts of a Web page that the author expects to change. Examples of live regions include dynamically updated content (sports stats, stock information), logs where new information is being added (chat transcript logs), notification areas (status, alerts), etc.

    -

    Live regions enable assistive technologies, such as screen readers, to be informed of updates without losing the users' place in the content. Live region settings provide hints to assistive technologies about how to process updates. Note that the assistive technology is responsible for handling these updates and enabling users to override these hints.

    -

    The section on Live Region Properties and how to use them gives the details of how to apply live region properties. This process will help rich internet application (RIA) developers to set live region settings that will provide a good user experience for most assistive technology users with little configuration on their part. When applying these live region properties, it is recommended that you conduct user testing. If the AT supports scripting of the response to live regions you may wish to customize the response, such as through a screen reader script for your Web page.

    -
      -
    1. -

      Identify the live regions

      -

      Live regions are any region on a page that receives dynamic updates through client-side scripting. Note the regions of your page that will be live.

      -
      2. -
    2. -

      See if any of the special case live regions meet your needs

      -

      WAI-ARIA provides a number of special case live region roles whose live region properties are pre-defined and which you may use. If one of these live region roles meet your needs just apply the specific role to the region of the Web page.

      -
      3. -
    3. -

      Decide the priority of each live region

      -

      When a live region changes, should the user be notified of the change? Notifications could include a sound for a screen reader user. (For simplicity, we will use the case of an audio notification in this discussion.) The shorter the interval between changes and the less important the information, the less likely that the user needs to hear every change. A simple example of changes that should not be heard are changes to time; a sound for every second would be very annoying.

      -

      If the user should hear the change, should the change be announced immediately, as soon as possible, or only when the user is idle? Announcing a change immediately can be disorienting for users, so that should be done sparingly. Most updates should probably only be announced when the user is idle.

      -

      After you have decided the priority for each live region, then decide the live property value:

      - -
      4. -
    4. -

      Decide how much context is needed for each update

      -

      When part of a live region changes, how much context is needed to understand the change. Does the user need to hear the entire live region or just the change by itself?

      -

      If the user needs to hear the entire live region, then mark the entire live region with aria-atomic="true".

      -
      5. -
    5. -

      Decide what types of changes are relevant for each live region

      -

      Three possible types of changes are: additions, removals, and text. Additions means new nodes are added to the DOM; removals means nodes are removed from the DOM; and text means changes are solely to the textual content. Should the user hear all types of changes or only certain types?

      -

      By default, the user will hear additions and text type changes. If you wish to explicitly define the types of changes, you need to set relevant="THE_TYPES_OF_CHANGES". If more than one type of change is relevant, the types are separated by a space. For example, to define additions and removals as relevant but not text, set relevant="additions removals".

      -
      6. -
    -
    -

    Live Region Properties and How to Use Them

    -

    One of the most important concepts behind live regions is politeness. Politeness indicates how much priority a live region has. The following politeness values are available for aria-live: off, polite, and assertive.

    -
    -
    aria-live="off"
    -
    This is the default. Any updates made to this region must not be announced to the user. live="off" would be a sensible setting for things that update very frequently such as GPS coordinates of a moving vehicle.
    -
    aria-live="polite"
    -
    Any updates made to this region should only be announced if the user is not currently doing anything. live="polite" should be used in most situations involving live regions that present new information to users, such as updating news headlines.
    -
    aria-live="assertive"
    -
    Any updates made to this region are important enough to be announced to the user as soon as possible, but it is not necessary to immediately interrupt the user. live="assertive" must be used if there is information that a user must know about right away, for example, warning messages in a form that does validation on the fly.
    -
    -

    There are times to suppress AT presentation changes while a region is updating. For that you can use the aria-busy property.

    -
    -
    aria-busy="true"
    -
    -

    To suppress presentation of changes until a region is finished updating or until a number of rapid-fire changes are finished, set aria-busy="true" and then clear the attribute when the region is finished. While it is busy, the AT will track and collate the changes. It will finally speak the changes once the region is no longer busy.

    -
    -
    -

    When a live region is updated, the update can often be announced on its own and still make sense. For example, if a news headline is added, it would make sense to simply announce the headline. However, sometimes the entire live region must be read in order to give the user enough context to make sense of the update. For example, it would not make sense to only give the current value of a stock without saying the name of the stock. The atomic setting gives assistive technologies a hint about which of these cases an update falls into.

    -
    -
    aria-atomic="false"
    -
    This is the default. It means that when there is a change in the region, that change can be presented on its own; the AT should not present the entire region. atomic="false" is generally a good idea as it presents users with only changes and does not cause them to hear repetitive information that has not changed. However, Web developers should take care that the changed information, when presented by itself, can still be understood and contextualized by the user.
    -
    aria-atomic="true"
    -
    If atomic is set to "true", it means that the region must be presented as a whole; when there is a change, the AT should present the entire region, not just the change. atomic="true" can make it harder for users to understand changes as the changed areas are not presented independently. atomic="true" can also be annoying as it can force users to listen to repetitive information that has not changed. However, atomic="true" is necessary in cases where the change, when presented by itself, cannot be understood and contextualized by the user. Note that when aria-atomic="true", the AT will attempt to speak the atomic region only once when multiple changes occur in the same region and it hasn't been spoken yet.
    -
    - Not all updates to a live region are relevant. For example, if the oldest headline in a list of headlines is removed and a new headline is added, the removal of the oldest headline is probably not important enough to announce to the user. However, in a chat application, when a user leaves the chat and their username is removed from the list of users, that removal may be important enough to announce. The relevant setting gives a hint about what types of changes are relevant and should be announced. Any change which is not relevant will be treated as if the region had live="off" and will not be announced. Multiple types of changes can be listed as relevant; the types are separated by a space. The default is relevant="additions text" and this is the most common use case. If the default is applicable to your application, you do not need to provide the relevant property explicitly. -
    -
    aria-relevant="additions"
    -
    Insertion of nodes to the live region should be considered relevant.
    -
    aria-relevant="removals"
    -
    Removal of nodes to the live region should be considered relevant. - Often, removals are not relevant because nodes are removed to make space for new information - e.g. a log implemented as a table where items are taken off the top. However, in the case of something like a buddy list, it is relevant if a buddy is removed. It doesn't require the screen reader to speak the removal, but it notifies the screen reader that it could be useful to do so. Use of aria-relevant="removals" or aria-relevant="all" should be used sparingly. Notification of an assistive technology when content is removed may cause an unwarranted number of changes to be notified to the user.
    -
    aria-relevant="text"
    -
    Changes to the textual content of nodes that already exist in the live region should be considered relevant. Textual content includes text equivalents, such as the alt attribute of images.
    -
    -

    This example shows two live regions. If both regions update simultaneously, liveRegionA should be spoken first because its message has a higher priority than liveRegionB.

    -
    - 
    <div id="liveRegionA" aria-live="assertive">
-</div>
-<div id="liveRegionB" aria-live="polite>
-</div>
    -
    -
    -
    -
    -

    Choosing Between Special Case Live Regions

    -

    You may wish to use a special live region role instead of applying live region properties. WAI-ARIA contains a number of standard roles which are by default considered "live" sections of your Web page. It is important to know when to use these and when to create a custom live region on your known. Here are some rules of thumb:

    -
    -

    alert - You may use the alert role for a one-time notification which shows for a period of time and then goes away. It is intended to alert the user that something has happened. The assistive technology should be notified by the user agent that an alert has occurred, if your operating system supports this type of event notification. When choosing to use alert you should use the alertdialog role instead if something inside the alert is to receive focus. Both alert and alertdialog usually appear to pop-up to the user to get their attention. Unless specified otherwise an alert region has an implicit aria-live of "assertive" and aria-atomic of "true".

    -

    status - You may use the status role when you want to mark an area which is updated periodically and provides a general status of your Web application. Many applications provide status widgets and they are often found, visibly, at the bottom of the application and contain a variety of widgets within it to convey status. Unless specified otherwise a status region has an implicit aria-live of "polite" and aria-atomic of "true".

    -

    timer - You may use a timer role when you want to mark an area which indicates an amount of elapsed time from a start point, or the time remaining until an end point. The text encapsulated within the timer indicates the current time measurement, and is updated as that amount changes. However, the timer value is not necessarily machine parsable. The text contents MUST be updated at fixed intervals, except when the timer is paused or reaches an end-point. The timer role has an impicit aria-live of "off".

    -

    marquee- You may use a marquee role when you need to mark an area with scrolling text such as a stock ticker. The latest text of the scrolled area must be available in the DOM. A marquee behaves like a live region, with an implicit aria-live property value of "off."

    -

    log - You may use log if you have a live area where new information is added, like a scrolling chat log of text. Unlike other regions, implied semantics indicate the arrival of new items and the reading order. The log contains a meaningful sequence and new information is added only to the end of the log, not at arbitrary points. Log has an implicit aria-live of "polite"If you have a chat text entry area you should indicate that it also controls the aria log aria like so:

    - 
    <div contenteditable="true" role="log" id="chatlog">
-</div>
-
-
-<label id="gettext">Send Text</label>
-<div aria-controls="chatlog"
-     role="textbox"
-     contenteditable="true"
-     aria-labelledby="gettext">
-</div
    -

    live region - If you have some other live area use case, WAI-ARIA allows you to mark an area using the aria-live attribute. This, accompanied by the collection of attributes which support the live property, allows you to create your own custom live area on your Web page. For more details regarding live regions refer to the live region section of this guide.

    -
    -

    Live region roles that are applied to elements having strong native semantics are not mapped consistently to the platform accessibility API. An example is the TABLE element. It is recommended that authors apply live regions to DIV and SPAN containers. For example:

    - 
    <!-- Live region 'log' role used with TABLE element:  the 'log' role is not consistently mapped to platform AAPI. -->
-<!-- Do not use. -->
-<table role="log" … >
-  …
-</table>
-
-<!-- Wrap the TABLE element in a DIV with role 'log' instead: -->
-<div role="log" … >
-  <table … >
-    …
-  </table>
-</div>
-
    - -
    -
    -
    -

    Presentation Role

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    This section describes the presentation role, including the conditions under which it is inherited by an element's children.

    -
    -

    Rationale

    -

    Authors devote a good deal of effort to the appearance of their web pages, and this is especially true in the case of scripted web applications. To this end authors employ various elements purely for visual presentation. For example, <img> elements are used for spacing and decoration; and <table>s are used to create a column based layout. Elements used strictly for presentation are semantically neutral and irrelevant in terms of accessibility. It is necessary to mark such elements as presentational so that they do not appear in the accessible tree created by the user agent. For example, a current technique used with spacer images is to provide blank alt text to indicate that the image is not meaningful. User agents will not publish any information about images with blank alt text to the platform accessibility API.

    -

    There are elements other than <img> and <table> that are used solely for visual presentation. Any element is a potential candidate for presentation, and, if so used, these elements also need to be marked as semantically neutral.

    -

    It is important to separate content and presentation. CSS 3 has introduced new table layout functionality to allow a user agent to layout content using CSS. There are many advantages to using this feature of CSS such as browser style sheet caching and improved adaptability to mobile devices with limited screen real estate. There are, however, cases where presentational markup cannot be avoided. In such instances, authors are counseled to consult WCAG 2.0 for more detailed guidance.

    -

    WAI-ARIA introduces the presentation role as a general device for marking elements as presentational. The presentation role overrides the element's native implicit role, and informs the user agent to not publish the element to the accessibility API. In fact, the preferred way to mark <img> elements as decorative is to use a role="presentation" attribute instead of (or in addition to) an empty alt attribute. Here is a code fragment sample:

    - -
    <!-- [role="presentation"] informs the user agent that the spacer images are for layout only. -->
-…
-<h2>Other Histories of Architecture</h1>
-<p>
-  <a href="www.somewhere.com">Ancient Roman Architecture</a>
-  <img src="spacer.png" role="presentation">
-  <a href="somewhere.else.com">19th Century Italian Architecture</a>
-  <img src="spacer.png" role="presentation">
-  <a href="www.elsewhere.com">Modern Buildings more than 100 Years Old</a>
-</p>
-
-<h2>Modern Building Design</h1>
-…
-
    -

    The resulting accessible tree is shown below. Note that none of the spacer <img> elements are present:

    -
      -
    • root -
        -
      • …
        • -
      • h2 -
          -
        • [text] Other Histories of Architecture
          • -
        -
        • -
      • p -
          -
        • a -
            -
          • [text] Ancient Roman Architecture
            • -
          -
          • -
        • a -
            -
          • [text] 19th Century Italian Architecture
            • -
          -
          • -
        • a -
            -
          • [text] Modern Buildings more than 100 Years Old
            • -
          -
          • -
        -
        • -
      • h2 -
          -
        • [text] Modern Building Design
          • -
        -
        • -
      • …
        • -
      -
      • -
    -
    -
    -

    Inheritance of Presentation by Parent Element's Children

    -

    In general, the presentation role is not inherited by an element's children. The exceptions are elements whose role entails that the element has required owned children. Examples include the <table> element and list role, and these exceptions are discussed further below. For all other elements, only the element marked presentational is eliminated from the accessible tree. Note, however, that its contents are published; in particular, the element's textual content is published, but any attributes of the element that may form a text-equivalent are not. For example, a header element with a presentation role would not appear in the accessible tree, but its text does. An image with a role of presentation is not exposed in the accessible tree, nor is the contents of its alt attribute. This is shown in the following code fragment:

    - -
    <!-- 1. [role="presentation"] negates the implicit 'heading' role semantics but does not affect the contents. -->
 
-<h1 role="presentation">Presentation role overrides Header role</h1>
-<h1>Another header</h1>
-
-<!-- 2. [role="presentation"] hides the image from the accessibility API and does not publish the alt attribute contents. -->
-
-<img role="presentation" alt="This text will not appear in the Accessibility API" src="…">
-
-
    -

    The first header element is absent from the accessible tree for the above example, but its text appears. The second header element is present as a heading. The img element is not exposed at all:

    -
      -
    • root -
        -
      • …
        • -
      • [text] Presentation role overrides Header role
        • -
      • h1 -
          -
        • [text] Another header
          • -
        -
        • -
      • …
        • -
      -
      • -
    -

    Be aware that the markup <img role="presentation" alt="non-empty alt text"…> is in fact contradictory: Declaring a role of presentation says that the image is for layout, is decorative and meaningless, whereas the non-empty alt text implies that the image is meaningful. It is recommended that authors instead use empty alt text (alt="") where they use role="presentation".

    -

    Earlier it was noted that the presentation role is not generally inherited by an element's children. The exception are roles that have required owned elements. Examples include the <table> element, and the list and tree roles. A list is required to have listitem children; a tree, treeitem children. The <table> element's child components are <tbody>, <thead>, <tfoot>, <th>, <tr>, <td>, and <caption>. These component elements would not appear in the markup without the enclosing <table> root element. Thus, when a table is used for layout, it follows that all of its component elements are present in the markup for layout as well. Since annotating all the required child elements with role="presentation" is error prone and difficult to maintain, it is sufficient to mark the table root element as presentational. The presentation role propagates to all the table component elements. However, as before, the contents of the table elements do appear in the accessible tree. Here is an example:

    - -
    <!-- Layout table marked with [role="presentation"]. -->
-
-<table role="presentation">
-  <tbody>
-    <tr> <td>Some text</td> <td><p>Paragraph</p></td> </tr>
-    <tr> <td><a href="www.somewhere.com">Link text</a></td> <td><img src="meaningful.jpg" alt="meaningful image"></td> </tr>
-  </tbody>
-</table>
-
    -

    All table specific elements (table, tr, td, etc.) are eliminated from the tree by inheriting the presentation role, but other elements and textual content in the table cells are exposed:

    -
      -
    • root -
        -
      • …
        • -
      • [text] Some text
        • -
      • p -
          -
        • [text] Paragraph
          • -
        -
        • -
      • a -
          -
        • Link text
          • -
        -
        • -
      • img -
          -
        • [name] meaningful image
          • -
        -
        • -
      • …
        • -
      -
      • -
    -

    The same logic applies to other roles that have required owned children, such as a list. If the list's root element is declared presentational using role="presentation", all of its listitem elements inherit the presentation role, and none of the list item elements appear in the accessible tree. However, the contents of each list item, that is, other elements and textual content, are included in the tree.

    -
    -
    -

    Overriding Presentation

    -

    The presentation role is overridden in some circumstances. Recall that the presentation role informs user agents that certain elements are semantically neutral, and are irrelevant for accessibility. If, however, there is an aspect of an element that makes it meaningful, it is no longer neutral, and cannot simultaneously be presentational. The Core Accessibility API Mappings describes the cases where this occurs:

    -
      -
    • element is focusable.
      • -
    • element has a global WAI-ARIA attribute, other than aria-hidden.
      • -
    • element is referenced by another element's aria-controls, aria-describedby, aria-flowto, aria-labelledby, or aria-owns property.
      • -
    • element normally inherits presentation from a parent, but the element explicitly declares a role other than presentation. -
        -
      • E.g., a table cell, <td>, within a <table role="presentation">, where that cell is marked with a button role: <td role="button" …> -- the cell has a role of button, not presentation. -
        • -
      -
      • -
    -

    These situations entail that the given element is semantically relevant and will appear in the accessible tree. Marking the element with a role="presentation" is an error, and user agents will ignore the presentation role in these cases. Authors are advised to not mark an element with a role of presentation when it has any of the above properties; rather, to use a role that reflects the element's purpose.

    -
    -
    -
    -

    Form Properties

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    -This section identifies authoring practices for elements used as form elements. -

    -
    -

    Use aria-invalid and aria-required To Improve Access to Forms

    -

    -Until the introduction of WAI-ARIA's aria-invalid state and aria-required property, only presentational strategies have been available to Web content authors to indicate that certain form fields and controls are required or invalid. In applications, these states are only available through styling or varying markup, which is inconsistent, and therefore is inconclusive. In Web-based forms, fields required may be marked by an asterisk. Forms submitted with required data missing or improperly specified may be redisplayed with the unacceptable elements highlighted in red. The assistive technology user is poorly served by such imprecise methods, and all users confront inconsistent indicators for consistent situations. -

    -

    -The WAI-ARIA invalid state and required property provide: -

    -
      -
    • -A programmatic aria-required property that can be applied to a form element to indicate to an AT that it is required to complete the form. -
      • -
    • -A programmatic aria-invalid state that can be used to indicate which data fields have incorrect data to an AT so that the user knows they have entered invalid data. Invalid data is often rendered in red by HTML form developers. -
      • -
    -

    Alert the User When Maximum Length Value Is Reached

    -

    When a text input field that has a maximum length value (or the host markup language's equivalent) receives focus, the value defined for -"maximum length" should be communicated to the user. When text entry reaches that maximum length (or the markup language's equivalent), an alert (expressed in accordance with user preferences and capabilities) should inform the user that the maximum length for a given field has been reached. Such an alert can be expressed programmatically or, using as an aural icon, by using a WAI-ARIA alert; the user agent may alert the user through a system beep and by triggering the operating systems' "show sounds" facility. When maximum length (or the markup language's equivalent) is reached, the user must then be able to move to another form field in a manner consistent with tab-navigation for that document.

    -
    -
    -

    Automatic Focus Changes

    -

    Having a user agent automatically change focus in a form in response to user input can be advantageous in situations where that change saves the user keystrokes or on-screen keyboard interaction in order to manually move the focus from one field to another. However, as with form auto-completion, this type of text input event must be firmly under user control because this may not have been the user's intention and some users with disabilities may become disoriented such as those with sight impairments. Consider these cases:

    -
      -
    • For a text input field that automatically moves focus to a new -field when the value defined for "maximum length" (or the markup language's -equivalent) is reached, the user must have the ability to suppress the change in focus. Otherwise, the user's assistive -technology may not be able to make the user aware of the error.
      • -
    • -A textarea field that has a scripted counter to display the number -of characters entered or the number of characters available for input; -in this case, the dynamic content (the character count) must be owned -by the textarea as a live region, so that the user can keep either a -running (real-time) account of how many characters are left for him -to input or can obtain such information on user query.
      • -
    -
    -
    -

    Form Auto-submit

    -

    Use caution when using automatic submission of a form without explicit user command or -in response to a user-defined setting that permits such behavior, as -expressed by the Priority 1 UAAG 1.0 Checkpoints - 7.1, - 7.2 and - 11.1. -Unless the user has specifically chosen to set the user agent to allow auto-submission, authors are advised not to set onChange or onFocus events either to trigger submission of a form or to provide an auto-submission event upon -completion of all or all required fields of a form or input -field.

    - -
    - -
    -
    -

    Math

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    Editors' note: This section was added as part of disposition of comment 4, but is very incomplete. The section needs to be reordered, so that instructions on how to use the math role properly appear before considerations of legacy content and negative examples (such as the use of generic HTML to approximate a visual representation of a mathematical expression). It needs more introductory text about how to use math. The examples need better introductions, and the positive examples should preceded the negative examples, which need to be explained more fully.

    -

    There exists significant amounts of legacy content that uses images - and/or textual approximations to represent mathematical expressions. - Examples of this include the use of ASCII art and/or the misuse of - HTML tags -- in particular, SUB and SUP -- to achieve a visual - approximation of a mathematical expression, one which is void of - the structure needed to render mathematical expressions inherently - meaningful.

    -

    Use of generic HTML to approximate a visual rendering - of a mathematical expression:

    -

    <i>a</i><i>x</i><sup>2</sup> + <i>b</i><i>x</i> + <i>c</i> = 0

    -

    Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

    - 
    <div role="math" aria-label="a times x squared plus b times x plus c equals 0">
-  <math xmlns='http://www.w3.org/1998/Math/MathML'>
-    <mrow>
-      <mrow>
-         <mrow>
-            <mi>a</mi>
-            <mo>&#x2062; <!-- invisible times --></mo>
-            <msup>
-              <mi>x</mi>
-              <mn>2</mn>
-            </msup>
-         </mrow>
-         <mo>+</mo>
-         <mrow>
-            <mi>b</mi>
-            <mo>&#x2062; <!-- invisible times --></mo>
-            <mi>x</mi>
-         </mrow>
-         <mo>+</mo>
-         <mi>c</mi>
-      </mrow>
-      <mo>=</mo>
-      <mn>0</mn>
-    </mrow>
-  </math>
-</div>
    -

    Similarly:

    -

    -<i>f</i>(<i>x</i>) - = <i>x</i><sup>2</sup> + <i>x</i> - 2 -

    -

    Accessible example of the same function, using the math role, appropriate label, and MathML rendering:

    -

    Todo: add aria-label here also

    - 
    <div role="math">
-  <math xmlns='http://www.w3.org/1998/Math/MathML'>
-    <mrow>
-      <mrow>
-         <mi>f</mi>
-         <mo>&#x2061;</mo>
-         <mrow>
-            <mo>(</mo>
-            <mrow>
-               <mi>x</mi>
-            </mrow>
-            <mo>)</mo>
-         </mrow>
-      </mrow>
-      <mo>=</mo>
-      <mrow>
-         <msup>
-           <mi>x</mi>
-           <mn>2</mn>
-         </msup>
-         <mo>+</mo>
-         <mi>x</mi>
-         <mo>&#x2212;</mo>
-         <mn>2</mn>
-      </mrow>
-    </mrow>
-  </math>
-</div>
    -
    -
    -

    Drag-and-Drop Support

    -

    aria-grabbed and aria-dropeffect have been deprecated in ARIA 1.1 - as such this section has been removed. Advice for implementing drag and drop will be added to a future version of the Authoring Practices Guide.

    - -
    -
    -

    States and Properties, and Assistive Technologies

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    Assistive Technologies (AT) access WAI-ARIA state and properties via a platform accessibility API. An example of such an API is Linux's AT-SPI. The user agent is responsible for publishing WAI-ARIA roles, states, and properties and relevant changes via the accessibility API. For more information, see the Core Accessibility API Mappings [[CORE-AAM]].

    -

    With respect to desktop applications, the interaction between the platform accessibility API and an AT is bidirectional. The application sends information to the AT using the accessibility API, and the AT can request a change in the accessible state of an application through the same accessibility API. However, with respect to ARIA 1.0, the flow of information is one way only from WAI-ARIA to the accessibility API. There is no provision, currently, to go the other way. An AT cannot use an accessibility API to alter any WAI-ARIA information in the DOM.

    -

    The reason is that there is no consistent cross-browser implementation of a mutation event that web applications can rely on to detect when a WAI-ARIA state or property has changed. Web applications use WAI-ARIA information for rendering their components. For example, if the web application includes a DHTML checkbox as part of its interface, then the web app renders the visual appearance of the checkbox based on its aria-checked state. If an outside agent were to change the state of that checkbox without the web app receiving any notification, then the checked state of the checkbox is no longer in agreement with its visual appearance. It is likely that the behavior of the web app will suffer.

    -

    W3C is investigating device-independent interfaces to allow web applications to receive notification of changes to WAI-ARIA states and properties. When this is available, WAI-ARIA will be bidirectional with respect to the platform accessibility API, allowing Assistive Technologies to alter WAI-ARIA states and properties. Even so, the set of states and properties that an Assistive Technology is likely to change is limited to the following:

    -
      -
    • aria-activedescendant
      • -
    • aria-expanded
      • -
    • aria-grabbed
      • -
    • aria-selected
      • -
    • aria-sort
      • -
    • aria-valuenow
      • -
    -

    The following States and Properties are unlikely to be manipulated by an assistive technology: An AT would need to have greater understanding of the application and the results could be adverse.

    -
      -
    • aria-atomic
      • -
    • aria-autocomplete
      • -
    • aria-busy
      • -
    • aria-checked
      • -
    • aria-controls
      • -
    • aria-describedby
      • -
    • aria-disabled
      • -
    • aria-dropeffect
      • -
    • aria-flowto
      • -
    • aria-haspopup
      • -
    • aria-hidden
      • -
    • aria-invalid
      • -
    • aria-labelledby
      • -
    • aria-level
      • -
    • aria-live
      • -
    • aria-multiline
      • -
    • aria-multiselectable
      • -
    • aria-owns
      • -
    • aria-posinset
      • -
    • aria-pressed
      • -
    • aria-readonly
      • -
    • aria-relevant
      • -
    • aria-setsize
      • -
    • aria-valuemax
      • -
    • aria-valuemin
      • -
    • aria-valuetext
      • -
    -
    -
    -

    Reusable Component Libraries

    -

    This section has not been updated since it was integrated from APG version 1.0 -- an APG task force review is pending.

    -

    Rich internet applications are complex to author. To save time, it is often faster to use existing widget libraries that implement WAI-ARIA and that have already gone through:

    -
      -
    • extensive assistive technology testing
      • -
    • cross browser testing
      • -
    • testing to ensure that the widgets respond to desktop settings
      • -
    • testing to ensure that the widgets match a common keyboard style guide
      • -
    -

    Some publicly available UI component libraries have already implemented WAI-ARIA. Authors can reuse such libraries to start developing accessible rich internet applications.

    -
    -
    -

    Appendices

    -
    -

    Understanding Screen Reader Document Reading and Application Reading Modes

    -

    Placeholder for a section covering this topic that is yet to be written.

    -
    -
    -

    Background on WAI-ARIA

    -

    This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

    -

    According to the SecuritySpace Technology Penetration Report, more than 55% of all Web sites today contain JavaScript, dramatically affecting the ability for persons with disabilities to access Web content. New Rich Internet Applications (RIAs) render custom widgets, modeling rich desktop components to perform UI updates without having to reload the entire page - much like a graphical user interface (GUI). Legacy GUI accessibility frameworks address these issues through a comprehensive accessibility application programming interface (API) and infrastructure to foster interoperability with assistive technologies. These APIs constitute a contract between applications and assistive technologies, such as screen readers, to enable them to access rich dynamic content with the appropriate semantics needed to produce a usable alternative. No such contract exists between modern RIAs and assistive technologies, creating an accessibility gap for persons with disabilities.

    -

    Unfortunately, HTML and other markup languages do not provide adequate - support for accessible dynamic content. Until now, the W3C WAI has discouraged the use of JavaScript per [[WAI-WEBCONTENT]], Checkpoint 6.1). - A - number of W3C initiatives underway address this problem using - a declarative markup approach. This primer describes a means to - bridge the interoperability problem with assistive - technologies now by incorporating the appropriate metadata into - current HTML and XHTML markup to support today's accessibility APIs. Moreover, the primer provides web developers with a conceptual understanding of WAI-ARIA as a prelude to using the [[WAI-ARIA]]. WAI-ARIA brings advanced accessibility features of the desktop to the web through the creation of cross-cutting technologies that - (X)HTML authors can incorporate in their markup. WAI-ARIA defines roles, states, and properties, where those roles reflect standard GUI elements that are recognized by accessibility Application Programming Interfaces (APIs). These metadata that describes these - GUI widgets and document structures aides assistive technology - vendors in providing accessible, usable solutions. The W3C WAI PF working group is working with User Agent manufacturers, assistive - technology vendors, and accessibility tool providers, to ensure an end-to-end working solution.

    -

    For an introduction to WAI-ARIA, see the Accessible Rich Internet Applications Suite (WAI-ARIA) Overview. The WAI-ARIA Primer is part of a set of resources that support the WAI-ARIA specification. The Primer provides a basic introduction to the concepts behind and reason for WAI-ARIA, and the WAI-ARIA Authoring Practices describe recommended usage patterns for Web content developers. The WAI-ARIA Suite fills gaps identified by the [[WAI-ARIA-ROADMAP]]. These documents serve as important places of clarification where topics appear to be unclear.

    -
    -

    The Problem

    -

    Aspects of traditional Hypertext Markup Language (HTML) make accessible support of dynamic content difficult:

    -
      -
    1. Accessibility of dynamic content relies on abstracting semantics from both content and presentational information. Extracting semantic cues from current HTML content is typically unreliable as the cues are limited to tag elements names.
      2. -
    2. While HTML allows content to be repurposed for presentational formatting, it lacks the ability to attach meaningful metadata about document structure and to convey semantic information. A common example of this is content formatted with tables rather than style sheets.
      3. -
    3. When combined with script and cascading style sheets (CSS), HTML can be repurposed to create dynamic custom components without providing a means to convey semantic information to native accessibility architectures designed to support dynamic graphical user interface (GUI) content.
      4. -
    4. Custom components built from common HTML elements often are not keyboard accessible.
      5. -
    -

    Authors of JavaScript-generated content do not want to limit themselves to using standard tag elements that define the actual user interface element such as tables, ordered lists, etc. Rather, they make extensive use of elements such as DIV tags in which they dynamically apply a user interface (UI) through the use of style sheets and dynamic content changes. HTML DIV tags provide no semantic information. For example, authors may define a DIV as the start of a pop-up menu or even an ordered list. However, no HTML mechanism exists to:

    -
      -
    • Identify the role of the DIV as a pop-up menu
      • -
    • Alert assistive technology when these elements have focus
      • -
    • Convey accessibility property information, such as whether the pop-up menu is collapsed or expanded
      • -
    • Define what actions can be formed on the element other than through a device-dependent means through the event handler type (onmouseover, onclick, etc.)
      • -
    -

    In short, JavaScript needs an accessibility architecture to write to such that a solution can be mapped to the accessibility - frameworks on the native platform by the user agent.

    -

    The following diagram illustrates a typical document object model (DOM) node in - a Model-View-Controller architecture. Accessibility information surfaced to assistive technologies is provided only by the HTML element's tag name, with only the accessibility attributes that tag can provide.

    -

    shows that on the node, data, or the - "Model", which should include semantic information, is separated - from the user interface presentation, the "View." Here, the - document element is managed by the user agent based on the default - behavior of the element. The user agent's default behavior at the - document element forms the controller.

    -
    - Accessibility information mapped to a DOM element in the Document Object Model -
    Accessibility Interoperability at a DOM Node without JavaScript
    -
    -

    The box between the DOM node - and the assistive technology contains the contract - provided by the user agent to the assistive technology. This data - includes typical accessibility information found in the - accessibility API for many accessible platforms for GUIs - (role, state, caret, selection, text, hypertext, name - description, parent/child information, parent/child - information, and relations). For HTML and other W3C markup, the - accessibility information provided solely depends upon what the element's tag name and any accessibility attributes that map to that tag provides. For example, the accessible role of a table is table. The author provides an accessible description by assigning a title attribute.

    -

    In contrast, with JavaScript, user actions can trigger updates in the data and presentation, but the default accessibility information available in the element tags is no longer valid.

    -
    DOM Element with JavaScript controller -
    Accessibility - Interoperability at a DOM Node with JavaScript
    -

    shows the same DOM node provided - in Figure 1.0 but with JavaScript acting as the new controller. - JavaScript overrides the default user agent behavior at the DOM - node. It manipulates the data, content, and style in response to - events caused by user interaction to produce custom widgets. In - this situation, the default accessibility information is no longer - valid and, therefore, the contract is now invalid. Figure 2.0 shows - the contract with asterisks in front of role, state, actions, - value, event changes, and relations. These asterisks represent - potential accessibility errors and gaps in the base markup. These - gaps result from the author's inability to provide the new semantic - data needed to support the contract.

    -
    -
    -

    Requirements

    -

    Any solution to facilitate the creation of accessible rich Internet applications (RIAs) must:

    -
    -
    Allow for discovery of custom UI components - through the use of Semantic Web technologies
    -
    Web ontologies allow for storage of semantic information about - objects and how they relate to others in the ontology.
    -
    Support today's accessibility - architectures
    -
    Accessibility architecture today is centered around object - technology. Each object in an application or document exposes - its accessible properties to an assistive - technology.
    -
    Allow for separation of content and - presentation
    -
    Dynamic content authors must be able to store the accessible - meta data in the document independent of how it is rendered.
    -
    Allow for passive monitoring of the application - by an assistive technology
    -
    Assistive technology vendors should not be required to poll an - application for changes in accessibility information.
    -
    Leverage new W3C efforts to solve the - problem
    -
    This problem needs to be solved quickly. A number of - efforts are underway, such that minimal changes may be required to - bring them to the level needed.
    -
    Be light weight
    -
    The solution needs to be light-weight in order to promote adoption by Web authors.
    -
    Scaleable
    -
    The solution needs to be scalable; it must make simple things - easy while making complex things possible.
    -
    Internationalizable
    -
    Like other Web solutions, our solutions must be - internationalizable.
    -
    Guarantee user agent support up front
    -
    User agent manufacturers must be involved up front to ensure support for the solution when the specification is complete.
    -
    Involve assistive technology vendors up - front
    -
    To ensure interoperability, assistive technology vendors need to be involved from day one. - The effort must leverage support by AT vendors to ensure that a - total solution is available when the specification is complete.
    -
    Produce Developer Guidelines during the - process
    -
    This is a critical mistake made by people creating a new - accessibility model. Developers must be engaged early on so that - they can contribute feedback and start producing workable solutions - early.
    -
    -
    -
    -

    Solution

    -

    What is clear from the problem statement is that developers of dynamic web content cannot provide the appropriate accessibility information in the markup to support the accessibility APIs on the target platform. This problem is not limited to HTML. It extends to other markup, including Scaleable Vector Graphics [SVG]. This primer addresses the problem for web content delivered to desktop browsers and introduces you to common extensions to both HTML and XHTML called [[WAI-ARIA]]. The goal is to make these standard features in HTML 5.

    -
    -
    -

    HTML Accessibility API Support Analysis

    -

    Using as a template for addressing the - problem and U.S. Section 508 accessibility standards, Table 1.0 illustrates gaps - in the infrastructure and identifies W3C standards that should be used to - address the problem. In the right column, table cells that are empty - or that indicate a limitation represent accessibility gaps in HTML - and XHTML.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Table 1.0 Platform Gap Analysis - for Accessible Dynamic Web Content for HTML and XHTML -
    Required ComponentsWho does what today? (HTML)
    Events: 
    FocusChangeDOM 2, 3 events
    ActivationUser Agent API
    Caret ChangeUser Agent API
    Value Change 
    State Change 
    Selection ChangeUser Agent API
    MutationDOM Events
    Accessible - Actions: 
    Event Handler functional information to label the actions 
    Access to the available event - handlers for enumerating the actions 
    State Information: 
    Role Information:Limited to standard HTML tag names. (Mix - Content/presentation)
    Relationships: Parent/childLimited DOM (affected by style) (Mix Content/presentation)
    Relationships: (Label, MemberOf - Group, - ControllerFor)Limited to HTML (Title, alt, label)
    TextCore DOM from parsed HTML
    Content selection:Browser-dependent (incomplete)
    Font/Font Style Information:Can set but can't get final format
    Description/Help:Limited to HTML 4.0 - Alt Text, title text
    Accessible value:Limited to form elements
    Coordinates (Bounding rectangle, etc.):User Agents. platform accessibility API
    Accessible Name: 
    Respond Desktop Font/Color - Changes:Partial (conflicts with CSS and JavaScript)
    Device independent navigation: 
    Accessibility API Mapping:Partial - User Agents
    Provide focus to all active elements (important for - equivalent keyboard access on desktops)Limited to forms and anchors
    +
    +

    Background on WAI-ARIA

    +

    [Placeholder section that will be resolved by issue #84. ] +

    +
    + +
    -
    + -
    -

    Filling the Gaps for Content Delivered to Desktop Browsers

    -

    This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

    -

    At this time,W3C WAI Protocols and - Formats working group's primary focus is on extensions to HTML 4.01 and XHTML 1.X by extending the host language to include WAI-ARIA with a migration path to HTML 5. This will require the creation of new hybrid document type definitions (DTDs) that incorporate the extensions. This work will be in the [[WAI-ARIA]] specification. WAI-ARIA will constitute - extensions to fill most of the gaps needed to support - accessibility API infrastructures and dynamic (X)HTML content. The comprehensive gap analysis of (X)HTML, used to form WAI-ARIA is found in Table 1.0 and how WAI-ARIA fills those gaps. In the future we hope to incorporate WAI-ARIA into many host languages to improve their accessibility. The critical extensions needed to make accessible dynamic Web content accessible, through rich interoperability with assistive technologies, - are summarized here:

    -
    -

    States, and Property attributes - This is the set of attribute modifications to (X)HTML necessary to provide full keyboard focus and states and properties that may be mapped directly or indirectly to platform accessibility APIs to ensure full interoperability with assistive technologies for WAI-ARIA.

    -

    Role attribute - The role attribute, borrowed from the, [[ROLE-ATTRIBUTE]], allows the author to annotate host languages with machine-extractable semantic information about the purpose of an element. It is targeted for accessibility, device adaptation, server-side processing, and complex data description. WAI-ARIA uses the role attribute to provides the role information, in to an assistive technology.

    -

    Role document landmark values - These values, borrowed from the [[ROLE-ATTRIBUTE]] provides a standard set of role attribute values designed to define pertinent parts of a document (landmarks) for the purpose of accessibility. User agents may incorporate device equivalents, such as key mappings in the case of a desktop user agent, to navigate to these sections of a document.

    -

    Taxonomy of WAI-ARIA role values - The necessary core roles found in Accessibility API sets - for Windows and Linux as well as roles representative of document structure, such as banner or treegrid. Use of document - structure is necessary for assistive technologies to navigate - complex documents and to know when they have entered active areas - of a Web page such as in the case of a dynamic scripted Web - application. The taxonomy is designed to help user agents or - authoring tools determine what properties a given role supports and to assist with accessibility API mapping of these - properties. The taxonomy will is like a class hierarchy used to - convey semantics and structure and includes knowledge about each - role. At this time, that taxonomy is modeled using [[RDF-CONCEPTS]] and [[OWL-FEATURES]].

    -
    -

    In short, WAI-ARIA will be used to fix the dynamic accessibility of scripted Web content, - in particular the use of JavaScript with (X)HTML markup. They are meant to be - cross-cutting and should apply to other markup like SVG. Less - critical for (X)HTML but helpful for accessibility - will be the descriptive extensions to XML events and the new [[XHTML Access]]. Web Content Accessibility Guidelines 2.0 calls for the WAI-ARIA properties in guideline 4.1 Maximize compatibility with current and future agents, including assistive technologies (roles, states, properties, and values) and section guideline 1.3 Create content that can be presented in different ways (for example spoken aloud, simpler layout, etc.) without losing information or structure (relationships).

    -

    The - next section describes how the specifications are used together as well as how they will be implemented in HTML 4.

    -
    -

    Use of New Provisions for Keyboard Focus and Semantics to Support Platform Accessibility APIs

    -

    Adaptive technologies, which need to provide alternative access to - complex user interfaces authored via HTML, are often left guessing - at the semantics behind specific portions of HTML document. As an - example, an XHTML document might use a certain HTML construct, such - as a collection of DIV tags, to create navigation bars, a - site-navigation menu, and other GUI-like user interface widgets. To - fix the problem, we incorporate the role - attribute, assign the accessible state properties, and give the object - focus using the new TABINDEX feature. Addition of this information - helps authors to provide the necessary information to - enable the user agent to support the accessibility API accessed by - the adaptive technology.

    -
    -

    Provision of the Role Attribute: "What is the Object?"

    -

    Each platform accessibility API has the notion of a "role" for a - GUI object. This is the case for [[JAPI]], [[MSAA]]], [[AXAPI]], and the [[ATK]], or [[UI-AUTOMATION]] (called content type in UI Automation). The WAI-ARIA specifications are based on XHTML 1.X and include the role attribute. The "role" attribute takes a qname, enabling authors to reference the role attribute from the WAI-ARIA Roles. In - the following example, we use qname to reference the menu role in the WAI-ARIA specification.

    -
    -

    Example: Use of WAI-ARIA to incorporate - role information into XHTML 1.x

    - 
    -<?xml version="1.1" encoding="us-ascii"?>
-<!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml"
->
-    <body>
-        <div role="menu">
-            File
-        </div>
-    </body>
-</html>
-
    -
    -

    WAI used RDF/OWL to model our taxonomy for WAI-ARIA. In fact, if a host language sought to use namespaces or qnames, they could do so to reference the WAI-ARIA role taxonomy. The WAI-ARIA role taxonomy could be used by authoring tool developers to ensure that states and properties assigned to a given role are accurate.

    -
    -
    -

    Provision of the Accessibility State Information: "What meaningful properties does this object have at this time?"

    -

    Since this is dynamic content, the state of these new repurposed - objects will change. The WAI-ARIA specification shall provide the common - accessible properties needed to support the accessible state or - property information provided by the platform accessibility API - defined previously. This specification was created based on an - analysis of the accessibility properties defined in MSAA and ATK. - The following example extends the previous approach by adding the aria-haspopup accessibility property.

    -
    -

    Example: Use of WAI-ARIA to incorporate accessible state information information into XHTML 1.x

    - 
    -<?xml version="1.1" encoding="us-ascii"?>
-<!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
-    http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-
-
->
-        <body>
-            <div role="menu" aria-haspopup="true">
-                File
-        </div>
-    </body>
-</html>
-
    -
    -

    A Windows user agent may now map this property to the Microsoft - Active Accessibility state of STATE_SYSTEM_HASPOPUP. Adding or - removing this state would result in the Windows user agent sending - an EVENT_OBJECT_STATECHANGE event to the assistive technology. The - task of the JavaScript page author would be to maintain this state - attribute, which can easily be done through the use of Document - Object Model calls.

    -
    -
    -

    Provision of the Keyboard or Input Focus: "What object am I working on?"

    -

    Virtually all adaptive technology solutions, such as screen - readers and onscreen keyboards, must know which object currently - has focus. For example, an author might want to insert text into the - current object with focus or to announce information - about the object that has focus. With today's HTML 4.01 and XHTML 1.x, script authors can only provide focus to form - and anchor elements yet the Document Object Model Specification - allows all elements to receive events including keyboard events. - This means that HTML, by design prohibits script authors from - making all HTML elements keyboard accessible. This single problem - effects usability of Web pages where one gains access to - elements by using the Tab key on desktop browsers. This slow, - unproductive, approach makes portal navigation difficult because all active elements must be tabbed through to put focus on an - active element in the last portlet in a document. To solve this - problem in XHTML 1.x, we are incorporating a feature in Firefox and - Internet Explorer to define the tabindex for -1. This allows a script author to - give an element focus without placing it in the tab order: The - following table describes these changes that will be incorporated - into the new Accessible Adaptive Application specification.

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Accessible Adaptive Application Changes to Support Use of tabindex to give Element Focus -
    tabindex attributeFocusable with mouse or JavaScript via element.focus()Tab navigable
    not presentFollows default behavior of element (yes for form controls, - links, etc.)Follows default behavior of element
    Negative, e.g. tabindex="-1" YesNo, author must focus it with element.focus() as a - result of arrow or other key press
    Zero, e.g. tabindex="0" YesIn tab order relative to element's position in document
    Positive, e.g. tabindex="33" YesTabindex value directly specifies where this element is - positioned in the tab order. These elements will be positioned in - the tab order before elements that have tabindex="0" or that are - naturally included in the tab order (form elements and links)
    -

    The following example shows the introduction of TABINDEX to - provide focus to a DIV having the new accessibility meta data:

    -
    -

    Example: Use of tabindex to give non-form - and anchor elements focus in XHTML 1.x

    - 
    -<?xml version="1.1" encoding="us-ascii"?>
-   <!DOCTYPE html PUBLIC "Accessible Adaptive Applications//EN"
-    http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-
-
-
->
-    <body>
-        <div role="menu" aria-haspopup="true" tabindex=-1>
-            File
-        </div>
-    </body>
-</html>
-
    -
    -
    -
    -

    Supporting WAI-ARIA in XHTML and HTML 4.01

    -

    Unlike XHTML, HTML 4.01 is non-extensible in that it is not possible to extend HTML 4 through the use of namespaces. That said, members of the working group have worked with the HTML working group to agree on a vehicle that does not use namespaces, which at this time is supported by XHTML and HTML which will be supported in HTML 5 when it becomes recommendation. Firefox 3 is leading the way to implement this, and other browser manufacturers are working to support it as well. The technique allows all role values specified in WAI-ARIA (including those specified by the XHTML Role attribute module) to be specified without a namespace prefix. Additionally, WAI-ARIA states and properties shall be represented as aria- followed by the concatenated WAI-ARIA state or property.

    -
    -

    Example: Browser supported HTML technique for the tabindex example in section 5.1.3

    - 
    -
-<html lang="en">
-  <head>
        <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
      </head>
-    <body>
-        <div role="menu" aria-haspopup="true" tabindex=-1>
-            File
-        </div>
-    </body>
-</html>
-
    -
    -

    In order to validate these extended attributes for HTML and XHTML the WAI-PF working group will investigate the creation of an enhanced schema or DTD for each host language.
    -

    -
    -
    -
    -

    Use of XHTML Role Landmarks to Improve Document Navigation

    -

    In addition to the common roles which will reside in WAI-ARIA Roles, both XHTML 2.0, and the XHTML Role attribute module ([[ROLE-ATTRIBUTE]], Section 4) defines a collection of common role, regional, landmarks that define pertinent parts of a - document for the purpose of accessibility. User agents may - incorporate device equivalents, such as key mappings in the case of - a desktop user agent, to navigate to these sections of a document - independent of the Web site. The addition of these semantics allows - the user agent to provide standardized navigation to common - document sections. This is especially important for portals to - improve the usability. These may be used as attributes in XHTML 1.x - by applying them to sections of the document as shown in this - example. Note: since these roles are a part of XHTML they do not need to be namespace qualified.

    -
    -

    Example: Use of XHTML navigation role to define a landmark for the - navigation section in an XHTML 1.X document

    - 
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
-<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
-<head>
-  <title>application/xhtml+xml: Navigation Roles Example 1</title>
-  <link rel="stylesheet" href="css/nav1_xhtml.css"  type="text/css" ></link>
-  <script type="text/javascript" src="../js/globals.js"></script>
-  <script type="text/javascript" src="../js/widgets_xhtml.js"></script>  <link rel="icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon" />
-  <link rel="shortcut icon" href="http://www.cites.uiuc.edu/favicon.ico" type="image/x-icon" />
-</head>
-<body onload="widgets.init()">
-.
-.
-.
-<div id="leftnav">
-<h2 class="nav" id="leftnav_label">Career Center Services</h2>
- <ul title="Career Center Services" role="navigation" aria-labelledby="leftnav_label">
-   <li><a href="http://www.uiuc.edu/">Career Home</a></li>
-   <li><a href="http://www.uiuc.edu/">Career Counseling</a></li>
-   <li><a href="http://www.uiuc.edu/">Pre-Health Advising</a></li>
-   <li><a href="http://www.uiuc.edu/">Services</a></li>
-   <li><a href="http://www.uiuc.edu/">Workshops</a></li>
-   <li><a href="http://www.uiuc.edu/">Resource Center</a></li>
-   <li><a href="http://www.uiuc.edu/">Question Board/FAQ</a></li>
- </ul>
-
-...
-
-</body>
    -
    -

    The example above was taken from the header from the Career Center Web page at the University of Illinois at - Urbana-Champaign. Students from this university, under Jon - Gunderson's guidance created Accessibility - extensions for Mozilla/Firefox, in part, to allow a page author or - user to view a list of navigation landmarks. - This tool, shown in , lists the navigation sections on the page. Keyboard navigation of the list of navigation bars causes the - corresponding document section to be highlighted. The title for each navigation region displays in the list.

    -
    Table of Contents from Landmarks -
    Table of Contents generated from navigation landmarks in the header
    -
    -

    shows the accessibility - extensions for Mozilla/Firefox from the University of Illinois at - Urbana-Champaign to render the document landmarks. This picture - shows the Firefox browser rendering the University of Illinois - Career Career Center home page. In this example. The "List of Navigation Bars" viewer is shown, launched from the extension on the - toolbar. The viewer shows that the secondary "Career Center Services" is selected resulting - in that section of the document being highlighted in yellow. The - Navigation Bar Lists Viewer lists the following list of titles corresponding to the navigation sections:

    -
      -
    • Career Counseling Resources
      • -
    • Resources by Audience
      • -
    • Career Center Services
      • -
    • Quick Links
      • -
    -
    -
    -

    WAI-ARIA Role Taxonomy - Extensible Semantic Role Model, using RDF/OWL

    -

    The WAI-ARIA role taxonomy was modeled using semantic web technology, in the form of [[RDF-CONCEPTS]] and the [[OWL-FEATURES]], as a vehicle to define a knowledge-based class hierarchy for roles. This model shows what states and properties are supported, by each role in the taxonomy. The role in the class hierarchy inherits properties from its ancestors and defines its own properties. Where applicable, semantic web technology is used to define related concepts within other namespaces. This information is critical in determining how to choose a role and how to interact with it. The role taxonomy uses RDF as a way for using data to describe data and provides a - W3C standards-based approach to represent this information.

    -
    - - Sample Semantic Map for Taxonomy -
    Example, Partial RDF Map for a possible ButtonUndo role as an extended role to WAI-ARIA
    -
    -

    shows a basic RDF mapping that - defines a set of terms and relationships defining an object. At the - center is a Widget object that defines common states and properties - for all GUI widgets. The Button object extends Widget and inherits - defined accessibility properties from the superclass Widget. It - also defines a relatedConcept property to a Link object. - The ButtonUndo role extends Button. It has a relatedConcept of an HTML input object. - ButtonUndo will introduce Dublin Core meta data such as the - description of the object. The terms relatedConcept and - requiredState are terms that will be defined as part of the - corresponding RDF schema. Each role instance will represent - standard Roles found in the platform accessibility APIs of platforms like - Windows and Gnome as well as content structure. These roles will - form the taxonomy. Although host language browser implementations may reference WAI-ARIA roles without namespaces, the RDF representation for a given role may be referenced using a - qname from a Host XML markup language. This examples shows an XHTML reference to a grid role in the RDF representation of the WAI-ARIA taxonomy:

    -

    <div - role="grid"> whereby grid expands to: - http://www.w3.org/2005/01/wai-rdf/GUIRoleTaxonomy#grid in the - button markup.

    -

    The power of this design is that it enables a web authoring tool to go back - into the corresponding RDF/OWL markup and determine what properties it - supports for Accessibility API mapping. Additional, middleware solutions can now make intelligent - transformations of Web Content by processing the semantics behind - rich browser and rich structured frameworks to adapt accessible - solutions for a broader user base. Our immediate goal is to fix the - accessibility problem with scripted Web content. Assistive - technologies will use the standard roles to determine how to render - most content.

    -
    -

    Interoperability Example: Grid Role

    -

    To understand the power of this approach, consider the case of a Grid Role, analogous to a table. shows a DHTML example using - XHTML, JavaScript, and CSS to produce a GUI-like application. This - example developed in IBM shows a notebook - tab with a data grid that behaves like a traditional desktop GUI. - The user uses arrow keys to navigates the data grid and among the page tabs. - Using the Tab key, a user navigates between the notebook tab, the edit fields, buttons, and - the data grid.

    -
    DHTML example of GUI-like notebook tab with a data grid -
    DHTML Example
    -
    -

    Accessible role and state - meta data from the WAI-WAI-ARIA Roles, States, and Properties specification, are added as attributes to - each of the XHTML elements repurposed as GUI widgets dynamically. - The user agent, in this case Firefox, maps this information to the - platform accessibility API. shows - the Microsoft Active Accessibility rendering of the new - accessibility markup provided on the DataGrid page tab which has - focus.

    -
    MSAA Inspect Tool diagnostics for Notebook page tab -
    Microsoft Inspect Tool rendering of the page tab - DataGrid
    -
    -

    show a Microsoft Inspect 32 - rendering of the DataGrid Page page tab in Figure 5.0. Inspect32 - provides Microsoft Active Accessibility information; here it shows the - accessible role of "page tab" and accessible state information of - focused, focusable, and linked. There are no page tab elements in - XHTML. Here, an XHTML DIV element is repurposed by a - JavaScript controller to look like a notebook tab. It is now able - to receive focus, unlike in standard XHTML 1.X, and it does so without - requiring tabbing. With these specifications, the script - author can now add the accessibility properties to support platform - accessibility API. Accessible state properties for the DataGrid - page tab are shown as focused, focusable, and linked. Unlike a GUI - application, authors need only enable their applications once for - multiple operating system platforms.

    -

    Beyond scripted Web content, the working group intends to extend - the use of roles to enable other user cases. These may include:

    -
      -
    • Structured Textual Markup - enhancing - structure of the markup of a document, including Data Tables , or - translating the structure of an XML document to a markup structure - that user agents are used to dealing with (e.g. myXML to XHTML) - Binding sections of a document to a common role. This allows for - different navigation techniques though a document
      • -
    • Knowledge representation of Web content - As a - secondary benefit, roles improve compatibility with Knowledge-Based - Services and the Semantic Web. By integrating accessibility and the - semantic Web, accessibility can be moved forward, paving the way - for customized accessible searches and intelligent user agents with - additional applications.
      • -
    • Adding concepts in the type of content for adaptation - to the user scenario - The more that is understood about - content, the better it can be adapted for the end user. For example: -
        -
      1. If it is known that a page hyperlink has the role of taking the - user to the site's home page, then that knowledge can be used to - create enhanced accessibility in different ways in many different - scenarios, such as icons or access keys.
        2. -
      2. If it is known that a text box is for the user email address, - then the user agent can support users filling in the form by - labeling it with an icon or symbol, automatically validating it, or - even form filling.
        3. -
      3. If it is known that a paragraph is complex, then a simple equivalent - can be shown in its place
        4. -
      4. If a word is ambiguous, then a role of a concept can be given, - providing clarity An example of this may be : <span - role="role:nonliteral" aria:hasAlternate="no">
        5. -
      -
      • -
    - -
    -
    -
    -

    Accessibility Events and Event Handling

    -

    Interoperability between applications and assistive technologies - requires event notification for accessibility. The events will be fired via the user - agent. The accessible value and state property changes will be - generated in response to changes in the DOM attributes as defined - by the WCAG 1.0 AAA specification. User agents supporting the platform - accessibility API, will support event notification such as the state change or value change events.

    -
    -
    -
    -

    Building Accessible Applications with WAI-ARIA

    -

    This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

    -

    This section provides a brief introduction to the process of making applications accessible using WAI-ARIA. The choice and usage of roles can be complex and context dependent. It is beyond the scope of this document to explain implementations for all the possible WAI-ARIA use cases. WAI-ARIA Authoring Practices provides detailed guidance on WAI-ARIA implementation methodology as well as references to sample code.

    -

    First steps to making an application accessible:

    -
      -
    1. Each element or widget has correct and complete semantics that fully describe its behavior (using element names or roles);
      2. -
    2. The relationships between elements and groups are defined;
      3. -
    3. States, properties, and container relationships are valid for each element's behavior and are accessible via the [[dom]] and the platform accessibility API; and
      4. -
    4. Keyboard focus should be maintained for the duration of the user's interaction with the application.
      5. -
    5. All interactive components should be keyboard operable.
      6. -
    -

    WAI-ARIA provides authors with the means to make the different elements in a web application semantically rich. User agents use the role semantics to understand how to handle each element. Roles convey additional information that the assistive technologies need to anticipate the behavior of the elements inside the application such as how to present the corresponding WAI-ARIA states and properties to the user. The user agent will use the accessibility semantics from the host language and WAI-ARIA accessibility semantics (which may augment or override those of the host language) and present them to assistive technologies through the Document Object Model or the platform accessibility API. The user agent will create an accessible representation of each element in the web page, and will use the appropriate accessibility API to notify assistive technologies of changes to the semantics of those elements.

    -

    The following steps are recommended when WAI-ARIA is applied to content:

    -
      -
    1. -

      Use native markup when possible.

      -

      Use the semantic elements that are defined in the host markup language. For example, with HTML or XHTML, it is better to use the native checkbox than to use a div element with role checkbox as these should already be accessible through your browser. There may also be cases where WAI-ARIA can augment an existing element in the host language. For example, a grid and gridcell elements can reuse the functionality of a table when overlaying it. WAI-ARIA roles, states, and properties are best used when the markup language does not support all the semantics required. When a role attribute is added to an element, the semantics and behavior of the element are augmented or overridden by the role behavior.

      -
      2. -
    2. -

      Apply the appropriate roles.

      -

      Set roles to make sure elements behave predictably and correctly describe the behavior of each element within the application, unless element behaviors are fully described by the native markup language. Roles for interactive elements should support all the attributes that the element could use. Once a role attribute is set it should not be changed as this may confuse the end user. This does not preclude an element being removed which has the role attribute set, but only states and properties (aria-* attributes) should be changed for a given element.

      -
      3. -
    3. -

      Preserve semantic structure.

      -

      Structural information is critical to providing context to persons with disabilities. Preserve DOM hierarchy within structural elements and widgets:

      -
        -
      • Form logical groups within user interface widgets, such as treeitem elements in a group.
        • -
      • Identify large perceivable regions and apply a landmark role to those areas. This will facilitate keyboard navigation. It will also facilitate content management by assistive technologies by providing semantics to manage how much information is rendered at a given time. The use of WAI-ARIA landmarks helps everyone, including vision-impaired users, dexterity-impaired users, and even users with cognitive or learning impairments.
        • -
      • For areas of the page that contain a group of elements that are likely to change through an Ajax application it may be specified as a live region, through the use of the aria-live attribute or it may be marked with pre-defined roles, such as log, which has assumed behavior of a live region.
        • -
      -
      4. -
    4. -

      Build relationships.

      -

      Look for relationships between elements, and mark them using the most appropriate property or attribute. For example, if a page contains both a search form and search results region, mark each container as a region and set the aria-controls attribute of the search form to reference the search results. See relationships in WAI-ARIA.

      -

      Some relationships are determined automatically from the host language, like label elements associated with input elements in HTML.

      -
      5. -
    5. -

      Set states and properties in response to events.

      -

      Once the role for an element has been set, change states and properties as appropriate during the element's life cycle, usually in response to user input events. Only use attributes supported for the chosen role or element.

      -

      User agents should notify assistive technologies of state changes. Conversely, assistive technologies' notification of property changes depends on the method by which assistive technologies communicate with the user agent. For example, the aria-multiline attribute (a property) is not something that changes frequently, whereas the aria-checked attribute (a state) changes frequently in response to user input.

      -
      6. -
    6. -

      Support full, usable keyboard navigation.

      -

      Usable keyboard navigation in a rich internet application is different from the tabbing paradigm in a static document. Rich internet applications behave more like desktop applications where the user tabs to significant widgets and uses the arrow keys to navigate within a complex widget, such as a menu or spreadsheet. The changes that WAI-ARIA introduces in keyboard navigation make this enhanced accessibility possible. Tabbing in the document should follow a logical navigation structure. Authors implementing arrow key navigation should, where possible, follow the design patterns in the WAI-ARIA Authoring Practices Guide. When using these features, it is important as always to ensure keyboard navigation is logical.

      -
      7. -
    7. -

      Synchronize the visual interface with the accessible interface.

      -

      This will allow the state of your UI to be perceivable to the user as well as assistive technologies. For example, the author should use the appropriate WAI-ARIA attribute on a form element that is visually styled to appear required (aria-required) or a gridcell that is visually styled to appear selected (aria-selected). Authors may choose to achieve visual synchronization of these interface elements by using a script or by using CSS attribute selectors.

      -
      8. -
    -
    -

    Example: Building a Tree Widget

    - Graphic of an example tree view. -

    A basic tree view allows the user to select different list items and expand and collapse embedded lists. Arrow keys are used to navigate through a tree, including left/right to collapse/expand sub trees. Clicking the visible expander button with the mouse also toggles expansion. Further keyboard implementation details for tree widgets may found in the .

    -

    To make this feature accessible we need to:

    -
      -
    • Inform assistive technologies about the role of each element;
      • -
    • Inform assistive technologies about the relationships between tree items;
      • -
    • Give a clear keyboard focus that will not confuse users with disabilities; and
      • -
    • Expose the changing states (expanded and collapsed) of the tree items.
      • -
    -

    Following the steps below:

    -
      -
    1. -

      Look at the native markup language

      -

      Although standard list behavior is supported by the native ul and li elements in HTML, there is no element that natively supports list expansion and selection. Since there is not, we will need to use roles.

      -
      2. -
    2. -

      Finding the right roles

      -

      Since there is no native tree element in HTML, we need to add roles from the taxonomy that support the additional states and properties needed. The roles that support tree behavior are:

      -
        -
      • tree: A tree is the main container element for our tree. It is a form of a select where sub-level groups of treeitems may be collapsed and expanded.
        • -
      • treeitem: A treeitem is an option item of a tree. This is an element within a tree; sub-level groups of treeitems may be expanded or collapsed.
        • -
      • group: A group encloses a set of sub-level treeitems.
        • -
      -
      3. -
    3. -

      Look for groups and build relationships

      -

      Tree relationships can be made simply via the DOM and logical structure of the page. A tree element will be the main container encompassing all other elements in the tree. Each selectable item in the tree will be a treeitem.

      -

      When a treeitem contains an embedded list of treeitems they will be all be embedded in a group. A group should be contained inside the tree item that is the parent item.

      - 
      <h1 id="treelabel">WAI-ARIA Tree Example</h1>
-<ul role="tree" aria-labelledby="treelabel" aria-activedescendant="example_id" tabindex="0">
-  <li role="treeitem" aria-expanded="true">Animals
-    <ul role="group">
-      <li role="treeitem">Birds</li>
-      <li role="treeitem" aria-expanded="false">Cats
-        <ul role="group">
-          <li role="treeitem">Siamese</li>
-          <li role="treeitem">Tabby</li>
-        </ul>
-      </li>
-      <li role="treeitem" aria-expanded="true">Dogs
-        <ul role="group">
-          <li role="treeitem" aria-expanded="true">Small Breeds
-            <ul role="group">
-              <li role="treeitem">Chihuahua</li>
-              <li role="treeitem" id="example_id">Italian Greyhound</li>
-              <li role="treeitem">Japanese Chin</li>
-            </ul>
-          </li>
-          <li role="treeitem" aria-expanded="false">Medium Breeds
-            <ul role="group">
-              <li role="treeitem">Beagle</li>
-              <li role="treeitem">Cocker Spaniel</li>
-              <li role="treeitem">Pit Bull</li>
-            </ul>
-          </li>
-          <li role="treeitem" aria-expanded="false">Large Breeds
-            <ul role="group">
-              <li role="treeitem">Afghan</li>
-              <li role="treeitem">Great Dane</li>
-              <li role="treeitem">Mastiff</li>
-            </ul>
-          </li>
-        </ul>
-      </li>
-    </ul>
-  </li>
-  <li role="treeitem" aria-expanded="true">Minerals
-    <ul role="group">
-      <li role="treeitem">Zinc</li>
-      <li role="treeitem" aria-expanded="false">Gold
-        <ul role="group">
-          <li role="treeitem">Yellow Gold</li>
-          <li role="treeitem">White Gold</li>
-        </ul>
-      </li>
-      <li role="treeitem">Silver</li>
-    </ul>
-  </li>
-  <li role="treeitem" aria-expanded="true">Vegetables
-    <ul role="group">
-      <li role="treeitem">Carrot</li>
-      <li role="treeitem">Tomato</li>
-      <li role="treeitem">Lettuce</li>
-    </ul>
-  </li>
-</ul>
      -

      The use of aria-expanded should mirror that which is visibly expanded on screen, so authors may wish to use CSS attribute selectors to toggle visibility or style of an item based on the value of an WAI-ARIA state or property. The following example would hide the sub-level groups of a collapsed tree node.

      - 
      [aria-expanded="false"] [role="group"] { display: none; }
      -

      - - At the time of this writing, this CSS example, while technically correct, will not redraw styles properly in some browsers if the attribute's value is changed dynamically. It may be necessary to toggle a class name, or otherwise force the browser to redraw the styles properly.

      -

      Sometimes a tree structure is not explicit via the DOM and logical structure of a page. In such cases the relationships must still be made explicit using the states and properties. In the following example, the aria-owns attribute indicates that the div with id "external_treeitem" should be considered a child of the ul element with the attribute, even though it is not a child in the DOM.

      - 
      ...
-<li role="treeitem" aria-expanded="true" aria-owns="external_group">Vegetables</li>
-...
-<ul role="group" id="external_group">
-  <li role="treeitem">Carrot</li>
-  <li role="treeitem">Tomato</li>
-  <li role="treeitem">Lettuce</li>
-</ul>
-...
      -

      Sometimes trees (and other lists or grids) cannot be completed represented in the DOM due to performance limitations of the browser. For example, an application interface may only need to display 100 items out of a set of 100,000. Including all 100,000 items in the DOM could cause performance problems on both the client and server machines.

      -

      If items in a managed widget are loaded, for example, via the XMLHttpRequest object, and not present in the DOM at all times, authors should use aria-level, aria-posinset and aria-setsize, and ensure that aria-owns is not required to convey membership with the widget.

      - 
      ...
-<li role="treeitem" aria-level="1" aria-posinset="3" aria-expanded="true" aria-setsize="3">
-  Vegetables
-  <ul role="group">
-    <li role="treeitem" aria-level="2" aria-posinset="6" aria-setsize="8">Carrot</li>
-    <li role="treeitem" aria-level="2" aria-posinset="7" aria-setsize="8">Tomato</li>
-    <li role="treeitem" aria-level="2" aria-posinset="8" aria-setsize="8">Lettuce</li>
-  </ul>
-<li>
-...
      -
      4. -
    4. -

      Use states and properties in response to events

      -

      Control the behavior of the element in response to user input events such as from the keyboard and the mouse, which includes maintaining the current states and properties for that element. For example, a tree control will need to respond to click events on the expand/collapse triggers, and key events on the currently active descendant. Use device-independent events with supporting JavaScript to handle user interaction. For detailed examples of this please refer to the Design Patterns section.

      -
      5. -
    -
    -
    -
    -

    Reasons for Adopting WAI-ARIA

    -

    This section has not been updated since it was integrated from the ARIA 1.0 Primer -- an APG task force review is pending.

    -

    By adopting WAI-ARIA, both developers of static web sites and of dynamic Internet applications can improve the usability, accessibility, and scalability of their products. Developers of static web content can continue to follow the 1999 WCAG 1.0 standards, while improving usability and accessibility through the use of WAI-ARIA landmark roles, aria-labelledby relationships, and properties like aria-invalid and aria-required that can apply to HTML form controls. In richer, dynamic content, developers create custom widgets like calendars and spreadsheets based on technologies such as Ajax and CSS; to achieve accessibility, they need to use WCAG 2.0. Previously, when delivering rich Internet applications to users, to comply with WCAG 1.0, developers resorted to providing alternative, static content. While such measures met the WCAG 1.0 requirements, people using assistive technologies were not provided the richer user experience. When tables are used for layout, rather than CSS absolute positioning, historically, they have been problematic for assistive technologies to interpret. When the WAI-ARIA role of presentation is used on such tables, the assistive technology ignores the table structure, providing a more accessible experience without requiring major recoding.

    -
    -

    Technical Benefits

    -

    Consider a rich Internet application where developers attempt to achieve keyboard accessibility using markup language. Without WAI-ARIA, results may be keyboard accessible but not highly usable; consider a user having to press Tab thirty times to put focus on a checkbox. To achieve keyboard accessibility in HTML without WAI-ARIA, developers must code active elements either as a link or as a form element. Accordingly, this means that no additional semantics are required or provided, other than that provided by the host language. In addition, WCAG 1.0 requires that content be renderable with Cascading Style Sheets turned off in the browser. This approach creates the following general usability problems:

    -
      -
    • All keyboard-accessible controls must be either forms or anchors, forcing the user to tab through all focusable elements on the web page to navigate. If you need to navigate from the first link on the page to the last link on the page, that could be a very long trip and takes usability a step back.
      • -
    • Without WAI-ARIA semantics, you cannot provide contextual information to the user.
      • -
    • If you repurpose HTML elements you cannot provide the appropriate role and context information for the new widget. Lack of context is a serious usability problem. WAI-ARIA semantics results in providing contextual information to the user.
      • -
    • CSS is used for absolute positioning. If you remove that capability, usability features of widgets like pop-up menus disappear. Imagine activating the file menu and the menu showing up at the bottom of the page.
      • -
    -

    WAI-ARIA and WCAG 2.0 coding techniques are useful for developing content and applications that can scale across a variety of user agents, including those on mobile devices.

    -

    For all these reasons, adopting WAI-ARIA makes good technical as well as business sense. For a further illustration, compare how accessibility is achieved with WCAG techniques without and with WAI-ARIA, as shown in .

    -
    - -

    Editor's Note: Figure 7, described as WAI-ARIA tree widget usability comparison, refers to a resource that has not yet been found.

    -
    Usability of Tree Widget Using WAI-ARIA Semantics to Implement WCAG 2.0 Guidelines Compared to WCAG 1.0 Without WAI-ARIA
    -
    - -

    - - shows an "accessible" widget for a tree item, within a tree widget, using WCAG 1.0 without WAI-ARIA, which ,when supplied to a screen reader, may say "link folder Year." There is no information to indicate that the folder is closed (aria-expanded = "false"). There is no information to indicate its depth (aria-level="2"), position in the set and the set size at the level, all of which provides the user with context something sighted users may take for granted. The role is used to indicate that it is a treeitem which indicates that the item should behave and navigate with the keyboard like a tree item. A screen reader using the WAI-ARIA version might say "Closed Folder Year, Closed Folder one of two, Depth two, unchecked." Furthermore, the WAI-ARIA version can allow the tree items to be navigated with arrow keys and without requiring they be navigated as part of a global web page tabbing scheme. This is not what any user would expect of a tree widget. Finally, if you were told all widgets were links on the web page, consider how usable -- or not -- that would be.

    -
    -
    -

    Business Benefits

    -

    If, as described above, coding techniques to achieve accessibility compliance do not promote overall usability, then business strategists must ask "Why invest in accessibility?" With WAI-ARIA, businesses can invest in accessible development and reap benefits for all users, not just those with disabilities or using assistive technologies. Some benefits include:

    -
      -
    • Because WAI-ARIA is being developed through the PFWG with cooperation from browser and assistive technology vendors, accessibility and interoperability with those technologies will be easier to achieve, reducing or eliminating the need for per-browser and per-screenreader coding to achieve accessibility.
      • -
    • In addition to people with disabilities, all users benefit from WAI-ARIA because it establishes a Web-standard for keyboard interaction, easing the learning curve for users moving among applications, sites, and browsers.
      • -
    • Implementing WAI-ARIA can facilitate test automation. Test engines require semantic information about user interface elements, unique names, exposure of state, specific properties in order to run automated test scripts. WAI-ARIA provides that semantic information needed for efficient test automation.
      • -
    -
    -
    -
    -
    - +