Change record status: 
Project: 
Introduced in branch: 
8.7.x
Introduced in version: 
8.7.x
Description: 

The AJAX system now supports links with the use-ajax class to replace the content of a specific selector in the page.

The following new data attributes are now supported on links with the use-ajax class:

  • data-ajax-wrapper: This accepts the ID of the HTML element (without the #) that should be replaced by the content fetched via AJAX. The AJAX system already supported setting the wrapper for Drupal.Ajax, this behavior has not been changed. Now AJAX links can also use this.
  • data-ajax-progress: By default the AJAX links used the throbber progress indicator. AJAX links can now override the default with this data attribute (by setting this to 'fullscreen' for example).
  • data-ajax-focus: This accepts a jQuery selector targeting the element that should receive focus. By default the the focus is returned to the AJAX link after the AJAX request is handled. AJAX links can now override this default with this data attribute. This was added to improve accessibility.

When the use-ajax class is added, an AJAX request fetches the response of the link in the href attribute of the link as usual. The response does not have to be an AJAX response, the called URL can also return a render array.

When an AJAX response is returned, the AJAX response takes precedence over the settings on the AJAX link. For example, if the AJAX link contains a data attribute data-ajax-wrapper to replace an element with the ID content, and the AJAX response is defined to replace the element with ID sidebar, the sidebar is replaced as defined by the AJAX response.

Example usage
<a href="/custom-callback" data-ajax-wrapper="content" data-ajax-progress="fullscreen" data-ajax-focus="#content h1">Example link</a>

When the example link is clicked:

  1. An AJAX call is made to /custom-callback.
  2. While waiting on the response the fullscreen progress indicator is used by the AJAX system.
  3. The returned content replaces the HTML element with ID content.
  4. After the content is replaced, the focus is set on the HTML element with selector #content h1.
Impacts: 
Module developers
Themers