WordPress.org

Make WordPress Core

Opened 3 years ago

Last modified 2 weeks ago

#30741 new enhancement

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

Reported by: celloexpressions Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version: 4.1
Component: Customize Keywords: needs-patch
Focuses: Cc:

Description

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.

Change History (29)

#1 @celloexpressions
3 years ago

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

#2 @celloexpressions
3 years ago

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.

#3 follow-up: @celloexpressions
3 years ago

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.

#4 in reply to: ↑ 3 @celloexpressions
3 years ago

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.

#5 @celloexpressions
3 years ago

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

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


3 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

This ticket was mentioned in Slack in #core by westonruter. View the logs.


2 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


2 years ago

#15 @celloexpressions
22 months ago

  • Priority changed from high to normal

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.

#16 follow-up: @celloexpressions
14 months ago

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.

This ticket was mentioned in Slack in #core-customize by celloexpressions. View the logs.


14 months ago

#18 in reply to: ↑ 16 @celloexpressions
14 months ago

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.

This ticket was mentioned in Slack in #themereview by celloexpressions. View the logs.


14 months ago

This ticket was mentioned in Slack in #core-customize by melchoyce. View the logs.


7 months ago

#21 @westonruter
7 months ago

  • Keywords close added

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.

#22 @celloexpressions
7 months ago

  • Keywords close removed
  • Milestone changed from Future Release to 4.8

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.

#23 @jbpaul17
5 months ago

  • Milestone changed from 4.8 to 4.8.1

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.

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


5 months ago

#25 @westonruter
4 months ago

  • Milestone changed from 4.8.1 to 4.9

#26 @westonruter
3 months ago

  • Milestone changed from 4.9 to Future Release

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.

#27 @westonruter
2 weeks ago

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.

#28 @westonruter
2 weeks ago

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.

#29 @westonruter
2 weeks ago

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.

Note: See TracTickets for help on using tickets.