#a11y-headings - Adapt title in Settings API to new hierarchy

[neoxx]

Following ​https://make.wordpress.org/core/2015/10/28/headings-hierarchy-changes-in-the-admin-screens/ the title in do_settings_sections() should move up one level, too.

#a11y-headings

[afercia]

@neoxx good catch, thanks very much :) Wondering what to do here, in some cases should be a <h3>:

Without the "tabs", should be a <h2>. We've discussed a bit the "tabs", probably they shouldn't be within a heading in the first place and they're more a navigation sub-menu. I'd be inclined to keep things simple and just change the heading output by do_settings_sections() in a <h2>. As a side note, this is one of the reasons why I'm not so happy when core outputs some HTML assuming it's the proper markup in any case, without giving users the ability to filter it some way :)
Will ask the accessibility team for some feedback, the proposed patch looks the best option to me.

[joedolson]

I feel like we ought to treat this as if the tabs default markup was *not* a heading, and make plans to remove the heading wrapping the tabs in a future release. I don't feel that usage of a heading is at all appropriate, and it's something we should really fix; I'd rather accept the slightly incorrect headings hierarchy temporarily with the long-term goal of resolving if by fixing the tabs structure.

[afercia]

In 35459:

Accessibility: Bump the Settings API sections heading one level up.

Also, fix a typo in the do_settings_sections() DocBlock.

Props neoxx.
Fixes #34492.

[theZedt]

Is this absolutely necessary?

We are relying on the section titles being wrapped in h3 tags in our theme options and this change completely breaks 4 of our 5 themes settings pages which use accordions.
I don't think we'd be the only ones affected...

Adding a filter for the title would be a good workaround so we can change the wrapping ourselves in our usage scenario.

[afercia]

@theZedt hi, as far as I see this specific change doesn't touch anything related to accordions (meaning the built-in accordions provided by WordPress, see do_accordion_sections(), accordion.js ). Is yours a custom implementation?

[theZedt]

Our themes have their roots before Wordpress 3.6 introduced do_accordion_sections() so they still rely on the older do_settings_sections() with the JS accordion manually applied on top (onto the h3 tags outputted by that).

By the look of the codex entry for do_accordion_sections(), it wasn't too publicized or documented...

[afercia]

Replying to theZedt:

still rely on the older do_settings_sections() with the JS accordion manually applied on top (onto the h3 tags outputted by that).

Thanks for the details. So, since /wp-admin/js/accordion.js targets any element with a CSS class .accordion-section-title I'm assuming you're not using that but you're using a custom implementation that targets the h3. If so, you can simply update the jQuery selector. Core can't predict or guarantee support for custom implementations.