Skip Headers
Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework
11g Release 1 (11.1.1)

Part Number B31973-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

21 Developing Accessible ADF Faces Pages

This chapter describes how to add accessibility support to ADF Faces components with keyboard shortcuts and text descriptions of the component name and state. Accessibility guidelines for ADF pages that use partial page rendering, scripting, styles, and certain page and navigation structures are also described.

This chapter includes the following sections:

21.1 Introduction to Accessible ADF Faces Pages

Accessibility involves making your application usable by persons with disabilities such as low vision or blindness, deafness, or other physical limitations. In the simplest of terms, this means creating applications that can be used without a mouse (keyboard only), used with a screen reader for blind or low-vision users, and used without reliance on sound, color, or animation and timing.

Oracle software implements the standards of Section 508 and WCAG 1.0 AA using an interpretation of the standards at http://www.oracle.com/accessibility/standards.html.

ADF Faces user interface components have built-in accessibility support for visually and physically impaired users. User agents such as a Web browser rendering to nonvisual media such as a screen reader can read component text descriptions to provide useful information to impaired users. Access key support provides an alternative method to access components and links using only the keyboard. ADF Faces accessibility audit rules provide direction to create accessible images, tables, frames, forms, error messages and popup windows using accessible HTML markup.

While following provided ADF Faces accessibility guidelines for component-specific, and page and navigation structures is useful, it is not a substitute for familiarity with accessibility standards and performing accessibility testing with assistive technology.

21.2 Developing Accessible ADF Faces Components and Pages

Guidelines for component-specific accessibility are provided in Table 21-1, "ADF Faces Components Accessibility Guidelines". The guidelines include a description of the relevant property with examples and tips. For information about auditing compliance with ADF Faces accessibility rules see Section 21.2.2, "How to Run an ADF Faces Accessibility Rules Audit".

To develop accessible page and navigation structures follow these additional accessibility guidelines:

21.2.1 Using ADF Faces Component Accessibility Guidelines

To develop accessible ADF Faces components follow the guidelines described in Table 21-1. Components not listed do not have accessibility guidelines.

Note:

In cases where the label property is referenced in the accessibility guidelines, the labelAndAccessKey property may be used where available, and is the preferred option.

Unless as noted otherwise, you can also label ADF Faces input and select controls by:

  • Specifying the for property in an af:outputLabel component.

  • Specifying the for property in an af:panelLabelAndMessage component.

Table 21-1 ADF Faces Components Accessibility Guidelines

Component Guidelines

af:chooseColor

For every af:chooseColor component, there must be at least one af:inputColor component with a chooseId property which points to the af:chooseColor component.

af:chooseDate

For every af:chooseDate component, there must be at least one af:inputDate component with a chooseId property which points to the af:chooseDate component

af:commandButton

One of the following properties must be specified: text, textAndAccessKey, or shortDesc. The text should specify the action to be taken and make sense when read out of context. For example use "go to index" instead of "click here".

af:commandLink

Specify the text property. The text should specify where the link will take the user and make sense when read out of context. For example use "go to index" instead of "click here". Multiple links that go to the same location must use the same text and unique links must have unique text.

af:commandMenuItem

af:commandNavigationItem

af:comandToolbarButton

One of the following properties must be specified: text, textAndAccessKey, or shortDesc.

af:dialog

af:document

Specify the title property.

af:goButton

One of the following properties must be specified: text, textAndAccessKey, or shortDesc. The text should specify the action to be taken and make sense when read out of context. For example use "go to index" instead of "click here".

af:goLink

Specify the text property. The text should specify where the link will take the user and make sense when read out of context. For example use "go to index" instead of "click here". Multiple links that go to the same location must use the same text and unique links must have unique text.

af:image

Specify the shortDesc property. If the image is only present for decorative purposes and communicates no information, set shortDesc to the empty string.

Use the longDescURL property for images where a complex explanation is necessary. For example, charts and graphs require a description file that includes all details that make up the chart.

