WordPress Theme Customizer Javascript Interface

Here, we focus on understanding the javascript nuts and bolts of the WordPress theme customizer interface.

This will allow us to –

• Extract and change theme customizer settings.
• Extract and change theme customizer controls.
• Call theme customizer functions, such as refreshes and more.

wp.customize

Understanding the WP theme customizer interface centers around understanding the wp.customize javascript object. The three core files related to wp.customize are –

• wp-admin/js/customize-controls.js – Contains special objects related to the theme customizer interface including Setting, ColorControl, PreviewFrame, Previewer, and more.
• wp-includes/js/customize-preview.js – Sets up and creates the theme customizer interface.
• wp-includes/js/customize-base.js – All theme customizer objects from the above two files are built (i.e. extended from) theme base objects. These base-objects are helpful for showing us what common access functions are available for the higher level objects.

Note that the wp.customize object is commonly set to the api variable in these files.

var api = wp.customize;

There are two important classes of objects contained within wp.customize – settings and controls.

Initializing the wp.customize Object

At the start, the wp.customize object is populated with the array of settings, values, nonces, and more, passed over by the PHP portion of the theme customizer. If we look at the source of theme customizer page, we will notice that at the end of the page, the _wpCustomizeSettings variable is set to a large array of values that looks like this –

var _wpCustomizeSettings = {"theme":{"stylesheet":"genesis-skins","active":true},"url":{"preview":"http:\/\/mysite.com\/","parent":"http:\/\/mysite.com\/wp-admin\/","activated":"http:\/\/mysite.com\/wp-admin\/themes.php?activated=true&previewed","ajax":"\/wp-admin\/admin-ajax.php","allowed":["http:\/\/mysite.com\/"],"isCrossDomain":false, ...

This array is set to the settings attribute in the wp.customize object (source here).

api.settings = window._wpCustomizeSettings;

From this array, which contains the settings and control names and attributes, a set of javascript object settings and controls are created.

Settings and Controls

Control objects are stored in wp.customize.control (as a collection of Values) and setting objects are stored in wp.customize itself (as a collection of Values). The Values class has the following useful access functions that we can use to extract setting and control objects from wp.customize.

• instance( id ) – Gets an object from the collection with the specified ‘id’.
• has( id ) – Returns true if collection contains an object with the specified ‘id’ and false otherwise.
• add( id, value ) – Adds an object to the collection with the specified id and value.
• remove( id ) – Removes an object from the collection.
• create( id ) – Creates a new object using the default constructor, and adds it to the collection.
• each( callback, context ) – Iterates over elements within the collection.

With these tools in hand, we can get to a setting object in the theme customizer interface by doing –

var api = wp.customize,
    mysetting = api.instance('footer_image');

or for a settings array,

var api = wp.customize,
    mysetting = api.instance('my_theme_options[footer_image]');

NOTE – If we are making javascript calls from the preview frame, then we would want to set api to parent.wp.customize.

The get function gets us the setting value.

console.log(api.instance('my_theme_options[footer_image]').get());

>http://mysite.com/wp-content/uploads/2013/03/Mech-Girl-Footer4.jpg 

We can also change theme customizer setting values to whatever we want by using the set function.

api.instance('my_theme_options[footer_image]').set('http://mysite.com/wp-content/uploads/2013/03/Mech-Girl-Header4.jpg')

Similarly we can get and manipulate control objects.

console.log(api.control.instance('footer_image'));

>k {params: Object, previewer: k, id: "footer_image", selector: "#customize-control-footer_image", container: v.fn.v.init[1]…} 

For example, if I want to manually set a color controller to a particular value, this is what I would do –

	function mySetColor(cname, newColor) {
		var	control = api.control.instance(cname);
			picker = control.container.find('.color-picker-hex');
			
		control.setting.set(newColor);
		picker.val( control.setting() ); return;
		
	}

cname is the controller name and newColor is the new color we want to assign our controller to.

Another really useful object is the previewer (Previewer class). We can use this object to manually refresh our theme preview interface.

		api.instance('my_theme_options[footer_image]').previewer.refresh();

AJAX calls

During Ajax calls, customizer settings are passed back in a $_POST request that looks something like this-

Array
(
    [wp_customize] => on
    [theme] => genesis-skins
    [customized] => {\"blogname\":\"Test Blog\",\"blogdescription\":\"Test Blog with WordPress Test Data\", ... }
)

The post values can then be retrieved using $wp_customize->post_value($setting).