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


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

22.1 Introduction to Accessible ADF Faces Pages

Accessibility involves making your application usable for persons with disabilities such as low vision or blindness, deafness, or other physical limitations. 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 the Web Content Accessibility Guidelines (WCAG) 1.0 AA using an interpretation of the standards at

Additional framework and platform issues presented by client-side scripting, in particular using asynchronous JavaScript and XML (AJAX) have been addressed in Oracle's accessibility strategy.

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 components, page, and navigation structures is useful, it is not a substitute for familiarity with accessibility standards and performing accessibility testing with assistive technology.

22.2 Exposing Accessibility Preferences

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:

You can also use the @accessibility-profile element to define finer-grain accessibility preferences in the style sheet or you can specify the accessibility profile options in the trinidad-config.xml file.The options are high-contrast, large-fonts, or both. For more information, see Section 20.1.1, "Oracle ADF Faces Skins."

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

  2. In the XML editor, enter the element name <accessibility-mode> and accessibility support value (default, screenReader, or inaccessible). For example:


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

  3. Enter the element name <accessibility-profile> and accessibility profile value (high-contrast, large-fonts). For example:

    <!-- Enable both high-contrast and large-fonts content -->
    <accessibility-profile>high-contrast large-fonts</accessibility-profile>

    This code sets the application's profile support to use both high contrast and large fonts.

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

    1. In the Application Navigator, select the trinidad-config.xml file.

    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 Property Inspector. Enter a value or select one from the 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}"/>

22.3 Specifying Component-Level Accessibility Properties

Guidelines for component-specific accessibility are provided in Section 22.3.1, "ADF Faces Component 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 22.5, "Running Accessibility Audit Rules."

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.


Access keys are not displayed if the accessibility mode is set to screenReader mode. For more information, see Section 22.2, "Exposing Accessibility Preferences."

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.

To develop accessible page and navigation structures follow the additional accessibility guidelines described in Section 22.4, "Creating Accessible Pages."

22.3.1 ADF Faces Component Accessibility Guidelines

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


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 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 22-1 ADF Faces Components Accessibility Guidelines

Component Guidelines


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.


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


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


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.




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



Specify the title property.


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


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.


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.


Specify the shortDesc property.










Specify the label property.

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


The value property must specify valid HTML.


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



Specify the text property.


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



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


Specify the title property.


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


Specify the headerText property.


Specify the searchDesc property.


Specify the label property.



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


Specify the label property. Note that using the for attribute of af:outputLabel and af:panelMessageAndLabel components is not an acceptable alternative.









Specify the label property.

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


Specify the text property.


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



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.

22.3.2 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 22-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 22-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 22-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 22-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 22-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 22-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 22-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 22-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.

22.3.3 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, you can make resource bundles 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 21.3.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 21.3.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 base resource bundle as Edit:


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

  4. Add a <resource-bundle> element to the faces-config.xml file for your application. Example 22-5 shows an entry in a JSF configuration file for a resource bundle.

    Example 22-5 Resource Bundle in JSF Configuration File


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

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

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

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

22.4 Creating Accessible Pages

In addition to component-level accessibility guidelines, you should also follow page-level accessibility guidelines when you design your application. While component-level guidelines may determine how you use a component, page-level accessibility guidelines are more involved with the overall design and function of the application as a whole.

The page-level accessibility guidelines are for:

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

22.4.2 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 mouseover or mouseout.

    • Mouseover or mouseout 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.

22.4.3 How to Use Styles

ADF Faces components are already styled and you may not need to make any changes. If you want to use cascading style sheet (CSS) to directly modify their default appearance, you should follow these accessibility guidelines:

  • Be aware of accessibility implications when you override default component appearance.

    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.

22.4.4 How to Use Page Structures and Navigation

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

  • Use af:panelSplitter component for layouts.

    When implementing geometry-managed layouts, using af:panelSplitter allows users to:

    • Redistribute space to meet their needs

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

    If you are planning to use af:panelStretchLayout, you should consider using af:panelStretchLayout instead when is appropriate

    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 within 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 be able to determine their location within a web site or application. The use of af:breadCrumbs achieves this purpose.

22.4.5 How to Use WAI-ARIA Landmark Regions

The WAI-ARIA standard defines different sections of the page as different landmark regions. Together with WAI-ARIA roles, they convey information about the high-level structure of the page and facilitate navigation across landmark areas. This is particularly useful to users of assistive technologies such as screen readers.

ADF Faces includes landmark attributes for several layout components, as listed in Table 22-2.

Table 22-2 ADF Faces Components with Landmark Attributes

Component Attribute















These attributes can be set to one of the WAI-ARIA landmark roles, including:

  • banner

  • complimentary

  • contentinfo

  • main

  • navigation

  • search

When any of the landmark-related attributes is set, ADF Faces renders a role attribute with the value you specified.

22.5 Running Accessibility Audit Rules

JDeveloper provides ADF Faces accessibility audit rules to investigate and report compliance with many of the common requirements described in Section 22.3.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, deselect 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.