WordPress.org
Get WordPress

Make WordPress Core

Changeset 46236


Ignore:
Timestamp:
09/22/2019 10:31:34 PM (5 years ago)
Author:
afercia
Message:

Accessibility: Make sure the navigation ARIA landmarks used for posts and comments navigation are properly labelled.

The <nav> element defines an ARIA landmark by default: landmarks help assistive technology users to perceive the page main sections and jump through them. However, when a landmark is used more than once in a page, it needs to be distinguished from the other ones to let users understand what the landmark is about.

Adds an aria-label parameter to the following functions:

  • _navigation_markup()
  • get_the_post_navigatio()
  • get_the_posts_navigation()
  • get_the_posts_pagination()
  • get_the_comments_navigation()
  • get_the_comments_pagination()

Props sabernhardt, williampatton, SergeyBiryukov, audrasjb.
Fixes #47123.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/link-template.php

    r46232 r46236  
    25452545 * @since 4.1.0
    25462546 * @since 4.4.0 Introduced the `in_same_term`, `excluded_terms`, and `taxonomy` arguments.
     2547 * @since 5.3.0 Added the `aria_label` parameter.
    25472548 *
    25482549 * @param array $args {
    … …  
    25542555 *     @type array|string $excluded_terms     Array or comma-separated list of excluded term IDs. Default empty.
    25552556 *     @type string       $taxonomy           Taxonomy, if `$in_same_term` is true. Default 'category'.
    2556  *     @type string       $screen_reader_text Screen reader text for nav element. Default 'Post navigation'.
     2557 *     @type string       $screen_reader_text Screen reader text for the nav element. Default 'Post navigation'.
     2558 *     @type string       $aria_label         ARIA label text for the nav element. Default 'Posts'.
    25572559 * }
    25582560 * @return string Markup for post links.
    25592561 */
    25602562function get_the_post_navigation( $args = array() ) {
     2563    // Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
     2564    if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
     2565        $args['aria_label'] = $args['screen_reader_text'];
     2566    }
     2567
    25612568    $args = wp_parse_args(
    25622569        $args,
    … …  
    25682575            'taxonomy'           => 'category',
    25692576            'screen_reader_text' => __( 'Post navigation' ),
     2577            'aria_label'         => __( 'Posts' ),
    25702578        )
    25712579    );
    … …  
    25912599    // Only add markup if there's somewhere to navigate to.
    25922600    if ( $previous || $next ) {
    2593         $navigation = _navigation_markup( $previous . $next, 'post-navigation', $args['screen_reader_text'] );
     2601        $navigation = _navigation_markup( $previous . $next, 'post-navigation', $args['screen_reader_text'], $args['aria_label'] );
    25942602    }
    25952603
    … …  
    26132621 *
    26142622 * @since 4.1.0
     2623 * @since 5.3.0 Added the `aria_label` parameter.
    26152624 *
    26162625 * @global WP_Query $wp_query WordPress Query object.
    … …  
    26232632 *     @type string $next_text          Anchor text to display in the next posts link.
    26242633 *                                      Default 'Newer posts'.
    2625  *     @type string $screen_reader_text Screen reader text for nav element.
     2634 *     @type string $screen_reader_text Screen reader text for the nav element.
    26262635 *                                      Default 'Posts navigation'.
     2636 *     @type string $aria_label         ARIA label text for the nav element. Default 'Posts'.
    26272637 * }
    26282638 * @return string Markup for posts links.
    … …  
    26332643    // Don't print empty markup if there's only one page.
    26342644    if ( $GLOBALS['wp_query']->max_num_pages > 1 ) {
     2645        // Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
     2646        if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
     2647            $args['aria_label'] = $args['screen_reader_text'];
     2648        }
     2649
    26352650        $args = wp_parse_args(
    26362651            $args,
    … …  
    26392654                'next_text'          => __( 'Newer posts' ),
    26402655                'screen_reader_text' => __( 'Posts navigation' ),
     2656                'aria_label'         => __( 'Posts' ),
    26412657            )
    26422658        );
    … …  
    26532669        }
    26542670
    2655         $navigation = _navigation_markup( $navigation, 'posts-navigation', $args['screen_reader_text'] );
     2671        $navigation = _navigation_markup( $navigation, 'posts-navigation', $args['screen_reader_text'], $args['aria_label'] );
    26562672    }
    26572673
    … …  
    26752691 *
    26762692 * @since 4.1.0
     2693 * @since 5.3.0 Added the `aria_label` parameter.
    26772694 *
    26782695 * @param array $args {
    … …  
    26812698 *     @type string $screen_reader_text Screen reader text for navigation element.
    26822699 *                                      Default 'Posts navigation'.
     2700 *     @type string $aria_label         ARIA label text for the nav element. Default 'Posts'.
    26832701 * }
    26842702 * @return string Markup for pagination links.
    … …  
    26892707    // Don't print empty markup if there's only one page.
    26902708    if ( $GLOBALS['wp_query']->max_num_pages > 1 ) {
     2709        // Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
     2710        if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
     2711            $args['aria_label'] = $args['screen_reader_text'];
     2712        }
     2713
    26912714        $args = wp_parse_args(
    26922715            $args,
    … …  
    26962719                'next_text'          => _x( 'Next', 'next set of posts' ),
    26972720                'screen_reader_text' => __( 'Posts navigation' ),
     2721                'aria_label'         => __( 'Posts' ),
    26982722            )
    26992723        );
    … …  
    27082732
    27092733        if ( $links ) {
    2710             $navigation = _navigation_markup( $links, 'pagination', $args['screen_reader_text'] );
     2734            $navigation = _navigation_markup( $links, 'pagination', $args['screen_reader_text'], $args['aria_label'] );
    27112735        }
    27122736    }
    … …  
    27312755 *
    27322756 * @since 4.1.0
     2757 * @since 5.3.0 Added the `aria_label` parameter.
    27332758 * @access private
    27342759 *
    27352760 * @param string $links              Navigational links.
    2736  * @param string $class              Optional. Custom class for nav element. Default: 'posts-navigation'.
    2737  * @param string $screen_reader_text Optional. Screen reader text for nav element. Default: 'Posts navigation'.
     2761 * @param string $class              Optional. Custom class for the nav element. Default: 'posts-navigation'.
     2762 * @param string $screen_reader_text Optional. Screen reader text for the nav element. Default: 'Posts navigation'.
     2763 * @param string $aria_label         Optional. ARIA label for the nav element. Default: same value as $screen_reader_text.
    27382764 * @return string Navigation template tag.
    27392765 */
    2740 function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader_text = '' ) {
     2766function _navigation_markup( $links, $class = 'posts-navigation', $screen_reader_text = '', $aria_label = '' ) {
    27412767    if ( empty( $screen_reader_text ) ) {
    27422768        $screen_reader_text = __( 'Posts navigation' );
    27432769    }
     2770    if ( empty( $aria_label ) ) {
     2771        $aria_label = $screen_reader_text;
     2772    }
    27442773
    27452774    $template = '
    2746     <nav class="navigation %1$s" role="navigation">
     2775    <nav class="navigation %1$s" role="navigation" aria-label="%4$s">
    27472776        <h2 class="screen-reader-text">%2$s</h2>
    27482777        <div class="nav-links">%3$s</div>
    … …  
    27532782     *
    27542783     * Note: The filtered template HTML must contain specifiers for the navigation
    2755      * class (%1$s), the screen-reader-text value (%2$s), and placement of the
    2756      * navigation links (%3$s):
    2757      *
    2758      *     <nav class="navigation %1$s" role="navigation">
     2784     * class (%1$s), the screen-reader-text value (%2$s), placement of the navigation
     2785     * links (%3$s), and ARIA label text if screen-reader-text does not fit that (%4$s):
     2786     *
     2787     *     <nav class="navigation %1$s" role="navigation" aria-label="%4$s">
    27592788     *         <h2 class="screen-reader-text">%2$s</h2>
    27602789     *         <div class="nav-links">%3$s</div>
    … …  
    27692798    $template = apply_filters( 'navigation_markup_template', $template, $class );
    27702799
    2771     return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links );
     2800    return sprintf( $template, sanitize_html_class( $class ), esc_html( $screen_reader_text ), $links, esc_html( $aria_label ) );
    27722801}
    27732802
    … …  
    29783007 *
    29793008 * @since 4.4.0
     3009 * @since 5.3.0 Added the `aria_label` parameter.
    29803010 *
    29813011 * @param array $args {
    … …  
    29863016 *     @type string $next_text          Anchor text to display in the next comments link.
    29873017 *                                      Default 'Newer comments'.
    2988  *     @type string $screen_reader_text Screen reader text for nav element. Default 'Comments navigation'.
     3018 *     @type string $screen_reader_text Screen reader text for the nav element. Default 'Comments navigation'.
     3019 *     @type string $aria_label         ARIA label text for the nav element. Default 'Comments'.
    29893020 * }
    29903021 * @return string Markup for comments links.
    … …  
    29953026    // Are there comments to navigate through?
    29963027    if ( get_comment_pages_count() > 1 ) {
     3028        // Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
     3029        if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
     3030            $args['aria_label'] = $args['screen_reader_text'];
     3031        }
     3032
    29973033        $args = wp_parse_args(
    29983034            $args,
    … …  
    30013037                'next_text'          => __( 'Newer comments' ),
    30023038                'screen_reader_text' => __( 'Comments navigation' ),
     3039                'aria_label'         => __( 'Comments' ),
    30033040            )
    30043041        );
    … …  
    30153052        }
    30163053
    3017         $navigation = _navigation_markup( $navigation, 'comment-navigation', $args['screen_reader_text'] );
     3054        $navigation = _navigation_markup( $navigation, 'comment-navigation', $args['screen_reader_text'], $args['aria_label'] );
    30183055    }
    30193056
    … …  
    30363073 *
    30373074 * @since 4.4.0
     3075 * @since 5.3.0 Added the `aria_label` parameter.
    30383076 *
    30393077 * @see paginate_comments_links()
    … …  
    30423080 *     Optional. Default pagination arguments.
    30433081 *
    3044  *     @type string $screen_reader_text Screen reader text for nav element. Default 'Comments navigation'.
     3082 *     @type string $screen_reader_text Screen reader text for the nav element. Default 'Comments navigation'.
     3083 *     @type string $aria_label         ARIA label text for the nav element. Default 'Comments'.
    30453084 * }
    30463085 * @return string Markup for pagination links.
    30473086 */
    30483087function get_the_comments_pagination( $args = array() ) {
    3049     $navigation   = '';
     3088    $navigation = '';
     3089
     3090    // Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
     3091    if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
     3092        $args['aria_label'] = $args['screen_reader_text'];
     3093    }
     3094
    30503095    $args         = wp_parse_args(
    30513096        $args,
    30523097        array(
    30533098            'screen_reader_text' => __( 'Comments navigation' ),
     3099            'aria_label'         => __( 'Comments' ),
    30543100        )
    30553101    );
    … …  
    30643110
    30653111    if ( $links ) {
    3066         $navigation = _navigation_markup( $links, 'comments-pagination', $args['screen_reader_text'] );
     3112        $navigation = _navigation_markup( $links, 'comments-pagination', $args['screen_reader_text'], $args['aria_label'] );
    30673113    }
    30683114
Note: See TracChangeset for help on using the changeset viewer.