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

Tweet

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

Related Articles

How to Add the WordPress 3.5 Media Manager Interface - Part 2

How to make some simple customization to the WordPress 3.5 media manager interface.

How to Hook into the Media Upload Popup Interface

What is the media upload popup interface? That is simply the popup window that appears when we click on the Add Media button (for adding images and video) while in the Edit Post screen. The same interface is also currently being used for - Setting featured images in posts, and Setting header images in a theme. It can also be very useful in a plugin. For example, my Shiba Gallery plugin uses the Media Upload Interface to assign a default picture for posts and pages that do not have [...]

How to Add the WordPress 3.5 Media Manager Interface

A tutorial on how to add the new WordPress 3.5 media manager interface into our own plugin or theme.

Comments

  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
  4. Thomas says

    September 11, 2014 at 5:07 am

    Hallo ShibaShake,

    I have following line in my custimizer.js:

    ( function( $ ) {
    wp.customize( 'headerbackgroundcolor', function( value ) {
    value.bind( function( to ) {

    Need value of 'headerbackgroundalpha'
    } );
    } );
    .
    .
    .

    In my Theme Customizer I have the option to set an alpha-value of the header-background. Is it possible to read out the current value of the setting of ”headerbackgroundalpha” inside the wp.customize prozedure above?

    Thanks a lot

    Reply
  5. Brian says

    August 9, 2014 at 1:26 pm

    I’m wondering if it’s possible to extend the `customize-control.js` methods that are made available by default. I need to hook in there and do some special logic, but it’s wrapped in an immediately invoked function expression

    /* globals _wpCustomizeHeader, _wpMediaViewsL10n */
    (function( exports, $ ){
    // code
    })( wp, jQuery );

    So I’m not able to extend the prototype from the window object. Any idea if such a thing is possible? There is even mention of overriding this in the .toggle() methods documentation / description: https://github.com/WordPress/WordPress/blob/master/wp-admin/js/customize-controls.js#L110, but I’m not sure if they mean by simply forking the whole JS file, dequeueing the WP version and enqueuing your own or if they mean or something different.

    Reply
  6. Wouter says

    June 20, 2014 at 2:11 am

    Hi,

    I have a question using the customizer in wordpress. I have a jQuery draggable widget (a logo of a website), only draggable when in “customize theme”. I would like to have it’s position; top and left passed to a control in the customizer of WordPress; so that when saved and published; the logo is effectively where I dragged it to… I need the top and left position (which I have) saved in to a textbox in wordpress customizer in other words… Doing a hook of an object and change it’s settings…Is that possible?

    Thanks

    Reply
    • ShibaShake says

      June 20, 2014 at 8:32 am

      Yes, I did something similar in my Genesis Skins and Shiba Skins child themes. The blog title text is draggable. The code for that should be in shiba-gs-customizer.php or shiba-skins-customizer.php.

      Reply
      • Wouter says

        June 20, 2014 at 9:19 am

        ShibaShake : thanks, your code is very clear; I figured it out, and it now works like a charm! Thank you very much ๐Ÿ˜‰

        Reply
      • Wouter says

        June 20, 2014 at 9:53 am

        Still one small problem. In your code, you set two settings left and top… Same what I’m trying to achieve. However, as soon as I set one (left) (instance.setting.set); it immediately refreshes the preview; and does not set the top (which is the second instance.setting.set) in my jQuery code… Hope I’m making myself clear, but I need to hold the “automatic” update; how do I do that? I can do a manual one, from the code above, so that will be no problem.

        Reply
        • ShibaShake says

          June 20, 2014 at 12:59 pm

          I just left the ‘transport’ attribute for those settings at the default (‘refresh’) rather than ‘postMessage’. postMessage binds a listener to the setting, whereas refresh does not.

          http://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting

          Reply
          • Wouter says

            June 22, 2014 at 9:04 am

            @Sheba : thx again, I’ve done some experimenting, works very well …

  7. gabriel duncan says

    June 19, 2014 at 2:53 pm

    i know i’m a little late to the party…

    thanks for this tutorial! i have a question. I want to listen for changes to any control value, say a color picker, but also to ALL control values and then bind a function based on the type of control. is there a nice way to use this api to do that? or do i need to go ahead and define each function manually for each control like the docs say?

    any help would be greatly appreciated! thanks again!

    Reply
  8. sharma chelluri says

    April 24, 2014 at 6:21 am

    ShibaShake,

    I implemented this for dynamic changing of color pickers based on previous values.

    The detail oriented and untouched subject of customizer helped me and saved lot of time. Million Thanks for your help.

    Sharma chelluri

    Reply
  9. wLc says

    February 23, 2014 at 10:42 am

    This was invaluable. I created a custom drag & drop control and was banging my head on the wall trying to figure out how to get the preview window to refresh.

    Thanks a million.

    Reply
  10. Charlotte says

    February 21, 2014 at 7:25 pm

    Really nice to see a customizer tutorial that hasn’t been copied from otto – very useful information here that helped me a lot, thanks and much appreciated!

    Reply
  11. Dennis says

    April 4, 2013 at 5:29 pm

    I really appreciated this post. It showed me exactly what I was struggling with in a client’s theme customizer code. I was struggling with how to set the value once I had gathered it through a thickbox popup. I used the information provided in this post to help create my own class based on the Image Control class and documented the process on my blog at: http://hosting.fancyfiber.com/2013/04/04/wordpress-theme-customizer-custom-image-library/

    Again, I really appreciate the information you provided here! Helped immensely.

    Reply

Leave a Reply Cancel reply

Your email address will not be published.

Recent Posts

  • Screen-shot of mobile responsive Poll Daddy object, where text floats properly to the right of radio buttons.How to Make Poll Daddy Objects Mobile Responsive
  • Screen-shot of blog post with no page border (flowing design).Genesis Skins 1.5
  • Screen-shot of the media manager Create-Gallery screen, while doing a post search.Shiba Media Library 3.7
  • Screenshot of the Edit Gallery screen after we hit the Create Gallery button.How to Expand the WordPress Media Manager Interface
  • Blonde girl looking through and holding a circular picture frame.Shiba Gallery 4.3
  • Close-up of beautiful blonde holding a square picture frame.Google Authorship - Good or Bad for Search Traffic?
  • Shiba Widgets 2.0
  • Media Temple screenshot of editing my sub-domain DNS entry.Using CDN Cnames with w3tc and MultiSite
  • Shiba Skins WordPress ThemeShiba Skins WordPress Theme
  • How to add the Media Manager Menu to the Theme Preview InterfaceHow to Add the Media Manager Menu to the Theme Preview Interface

Recent Comments

  • WordPress Search Widget – How to Style It (56)
    • Nelson
      - Tanks master - Fine
    • TelFiRE
      - How do you style the "X" that shows up when you start typing?
  • Update custom inputs with the proper data using Javascript.Expand the WordPress Quick Edit Menu (58)
    • Mike G
      - This is exactly what is happening to me. It is updating the value in the database and in the column, but I have to refresh ...
    • PhoenixJP
      - Thanks for this tutorial. Does someone knows if this still work with wordpress 5.03 and 5.1.
    • Francine Carrel
      - This is a very long time away from your original comment, but did you ever work it out? I am stuck on the exact same thing ...
  • Custom meta-box with a set of radio-buttons.Add a Metabox to Your Custom Post Type Screen (27)
    • mike
      - Hi Shiba am a newbie to wordpress, I just installed a plugin with a custom post type, but has no option for discussion and ...
  • Write a Plugin for WordPress Multi-Site (45)
    • Andrew
      - Hi,action 'wpmu_new_blog' has been deprecated. Use โ€˜wp_insert_siteโ€™ instead.
  • Populate our Edit Gallery menu using a gallery shortcode.How to Add the WordPress 3.5 Media Manager Interface – Part 2 (29)
    • Janine
      - Still relevant in 2019.
  • WordPress Excerpt – How to Style It (36)
    • James
      - Great post. I really need some help. I have set border lines around my excerpts on my blog page/post page. The problem is ...
  • Add Custom Taxonomy Tags to Your WordPress Permalinks (123)
    • Darshan Saroya
      - Update permalinks. Go to settings > permalink and just save it.

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