[wp-trac] [WordPress Trac] #39441: Improve the Settings API for accessibility and ease of use.

[WordPress Trac]

#39441: Improve the Settings API for accessibility and ease of use.
-------------------------------------+-------------------------------------
 Reporter:  flixos90                 |       Owner:
     Type:  enhancement              |      Status:  new
 Priority:  normal                   |   Milestone:  Future Release
Component:  Plugins                  |     Version:
 Severity:  normal                   |  Resolution:
 Keywords:  settings-api has-patch   |     Focuses:  accessibility,
  2nd-opinion                        |  administration
-------------------------------------+-------------------------------------

Old description:

> 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.

New description:

 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.

--

Comment (by flixos90):

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

--
Ticket URL: <https://core.trac.wordpress.org/ticket/39441#comment:3>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform