Section refreshes are a commonly-used action configurable on any control that accepts an action set in Traditional UI. Throughout Pega Platform, section refreshes are widely used to introduce or support dynamic web page content using AJAX. The main purpose of section refreshes is to submit any recent changes of user-inputted or system data to the server, while reloading a part or the entirety of the UI to ensure the contents and any satisfied visibility conditions are updated.

For example, an application author may want to display an input field in a form labeled as "Last name" after the user has entered a value in the "First name" field. Using a section refresh allows the user's data to be sent to the server and satisfy the condition to allow the Last name field to then become visible on the UI.

How refreshes may affect accessibility

When a refresh occurs, typically through a Refresh Section action, Pega re-generates the entire markup within the refreshed section, replacing the previous markup with new markup and any content changes. This behavior can introduce conflicts with dynamic announcements and focus management, but may be mitigated depending on 

Focus management

To illustrate how this affects keyboard users, consider a scenario where selecting a radio button reveals additional form fields below it. After the user selects the radio button, there is a brief moment during which the radio buttons are removed from the markup before being reinserted into the Document Object Model (DOM) once the refresh completes.

As long as the element that initiated the refresh remains present in the UI, Pega attempts to return focus to that same element immediately after the markup is re-generated. For screen reader users, this may result in the element being re-announced, as the keyboard focus is technically being brought onto that element for the first time in the new DOM structure.

Live announcements

Live announcements , typically introduced through attributes such as aria-live and role="alert", are used to notify screen reader users of any relevant content changes on the page that may be outside of their current focus. Standard authoring does not allow for insertion of such attributes onto controls other than adding the role of "alert" to a dynamic layout, which is often done to provide live announcements for error messages.

The way these attributes typically function on the web is that they are placed on some container element that should remain static in the DOM. When some action occurs on the UI and new text or content is introduced, adding it inside of the container element ensures that screen readers recognize it to be immediately announced back to the user when it appears.

A common example of how this may conflict with the refresh behavior involves dynamic layouts with a visibility condition and the role of alert configured on them. If a user takes some action that makes this dynamic layout (and its contents) then become visible on the UI, the expectation is that screen readers will recognize the live region and immediately announce its contents. However with this approach, the live region and its contents are technically being inserted into the DOM together for the first time, rather than having the container element remain static and only its contents being updated. Screen readers may exhibit conflicting behavior in recognizing that content within the container was updated, since the container element was not present in the DOM prior to the refresh.

Mitigating limitations through configuration

While the logic governing how Pega handles section refreshes can introduce some conflicts with accessibility, there are some alternative approaches that can help to mitigate the behavior. 

Separate parts of the UI into sections that can be specifically targeted for a refresh. The Refresh action by default targets the current section, but can be modified to only target content in a specific section. By separating parts of the UI into separate sections, you can ensure that only the content in the separate gets its markup re-generated.

This can be useful for when a refresh is required to update or display new content outside of the user's current focus, such as making form fields or text become visible lower in the form. Doing so will retain focus on the control the user is interacting with without having it be re-generated and re-focused due to the entire parent section being refreshed. This approach may require a Post Value action before the Refresh-Other section action to ensure the user-inputted data is sent to the server.

Use targeted section refreshes to ensure live region containers remain static. This approach is similar to the above, where we only target the content that needs to be refreshed rather than the whole UI. For example, let's say an application author wants to display a confirmation message below a radio button control after the user selects option B. This radio button contains a Post Value action and Refresh-other section action.

In this parent section, we create a dynamic layout below the field that has the role of "alert" configured. This will remain static on the UI:

Within it is an embedded section containing the content that will appear when the visibility condition is met, that being if the radio button selection is option "B". This is the other section being targeted by the refresh action on the radio button control.

At runtime, we can see that when the user selects option "B", the confirmation message appears on the UI and is immediately announced by screen readers:

By using specific targets for refresh actions and designing live regions in such a way that they can remain static on the UI, many of the shortcomings of a full section-wide refresh can be mitigated to account for accessibility needs. To read more on live announcements and further authoring options for customizations, see the Support Doc on Dynamic announcement interactions with assistive technology in Traditional UI.

Special thanks to Jesse Monks for his support in creating this document.