Creating panels, sections, and controls with the Customize JS API

Until now I mostly used the PHP API of the customizer. Since Weston Ruter’s post about the improvements of the Customize JS API in WordPress 4.9, I wanted to change that and learn more about the Customize JS API. This post shows you how to create panels, sections, and controls with that API.

Why the Customize JS API has advantages against the PHP API

I did not think about that much – I began with the PHP API and stayed with it. But the PHP API is – like Weston writes in his post – just a wrapper for the JS API. He also writes:

»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.«

Weston Ruter in Improvements to the Customize JS API in 4.9

So I thought to myself, I will try it out at the next opportunity. And because my Hannover and Bornholm themes need a visual and technical update, I already had it.

Disadvantage of the Customize JS API

There is also a disadvantage of the Customize JS API: currently, it is not very well documented, so it takes some time to find information, even if the API is entirely written in one (or just some) core files, so theoretically one could extract its functioning from there. For me, that was just a little help.

More helpful was Google, and frequently appearing answers and posts from Weston Ruter 🙂

But now let us come to the main topic of this post:

Creating panels, sections, and controls with the JS API

At first, we need to enqueue a JS file into the customizer’s control area. For that we use the following code:

// Include scripts into the customizer.
add_action( 'customize_controls_enqueue_scripts', 'hannover_customizer_controls_script' );

/**
 * Prints styles inside the customizer view.
 */
function hannover_customizer_controls_script() {
	// Add script control section.
	wp_enqueue_script( 'hannover-customize-controls', get_theme_file_uri( 'assets/js/customize-controls.js' ), [], null, true );
}

Now we create the customize-controls.js in the assets/js folder with the following content:

/**
 * Custom JavaScript functions for the customizer controls.
 *
 * @version 2.0.0
 *
 * @package Hannover
 */
;(function (api) {
	api.bind('ready', function () {
		// Create theme options panel.
		api.panel.add(
			new api.Panel('hannover_theme_options', {
				title: 'Theme Options',
			})
		);

		// Add section.
		api.section.add(
			new api.Section('hannover_example_section', {
				title: 'Example Section',
				panel: 'hannover_theme_options',
				customizeAction: 'Customizing ▸ Theme Options'
			})
		);

		// Add checkbox control.
		api.control.add(
			new api.Control('hannover_example_control', {
				setting: 'hannover_example_setting',
				type: 'checkbox',
				section: 'hannover_example_section',
				label: 'Check this box to do something.'
			})
		);
	});
})(wp.customize);

We wait until the Customizer is ready and add a panel, section, and control. You can see that the code for adding each of the elements is quite similar. The first parameter of the new call is the ID, after that, there comes an object with the options, like known from the PHP API.

One exception from that: customizeAction for new api.Section defines the string that is shown above the title in the section view:

Above the title of the customizer section, the customizeAction string is displayed. (Screenshot: own installation)

And with that, we are at the end of this small introduction to the Customize JS API. Important is, that – generally – you define the settings with the PHP API – otherwise, the values are not stored in the database. There is a way to create settings via the JS API dynamically, but that is the topic of another article.

Related posts

2 comments on »Creating panels, sections, and controls with the Customize JS API«

  1. Adri

    Hi,
    Thanks for your nice post. It's really hard to get info on the customize JS API.
    Unfortunately, I have tried your code and could not get it to work.
    My customize-controls.js file is identical to yours, so I think the issue is that the script is not properly enqueued, do you know how can I check wether has been properly enqueued?

    Here is a gist showing my functions.php related code and my customize-controls.js file
    https://gist.github.com/adrisantos07/81fe2fe6e9d4d0d932f8df0d0d18e78b
    Thanks

    Reply
    1. Florian Brinkmann

      Hi Adri,

      yes, you are right, the documentation could be better … 🙂

      To check if the script is enqueued, take a look at the source code in the customizer via the dev tools of your browser, and search for the script file’s name. And if it is enqueued, also check if the path is correct (just try to load the script URL in the browser).

      If the script is correctly loaded and it does not work, maybe the customizer setting needs to exist (be registered via PHP) – I am not 100 percent sure, maybe the control does not show up, if it has a value for setting that does not exist.

      Best,
      Florian

      Reply

Leave a Reply to Adri Cancel reply

Your email address will not be published. Required fields are marked *