Make WordPress Core

Opened 7 years ago

Closed 5 years ago

Last modified 5 years ago

#42057 closed enhancement (fixed)

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

Reported by: williampatton's profile williampatton Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 5.2 Priority: normal
Severity: normal Version: 4.8.2
Component: General Keywords: dev-feedback has-patch commit
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 (4)

42057.diff (3.5 KB) - added by williampatton 7 years ago.
Patch to allow passing of $args array to add a label
42057.2.diff (3.7 KB) - added by williampatton 5 years ago.
42057.3.diff (3.7 KB) - added by williampatton 5 years ago.
fixed issue with args array not being cast back after filters
42057.4.diff (4.0 KB) - added by afercia 5 years ago.

Download all attachments as: .zip

Change History (40)

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


7 years ago

#2 @afercia
7 years 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
7 years 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
7 years ago

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

#4 @williampatton
7 years 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
7 years 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 7 years ago by sami.keijonen (previous) (diff)

#6 @williampatton
7 years 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 7 years ago by williampatton (previous) (diff)

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


7 years ago

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


7 years ago

#9 @williampatton
7 years 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.


6 years ago

#11 @afercia
6 years ago

  • Milestone changed from Awaiting Review to Future Release
  • Owner set to sami.keijonen
  • Status changed from new to assigned

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


6 years ago

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


6 years ago

#14 @SergeyBiryukov
6 years ago

  • Milestone changed from Future Release to 5.0

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


6 years ago

#16 @afercia
6 years ago

  • Milestone changed from 5.0 to 4.9.9

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

#17 @pento
6 years ago

  • Milestone changed from 4.9.9 to 5.0.1

#18 @pento
5 years ago

  • Milestone changed from 5.0.1 to 5.0.2

#19 @pento
5 years ago

  • Milestone changed from 5.0.2 to 5.0.3

#20 @audrasjb
5 years ago

  • Keywords dev-feedback added
  • Milestone changed from 5.0.3 to 5.1

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.

#21 @pento
5 years ago

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.

#22 @pento
5 years ago

  • Milestone changed from 5.1 to 5.2

#23 @williampatton
5 years ago

  • Keywords needs-refresh added

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

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


5 years ago

#25 @williampatton
5 years ago

Patch refreshed and comments addressed.

@williampatton
5 years ago

fixed issue with args array not being cast back after filters

#26 @williampatton
5 years ago

  • Keywords has-patch added; needs-refresh removed

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


5 years ago

#28 @SergeyBiryukov
5 years ago

  • Owner changed from sami.keijonen to SergeyBiryukov
  • Status changed from assigned to reviewing

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


5 years ago

@afercia
5 years ago

#30 @afercia
5 years ago

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 :)

#31 @williampatton
5 years ago

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 :)

#32 @afercia
5 years ago

  • Keywords commit added

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


5 years ago

#34 @SergeyBiryukov
5 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

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.

#35 @SergeyBiryukov
5 years ago

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.

#36 @SergeyBiryukov
5 years ago

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.

Note: See TracTickets for help on using tickets.