af:inlineFrame

Specify the shortDesc property.

af:inputColor

af:inputComboboxListOfValues

af:inputDate

af:inputFile

af:inputListOfValues

af:inputNumberSlider

af:inputNumberSpinbox

af:inputRangeSlider

af:inputText

Specify the label property.

For af:inputComboboxListOfValues and af:inputListOfValues components, the searchDesc must also be specified.

af:outputFormatted

The value property must specify valid HTML.

af:outputLabel

When using to label an ADF Faces input or select control, the for property must be specified.

af:panelBox

af:panelHeader

Specify the text property.

af:panelLabelAndMessage

When using to label an ADF Faces input or select control, the for property must be specified.

af:panelSplitter

af:panelStretchLayout

Refer to Section 21.2.6, "How to Use Page Structures and Navigation".

af:panelWindow

Specify the title property.

af:poll

When using polling to update content, allow end users to control the interval, or to explicitly initiate updates instead of polling.

af:query

Specify the headerText property.

af:quickQuery

Specify the searchDesc property.

af:richTextEditor

Specify the label property.

af:selectBooleanCheckbox

af:selectBooleanRadio

One of the following properties must be specified: text, textAndAccessKey, or label.

af:selectItem

Specify the label property. Note that using the for attribute of af:outputLabel and af:panelMessageAndLabel components are not acceptable alternatives.

af:selectManyCheckbox

af:selectManyChoice

af:selectManyListbox

af:selectManyShuttle

af:selectOneChoice

af:selectOneListbox

af:selectOneRadio

af:selectOrderShuttle

Specify the label property.

For the af:selectManyShuttle and af:selectOrderShuttle components, the leadingHeader and trailingHeader properties must be specified.

af:showDetailHeader

Specify the text property.

af:showDetailItem

One of the following properties must be specified: text, textAndAccessKey, or shortDesc.

af:table

af:treeTable

Specify the summary property. The summary should describe the purpose of the table.If the table is used for layout purposes, the summary property must contain an empty string.

All table columns must have column headers.


21.2.2 How to Run an ADF Faces Accessibility Rules Audit

JDeveloper provides ADF Faces accessibility audit rules to investigate and report compliance with many of the common requirements described in Table 21-1, "ADF Faces Components Accessibility Guidelines". Running an audit report involves creating and running an audit profile.

To create an audit profile:

  1. From the main menu choose Tools > Preferences.

  2. In the Audit: Profiles dialog, unselect all checkboxes except ADF Faces Accessibility Rules.

  3. Save the profile with a unique name and click OK.

To run the audit report:

  1. From the main menu choose Build > Audit target.

  2. Select the audit profile you created from the list.

  3. Click OK to generate the report.

The audit report results are displayed in the Log window. After the report completes, you can export the results to HTML by clicking the Export icon in the Log window toolbar.

21.2.3 How to Use Partial Page Rendering

Screen readers do not reread the full page in a partial page request. Partial page rendering (PPR) causes the screen reader to read the page starting from the component that triggered the partial action. Therefore, place the target component after the component that triggers the partial request; otherwise the screen reader will not read the updated target.

For example, the most common PPR use case is the master-detail user interface, where selecting a value in the master component results in partial page replacement of the detail component. In such scenarios, the master component must always appear before the detail component in the document order.

Screen reader or screen magnifier users may have difficulty determining exactly what content has changed as a result of partial page rendering activity. It may be helpful to provide guidance in the form of inline text descriptions that identify relationships between key components in the page. For example, in the master-detail scenario, some text that indicates that selecting a row on a master component will result in the detail component being updated could be helpful. Alternatively, a help topic that describes the structure of the page and the relationships between components may also be helpful.

21.2.4 How to Use Scripting

Client-side scripting is not recommended for any application problem for which there is a declarative solution and should be kept to a minimum.

Follow these accessibility guidelines when using scripting:

  • Do not interact with the component DOM (Document Object Model) directly.

    ADF Faces components automatically synchronize with the screen reader when DOM changes are made. Direct interaction with the DOM is not allowed.

  • Do not use JavaScript timeouts.

    Screen readers do not reliably track modifications made in response to timeouts implemented using the JavaScript setTimeout() or setInterval() APIs. Do not call these methods.

  • Provide keyboard equivalents.

    Some users may not have access to a mouse. For example, some users may be limited to keyboard use only, or may use alternate input devices or technology such as voice recognition software. When adding functions using client-side listeners, the function must be accessible in a device-independent way. Practically speaking this means that:

    • All functions must be accessible using the keyboard events.

    • Click events should be preferred over mouseup or mousedown.

    • Mouseup or mousedown events should additionally be available through a click event.

  • Avoid focus changes.

    Focus changes can be confusing to screen reader users as these involve a change of context. Applications should avoid changing the focus programmatically, and should never do so in response to focus events. Additionally, popup windows should not be displayed in response to focus changes because standard tabbing will be disrupted.

  • Provide explicit popup triggers.

    Screen readers do not automatically respond to inline popup startups. In order to force the screen reader to read the popup contents when in screen reader mode, the rich client framework explicitly moves the keyboard focus to any popup window just after it is opened. An explicit popup trigger such as a link or button must be provided, or the same information must be available in some other keyboard or screen reader accessible way.

21.2.5 How to Use Styles

ADF Faces components are already styled and the use of a cascading style sheet (CSS) to directly modify their default appearance should be avoided.

Follow these accessibility guidelines when using styles:

  • Do not override default component appearance.

    Avoid using CSS to change the default appearance of ADF Faces components. Using CSS to change the appearance of components can have accessibility implications. For example, changing colors may result in color contrast issues.

  • Use scalable size units.

    When specifying sizes using CSS, use size units that scale relative to the font size rather than absolute units. For example, use em, ex or % units rather than px. This is particularly important when specifying heights using CSS, because low-vision users may scale up the font size, causing contents restricted to fixed or absolute heights to be clipped.

  • Do not use CSS positioning.

    CSS positioning should be used only in the case of positioning the stretched layout component. Do not use CSS positioning elsewhere.

21.2.6 How to Use Page Structures and Navigation

Follow these accessibility guidelines when using these page structures and navigation tools:

  • Use af:panelSplitter component instead of af:panelStretchLayout component.

    When implementing geometry-managed layouts, favor af:panelSplitter over af:panelStretchLayout where possible, which allows users to:

    • Redistribute space to meet their needs.

    • Hide or collapse content that is not of immediate interest.

    These page structure qualities are useful to all users, and are particularly helpful for low-vision users and screen-reader users.

    As an example, a chrome navigation bar at the top of the page should be placed within the first facet of a vertical af:panelSplitter component rather than the top facet of af:panelStretchLayout component. This allows the user to decrease the amount of space used by the bar, or to hide it altogether. Similarly, in layouts that contain left, center, or right panes, use horizontal splitters to lay out the panes.

  • Enable scrolling of flow layout contents.

    When nesting flow layout contents such as layout controls inside of geometry managed parent components such as af:panelSplitter or af:panelStretchLayout, wrap af:panelGroupLayout with layout="scroll" around the flow layout contents. This provides scrollbars in the event that the font size is scaled up such that the content no longer fits. Failure to do this can result in content being clipped or truncated.

  • Use header-based components to identify page structure.

    HTML header elements play an important role in screen readability. Screen readers typically allow users to gain an understanding of the overall structure of the page by examining or navigating across HTML headers. Identify major portions of the page through components that render HTML header contents including:

    • af:panelHeader

    • af:showDetailHeader

    • af:showDetailItem in af:panelAccordion (each accordion in a pane renders an HTML header for the title area)

  • Use af:breadCrumbs component to identify page location.

    Accessibility standards require that users are able to determine their location within a web site or application. The use of af:breadCrumbs achieves this purpose.

