WordPress.org

Make WordPress Core

Opened 3 months ago

Last modified 5 weeks ago

#42057 assigned enhancement

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

Reported by: williampatton Owned by: sami.keijonen
Milestone: Future Release Priority: normal
Severity: normal Version: 4.8.2
Component: General Keywords:
Focuses: accessibility Cc:

Description

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.

Attachments (1)

42057.diff (3.5 KB) - added by williampatton 3 months ago.
Patch to allow passing of $args array to add a label

Download all attachments as: .zip

Change History (12)

This ticket was mentioned in Slack in #accessibility by williampatton. View the logs.


3 months ago

#2 @afercia
3 months ago

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

https://cldup.com/SYU_Sh13OH.jpg

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.

#3 @sami.keijonen
3 months ago

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
3 months ago

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

#4 @williampatton
3 months ago

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.

#5 @sami.keijonen
3 months ago

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.

Last edited 3 months ago by sami.keijonen (previous) (diff)

#6 @williampatton
3 months ago

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'.

Last edited 3 months ago by williampatton (previous) (diff)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.


3 months ago

This ticket was mentioned in Slack in #accessibility by sami.keijonen. View the logs.


3 months ago

#9 @williampatton
3 months ago

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
)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.


5 weeks ago

#11 @afercia
5 weeks ago

  • Milestone changed from Awaiting Review to Future Release
  • Owner set to sami.keijonen
  • Status changed from new to assigned
Note: See TracTickets for help on using tickets.