Make WordPress Core


Ignore:
Timestamp:
03/21/2019 09:19:14 AM (6 years ago)
Author:
SergeyBiryukov
Message:

Accessibility: Add ability to pass an ARIA label for the <form> element returned by get_search_form().

This allows screen readers to properly announce each search landmark region independently.

Introduce search_form_args filter for the arguments used when generating the search form.

Props afercia, williampatton.
Fixes #42057.

File:
1 edited

Legend:

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

    r44898 r44956  
    176176 *
    177177 * @since 2.7.0
    178  *
    179  * @param bool $echo Default to echo and not return the form.
    180  * @return string|void String when $echo is false.
    181  */
    182 function get_search_form( $echo = true ) {
     178 * @since 5.2.0 The $args array parameter was added in place of an $echo boolean flag.
     179 *
     180 * @param array $args {
     181 *     Optional. Array of display arguments.
     182 *
     183 *     @type bool   $echo       Whether to echo or return the form. Default true.
     184 *     @type string $aria_label ARIA label for the search form. Useful to distinguish
     185 *                              multiple search forms on the same page and improve
     186 *                              accessibility. Default empty.
     187 * }
     188 * @return string|void String when the $echo param is false.
     189 */
     190function get_search_form( $args = array() ) {
    183191    /**
    184192     * Fires before the search form is retrieved, at the start of get_search_form().
     
    192200
    193201    $format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml';
     202
     203    /*
     204     * Back compat: to ensure previous uses of get_search_form continue to
     205     * function as expected, we handle a value for the boolean $echo param removed
     206     * in 5.2.0. Then we deal with the $args array and cast its defaults.
     207     */
     208    $echo = true;
     209    if ( false === $args ) {
     210        $echo = false;
     211    }
     212
     213    if ( ! is_array( $args ) ) {
     214        // Set an empty array and allow default arguments to take over.
     215        $args = array();
     216    }
     217
     218    // Defaults are to echo and to output no custom label on the form.
     219    $defaults = array(
     220        'echo'       => $echo,
     221        'aria_label' => '',
     222    );
     223
     224    $args = wp_parse_args( $args, $defaults );
     225
     226    /**
     227     * Filters the array of arguments used when generating the search form.
     228     *
     229     * @since 5.2.0
     230     *
     231     * @param array $args The array of arguments for building the search form.
     232     */
     233    $args = apply_filters( 'search_form_args', $args );
    194234
    195235    /**
     
    209249        $form = ob_get_clean();
    210250    } else {
     251        // Build a string containing an aria-label to use for the search form.
     252        if ( isset( $args['aria_label'] ) && $args['aria_label'] ) {
     253            $aria_label = 'aria-label="' . esc_attr( $args['aria_label'] ) . '" ';
     254        } else {
     255            /*
     256             * If there's no custom aria-label, we can set a default here. At the
     257             * moment it's empty as there's uncertainty about what the default should be.
     258             */
     259            $aria_label = '';
     260        }
    211261        if ( 'html5' == $format ) {
    212             $form = '<form role="search" method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
     262            $form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
    213263                <label>
    214264                    <span class="screen-reader-text">' . _x( 'Search for:', 'label' ) . '</span>
     
    218268            </form>';
    219269        } else {
    220             $form = '<form role="search" method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
     270            $form = '<form role="search" ' . $aria_label . 'method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
    221271                <div>
    222272                    <label class="screen-reader-text" for="s">' . _x( 'Search for:', 'label' ) . '</label>
     
    241291    }
    242292
    243     if ( $echo ) {
     293    if ( isset( $args['echo'] ) && $args['echo'] ) {
    244294        echo $result;
    245295    } else {
Note: See TracChangeset for help on using the changeset viewer.