21.3 Defining Access Keys for ADF Faces Components

Access key support for ADF Faces input or command and go components such as af:inputText, af:commandButton, and af:goLink involves defining labels and specifying keyboard shortcuts. While it is possible to use the tab key to move from one control to the next in a web application, keyboard shortcuts are more convenient and efficient.

To specify an access key for a component, set the component's accessKey attribute to a keyboard character (or mnemonic) that is used to gain quick access to the component. You can set the attribute in the Property Inspector or in the page source using &amp encoding.

Note:

Access keys are not displayed if the accessibility mode is set to screenReader mode. For more information, see Section 21.4, "Selecting Accessibility Modes".

The same access key can be bound to several components. If the same access key appears in multiple locations in the same page, the rendering agent will cycle among the components accessed by the same key. That is, each time the access key is pressed, the focus will move from component to component. When the last component is reached, the focus will return to the first component.

Using access keys on af:goButton and af:goLink components may immediately activate them in some browsers. Depending on the browser, if the same access key is assigned to two or more go components on a page, the browser may activate the first component instead of cycling through the components that are accessed by the same key.

21.3.1 How to Define Access Keys for an ADF Faces Component

In the Property Inspector of the component for which you are defining an access key, enter the mnemonic character in the accessKey attribute field. When simultaneously setting the text, label, or value and mnemonic character, use the ampersand (&) character in front of the mnemonic character in the relevant attribute field.

Use one of four attributes to specify a keyboard character for an ADF Faces input or command and go component:

  • accessKey: Use to set the mnemonic character used to gain quick access to the component. For command and go components, the character specified by this attribute must exist in the text attribute of the instance component; otherwise, ADF Faces does not display the visual indication that the component has an access key.

    Example 21-1 shows the code that sets the access key to the letter h for the af:goLink component. When the user presses the keys ALT+H, the text value of the component will be brought into focus.

    Example 21-1 AccessKey Attribute Defined

    <af:goLink text="Home" accessKey="h">
    
  • textAndAccessKey: Use to simultaneously set the text and the mnemonic character for a component using the ampersand (&) character. In JSPX files, the conventional ampersand notation is &amp;. In JSP files, the ampersand notation is simply &. In the Property Inspector you need only the &.

    Example 21-2 shows the code that specifies the button text as Home and sets the access key to H, the letter immediately after the ampersand character, for the af:commandButton component.

    Example 21-2 TextAndAccessKey Attribute Defined

    <af:commandButton textAndAccessKey="&amp;Home"/>
    
  • labelAndAccessKey: Use to simultaneously set the label attribute and the access key on an input component, using conventional ampersand notation.

    Example 21-3 shows the code that specifies the label as Date and sets the access key to a, the letter immediately after the ampersand character, for the af:selectInputDate component.

    Example 21-3 LabelAndAccessKey Attribute Defined

    <af:inputSelectDate value="Choose date" labelAndAccessKey="D&amp;ate"/>
    
  • valueAndAccessKey: Use to simultaneously set the value attribute and the access key, using conventional ampersand notation.

    Example 21-4 shows the code that specifies the label as Select Date and sets the access key to e, the letter immediately after the ampersand character, for the af:outputLabel component.

    Example 21-4 ValueAndAccessKey Attribute Defined

    <af:outputLabel for="someid" valueAndAccessKey="Select Dat&amp;e"/>
    <af:inputText simple="true" id="someid"/>
    

Access key modifiers are browser and platform-specific. If you assign an access key that is already defined as a menu shortcut in the browser, the ADF Faces component access key will take precedence. Refer to your specific browser's documentation for details.

In some browsers, if you use a space as the access key, you must provide the user with the information that Alt+Space or Alt+Spacebar is the access key because there is no way to present a blank space visually in the component's label or textual label. For that browser you could provide text in a component tooltip using the shortDesc attribute.

