WordPress.org

Ready to get started?Download WordPress

Codex

Plugin API/Action Reference/customize preview init

Contents

Description

This action hook allows you to enqueue assets (such as javascript files) directly in the Theme Customizer only. To output saved settings onto your live site, you still need to output generated CSS using the wp_head hook.

Generally, this hook is used almost exclusively to enqueue a theme-customizer.js file for controlling live previews in WordPress's Theme Customizer.

For more information, see the codex article on the Theme_Customization_API

Examples

Usage might look like this...


/**
 * This outputs the javascript needed to automate the live settings preview.
 * Also keep in mind that this function isn't necessary unless your settings 
 * are using 'transport'=>'postMessage' instead of the default 'transport'
 * => 'refresh'
 * 
 * Used by hook: 'customize_preview_init'
 */
public static function mytheme_customizer_live_preview()
{
	wp_enqueue_script( 
		  'mytheme-themecustomizer',			//Give the script an ID
		  get_template_directory_uri().'/assets/js/theme-customizer.js',//Point to file
		  array( 'jquery','customize-preview' ),	//Define dependencies
		  '',						//Define a version (optional) 
		  true						//Put script in footer?
	);
}
add_action( 'customize_controls_enqueue_scripts', 'mytheme_customizer_live_preview' );

Example Javascript Handler

The following is one example of what a Javascript live preview file might look like for a custom implementation of the Theme Customizer...


The contents of your theme-customizer.js file might look like this:


/**
 * This file adds some LIVE to the Theme Customizer live preview. To leverage
 * this, set your custom settings to 'postMessage' and then add your handling
 * here. Your javascript should grab settings from customizer controls, and 
 * then make any necessary changes to the page using jQuery.
 */
( function( $ ) {

	// Update the site title in real time...
	wp.customize( 'blogname', function( value ) {
		value.bind( function( newval ) {
			$( '#site-title a' ).html( newval );
		} );
	} );
	
	//Update the site description in real time...
	wp.customize( 'blogdescription', function( value ) {
		value.bind( function( newval ) {
			$( '.site-description' ).html( newval );
		} );
	} );

	//Update site title color in real time...
	wp.customize( 'header_textcolor', function( value ) {
		value.bind( function( newval ) {
			$('#site-title a').css('color', newval );
		} );
	} );

	//Update site background color...
	wp.customize( 'background_color', function( value ) {
		value.bind( function( newval ) {
			$('body').css('background-color', newval );
		} );
	} );
	
	//Update site title color in real time...
	wp.customize( 'mytheme_options[link_textcolor]', function( value ) {
		value.bind( function( newval ) {
			$('a').css('color', newval );
		} );
	} );
	
} )( jQuery );

As you can see from the example above, a single basic handler looks like this...


wp.customize( 'YOUR_SETTING_ID', function( value ) {
	value.bind( function( newval ) {
		//Do stuff (newval variable contains your "new" setting data)
	} );
} );

Note: This example above needs to be replaced. .bind() is deprecated since jQuery 1.7 and one should use .on() or .delegate() instead.

Note: Again, keep in mind that the above will only work if you have set all referenced SETTINGS to 'transport'=>'postMessage'. By default, WordPress uses 'transport'=>'refresh' for all settings (including the ones that are built in). You can override those defaults using the customize_register action hook.

Related