Make WordPress Core


Ignore:
Timestamp:
07/06/2020 08:42:14 PM (4 years ago)
Author:
afercia
Message:

Accessibility: Widgets: Add theme support to make widgets output list of links wrapped within a <nav> element.

Widgets that output list of links can now be wrapped within <nav> elements to improve semantics and accessibility.

The <nav> elements are also native landmark regions, which helps assistive technology users to navigate through them. Themes can opt-in to this new behavior by declaring support for the new html5 feature navigation-widgets.

Props joedolson, simonjanin, audrasjb, afercia.
Fixes #48170.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/nav-menu-template.php

    r48185 r48349  
    1616 * @since 3.0.0
    1717 * @since 4.7.0 Added the `item_spacing` argument.
     18 * @since 5.5.0 Added the `container_aria_label` argument.
    1819 *
    1920 * @param array $args {
    2021 *     Optional. Array of nav menu arguments.
    2122 *
    22  *     @type int|string|WP_Term $menu            Desired menu. Accepts a menu ID, slug, name, or object. Default empty.
    23  *     @type string             $menu_class      CSS class to use for the ul element which forms the menu. Default 'menu'.
    24  *     @type string             $menu_id         The ID that is applied to the ul element which forms the menu.
    25  *                                               Default is the menu slug, incremented.
    26  *     @type string             $container       Whether to wrap the ul, and what to wrap it with. Default 'div'.
    27  *     @type string             $container_class Class that is applied to the container. Default 'menu-{menu slug}-container'.
    28  *     @type string             $container_id    The ID that is applied to the container. Default empty.
    29  *     @type callable|bool      $fallback_cb     If the menu doesn't exist, a callback function will fire.
    30  *                                               Default is 'wp_page_menu'. Set to false for no fallback.
    31  *     @type string             $before          Text before the link markup. Default empty.
    32  *     @type string             $after           Text after the link markup. Default empty.
    33  *     @type string             $link_before     Text before the link text. Default empty.
    34  *     @type string             $link_after      Text after the link text. Default empty.
    35  *     @type bool               $echo            Whether to echo the menu or return it. Default true.
    36  *     @type int                $depth           How many levels of the hierarchy are to be included. 0 means all. Default 0.
    37  *     @type object             $walker          Instance of a custom walker class. Default empty.
    38  *     @type string             $theme_location  Theme location to be used. Must be registered with register_nav_menu()
    39  *                                               in order to be selectable by the user.
    40  *     @type string             $items_wrap      How the list items should be wrapped. Default is a ul with an id and class.
    41  *                                               Uses printf() format with numbered placeholders.
    42  *     @type string             $item_spacing    Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'. Default 'preserve'.
     23 *     @type int|string|WP_Term $menu                 Desired menu. Accepts a menu ID, slug, name, or object. Default empty.
     24 *     @type string             $menu_class           CSS class to use for the ul element which forms the menu. Default 'menu'.
     25 *     @type string             $menu_id              The ID that is applied to the ul element which forms the menu.
     26 *                                                    Default is the menu slug, incremented.
     27 *     @type string             $container            Whether to wrap the ul, and what to wrap it with. Default 'div'.
     28 *     @type string             $container_class      Class that is applied to the container. Default 'menu-{menu slug}-container'.
     29 *     @type string             $container_id         The ID that is applied to the container. Default empty.
     30 *     @type string             $container_aria_label The aria-label attribute that is applied to the container when it's a nav element. Default empty.
     31 *     @type callable|bool      $fallback_cb          If the menu doesn't exist, a callback function will fire.
     32 *                                                    Default is 'wp_page_menu'. Set to false for no fallback.
     33 *     @type string             $before               Text before the link markup. Default empty.
     34 *     @type string             $after                Text after the link markup. Default empty.
     35 *     @type string             $link_before          Text before the link text. Default empty.
     36 *     @type string             $link_after           Text after the link text. Default empty.
     37 *     @type bool               $echo                 Whether to echo the menu or return it. Default true.
     38 *     @type int                $depth                How many levels of the hierarchy are to be included. 0 means all. Default 0.
     39 *     @type object             $walker               Instance of a custom walker class. Default empty.
     40 *     @type string             $theme_location       Theme location to be used. Must be registered with register_nav_menu()
     41 *                                                    in order to be selectable by the user.
     42 *     @type string             $items_wrap           How the list items should be wrapped. Default is a ul with an id and class.
     43 *                                                    Uses printf() format with numbered placeholders.
     44 *     @type string             $item_spacing         Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'. Default 'preserve'.
    4345 * }
    4446 * @return void|string|false Void if 'echo' argument is true, menu output if 'echo' is false.
     
    4951
    5052    $defaults = array(
    51         'menu'            => '',
    52         'container'       => 'div',
    53         'container_class' => '',
    54         'container_id'    => '',
    55         'menu_class'      => 'menu',
    56         'menu_id'         => '',
    57         'echo'            => true,
    58         'fallback_cb'     => 'wp_page_menu',
    59         'before'          => '',
    60         'after'           => '',
    61         'link_before'     => '',
    62         'link_after'      => '',
    63         'items_wrap'      => '<ul id="%1$s" class="%2$s">%3$s</ul>',
    64         'item_spacing'    => 'preserve',
    65         'depth'           => 0,
    66         'walker'          => '',
    67         'theme_location'  => '',
     53        'menu'                 => '',
     54        'container'            => 'div',
     55        'container_class'      => '',
     56        'container_id'         => '',
     57        'container_aria_label' => '',
     58        'menu_class'           => 'menu',
     59        'menu_id'              => '',
     60        'echo'                 => true,
     61        'fallback_cb'          => 'wp_page_menu',
     62        'before'               => '',
     63        'after'                => '',
     64        'link_before'          => '',
     65        'link_after'           => '',
     66        'items_wrap'           => '<ul id="%1$s" class="%2$s">%3$s</ul>',
     67        'item_spacing'         => 'preserve',
     68        'depth'                => 0,
     69        'walker'               => '',
     70        'theme_location'       => '',
    6871    );
    6972
     
    177180            $class          = $args->container_class ? ' class="' . esc_attr( $args->container_class ) . '"' : ' class="menu-' . $menu->slug . '-container"';
    178181            $id             = $args->container_id ? ' id="' . esc_attr( $args->container_id ) . '"' : '';
    179             $nav_menu      .= '<' . $args->container . $id . $class . '>';
     182            $aria_label     = ( 'nav' === $args->container && $args->container_aria_label ) ? ' aria-label="' . esc_attr( $args->container_aria_label ) . '"' : '';
     183            $nav_menu      .= '<' . $args->container . $id . $class . $aria_label . '>';
    180184        }
    181185    }
Note: See TracChangeset for help on using the changeset viewer.