Build-out API for adding Customizer Panels, Sections, and Controls entirely with JS

[celloexpressions]

Status as of 4.1: we have "add" methods in JS, but they're currently incomplete. This was by design - we wanted to get the object relationships fleshed out in JS first, then do another pass to connect all of the pieces for dynamically-adding controls 100%. Essentially, this is about linking #28709 and #29572 together and also expanding them to cover object containers, rather than just their contents.

This is somewhat a container ticket for tracking #30737, as well as #30738 and #30740. The specific thing I want to use this ticket for is to add functions for rendering control containers, and to make sure we aren't missing any pieces to make this a seamless experience for developers.

I'm starting by building out workarounds in the Menu Customizer plugin - ideally all of these changes get leveraged there, and that makes its way into core in the near future as well.

[celloexpressions]

Looks like we don't have a clean way to remove panels/sections/controls either. I'd like to see a way to remove a section that automatically did all of the controls in it too, for example (sample use case: deleting a menu).

[celloexpressions]

Proposed API structure in PHP for dealing with rendering the content & container for each object type:

• render() -> render_template()
• [render_]container[_template]() would NOT be needed - render_template() would do the container and call content_template() like render() calls render_content()
• render_content() -> content_template()
• print_template() to print the templates in <script> tags

Patches on #30737 will be made with this in mind. Note that sections don't have a separate content part; but panels and controls do.

[celloexpressions]

General note: we need to ensure that check_capabilities() is still addressed when everything is fully added via JS. Probably a matter of only passing their JSON data when check capabilities is true, rather than rendering or passing the content JSON when it's true.

[celloexpressions]

Replying to celloexpressions:

General note: we need to ensure that check_capabilities() is still addressed when everything is fully added via JS. Probably a matter of only passing their JSON data when check capabilities is true, rather than rendering or passing the content JSON when it's true.

Was briefly concerned that we have major problems here in 4.1, but because there is no API for rendering an entire control from JS yet, maybe_render() is still called for controls whose content is rendered from JS templates, meaning that the controls are not accessible if the capabilities aren't met. Moving forward, we need to wrap all objects' json() methods with capability checks, and that probably should have been done originally too.

[celloexpressions]

#30737 and #30738 are both dependencies for this ticket. #30737 now has a patch, working on #30738 later today.

[celloexpressions]

This (obviously) no longer blocks menus in the Customizer. It remains a gap in the API, especially in the context of dynamically created Customizer UI. We should revisit when we're ready to do another round of developer-focused API improvements, likely not for 4.5 right now.

[celloexpressions]

Currently, to remove a control you need to do both control.container.remove(); and api.control.remove( control.id );. We should create a shortcut where control.remove(); self-destructs. Panels and sections should have similar approaches that also delete children, and we also need to revisit adding controls in JS here.

[celloexpressions]

Replying to celloexpressions:

Currently, to remove a control you need to do both control.container.remove(); and api.control.remove( control.id );. We should create a shortcut where control.remove(); self-destructs. Panels and sections should have similar approaches that also delete children, and we also need to revisit adding controls in JS here.

See #31334 for that piece.

[westonruter]

I think this can be closed now that most of the linked tickets are closed and or already exist separately, so I don't think we need a tracking ticket anymore.

[celloexpressions]

The other tickets were prerequisites, but there remain gaps in the API here.

It's been quite a while since this was looked at holistically, so I think the next step is to identify where there are specific holes in the API. It should be possible to create all four object types (and maybe also partials eventually?) directly in JS by associating with a particular object type as registered and defined in PHP. 2 theoretically outlines how the PHP corresponds to this, but we need to make sure the object container and content representations make sense and align with how JS-side addition works.

The specific thing I want to use this ticket for is to add functions for rendering control containers, and to make sure we aren't missing any pieces to make this a seamless experience for developers.

I think this still applies here - workarounds are typically required to add controls, where the API should make it a more seamless process. We also need to better align the container/content concepts in panels and controls, and decide whether this should also exist for sections.

Once the current state of the API is evaluated (ideally by someone who doesn't work with it regularly and isn't familiar with workarounds where things are possible but not as easy as they should be), we can decide what the specific path forward is for improving and finalizing this part of the API.

I'm moving this to 4.8 as it's important to finalize this API as we move toward instantiating the customizer dynamically with JS on the frontend - this API will be used for all controls and the roles of the PHP and JS side APIs in this process needs to be refined.

[jbpaul17]

With no patch and with 4.8 beta 1 on Friday, I'm going to punt this. If a patch lands and testing passes soon, then we can look to pull this back into 4.8.

[westonruter]

Similarly as noted in #30277, I think this makes the most sense to be done as part of a Customizer rewrite, perhaps in a feature plugin powered by the new ​endpoints and making use of React or Vue to power the UI, while naturally maintaining the same Customize JS API.

[westonruter]

In 41726:

Customize: Improve usability of Customize JS API.

• Eliminate need to pass both ID and instance in calls to Values#add() for panels, sections, controls, settings, partials, and notifications.
• Eliminate need to supply content param when constructing a Control.
• Unwrap the options.params object passed in constructors to just pass a flat options. (Back-compat is maintained.)
• Add support for templateId param for Control to override which template is used for the content.
• Remove unused previewer being supplied in Control instances.
• Rename classes to containerClasses on Notification.
• Automatically supply instanceNumber to improve stable sorting.
• Use api.Notifications for notifications in settings instead of api.Value.

See #30741.
Fixes #42083.

[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 41768:

Customize: Improve the menu creation flow.

Often, folks run into two issues when they create new menus: they click "Add a Menu" thinking it will add a new page to their menu, or they forget to assign their new menu to a location, and then wonder why it doesn't show up on their site.

This commit rearranges the order of items in the menu panel, and updates the flow for creating a menu by breaking it up into steps. Additionally, more help text has been added to guide people through the process of creating a menu.

Also adds default type lookups for Panel and Section instances. See #30741.

Props bpayton, obenland, westonruter, celloexpessions, afercia, melchoyce, zoonini, michelleweber.
Fixes #40104.

[westonruter]

In 41961:

Customize: Improve back-compat for wp.customize.Control subclasses that expect options.params to be present for direct manipulation before calling parent initialize method.

Fixes known incompatibility with Make theme.

Amends [41726].
See #30741.

[celloexpressions]

Closing based on 26. As Weston notes and as evidenced by the commits referencing this ticket, there is now parity between the PHP and JS APIs for most actions. The remaining tasks are addressed in standalone tickets. Further API improvements and a holistic assessment can come with a future rewrite.