Software Engineering

ADF Accessibility: Notify assistive technology using WAI-ARIA status live region

When using Oracle Application Development Framework (ADF) for web development the framework already provides several techniques to improve assistive technology support. In this respect an interesting feature is the JavaScript function announceToAssistiveTechnology() which was added in ADF (ADF New Features). The function enables developers to actively announce messages to assistive technology tools. Unfortunately, this functionality only works when using screen reader rendering mode. Nevertheless, we had the requirement to provide a comparable functionality when using standard rendering mode. This blog post describes the applied approach to achieve a similar result.

How does it work?

The first step is to understand how this technique works. In general, Oracle’s JavaScript function uses a WAI-ARIA status live region. The WAI-ARIA  initiative aims to create standards in order to improve internet accessibility for users with disabilities. Assistive technology tools like screen readers implement this standard and therefore react on certain HTML-Element attributes. Developers can use the standard during website implementation and include additional elements in order to announce messages to assistive technology tools. One possibility is the use of status live regions. Their content is monitored by assistive technology tools and re-announced as soon as it changes.

In order to define a status live region, following WAI-ARIA attributes can be used:

role=“status“ – A container whose content is advisory information for the user but is not important enough to justify an alert

aria-live=“polite“ – Indicates that an element will be updated

aria-atomic=“true“ – Indicates whether assistive technologies will present all, or only parts of, the changed region

Implementing a custom solution for standard rendering mode

In order to implement a solution based on WAI-ARIA standards first of all a status live region is needed. A simple SPAN element, which is defined with the WAI-ARIA attributes described above, is enough to fulfill this requirement. One way to define the element on a page is to use the JSF Verbatim Tag:

In this example the CSS class p_OraHiddenLabel is used in order to push the SPAN element out of the visible view port. As result it is not visible on the rendered page, however the screen reader still recognizes it. Furthermore, it is important to choose a unique ID for this element such that it does not collide with other IDs generated by ADF. Depending on the requirements the element can be defined in a page template to enable the functionality on all pages using this template.

Secondly,  a JavaScript function is needed which updates the span’s content. In general, this function mimics  Oracle’s announceToAssistiveTechnology() function. The following code could be a possible JavaScript implementation.

This implementation uses two clientAttributes in order to pass information to the function:

message – The message which should be announced to assistive technology tools

onlyIfChanged – Boolean indicating if messages should only be passed to assistive technology tools if the current message is different from the last message

In order to determine if the current message differs from the last message the message is stored in an AdfPage object property.

In general, these are all components needed. Next step is to call the JavaScript function.

Using notifyAtUser within ADF

The JavaScript function notifyAtUser can be called using ADF’s clientListener. As described above it only requires two clientAttributes, message and onlyIfChanged. Therefore, one only has to add the following three ADF tags to any component which supports the clientListener technique and should announce some event to assistive technology tools.

In this example notifyAtUser will be called as soon as the surrounding component obtains focus. As result it will announce the String “Some important information!” to the AT technology.


In this blog post we adopted an approach which is also used by Oracle within the screen reader mode in order to add custom assistive technology tool support to an ADF application. Although this approach might be appropriate if using screen reader mode is not possible, it should be the last option. In general, ADF has built in support for assistive technology tools and it should be preferred to self implemented solutions.