List table: headings for pagination and views links

[afercia]

One of the goals the accessibility team would like to propose for the next release is to improve the overall heading structure in the admin. Together with #31650 there's a lot of room for improvements.

The admin screens based on list tables have at least two places (maybe more) worthy of new headings: the "views" links and the pagination links.

See screenshot (headings are visible to give you an idea, they should be hidden).

Why this is useful?
Navigating through headings is ​the first thing screen reader users try to find information on a web page. With a few keystrokes you can quickly jump between headings and go directly to the tools you want to use.

For most screens we can just add the strings we need in the $current_screen object.
For posts and taxonomies though, we would need new labels in order to have fully translatable strings. Currently, posts and taxonomies can be provided with labels to be used in visible parts of the interface (e.g. the "Search" button, menu items, etc.) and it would be great to have labels to be used for accessibility purposes as well.

Discussed a bit ​on Slack with @sergeybiryukov we're open to discussion, any thoughts more than welcome.

Some things to discuss:

• should bulk actions and other available actions and filters selects have their own headings?
• what about adding a new heading right before the table? e.g. "Users list".
• better wording for the views links: "Filter xx to display"

[afercia]

Attached patch is nothing more than a proof of concept for now, many things are to be reviewed (naming conventions for example). In the patch:

• new method to add accessibility related information in class WP_Screen
• new labels for posts and taxonomies
• new hidden headings to improve accessibility in all the List Table screens

[rianrietveld]

Maybe add a heading at the start of the table too? So the screen reader user can jump directly to the top of the table?

[rianrietveld]

Patch 32147.patch was tested by the wpa11y test team.

Testers: Tobias Clemens Häcker, Geof Collis, Gabriela Nino de Rivera Torres, Shaun Everiss, Kim van Iersel, Michelle DeYoung

Questions to the team:

1: Do you find the extra headings useful?

Gabriela: I guess the extra information could be useful. VoiceOver and NVDA offer a way to navigate between headers in a page. The extra headers, if used correctly, could help the user to find easily a zone or section inside a page. For example, the user makes a plugin search, she open the header menu (in VoiceOver) or uses H or other command (NVDA) to navigate to the header for the results navigation or to the header placed before the results.
The user did not find what she is looking for, she open the header menu and select the header search to navigate to the search form. And more or less that's the idea. A easy way to move from a zone or section in a page.

Geof: I liked the new headings though, very useful.

Are the headings text clear to you?

Gabriela: Not always. In pages were results are display in a table, the navigation options are available before the table and after the table. But the two headers text are the same, for example: comments navigation. I see on the headers menu, two h2 comments navigation which is confusing. If we could say: top comments navigation and bottom comments navigation to give a better idea where are they in the page.
Others headers are kind of clear, for example: "Filter comments to display" it could be rephrased like "Options to filter comments".

Comment Shaun: I found all the level2 headings I noticed on the page there were 2 level 2 headings that said the same things, that of multimedia items or something like that.

Comment Geof: Noticed I am getting 2 'post navigation' headings, each one is different in its layout though, planned? I would think that I should be able to select which one I want.
I also changed the number of posts to show and the post navigation headings disappeared.

Comment Michelle:

• About "Posts navigation": Perhaps change to something like "Navigation for posts displayed in table" or "Pagination for posts displayed in table."
• About "Media items navigation": Perhaps change to something like "Navigation for Media items displayed in table" or "Pagination for Media items displayed in table."
• About "Plugins navigation": Perhaps change to something like "Navigation for plugins displayed in table" or "Pagination for plugins displayed in table."

3: What extra headings would you like?

Have headers that make easy for the user to move inside the main content.

4: Which heading is not necessary?

All are useful

Results per screen reader:

• Safari + VoiceOVer: works
• NVDA + Windows + FireFox: works
• Jaws: works
• ChromeVox: Probably depending on the settings it works or not

Tobias: ChromeVox doesn't select (and read) the new (invisible) headings:
Heading level 2 Filter posts to display
Heading level 2 Posts navigation
Heading level 2 Posts navigation

Michelle: Headings in ChromeVox work.

Comment by @afercia: ChromeVox: has some quircks... I need to go first to the Main Content and then focus the "Help" tab and then it correctly reads out the new headings. I fear we can't do much to fix this, looks like a ChromeVox specific issue.
Comment by Tobias: How about sending our feedback to the developers of ChromeVox, too?

Conclusions

• The extra headings are useful
• They work in the tested screen readers, only ChromeVox has some issues probably depending on user settings
• Two H2's like comments navigation are confusing. Change that into top comments navigation and bottom comments navigation to give a better idea where are they in the page

Suggestion for a better headings text:

• Change for example "Post navigation" into "Navigation for posts displayed in table"
• "Filter comments to display" it could be rephrased like "Options to filter comments"

[davidakennedy]

We chatted about this in today's accessibility meeting today, and I reviewed the hidden heading text from a native English speaker's perspective. They make sense and are intuitive based on the screen they correspond with – at least to me. :)

