wp.a11y.speak()

Topics

wp.a11y.speak() is a JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. method included into WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. as off version 4.2.

When content changes dynamically in a web page, wp.a11y.speak() can announce a message using aria-live. Then users who depend on a screen reader will be notified of any change to the content on the page.

Joe Dolson and Andrea Fercia wrote a clear introduction and manual on the method in Let WordPress Speak, new in WordPress 4.2

Example of a wp.a11y.speak() implementation

In this example a table with data is displayed. The user can select for example a categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. and the table with the data below will be updated dynamically.

With wp.a11y.speak() we can announce that the table has been updated with new data.

Note: for wp.a11y.speak() to work best, the screen-reader-text CSS class should be added to your theme CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site.. Also, wp.a11y.speak() is only available after DOM ready, so be sure not to call it earlier!

Top ↑

In functions.php

add_action( 'wp_enqueue_scripts', 'yourprefix_ajax' );

function yourprefix_ajax() {

    // Register the script.
    wp_register_script( 'your-prefix-ajax', get_template_directory_uri() . '/assets/js/your-ajax-file.js',
    [
        'wp-a11y',
    ], 
     false, 
     true 
     );

    // Localization.
    wp_localize_script( 'your-prefix-ajax', 'yourData', [
        strings' => [
            'resultsFound' => esc_html__( 'New results found and displayed in the table below', 'your-theme' )
        ],
    ] );
    wp_enqueue_script( 'your-prefix-ajax' );
}

Top ↑

In your-ajax-file.js

Within the js method generating the dynamic changes you can call:

// Announce change of data in the table.
wp.a11y.speak( yourData.strings.resultsFound, 'polite' );

Top ↑

The generated output

<div id="wp-a11y-speak-polite" aria-live="polite" aria-relevant="additions text" aria-atomic="true" class="screen-reader-text wp-a11y-speak-region">
New results found and displayed in the table below
</div>

This <div> will be added to the bottom of the web page.

Top ↑

Resources

  • WordPress speaks with wp.a11y.speak by Sami Keijonen, explanation, examples in GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ and a demo site
  • Let WordPress Speak, new in WordPress 4.2 by Joe Dolson and Andrea Fercia, introducing and explaining the method
  • The NPM Module @wordpress/a11y that has the “speak” method that allows you to easily announce dynamic interface updates to screen readers using ARIA live regions. This module is inspired by the speak function in wp-a11y.js
  • a11y-speak, a Github repository by Yoast containing a dedicated JS module, called A11ySpeak which makes the wp.a11y.speak functionality more universally available

Last updated: