Shiba

Adventures in WordPress

  • Home
  • Dog
  • Art
  • Contact
  • WordPress Articles
    • WP Plugins
    • WP Programming
    • WP Admin Panels
    • WP Theme Design
    • WP How-To
    • WP Theme Images
You are here: Home / WordPress Admin / Theme Customizer / WordPress Theme Customizer Javascript Interface

WordPress Theme Customizer Javascript Interface

by ShibaShake 21 Comments

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).

Leave a Reply Cancel reply

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

Comments

« Previous 1 2
  1. MailOptin Plugin says

    November 14, 2017 at 10:55 pm

    Excellent overview of the WordPress JS customizer API.

    Learned a ton from this post.

    Reply
  2. Wilson says

    October 4, 2016 at 11:17 am

    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;

    }

    You use this script to manually set a color controller to a particular value, how I could use it to set the value of a range controller?

    I really appreciate any help you can provide, thanks
    Wilson

    Reply
  3. Robin says

    January 9, 2016 at 2:14 pm

    I’ve been searching for a few days for how to deal with a setting I’m updating using postMessage which refuses to persist through a refresh. Your post is the first (and only) which I’ve found with the information I needed to make the final connection. Thank you!

    Reply
    • ShibaShake says

      January 9, 2016 at 8:50 pm

      You are very welcome. 🙂

      Reply
« Previous 1 2

Recent Posts

  • Screenshot of an example article in code view of a modified Gutenberg editor.How to Harness the Power of WordPress Gutenberg Blocks and Combine It with Legacy Free-Form Text
  • Screenshot of the Success, WordPress has been installed page.Migrating Your WordPress Website to Amazon EC2 (AWS)
  • Screenshot of WinSCP for creating a SFTP configuration.How to Set-Up SFTP on Amazon EC2 (AWS)
  • WordPress Gutenberg code view screenshot of this article.How to Prevent Gutenberg Autop from Messing Up Your Code, Shortcodes, and Scripts
  • Screenshot of the Success, WordPress has been installed page.How to Create a WordPress Website on Amazon EC2 (AWS)

Recent Comments

  • Screenshot of an example article in code view of a modified Gutenberg editor.How to Harness the Power of WordPress Gutenberg Blocks and Combine It with Legacy Free-Form Text (1)
    • tom
      - hi,my experience was like the same, but for me as theme developer the "lazy blocks"(https://wordpress.org/plugins/lazy-blocks/) ...
  • WordPress Custom Taxonomy Input Panels (106)
    • Phil T
      - This is unnecessarily confusing. Why declare a variable with the same name as your taxonomy? Why did you choose a taxonomy ...
  • Create Pop-up Windows in Your WordPress Blog with Thickbox (57)
    • Jim Camomile
      - I have used this tutorial several times and it is one of the few simple and effective ways to add popups with dynamic content, ...
  • How to Add Admin Columns in WordPress (7)
    • Andy Globe
      - Hi Friends, I am facing two problem in WordPress admin1. Load custom CSS for wp-admin on user-role base (editor) 2. ...
  • Example blog front-page using excerpts and the Shiba Theme.Optimize Your WordPress Plugins with Tags (5)
    • DF
      - thanks, i went the other way and added a filter if pages I wanted.

Copyright © 2023 · Genesis Skins by ShibaShake · Terms of Service · Privacy Policy ·