Preliminary notes:

• Pega implements dynamic announcements as is required by WCAG guidance. If you encounter an issue with out-of-the-box dynamic announcements, please contact the Pega support team to analyze the issue and determine an appropriate solution.

• The example provided illustrates an approach for implementing custom dynamic announcements using non-autogenerated HTML and JavaScript. Generally, Pega does not recommend the use of JavaScript as a means of custom component implementation as it may introduce challenges with future Platform updates. Please use at your discretion.

Dynamic announcements are a functionality designed to provide real-time announcements of pertinent information for screen reader users. These announcements are made using specific ARIA attributes, such as aria-live="polite"/"assertive", role="alert", and role="status". These attributes are placed on an HTML element that contains or will contain content, depending on user action. When any content within that element is modified or replaced, these attributes prompt screen readers to announce the newly added content to the user.

For users with impaired vision who may not be able to see the screen, letting them know that new content has been introduced and what those contents are becomes especially important. Common uses of dynamic announcements include announcing validation error messages as they appear on the user interface, status messages, and changes in content displayed on the web page outside of the user's current focus.

Dynamic announcements in Traditional UI

Pega Platform applications use dynamic announcements out-of-the-box for scenarios such as error messages and status banners. For example, if client-side validation introduces a field-level error when a user moves focus away from a required field left empty, an in-line error message appears below the field and is is contained in an element with aria-live="assertive".

The ability to introduce custom dynamic announcements is limited from an authoring perspective but can be achieved by adding the role="alert" attribute to a dynamic layout under the "General" tab.

Conflicts with refresh behavior

This approach can present challenges due to the way Pega handles partial page refreshes through AJAX. Partial page refreshes are often necessary to update content on the UI with the latest information and components based on real-time user action. When a refresh occurs, typically through a Refresh Section action, any modified content shown through validated visibility conditions are updated on the user interface. Pega re-generates the entire markup within the refreshed section, replacing the previous markup with new markup and any content changes. 

This behavior can conflict with the functionality of dynamic announcement attributes. Instead of modifying only the content within the container element, the refresh also re-generates the container element and its attributes. As a result, screen readers may not properly recognize new content modifications, since the dynamic announcement attributes are technically being introduced for the first time in the markup and no internal content change is detected.

Alternative approach for custom dynamic messages

If the authoring approach for introducing dynamic announcements causes conflicts with screen reader behavior, an alternative method can be used. To ensure that ARIA attributes function as expected when content is introduced, the container elements that hold these attributes must remain static on the user interface.

One approach is to embed a non-autogenerated HTML section within the section rule that contains the content expected to update dynamically. For this example scenario, a user enters data into an input field and then activates a button below it to triggers a Data Transform + Refresh that modifies the value and updates it visibly. The goal is to provide a live announcement for screen reader users to let them know of the update.

Following is the configuration of the embedded section and the button which performs the Data transform + Refresh:

Within the non-autogenerated HTML section, an HTML element can be defined with the appropriate dynamic announcement role to serve as the container for any dynamically appearing content. It is important to assign a unique ID or similar attribute to this element so it can be directly targeted with JavaScript when updating its contents:

Now that the container element has been defined and placed within the parent section, we need to run a script that will execute after the refresh occurs and update the container's contents. One option is to include the script within the relevant Harness' "Scripts & Styles" tab:

Within this file, we define the function that will be called after the refresh when activating the button it is configured on:

We can test the behavior at runtime while using a screen reader to verify the updated content is announced after performing the refresh as expected. Following is an image of the runtime UI with a value entered by the user prior to activating the button:

After activating the button, the container element with its newly-updated content appears on the UI and is explicitly announced by the screen reader:

This method can be extended and adapted to meet specific business requirements when the standard authoring tools are insufficient.