Make WordPress Core

Opened 4 years ago

Last modified 20 months ago

#39441 new enhancement

Improve the Settings API for accessibility and ease of use. — at Initial Version

Reported by: flixos90 Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Plugins Keywords: settings-api has-patch 2nd-opinion
Focuses: accessibility, administration Cc:


Today a kickoff meeting for the Settings API took place on Slack (Archive: https://wordpress.slack.com/archives/accessibility/p1483376507000492) where we discussed ways to improve it, both in terms of accessibility and ease of use.

After a good discussion we came to the conclusion that we would like to focus on the existing Settings API for now and do what we can to improve it. The Fields API project will eventually make the process of registering settings and having them automatically rendered even easier and complete, but we should not wait until it is ready for a core-merge, as some issues in the existing Settings API should be solved sooner than later.

We figured out two main goals:

  • Add some basic support to automatically render fields so that plugin developers no longer need to write their own callback functions for basic fields.
  • Get rid of the table structure to improve accessibility. Furthermore the accessibility team should also ensure that the markup generated as the core field output is accessible.

For the technical improvements, we would like to do the following:

  • Adjust add_settings_field() to support a predefined set of identifiers for a field type instead of a callback function. In that case a default callback function that we would introduce in core would take care of rendering the field. The requirement to write custom callbacks for even the most basic fields is one major issue with the current Settings API and why most people rely on external libraries for that.
  • Enhance the $args parameter of add_settings_field(). It should become more significant and probably go through some validation, filling it with default values. This is especially important for the new default callbacks.
  • Possibly support providing one $args array as sole parameter to add_settings_field() that contains the other parameters as well. This would of course need to work in a backward-compatible way.

For the accessibility part, we would like to do the following:

  • Scaffold an HTML prototype for what a settings page should look like. This will give a good overview of the accessibility approach we should take without having to deal with the PHP implementation.
  • Get rid of the current table structure. Whatever the above prototype looks like, it will not have tables anymore. We can generally remove the table structure and change it to something else easily, since all the table output is generated by core (in particular by do_settings_sections() and do_settings_fields()). For everyone who uses the API as recommended, this will not bring any BC issues unless they are using specific table-related selectors (like td) in CSS or JS code. It is unclear whether these should be considered edge-cases and whether a dev-note reflecting the changes is sufficient, or whether we should only support the new markup through an additional parameter which would default to the current table way. The latter is backward-compatible, but on the other hand it would decrease the amount of sites that become more accessible out-of-the-box.
  • Do not deal with people who completely write the table markup manually. We simply cannot do this, other than recommending them to switch to using the Settings API or at least changing their markup. The only thing to keep in mind here is that we should never remove any CSS related to these tables, in order to keep their code working.

All of these enhancements would also benefit #38374 as it would become a lot easier to change core's own settings pages to actually use the Settings API.

We will from now on have meetings on Slack to continue discussion in detail every 2 weeks on Monday at 17:00 UTC. However, general opinions and discussion can and should also be placed in this ticket.

Change History (1)

4 years ago

Note: See TracTickets for help on using tickets.