21.3.2 How to Define Localized Labels and Access Keys

Labels and access keys that must be displayed in different languages can be stored in resource bundles where different language versions can be displayed as needed. Using the <resource-bundle> element in the JSF configuration file available in JSF 1.2, resource bundles can be made available to all the pages in your application without using a f:loadBundle tag in every page.

To define localized labels and access keys:

  1. Create the resource bundles as simple .properties files to hold each language version of the labels and access keys. For details, see Section 20.2.1, "How to Define the Base Resource Bundle".

  2. Add a <locale-config> element to the faces-config.xml file to define the default and supported locales for your application. For details, see Section 20.2.3, "How to Register Locales and Resource Bundles in Your Application".

  3. Create a key and value for each string of static text for each resource bundle. The key is a unique identifier for the string. The value is the string of text in the language for the bundle. In each value, place an ampersand (& or amp) in front of the letter you wish to define as an access key.

    For example, the following code defines a label and access key for an edit button field in the UIStrings.properties base resource bundle as Edit:

    srlist.buttonbar.edit=&Edit
    

    In the Italian language resource bundle, UIStrings_it.properties, the following code provides the translated label and access key as Aggiorna:

    srlist.buttonbar.edit=A&ggiorna
    
  4. Add a <resource-bundle> element to the faces-config.xml file for your application. Example 21-5 shows an entry in a JSF configuration file for a resource bundle.

    Example 21-5 Resource Bundle in JSF Configuration File

    <resource-bundle>
       <var>res</var>
       <base-name>resources.UIStrings</base-name>
    </resource-bundle>
    

Once you set up your application to use resource bundles, the resource bundle keys show up in the Expression Language (EL) editor so you can assign them declaratively.

In the following example the UI component accesses the resource bundle:

<af:outputText value="#{res['login.date']}"/

For more information see Chapter 20, "Internationalizing and Localizing Pages".

21.4 Selecting Accessibility Modes

ADF Faces provides three levels of application accessibility support, configured in the trinidad-config.xml file using the <accessibility-mode> element. The acceptable values for <accessibility-mode> are:

21.4.1 How to Configure Accessibility Support in trinidad-config.xml

In JDeveloper, when you insert an ADF Faces component into a JSF page for the first time, a starter trinidad-config.xml file is automatically created for you in the /WEB-INF/ directory. The file has a simple XML structure that enables you to define element properties using the JSF expression language (EL) or static values. The order of elements in the file does not matter. You can configure accessibility support by editing the XML file directly or by using the Structure window.

To configure accessibility support in trinidad-config.xml in JDeveloper:

  1. In the Application Navigator, double-click trinidad.xml to open the file in the XML editor.

  2. Enter the element name <accessibility-mode> and accessibility support value (default, screenReader, or inaccessible) in the editor, for example:

    <accessibility-mode>screenReader</accessibility-mode>
    

    This code sets the application's accessibility support to the screen reader mode.

Alternatively, you can use the Structure window to insert the value.

  1. Select the trinidad-config.xml file in the Application Navigator.

  2. In the Structure window, right-click the XML file root element, choose the Insert Inside menu item, and click the <accessibility-mode> element.

  3. Double-click the newly inserted element in the Structure window to open the properties editor. Enter a value or select one from a dropdown list.

Once you have configured the trinidad-config.xml file, you can retrieve the property values programmatically or by using JSF EL expressions.

For example the following code returns nothing if the accessibility mode is not explicitly set:

String mode=ADFFacesContext.getCurrentInstance().getAccessibilityMode;

In this EL expression example, a null is returned if the accessibility mode is not explicitly set:

<af:outputText value="*#{requestContext.accessibilityMode}"/>

21.5 Providing Text for Screen Reader Support

ADF Faces components support text screen readers by providing text descriptions as well as the state of visual content, such as an enabled or disabled button.

