Add ability to pass a label for the <form> element returned by get_search_form()

[williampatton]

When more than a single landmark of the same type appears on page it should be labeled so that screen readers can announce it in a descriptive way to users. Currently the default markup of get_search_form(); returns HTML with landmark role="search" without a label (or option to add a label). If 2 calls to get_search_form(); are made then adding the roles without options for labels limits their usefulness.

When reviewing themes I see multiple calls on the same page often. Most commonly it's when someone rolls their own custom search feature (for example a search icon in navbar that brings a search form into view when toggled) is paired with a search widget in the sidebar. There are other situations where more than a single call to get_search_form(); may be made.

My proposal is to allow an args array to be passed to get_search_form(); so that a label could be defined and attached to the <form> element and screen readers can properly announce each search form independently.

In this proposal I do not suggest a default as announcing 'Search 1', 'Search 2' etc is only marginally more useful than simply announcing the role itself. There is a previous chanset regarding adding an incremental counter which could be used as a default when no label was passed which may well be worthwhile to look into and merging both into a single change. https://core.trac.wordpress.org/changeset/23801

Additional Notes: There is a backwards compatibility issue involved with this suggested change. I believe I can add this feature and ensure no changes are required on the end user part to keep old calls functional. Patch to be forthcoming.

[afercia]

For reference, this is how two search landmark regions are reported by screen readers (in this case, two search widgets):

When themes use a search form in the theme, say in the top toolbar, it would be easy for the theme to use the proposed label. Not sure how to handle the case of multiple search widgets.

[sami.keijonen]

Widget areas are indeed problematic. But it's a good start to explore args array to function get_search_form() which can be added in theme template files.

[williampatton]

Patch to allow passing of $args array to add a label

[williampatton]

I added a diff with changes that allows passing of an args array to get_search_form() and implements the label feature for the generated markup. It contains an empty default as it seems uncertain what the best way to label would be for cases where a custom label is not being passed.

The diff also has some back compat code which will negate the need for any changes for the end user and allowing the old echo/return flag to still function.

[sami.keijonen]

Many themes have searchform.php template file. I'm wondering is there any way to apply label in those themes also? Should/could it just be totally separate template part file.

[williampatton]

The searchform.php template is added with an require meaning that the $args array available in the get_search_form() local scope will also be available in the searchform.php file :)

It may be better for me to move the aria-label generation portion of my additions take place before the include so that the label is available to use in those files without need of possible redundant post-processing.

EDIT: corrected 'include' to 'require'.

[williampatton]

To confirm that the passed label (and any other args) would be available for use within a custom searchform.php file I created one in my test theme and placed some markup inside of it. I called the form manually like so:

get_search_form( array( 'label' => 'top nav search', ) );

At the top of the file I included code to print the list of available variables to debug log:

error_log( print_r( get_defined_vars(), true ), 0 );.

In my logs I see the list of variables available for use inside the searchform.php file and confirm that the passed label is available as part of the $args array.

[02-Oct-2017 18:58:25 UTC] Array
(
    [args] => Array
        (
            [echo] => 1
            [label] => top nav search
        )

    [format] => html5
    [defaults] => Array
        (
            [echo] => 1
            [label] => 
        )

    [result] => Array
        (
            [echo] => 1
            [label] => top nav search
        )

    [search_form_template] => /var/www/html/wp-content/themes/testtheme/searchform.php
)

[afercia]

Discussed during today's accessibility bug-scrub an agreed we'd like to propose this for 4.9.9 consideration.

[audrasjb]

Hi and thanks for the ticket/patch,

5.0.3 is going to be released in a couple of weeks. We are currently sorting the remaining tickets in the milestone. It doesn't appear that ticket can be handled in the next couple of weeks (still needs some discussion/work/component maintainers feedback). Let's address it in 5.1 which is coming in February. Feel free to change/ask to change the milestone if you think the issue can be quickly resolved.

[pento]

42057.diff​ needs to be refreshed. Additionally, there are a couple of issues I noticed:

• The function docblock needs an additional @since tag, describing the parameter change.
• The 'Back compat' comment block should have * at the start of each line.
• While it's possibly not necessary, we should continue to define $echo, so that it's available in a custom searchform.php file.

[williampatton]

I will handle a refresh for this patch in the coming weeks so this can be considered for 5.2 :)

[williampatton]

Patch refreshed and comments addressed.

[williampatton]

fixed issue with args array not being cast back after filters

[afercia]

42057.4.diff​ updates a few things:

• documentation
• the $args arguments need to be documented
• restored the @return tag
• changed the label argument name to aria_label for clarity
• the filtered $args array may not contain all the arguments so there's the need to check for them again

A final review would be appreciated :)

[williampatton]

Latest patch is working for me.

Documentation improvements, better variable name and an additional sanity check on $args containing what's needed - all good improvements here :)

[SergeyBiryukov]

In 44956:

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.

[SergeyBiryukov]

In 45340:

Accessibility: In back-compat code added for get_search_form() in [44956], when checking the (previously boolean) $args value, account for non-strict comparison.

Props dkarfa, sachyya-sachet.
Fixes #47177. See #42057.

[SergeyBiryukov]

In 45341:

Accessibility: In back-compat code added for get_search_form() in [44956], when checking the (previously boolean) $args value, account for non-strict comparison.

Props dkarfa, sachyya-sachet.
Merges [45340] to the 5.2 branch.
Fixes #47177. See #42057.