Devtantra Blog

Tutorials about Android, Angular, ReactJS, PHP, MySQL and Web Development

Improvements to the Customize JS API in 4.9

A Customizer is the one of the greatest feature of WordPress. Not only it is simple to handle WordPress site but also it resolved many pointer for developers. But in previous versions developer faced many issue. which are improved in 4.9, including: drafting/scheduling of changesets, autosave revisions, changeset post locking, frontend public previews, a new experience for browsing and installing themes, updated nav menu creation UX, and the code editing improvements for the Custom HTML widget and Additional CSS. But in addition to all of these, there are also many improvements for developers which will make extending the Customizer much more pleasant.

Something important to remember about the Customizer is that it is a single page application that is powered by JavaScript. Many developers may only interact with the PHP API for registering controls, settings, sections, panels, and partials. But controls, sections, and panels do not need to be registered in PHP at all. The PHP API for registration is essentially a wrapper for the underlying JS API. When you load the Customizer all of the params for the PHP-registered constructs are exported to the client for the JavaScript API to instantiate and initially add to the UI, but this JS API can dynamically instantiate additional constructs at any time thereafter in a Customizer session. This is how new widgets, nav menus, and nav menu items are added without requiring the entire Customizer to reload. You can also avoid statically registering settings and partials in PHP by instead adding filters to dynamically recognize settings and partials, allowing them to be registered on demand. All of this allows the Customizer application to scale out to be able to customize and preview an unlimited number of things on a site (e.g. any post or page with their postmeta in the Customize Posts feature plugin). The point here is that in order for the Customizer to scale, the JavaScript API must be used directly. So this is why the Customizer JS API improvements in 4.9 are important as they fix many longstanding annoyances and shortcomings with the JS API.

This dev note contains the following sections:

From above mentioned pointers I like Control Templates feature. Let’s us what new happened in it..

Control Templates

Refer back to the “Pane Width” example above where a type of number was supplied when constructing a base wp.customize.Control class. This would not work prior to 4.9 because there were no content templates defined for base control types. This is no longer the case with the resolution of #30738. If you construct a control and supply a type param that corresponds to an HTML5 input type, then the default control template will be used to render the control. Note that for color inputs, one should use the dedicated ColorControl.

A control’s template is normally derived by its type; for instance, a Background Position control has a type of background_position and then has a wp.template ID of customize-control-background_position-content. The template is normally output by a control’s WP_Customize_Control::content_template() template after the control has been registered via WP_Customize_Manager::register_control_type(). In 4.9 however, this can all be bypassed as controls now understand a templateId param.

An example of supplying an ad hoc templateId when constructing a control can be seen in the changeset status control, where it overrides the template used for this one radio control instance:

var statusControl = new api.Control( 'changeset_status', {
    priority: 10,
    type: 'radio',
    section: 'publish_settings',
    setting: api.state( 'selectedChangesetStatus' ),
    templateId: 'customize-selected-changeset-status-control',
    label: api.l10n.action,
    choices: api.settings.changeset.statusChoices
} );
api.control.add( statusControl );

Alternatively, if you have a custom control that you always want to have a specific template (as when calling WP_Customize_Manager::register_control_type() in PHP), you can now do this entirely in JS by adding templateId to the control subclass’s defaults, as can be seen in the PreviewLinkControl:

var PreviewLinkControl = api.Control.extend({
   defaults: _.extend(
         templateId: 'customize-preview-link-control'
   /* ... */

For some more examples, see answer on the WordPress Development Stack Exchange.

Speaking of WP_Customize_Manager::register_control_type(), the types for panels, sections, and controls now are all registered before the customize_register action is triggered. This means that if you have a plugin that unregisters all customize_register actions in order to create a “blank slate” plugin-specific Customizer, you no longer have to re-register these types to be able to use them.


Leave a Reply

%d bloggers like this: