Changeset 44956

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:

• trunk/src/wp-includes/general-template.php (modified) (5 diffs)

trunk/src/wp-includes/general-template.php

@@ -176 +176 @@
  *
  * @since 2.7.0
- *
- * @param bool $echo Default to echo and not return the form.
- * @return string|void String when $echo is false.
- */
-function get_search_form( $echo = true ) {
+ * @since 5.2.0 The $args array parameter was added in place of an $echo boolean flag.
+ *
+ * @param array $args {
+ *     Optional. Array of display arguments.
+ *
+ *     @type bool   $echo       Whether to echo or return the form. Default true.
+ *     @type string $aria_label ARIA label for the search form. Useful to distinguish
+ *                              multiple search forms on the same page and improve
+ *                              accessibility. Default empty.
+ * }
+ * @return string|void String when the $echo param is false.
+ */
+function get_search_form( $args = array() ) {
     /**
      * Fires before the search form is retrieved, at the start of get_search_form().
@@ -192 +200 @@
 
     $format = current_theme_supports( 'html5', 'search-form' ) ? 'html5' : 'xhtml';
+
+    /*
+     * Back compat: to ensure previous uses of get_search_form continue to
+     * function as expected, we handle a value for the boolean $echo param removed
+     * in 5.2.0. Then we deal with the $args array and cast its defaults.
+     */
+    $echo = true;
+    if ( false === $args ) {
+        $echo = false;
+    }
+
+    if ( ! is_array( $args ) ) {
+        // Set an empty array and allow default arguments to take over.
+        $args = array();
+    }
+
+    // Defaults are to echo and to output no custom label on the form.
+    $defaults = array(
+        'echo'       => $echo,
+        'aria_label' => '',
+    );
+
+    $args = wp_parse_args( $args, $defaults );
+
+    /**
+     * Filters the array of arguments used when generating the search form.
+     *
+     * @since 5.2.0
+     *
+     * @param array $args The array of arguments for building the search form.
+     */
+    $args = apply_filters( 'search_form_args', $args );
 
     /**
@@ -209 +249 @@
         $form = ob_get_clean();
     } else {
+        // Build a string containing an aria-label to use for the search form.
+        if ( isset( $args['aria_label'] ) && $args['aria_label'] ) {
+            $aria_label = 'aria-label="' . esc_attr( $args['aria_label'] ) . '" ';
+        } else {
+            /*
+             * If there's no custom aria-label, we can set a default here. At the
+             * moment it's empty as there's uncertainty about what the default should be.
+             */
+            $aria_label = '';
+        }
         if ( 'html5' == $format ) {
-            $form = '<form role="search" method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
+            $form = '<form role="search" ' . $aria_label . 'method="get" class="search-form" action="' . esc_url( home_url( '/' ) ) . '">
                 <label>
                     <span class="screen-reader-text">' . _x( 'Search for:', 'label' ) . '</span>
@@ -218 +268 @@
             </form>';
         } else {
-            $form = '<form role="search" method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
+            $form = '<form role="search" ' . $aria_label . 'method="get" id="searchform" class="searchform" action="' . esc_url( home_url( '/' ) ) . '">
                 <div>
                     <label class="screen-reader-text" for="s">' . _x( 'Search for:', 'label' ) . '</label>
@@ -241 +291 @@
     }
 
-    if ( $echo ) {
+    if ( isset( $args['echo'] ) && $args['echo'] ) {
         echo $result;
     } else {