wpaccessibility / settings-api-enhanced Goto Github PK

We should avoid to print out too many <div> elements.

See in the screenshot below what, at the moment, the API outputs for a section with two fields:

As I see it, there's no need for both the settings-fields and the settings-field divs. The real need is to distinguish fields that are within a section from the other ones, in order to style them properly. The settings-section already gives us what we need.

Unless I'm missing something, the inner divs could be safely removed.

I'm also concerned about the settings-field-control span element, used as a wrapper for the actual output from the field callback. Styling should be applied directly on the fields. I'm not really sure we need this additional <span>.

Note: when form controls are logically related and can be grouped under a "question" that relates to them all, the wrapper element should be a <fieldset> element with a <legend>. This is 99% true in the case of a group of radio buttons and should be evaluated on a case by case basis for other groups.

As discussed in today's meeting (see https://wordpress.slack.com/archives/C02RQBWTW/p1496073615671126), let's remove the unnecessary .settings-field-control element. That class should instead be used on the field element/s itself.

Note that this class name will definitely not be the name that we'll eventually use, but the name change is part of another discussion.

The Site Language select should be moved after "Week Starts On" for parity with the current WP page. See also what is already done in #16

For better readability, design consistency, and typography, any field in the Settings pages uses some bold text before the field. This also helps while visually scanning the page.

Text fields, textareas, selects, etc. can use their associated label as "bold text" before the fields.

Radio buttons are always more than 1 and when grouped in a <fieldset> element, they can use the fieldset <legend> element as "bold text". Same goes for checkboxes when more than one.

Single checkboxes instead don't have any semantic element that can be used as a "bold text" before the checkbox. Their associated label is on the right and must stay on the right.

We should explore what the best option is. Is it acceptable to print out some text that is used just for visual purposes (hidden from assistive technologies with aria-hidden="true")? Would that be easy to understand for people going to use the Settings API? Would it be abused?

Screnshot to illustrate the issue:

Worth nothing in this specific case the checkbox and the "New User Default Role" select are actually logically related, thus they should be within a <fieldset> so the text "Membership" (maybe consider a better wording? ) could be a <legend>. There are other cases where this is not the case though, and the issue stands.

Worth also considering that the "Anyone can register" checkbox and the "New User Default Role" select aren't so strictly related to "General settings" and probably should go in a "Membership settings" section/page. This wouldn't solve the issue of the "bold text" though.

Personally, I think single checkboxes are always a bit tricky and maybe worth exploring if this kind of setting can use a different control. Comparing with the multisite settings, there are 4 registration options, where one of them is "Registration is disabled".

So there's some inconsistency with the registration setting on a single site installation. For analogy then, maybe single site should use two radio buttons?

• Registration is disabled
• Anyone can register

I think it would be good to bold all labels. For example this is what it would look like:

My thinking it this visually helps distinction. Note, the screenshot includes the font increase I am suggesting too.

If I'm not wrong, the skip_title and skip_title_screen_reader arguments are not documented.

The field description output does basically always the same thing and could be abstracted in a method. If I'm not wrong, it currently does a slightly different thing only in the case of render_settings_field_radio() and render_settings_field_multibox().

