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.
Built from https://develop.svn.wordpress.org/trunk@44956


git-svn-id: http://core.svn.wordpress.org/trunk@44787 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/general-template.php

@@ -175,11 +175,19 @@ function get_template_part( $slug, $name = null ) {
  * search. To give a few examples of what it can be used for.
  *
  * @since 2.7.0
+ * @since 5.2.0 The $args array parameter was added in place of an $echo boolean flag.
  *
- * @param bool $echo Default to echo and not return the form.
- * @return string|void String when $echo is false.
+ * @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( $echo = true ) {
+function get_search_form( $args = array() ) {
 	/**
 	 * Fires before the search form is retrieved, at the start of get_search_form().
 	 *
@@ -192,6 +200,38 @@ function get_search_form( $echo = true ) {
 
 	$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 );
+
 	/**
 	 * Filters the HTML format of the search form.
 	 *
@@ -208,8 +248,18 @@ function get_search_form( $echo = true ) {
 		require( $search_form_template );
 		$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>
 					<input type="search" class="search-field" placeholder="' . esc_attr_x( 'Search &hellip;', 'placeholder' ) . '" value="' . get_search_query() . '" name="s" />
@@ -217,7 +267,7 @@ function get_search_form( $echo = true ) {
 				<input type="submit" class="search-submit" value="' . esc_attr_x( 'Search', 'submit button' ) . '" />
 			</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>
 					<input type="text" value="' . get_search_query() . '" name="s" id="s" />
@@ -240,7 +290,7 @@ function get_search_form( $echo = true ) {
 		$result = $form;
 	}
 
-	if ( $echo ) {
+	if ( isset( $args['echo'] ) && $args['echo'] ) {
 		echo $result;
 	} else {
 		return $result;

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.2-alpha-44955';
+$wp_version = '5.2-alpha-44956';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.