[afercia]

Trying to recap testers feedback:

• just one heading for pagination (the one on top)
• many testers asked to have at least one more heading right before the table

Also, basically all the tables are showing us nothing else than... a list. So maybe we should use "list"? See screenshot below (the headings should be hidden of course). Any thoughts more than welcome.

[afercia]

refreshed patch takes the approach visually represented in the screenshot above.

[afercia]

The Install new Theme and Install new Plugin screens will need something more if we want the heading before the list to be updated depending on the "tab" currently active:

For plugins, we'd need a translatable string with a placeholder, something like:
_x( '%s plugins list', 'current plugins tab' )
wondering if that would be an acceptable string, would like to have @ocean90 and/or @SergeyBiryukov feedback :)

For themes, the heading should be updated with JavaScript in theme.js depending on the current "section".

Any thoughts more than welcome.

[joedolson]

I think this is a good change. All for it.

[ocean90]

Replying to afercia:

For plugins, we'd need a translatable string with a placeholder, something like:
_x( '%s plugins list', 'current plugins tab' )
wondering if that would be an acceptable string, would like to have @ocean90 and/or @SergeyBiryukov feedback :)

No it wouldn't. Can't we just use a general "plugins list" headline? Looks like there is no separation for the users list based on the filtered role, why do we need one for plugins/themes?

[afercia]

Replying to ocean90:

Replying to afercia:
Can't we just use a general "plugins list" headline? Looks like there is no separation for the users list based on the filtered role, why do we need one for plugins/themes?

Not sure what do you mean with "separation" but you're right about the other screens, I mean also the Users, Posts, Pages, Comments, Media, etc. screens would need something to indicate which is the current view. Currently there's just some bold text and no semantic markup to say you're, for example, in the "sticky posts list". By the way this should probably go in a separate ticket, will use a "plugins list" heading for now. Thanks!

[afercia]

Refreshed patch adds a 'Plugins list' heading in the "Add Plugins" screens.

[rianrietveld]

Tested by the #wpa11y team:

Geof Collis: Really like the new setup!!

Shaun Everiss: The headings work now as expected.

Gabriela Nino de Rivera Torres: The hidden headings are a lot better. Headers are more clearer now than before. IMO, I really think there should be a hidden header for the search functionality. Searching is one of the common actions that the user does in admin, it will be nice to have it on the headers menu to have a shortcut.

[afercia]

Refreshed patch fixes a missing heading in the Comments screen and adds just one heading in the Link Manager (visible just in old installs with links or via dedicated plugin) screen.

[obenland]

The patch includes a notable addition to WP_Screen. We should think about making the property private and adding getter/setter methods, along the lines of how help and screen settings work.

Maybe we could also find a better method name than add_a11y_info. set_|get_screen_reader_text()? set_|get_a11y_heading()?

[afercia]

Replying to obenland:

We should think about making the property private

Need to access this property from the List Table class. Trying to implement your other suggestion, thanks.

[afercia]

Maybe a public render method?

[afercia]

Refreshed patch, introduces:

$_screen_reader_content
get_screen_reader_content()
get_screen_reader_text()
set_screen_reader_content()
remove_screen_reader_content()
render_screen_reader_content()

Tried to do my best, needs review and help for documentation :)

[joedolson]

Patch still applies after latest changes to List Tables, (see r32721 and following, r32736 and following, r32752 and following.)

[afercia]

Refreshed patch after recent taxonomy labels changes, see 32933.

[obenland]

Let's take a fresh look at this in 4.4. It's a pretty important change.

[afercia]

Given the work we're doing on the admin headings in 4.4 this would be needed to properly adjust the headings hierarchy in some screens, see for example #33818. cc @wonderboymusic
The patch might need a refresh and for sure needs a lead review.

[afercia]

Refreshed patch after some classes and functions recently moved to their own files.

[afercia]

Assigning to @wonderboymusic for his kind review and feedback.

[wonderboymusic]

In 34891:

List Tables/WP_Screen: in WP_Screen, add methods to store, retrieve, and render screen reader text, primarily used by list table screens.

These additions are based on an audit and recommendations by the Accessibility team. #a11y'all

Props afercia.
Fixes #32147.

[SergeyBiryukov]

Post type label keys should be as close to the string as possible, see comment:20:ticket:12968.

In 32147.8.patch​:

• Rename views to filter_items_list.
• Rename pagination to items_list_navigation.
• Rename list to items_list.

[afercia]

Thanks @SergeyBiryukov :) Also, just noticed we missed to add @since in the DocBlock for the added labels. cc @DrewAPicture

[SergeyBiryukov]

In 35376:

After [34891], rename new post type and taxonomy label keys to match the default strings.

See #32147.

[SergeyBiryukov]

In 35377:

After [34891] and [35376], add new labels to changelog entries.

Props afercia.
Fixes #32147.

[johnbillion]

In 35869:

Correct the hash notation documentation introduced in [34891].

See #32147