At the moment this project provides standard callbacks to output the following field types (@flixos90 please correct me if I'm wrong):

case 'text':
case 'email':
case 'url':
case 'tel':
case 'number':
case 'textarea':
case 'checkbox':
case 'select':
case 'radio':
case 'multibox': <-- multiple checkboxes

Should we add or remove support for some fields? About the number field, @rianrietveld ran some tests and it turned out it's poorly supported by assistive technologies. I think also browsers support is pretty inconsistent. I think it's worth some discussion 🙂

Margin/padding should be figured out:

• between fields within a section
• between sections

Furthermore font-size should be figured out:

• for titles (may be a <label>, <legend> or <span>)
• for fields (need to consider text inputs, textareas, dropdowns, radios, checkboxes etc.)
• for descriptions

@afercia and I have a different opinion, so let's further discuss this over time, hopefully with more input soon.

@afercia says that the .settings-fields div should be removed to prevent divitis, but I think it's necessary to be able to provide more precise styling. See #32 for more background.

In General Settings, Date Format and Time Format have a "Custom" radio button followed by a text field to enter a custom format. When using a keyboard or screen reader, when the text input field gets focused the related radio button gets selected.

Tabbing is the only way keyboard users and screen reader users have to navigate through a form, so they will very likely focus the text field but that doesn't mean they want to enter a custom format. They're just navigating the form.

To reproduce the worst scenario:

• use the keyboard to navigate
• once focus is on the first radio button in the group, use arrows to select your favorite format (not custom)
• now to exit the radio buttons group the only way is to tab again
• the text field gets focused and the radio button you previously selected isn't' selected any more
• keyboard users don't have a way to avoid this
• screen reader users, additionally, won't be even informed the selected radio button has changed

Worth considering to fix this in core whether or not the Settings Api Enhanced will get merged.

As discussed on Slack, see https://wordpress.slack.com/archives/C02RQBWTW/p1491840082372116 we should try to establish good CSS naming conventions. Also worth considering the CSS classes used for the fields can be re-used in other contexts, for example in the future Fields API and in any other part of the admin.

Some points emerged during the discussion:

• the general issues is trying to establish easy and maintainable patterns, taking into considerations the CSS Roadmap https://make.wordpress.org/core/2014/12/19/core-css-roadmap/.
• keep selectors specificity as low as possible, avoid overqualified selectors
• Helen Hou-Sandí suggested selectors should also provide a context:
  • "In an ideal world, you would have some baseline stuff for elements themselves, and then you scope upward to apply specific stuff based on context as needed".
  • "The goal should be for people (devs) to not have to do anything involving class names or CSS the vast majority of the time."
• Helen Hou-Sandí will try to start a doc to dump thoughts on the best option we have for CSS naming
• CSS classes to target stuff in JS: they should be separate from classes used for styling
• CSS classes for state naming for JS (e.g. .is-active or .is-dismissible)

Minor but worth considering. In the current implementation, a couple of times there's a check for is_callable() / is_string(). This could be re-used more and more in the future, and could maybe be abstracted in a utility method.

There are cases where it would be worth grouping multiple fields within a fieldset element with a legend. Should add_settings_section() optionally output a fieldset with legend?

Initially mentioned by @joehoyle in https://make.wordpress.org/core/2017/05/22/enhanced-settings-api-where-were-at/#comment-32484:

Settings can be registered for the REST API with information on their data type. For those fields where that data is available, we could use it to use sane defaults, for example use field type number if the field is registered as integer/float/number.

Worth noting that we'll still need add_settings_field() because register_setting() deals with the data itself, not the UI. Furthermore in the Settings API we'll often use data stored in serialized arrays (thanks WordPress), which can't be handled easily in the REST API at the moment. But it could indeed help with defaults.

Leftover 😬
require_once( ABSPATH . 'wp-admin/includes/translation-install.php' );
in
wp-admin/options-media.php

As discussed in today's meeting (see https://wordpress.slack.com/archives/C02RQBWTW/p1496073615671126), let's remove the wrap element since it's unnecessary.

render_settings_field_multibox() perfectly works for a group of checkboxes sharing the same name attribute. That is, a multi-choice where users can check multiple values for the same group.

This works in HTML but it's arguable useful for settings since there's rarely (never?) a setting with multiple values.

Instead, the current group of checkboxes in core are all single settings with a unique name attribute. They're visually grouped because logically related. However, the don't use the same setting name.

How to render a group like the following one?

The only way right now would be a custom callback 😞

I'm really digging the new way to present the information on the Settings pages, but visually I got a bit of a cluttered, disjointed feeling from glancing over the page. It's hard to describe, but it felt like it was hard to grasp what belonged together, a sort of mental noise. So I tweaked some CSS to see if I could get rid of that feeling. Tell me what you think:

• I simplified the padding on settings-field-title to 5px 0 (from 5px 10px 10px 0) to pull the fields and their titles closer together
• I moved the descriptions above the input fields. This makes more sense to me, reading the instruction before you fill something in. It also makes the inputs feel more like 'blocks', which helps with scanning and reduces the mental noise between fields.
• One other thing I struggled with is the white space between sections. It didn't so much separate sections as made it feel like the spacing was inconsistent, particularly also because it was used within sections (site title, tagline, then whitespace, wordpress address, site address, whitespace etc). So as an experiment I put a border between the sections, and for me that really helps. (It's border-top: 1px solid #cccccc; with margin-bottom reduced to 30px)

Noticed just know 😞 the custom structure field has the same keyboard trap that was in the General settings date/time custom format. Fixed in core in https://core.trac.wordpress.org/ticket/40515 and in this plugin in #26

For core, will open a Trac ticket.

Apart from following the WordPress CSS coding standards, the CSS should also use some best practices. The first one that come into my mind (but there are a lot) are, for example:

1
Don't use element selectors if not strictly necessary. Things like
.settings-fields p.timezone-info
could be simply
.settings-fields .timezone-info

2
Don't use element selectors and also lower specificity as much as possible. Selectors like
.settings-fields .settings-field-control p
should be just
.settings-fields .description

More example welcome.

Splitting this out from #6

See also discussion on Slack during Settings API meeting:
https://wordpress.slack.com/archives/C02RQBWTW/p1493049728130607

The main goal should be establishing a solid convention for naming CSS classes or ID attributes meant to be exclusively used for JS targeting. Quoting from Helen's doc"

Reusing styling class names is fragile and obscures intent when doing long-term maintenance.

As previously discussed in #38, we need to figure out a good way to handle radio groups with a custom text element.

There are currently three cases in core settings:

• General > Date Format
• General > Time Format
• Permalinks > Permalink Structure

What makes this even more complex is that all three fields contain an additional component: some kind of example (date format / time format / URL structure respectively). In the case of the Permalink Structure field, the example is even combined with the text field.

Let's think about how we can create clean markup for these fields which is accessible and at the same time visually clear.

Currently, the General Settings screen only uses sections for their visual padding.

I think it would be useful to add headings to at least a few of them. In particular, I'm thinking about making the "Membership" text for the "Anyone can register" checkbox its own section heading, which would then contain that checkbox plus new user default role dropdown. This would furthermore fix #5 for this specific field.

Since all the following fields belong together as they deal with the locale (so completely unrelated to "Membership"), the section needs an actual heading as well (probably "Locale").