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 Version 3

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:

Description (last modified by flixos90)

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 #38734 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 (5)

4 years ago

#1 @flixos90
4 years ago

  • Keywords has-patch 2nd-opinion added; needs-patch removed

39441.diff is an initial take on the technical part of the improvements from the ticket description (except implementing the single array parameter support of add_settings_field()). What the patch does:

  • Support passing one out of a few predefined strings as the $callback parameter in add_settings_field(), which then refer to core callback functions (happens in do_settings_fields()): What these strings and core-supported field types are needs to be discussed, I just added a few very basic ones that I think we should support. Four of the five callbacks are actually not yet implemented and only exist for demonstration purposes.
  • Enhance the $args parameter in add_settings_field(). It now supports more arguments and does some sanitization by filling defaults in. The only complex new argument is probably the value_callback one: It will be used to fetch the current value for the field. It usually does not need to be used, as most developers are probably using a regular get_option() call here. The default value for this argument is a new function get_settings_field_option() which retrieves the option based on the field's input_name argument. The function also supports fetching option values for multidimensional names, similar how it happens currently in the Customizer.

I also created a small plugin settings-api-tests.php that can be used to test this functionality. Note that some fields there won't have any output yet, simply because I didn't implement their functions yet, as I mentioned above.

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

4 years ago

#3 @flixos90
4 years ago

  • Description modified (diff)

Cross-reference to the ticket was wrong in the description. It is supposed to be #38734.

4 years ago

Note: See TracTickets for help on using tickets.