JS content templates for base WP_Customize_Control

[celloexpressions]

This will make it possible to create all of the base Customizer control types directly in JS, and will allow them to share a single template passed from the server on Customizer init for all controls with the basic types (following up on #28709).

I think we may need to explore adjusting how register_content_type works since this control handles multiple types and all fallback types. But more likely we'll just do something a bit different, probably adding fallback handling on the other side and hard-coding these types into the Customizer Manager somewhere.

Follow-up to #29572. Related to several tickets I'm currently creating.

[celloexpressions]

Basically need to convert WP_Customize_Control::render_content() into a JS/Underscore template, then hook up the necessary pieces to address this control applying to multiple types.

[celloexpressions]

Mostly complete but needs debugging.

[celloexpressions]

@westonruter 30738.wip-2.diff​ should be most of what we need but there's a syntax error in the big template, and I'm not finding it, do you see it? I think it should be a quick fix and that this should be a relatively easy/painless improvement, but we'll have to see how it goes.

[celloexpressions]

Patch is not yet functional - we need someone to pick this up or we're going to have to punt probably.

Note that Menus in the Customizer are currently using several custom controls that really shouldn't be custom controls to step around this and use a common setting, which I believe the settings control param can handle.

[obenland]

Replying to celloexpressions:

Patch is not yet functional - we need someone to pick this up or we're going to have to punt probably.

Yes, unless you and @westonruter find time to make a decision on it this weekend, this is probably going to get punted.

[celloexpressions]

This should definitely happen, but no longer a priority for 4.3. Need a functional patch first.

[westonruter]

There is a partial implementation of this in the ​Customize Posts plugin (see also #37275):

​https://github.com/xwp/wp-customize-posts/blob/develop/php/class-wp-customize-dynamic-control.php
​https://github.com/xwp/wp-customize-posts/blob/develop/js/customize-dynamic-control.js

Something implemented here, which I think has been discussed previously, is that the label element doesn't wrap the title and description anymore (for non-checkboxes at least), by introducing a random id for the input to be used with the label[for] attribute. This is turning out to be important now with the introduction of the new notifications in 4.6 which have a container that gets injected right after the site title. This means that if there is a button inside of a notification, it won't work as expected because it is wrapped in a label. Also related here is that notifications should support a template allowing them to allow arbitrary markup as opposed to an escaped message. This was noted by @celloexpressions in ​https://wordpress.slack.com/archives/core-customize/p1469851496000101

[westonruter]

This might go in another ticket, but we also should allow for a content_template param to be passed in when instantiating a widget in JS. When this is supplied, it should use that template instead of the template selected via the type param as output from the PHP WP_Customize_Control::content_template() method. This would allow for custom control templates to be easily used without having to define an entirely new WP_Customize_Control or hack around with the type parameter to get it to use something else.

[westonruter]

Here's an implementation of content_template param which can be incorporated into Control#renderContent(): ​https://github.com/xwp/wp-customize-posts/pull/225/commits/495b1fcb0c2286305b9e38f3c868f6ae3e970c83

[westonruter]

Adding to 4.7 due to the existing code in Customize Posts which can be lifted.

[jorbin]

Removing from the 4.7 milestone due to lack of traction.

[westonruter]

The dropdown-pages control type actually _should_ be included among the types that have content template, and the list of pages that appears in the select field should be fetched via the REST API and populate it dynamically. See also #39908.

[afercia]

Couple of considerations:

Labels
As per ​the Accessibility coding standards, all new code must use an explicitly associated label, that is the ones that don't wrap the associated element and use for/id attributes.

get_input_attrs()
It would be great to make this a general utility to be re-used in other places too, with an option to get or echo or two separate functions for that. See for example something very similar planned to be used for the Settings API revamping ongoing effort on GitHub: ​https://github.com/wpaccessibility/settings-api-enhanced/blob/50a91ffba9ef857f9b40010b1d8b3684ef645ae4/wp-admin/includes/template.php#L635

/cc @flixos90

[jbpaul17]

Punting to 4.8.1 per today's bug scrub.

[westonruter]

Just realized that the default param from WP_Customize_Setting is not getting exported from PHP to JS. Sometimes, as in the case of the color control, the default value from the setting is needed by the control. The color control currently copies the setting's default value into the control when the control is exported to the client, but this isn't going to facilitate controls that are added dynamically on the client. So I think something like export-setting-defaults.diff​ should also be done.

[celloexpressions]

I have no objections to export-setting-defaults.diff​ as a first step toward making this happen.

Also, +1 to including the dropdown-pages control and making use of the Rest API there, although perhaps the options should be included with the control params?

[westonruter]

​https://github.com/xwp/wordpress-develop/pull/261

[westonruter]

I refreshed the patches into 30738.2.diff​ with PR for review and amending: ​https://github.com/xwp/wordpress-develop/pull/261

[westonruter]

Header image control is currently broken (at least).

Also should incorporate the label fixes from #33085.

[westonruter]

Use settingless-control for display_header_text to avoid element unsyncing ​https://github.com/xwp/wordpress-develop/pull/261/commits/09e8afd

[westonruter]

Bumping priority to high for visibility and alignment with 4.9 goals, and given proximity to beta 1 deadline.

[westonruter]

For the approach on how we should handle input_attrs we should output just the raw key/value pairs and then loop over them in the template to output. This is what I just added in https://core.trac.wordpress.org/attachment/ticket/41872/41872.5.diff

[westonruter]

Two examples where this would be coming in handy:

• ​https://github.com/xwp/wordpress-develop/blob/346e07f0ae26bd8623cba9fe0d609c1205d55859/src/wp-admin/js/customize-controls.js#L6308-L6334
• ​https://github.com/xwp/wordpress-develop/blob/5a39ca3f5e6e58c797ac7f6d4957f3ec322604e0/src/wp-admin/js/customize-controls.js#L5251-L5261

The templateSelector, or rather templateId, or even template should be a parameter when constructing the control as was recently done for Notifications in r41374.

[westonruter]

In 41750:

Customize: Allow controls to be created with pre-instantiated Setting object(s), or even with plain Value object(s).

• Allow passing settings in keyed object (e.g. settings: { default: 'id' } ), or as an array (e.g. settings: [ 'id' ]) with first being default; again, Setting/Value` objects may be supplied instead of IDs.
• Allow a single setting to be supplied with just a single setting param, either a string or a Setting/Value object.
• Update changeset_status and scheduled_changeset_date to be added dynamically with JS and simply passing of api.state() instances as setting.
• Introduce a data-customize-setting-key-link attribute which, unlike data-customize-setting-link, allows passing the setting key (e.g. default) as opposed to the setting ID.
• Allow WP_Customize_Control::get_link() to return data-customize-setting-key-link when setting is not registered.
• Eliminate default_value from WP_Customize_Date_Time_Control since now comes from supplied Value.
• Export status choices as wp.customize.settings.changeset.statusChoices.
• Export date and time formats as wp.customize.settings.dateFormat and wp.customize.settings.timeFormat respectively.

Props westonruter, sayedwp.
See #39896, #30738, #30741, #42083.
Fixes #37964, #36167.

[westonruter]

In 41771:

Customize: Add default control template for standard input types.

Re-use default template instead of introducing custom one for the Discard Changes button.

See #30738.

[westonruter]

Here is a demo plugin showing how the new control default template can be used: ​https://gist.github.com/westonruter/fa261e53208a17a890960b015e5ad4bd

[westonruter]

In 41778:

Customize: Prevent color default control type from overriding template for ColorControl.

Amends [41771].
See #30738.

[westonruter]

In 41822:

Customize: Prevent outputting value attribute if already supplied among input_attrs.

This allows for input[type=button] controls to be added without producing illegal HTML.

Amends [41740].
See #30738, #33085.

[westonruter]

Another stab at this: ​https://github.com/xwp/wordpress-develop/pull/289

[westonruter]

In 41935:

Customize: Move control's fallback selection of default content template to renderContent method to align with sections and panels.

• Only use default control content template when a more specific template doesn't exist.
• Remove extraneous whitespace from being output in WP_Customize_Control::render() method.
• Move Custom Header template printing to customize_controls_print_footer_scripts action.

See #30738.

[westonruter]

We'll pick this up again in 5.0 via #42272. We'll leave server-registered base controls rendering their content on the server. For controls registered on the client, however, the new base JS templates can be freely used.

[westonruter]

In 41936:

Customize: Consistently use input_attrs as control param key in JS instead of inputAttrs.

See #30738, #41897.

[westonruter]

There is a problem with JS templates overriding any server-side content supplied for default types. The client-side template should only be used if the control's container is empty.

[westonruter]

In 41952:

Customize: Prevent using default template for a base control when it has content rendered on the server.

Also prevent invalid type attribute from being added to a select element.

See #30738.
Fixes #42286.

[celloexpressions]

Changes look good for 4.9. We should remove empty render_content() methods from other core controls as well as removing the base PHP templates in the future.

[westonruter]

In 42031:

Customize: Improve Media control accessibility and compatibility for settings passed as arrays or as solitary setting.

• Eliminate Media control template from having dependency on params.settings.default for element ID, to fix compat with params.settings array or single params.setting. See #36167.
• Move description out of label and add aria-describedby to Media control's Select button. See #30738, #33085.
• Obtain notification container whenever content is (re-)rendered (such as for Media control). See #38794.
• Re-render notifications after control content is re-rendered, if control is in expanded section. See #38794.

Amends [41390].
See #36167, #38794, #33085, #30738.

[westonruter]

Dev note: ​https://make.wordpress.org/core/2017/11/01/improvements-to-the-customize-js-api-in-4-9/