Images that are automatically generated by ADF Faces components have built-in descriptions that can be read by screen readers or nonvisual browsers, such as the error or warning icons produced by ADF Faces input components.

For images generated from user-provided icons, and images produced by certain components such as the af:commandNavigationItem, ADF Faces uses the text or icon attribute value supplied by the user to generate text that describes the component name as well as its state. Every icon and image must have a shortdesc attribute.

Example 21-6 shows a code fragment for a tabbed navigation pane where the generated text for the second tab would read: Page 2: Currently selected tab.

Example 21-6 Tabbed Navigation Pane for Screen Reader

<af:navigationPane hint="tabs">
  <af:commandNavigationItem text="Page 1" action=#{action.app1}/>
  <af:commandNavigationItem text="Page 2" selected="true"/>
  <af:commandNavigationItem text="Page 3" action=#{action.app2}/>
<af:navigationPane/>

21.5.1 How to Provide Screen Reader Support for Images, Icons and Other Objects

Use the shortDesc attribute to provide a short description about the object. The shortDesc attribute transforms into an HTML alt attribute.

Layout images such as background images, bullets, or curved borders around objects do not convey useful information other than to provide visual appeal to sighted users. If you use such images, you should still set shortDesc attributes on the images, but use empty strings as the attribute values.

For the af:selectInputText flashlight icon, set the searchDesc attribute to provide tooltip text that can also be read by a client agent.

21.5.2 How to Provide Screen Reader Support for Frames

If you must use frames, provide links to alternative pages without frames using the alternateContent facet on afh:frameBorderLayout component.

Example 21-7 shows the use of the alternateContent facet in the File Explorer Application.

Example 21-7 Frame with Screen Reader Support

<afh:frameBorderLayout shortDesc="File Explorer App">
  ...
  <f:facet name="alternateContent">
    <af:goLink text="Click here for a no frames version"     destination="noframes.html"/>
  </f:facet>
  ...
</afh:frameBorderLayout>

The alternateContent section corresponds to an HTML NOFRAMES tag.

With each frame, you should also provide a generic description about the contents by using shortDesc or the longDescURL attribute of the frame component. The longDescURL attribute specifies a link to a long description of the frame. This long description supplements the short description provided using the shortDesc attribute, and is also useful for nonvisual user agents such as a screen reader.

Example 21-8 shows the use of longDescURL to specify a link to the long description of a frame.

Example 21-8 Frame with Long Description

<afh:frameBorderLayout>
  <f:facet name="left">
    <afh:frame source="frame_leftTest.jspx" name="left" width="30%" shortDesc="Some brief text"/>
  </f:facet>
  <f:facet name="center">
    <afh:frame source="frame_centerTest.jspx" name="contents" longDescURL="link to some longer text"/>
  </f:facet>
  ...
</afh:frameBorderLayout>

21.5.3 How to Provide Screen Reader Support for Tables

When using tables, use the summary attribute to provide a description about the purpose of the table, its structure and contents, to user agents rendering to nonvisual media.

Example 21-9 shows the use of the summary attribute in a table to support a screen reader.

Example 21-9 Table with Screen Reader Support

<af:table summary="This table describes the contents of your shopping bag: item, name, unit price, quantity, and subtotal" value="#{myManagedBean.allItems}" var="shop">
  <af:column>
    <f:facet name="header">
      <af:outputText value="Name"/>
    </f:facet>
    <af:outputText value="#{shop.item}"/>
  </af:column>
  <af:column>
  <f:facet name="header">
    <af:outputText value="Price"/>
  </f:facet>
  <af:outputText value="#{shop.price}"/>
  </af:column>
</af:table>

Note:

ADF Faces also constructs error messages using the summary attribute text. For information, see Section 10.2.4, "How to Display a Table on a Page".

21.5.4 How to Provide Screen Reader Support for Text

The af:outputText component has a description attribute that lets you attach additional descriptive text for the screen reader and other accessibility agents; the text is not visible otherwise.