Customizer JavaScript APIs: Panel, Section, and Control

Today, we will resume our discussion on the JavaScript API in the WordPress Customizer. In the last tutorial, we prepared and loaded two JavaScript files, customizer-control.js and customizer-preview.js, that will allow us to interact with the JavaScript API from the Customizer back-end and the front-end or the Previewer interface. So be sure to follow the last tutorial before proceeding further.

In this tutorial, we will be focusing on the interface composing the Customizer back-end, Panels, Settings, and Controls. Again, if these three things are something new to you, I highly recommend that you follow our previous complete series: A Guide to the WordPress Theme Customizer.

Basic Interaction With the Customizer JavaScript API

Aside from the PHP API, with which I'm sure some of you are familiar, Panels, Sections, and Controls are also accessible through the JavaScript API. Likewise, we can then modify them. Here are some examples.

Select a particular control, section, or panel:

Reorganize their view order.

Move the "Site Title" control to, for example, the color section.

Toggle its visibility.

You can even parse the control DOM tree, which is one thing that would otherwise be convoluted to do in PHP.

These are a handful of things you can do with the Panels, Sections, and Controls in the Customizer JavaScript API. Let's now put these together into a more meaningful user experience.

Toggling Sections and Controls

At this point, we should have four controls in total. Two controls, the "Site Title" input and the "Display Site Title" checkbox, are in the "Site Identity" section. The other two are a color picker. They reside in the "Colors" section, and will set the "Site Title" text color and its hover state color respectively.

Input Checkbox and Color picker in the Customizer pane
Our four controls in the Customizer

Our plan herein is to display the Color controls only when the "Display Site Title" checkbox is checked since there is no reason to show these Site Title color controls when the Site Title is actually disabled.

In addition, this approach could help us to declutter Customizer by removing irrelevant Controls, Sections, and Panels from the Customizer sidebar. If this sounds like something you want to achieve, let's just get started.

Disabling a Control Input Field

To begin with, open our JavaScript file, customizer-control.js. Then, add the lines of code within the Customizer ready event:

Herein we've set an alias for the this keyword, which refers to the Customizer JavaScript API. Then, we hook in an anonymous function into the display_blogname setting since all customizations we are going to perform in the Customizer will be relative to the value of this particular setting.

Next, we select the input field of the 'Site Title' setting.

We can disable the input when the display_blogname checkbox is unticked.

As you can see above, we use the jQuery .prop() method to set the HTML disabled property to the input element. We use the .get() method to retrieve the current value. Lastly, using the .bind() method, we listen to the value change and set the disabled property accordingly.

Disabled and Enabled input field in customizer
Left: Enabled "Site Title" input field. Right: Disabled "Site Title" input field. Notice the checkbox.

Toggling Visibility

Now we proceed with the code to toggle the visibility of the color pickers that set the "Site Title" colors. As we've planned, we will remove the color pickers when the checkbox is unticked and show them again when it is ticked.

To begin with, we group the color picker setting IDs together in an array.

Then, we iterate a function over these control IDs that will toggle their visibility using the jQuery .toggle() method.

The structure of the above code is similar to our previous code, which disables the input element. Here we've selected each control in the array using the .control() method as we've already shown earlier in this tutorial. Next, we have a function to toggle each control using the jQuery .toggle() method, and run it upon the Customizer page initiation as well as when the value is changed.

Site Title input field is disabled and two color pickers are hidden
The "Display Site Title" checkbox unticked, the Site Title input is grayed out (disabled), and the respective color pickers in the Color section are now hidden.

What's Next

In this tutorial, I have shown you a simple example of how to utilise the Customizer JavaScript API to improve user experience in the Customizer. And there are a few things we can do to improve it further, such as removing the "Colors" section if there is no control to display within the section, and adjusting the color shade of the "Header Text Color: Hover" setting following the value in the "Header Text Color" setting.

In the next tutorial of this series, we are going to challenge ourselves with a slightly more complex example. We are going to build a "bridge" that will allow the Customizer Preview window to interact with the Control panel in the back-end. So, when a user clicks on, for example, the Site Title in the Preview window, the Customizer will slide in the respective input to the user.

Stay tuned!



Related Articles