Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1.4.0) B31973-06 |
|
![]() Previous |
![]() Next |
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:
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 Level AA using an interpretation of the standards at http://www.oracle.com/accessibility/standards.html
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.
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:
default
: By default, ADF Faces generates HTML code that is accessible to disabled users.
screenReader
: ADF Faces generates HTML code that is optimized for the use of screen readers. The screenReader
mode facilitates text usage for disabled users, but may degrade the output for nondisabled users or users with only some physical limitations. For example, access keys are disabled in screenReader
mode in order to prevent conflicts with keys used by assistive technology.
inaccessible
: ADF Faces removes all code that supports assistive technology. This optimization reduces the size of the generated HTML. The application, however, is no longer accessible to disabled users.
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, "ADF Faces Skins."
The acceptable values for <accessibility-profile>
are:
high-contrast
: ADF Faces can generate high-contrast–friendly visual content. The high-contrast mode is intended to make ADF Faces applications compatible with operating systems or browsers that have high-contrast features enabled. For example, ADF Faces changes its use of background images and background colors in high-contrast mode to prevent the loss of visual information. Note that the high-contrast mode is more beneficial if it is used in conjunction with your browser's or operating system's high-contrast mode. Also, some users might find it beneficial to use the large-font mode along with the high-contrast mode.
large-fonts
: ADF Faces can generate browser-zoom–friendly content. In default mode, most text and many containers have a fixed size to provide a consistent and defined look. In the large-font mode, text and containers have a scalable size. This allows ADF Faces both to be compatible with browsers that are set to larger font sizes and to work with browser-zoom capabilities. Note that if you are not using the large-font mode or browser-zoom capabilities, you should disable the large-font mode. Also, some users might find it beneficial to use the high contrast mode along with the large-font mode.
Note: The<accessibility-mode> and <accessibility-profile > elements are EL-bound to a session scope managed bean that contains the user-specific preference. |
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:
In the Application Navigator, double-click trinidad.xml.
In the XML editor, enter the element name <accessibility-mode>
and accessibility support value (default
, screenReader
, or inaccessible
). For example:
<accessibility-mode>screenReader</accessibility-mode>
This code sets the application's accessibility support to the screen reader mode.
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.
Alternatively, you can use the Structure window to insert the value:
In the Application Navigator, select the trinidad-config.xml file.
In the Structure window, right-click the XML file root element, choose the Insert Inside menu item, and click the <accessibility-mode> element.
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}"/>
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 &
encoding.
Note: Access keys are not displayed if the accessibility mode is set toscreenReader 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."
To develop accessible ADF Faces components, follow the guidelines described in Table 22-1. Components not listed do not have accessibility guidelines.
Table 22-1 ADF Faces Components Accessibility Guidelines
Component | Guidelines |
---|---|
|
For every |
|
For every |
|
One of the following properties must be specified: |
|
Specify the |
|
One of the following properties must be specified: |
|
Specify the |
|
One of the following properties must be specified: |
|
Specify the |
|
Specify the Use the |
|
Specify the |
|
Specify the For |
|
The |
|
When using this component to label an ADF Faces input or select control, the |
|
Specify the |
|
When using this component to label an ADF Faces input or select control, the |
|
Refer to Section 22.4.4, "How to Use Page Structures and Navigation." |
|
Specify the |
|
When using polling to update content, allow end users to control the interval, or to explicitly initiate updates instead of polling. |
|
Specify the following properties:
|
|
Specify the |
a |
Specify the |
|
One of the following properties must be specified: |
|
Specify the |
|
Specify the For the |
|
Specify the |
|
One of the following properties must be specified: |
|
Specify the All table columns must have column headers. |
If you are using ADF Faces table components in your web application, you must designate a column as the row header for screen reader mode. The row header is used by the screen reader software to announce the row when the end user selects it. Typically, a single column is used as a row header that allows multiple selections, but you can mark multiple columns as row headers. When you mark multiple columns as row headers, they appear as the initial columns of the table, and they are frozen.
Sometimes, for display purposes, you may not want to have a row header. In such a case, you must define one column in the table to have the rowHeader
attribute set to unstyled
. In screen reader mode, the table or the tree table component with the unstyled
row header column is moved to the starting position with displayIndex
set to 0
, and it is frozen. In default mode, the table or tree table component with the unstyled
row header column is not moved to the starting position, it is not frozen, and it is rendered without any row header CSS style.
To develop accessible ADF Data Visualization components, follow the accessibility guidelines described in Table 22-2. Components not listed do not have accessibility guidelines.
Table 22-2 ADF Data Visualization Components Accessibility Guidelines
Component | Guideline |
---|---|
|
Specify the |
|
Specify the |
|
Specify the Note that in screen reader mode, an instance of pivot table component substitutes the graph component, and the end user can then use the standard cursor keys to navigate through the data. In screen reader mode, the following visualization features of the graph component are not supported:
In screen reader mode, the following interactive features of the graph component are not supported:
|
|
Specify the |
|
Specify the |
Note: Thedvt:hierarchyViewer and dvt:map components do not have built-in accessibility support, and therefore do not have accessibility guidelines. You must provide alternate, accessible access for these components. |
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.
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 &
. 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.
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.
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.
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.
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:
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."
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."
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
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.
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['login.date']}"/
For more information, see Chapter 21, "Internationalizing and Localizing 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:
Using partial page rendering
Using scripting
Using styles
Using page structures and navigation
Using WAI-ARIA landmark regions
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.
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.
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 the 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.
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.
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.
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-3.
Table 22-3 ADF Faces Components with Landmark Attributes
Component | Attribute |
---|---|
|
|
|
|
|
firstLandmark
|
|
|
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.
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:
From the main menu, choose Tools > Preferences.
In the Audit: Profiles dialog, deselect all checkboxes except ADF Faces Accessibility Rules.
Save the profile with a unique name and click OK.
To run the audit report:
From the main menu, choose Build > Audit target.
Select the audit profile you created from the list.
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.