Using JavaScript on your theme customization screen

In my recent posts I’ve discussed how you can approach offering theme customization options using PHP – in this and my next few articles I’ll be looking at what we can achieve on the user end of things (that is, the browser) via JavaScript.

Introduction

The JavaScript API is being constantly expanded, including in regards to how one might apply it to a theme customization screen – the last major change introduced in WordPress 4.1 was templates for controls created using the Underscore.js library. In short, some controls are now generated on the basis of a template for the JavaScript language – with this it’s possible to, for example, regenerate the control’s code on the fly, taking into account changes in the value of its options. Before we get to such sophisticated issues, we’ll first need to understand the basics of the API. Let’s look at what each API method is meant to do, along with practical examples of its use on the theme customization screen.

Basics

All collections and API methods of the theme customization screen are included in the wp.customize object. Many developers add a api variable at the beginning to shorten the code:

var api = wp.customize;

If we refer to API from a level of a frame that displays the preview of the theme, we should refer to the parent.wp.customize object.

We may add the code via the customize_preview_init action or customize_controls_enqueue_scripts.

The available controls are contained in the wp.customize.control object, whereas the available settings are contained in the wp.customize object. Sections may be found in the strong>wp.customize.section, and panels in wp.customize.panel. Each of the elements of these objects is an instance of the Values class, which includes several useful methods, such as:

• add(id, value) – adds the object from the set with a specific identifier and value
• each(callback, context) – iterates through all elements of the set performing the desired function
• has(id) – checks whether there is an element from the set with a particular ID
• instance(id) – returns an element from the set with the specified ID (but it’s enough to simply call the set as a method to get the same effect: wp.customize.control(id))
• remove(id) – removes an element with the specified ID from the set

Modifying elements

Elements of the theme customization screen may be modified in many ways- here’s some of the most useful methods:

• expand() – expands panel/section
• collapse() – collapses panel/section
• toggle() – allows the activee status of the item to be changed
• activate() – activates an item
• deactivate() – deactivates an item
• focus() – scroll to the side panel of the item
• priority() – downloads/rearranges the items
• active() – returns the activity status of the item
• panel() – returns the name of the panel to which the item belongs
• section() – returns the name of the section to which the item belongs
• renderContent() – generates the new HTML structure element (if the element is generated using themes in JS – for now they are just more complex control of file, color, and other user controls selection)
• ready() – displays the rendered element (we should use it after renderContent).

Additionally, elements in the params firled stores the settings such as label or description:

• params.label
• params.description

Another notable field element is container – it includes a handle to an element that stores the control/panel/section. This allows us to modify the elements that we can’t usually modify by changing the parameters and calling the renderContent method.

Preview actions

Through the wp.customize.previewer object we may call actions such as:

• refresh preview – method refresh(),
• save settings – method save()

Some simple examples

Opening the “colors” section:

wp.customize.section("colors").expand();

Changing the order of the elements:

wp.customize.control("blogname").priority(100);

Transfer control to another section:

wp.customize.control("blogname").section("colors");

Change the name of the control and refresh its structure based on the template:

var ctrl = wp.customize.control("background_color");
ctrl.params.label = "New label";
ctrl.renderContent();
ctrl.ready();

Summary

The current API in JavaScript for the theme customization screen offers some really amazing opportunities that can be used to significantly enrich the theme configuration options.