[wp-trac] [WordPress Trac] #29572: Customizer: add a framework for rendering controls from JS templates

[WordPress Trac]

#29572: Customizer: add a framework for rendering controls from JS templates
------------------------------+-------------------------
 Reporter:  celloexpressions  |       Owner:
     Type:  feature request   |      Status:  new
 Priority:  normal            |   Milestone:  4.1
Component:  Customize         |     Version:  3.4
 Severity:  normal            |  Resolution:
 Keywords:  has-patch         |     Focuses:  javascript
------------------------------+-------------------------
Changes (by celloexpressions):

 * keywords:  needs-patch => has-patch
 * milestone:  Future Release => 4.1


Comment:

 Took a first stab at this, and it's easier than I expected.

 [attachment:29572.diff] implements a framework for rendering controls from
 JS/Underscore templates instead of from PHP. With multiple controls of the
 same type, this allows us to only send down the html once, in template
 form, and the data for each control, most of which was already passed as
 json. It also utilizes the framework in the core
 `WP_Customize_Color_Control`. As we re-think the upload and image controls
 in 4.1, those would also be good candidates for leveraging this.

 In terms of developers leveraging this API, writing JS templates like this
 is extremely similar to writing PHP for displaying controls. Devs don't
 ''need'' to do any JS beyond the template, which is added in PHP anyway.
 Here's what it looks like to implement this in an existing custom control
 class:
 1. Make your `render_content()` function empty (but it does need to exist
 to override the default one).
 2. Create a new function, `content_template()`, and put the old contents
 of `render_contents()` there.
 3. Add any custom class variables that are needed for the control to the
 data passed to json by modifying the `to_json()` function (see
 `WP_Customize_Color_Control` for an example).
 4. Convert the PHP from `render_content()` into a JS template, using `<#
 #>` around JS statements to evaluate and `{{ }}` around variables to
 print. PHP class variables are available in the data object; for example,
 the label can be printed with `{{ data.label }}`.
 5. '''Register the custom control class/type'''. This critical step tells
 the Customizer to print the template for this control. This is distinct
 from just printing templates for all controls that were added because the
 ideas are that many instances of this control type could be rendered from
 one template, and that any registered control types would be available for
 dynamic control-creation in the future. just do something like
 `$wp_customize->register_control_type( 'WP_Customize_Color_Control' );`.

 Ideally, with the control improvements in 4.0, custom controls should only
 be necessary when they need to do something with JS. Therefore, I'm okay
 with effectively removing the core examples of overriding the
 `render_content()` function by moving that logic to JS templates.

 @westonruter: any thoughts on how/whether widgets could leverage this? I'm
 not sure that it would be as useful there given the need to get the widget
 form from PHP. Menus, on the other hand, would benefit hugely from this.
 I'll look at leveraging that in the plugin once this lands in core.

 Note: framework for dynamically-creating controls via JS is not in the
 scope of this ticket (as it also requires information about associated
 sections/panels, priority, etc., which depends on the creation of those
 models). However, the code should be structured in a way that lends itself
 to the future build-out of a formalized framework for that. Notably this
 means naming things so that we can add `render_container`-type actions,
 which would probably be a function in the JS model that custom controls
 would only override in JS.

 This should give us potentially huge performance improvements when dealing
 with things like menus, since we only need to send the html structure down
 from the server once, and can reduce individual controls to their data (in
 json format). That will also facilitate lazy-loading controls based on
 user navigation.

 Related: #28709, #28580.

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