New theme in development and is currently live on - Please check back often for updates (11/12/16).

Tutorials · WordPress

Theme Configuration with Customizer API


The theme customizer API was added to WordPress at 3.4 and does good job of abstracting theme specific options and customisations whilst keeping the end user close to their design and content.

Recently at WordCamp Edinburgh I was introduced to the customizerĀ and hereĀ I will re-iterate what was explained and show you how to incorporate any customisations to your theme.

1) Setup

  • customizer.php – This will be loaded via functions.php in any active theme.
  • jquery.customizer.js – This will be enqueued and loaded only when viewing the customizer.

To load customizer.php in functions.php add this code.

locate_template(get_bloginfo('template_directory').'/resource/php/wordpress/customizer.php', true, true);

We pass 3 parameters to locate_template(), the first is the file we want to locate, the second is if we want to load the template and the third is if we want to require it only once, set this to false for example if we are using locate_template() in a loop.

Whilst here, let’s enqueue the JavaScript file from customizer.php.

// Live mods in customizer via the following script
function sc_customizer_script(){
    wp_enqueue_script('sc-app-customizer', get_bloginfo('template_directory').'/resource/js/jquery.customizer.js', array('jquery'), '0.0.1', true);
add_action('customize_preview_init', 'sc_customizer_script');

We’re looking for the event hook customize_preview_init here and when it is available our wrapper function of sc_customizer_script() will run.

Furthermore, we enqueue the script with wp_enqueue_script() which has 5 available parameters. A unique identifier for the script, the location of the script (we use get_bloginfo('template_directory') to find the working directory and then append the relative path to the file. Parameter three is an array of any dependencies our script has and in this case we specify only jQuery, the next parameter is the version and the final parameter is if we want this script to be loaded in the footer via wp_footer() (I’m not sure if this is relevant in WP-Admin).

2) Registering Customisations with WordPress

When the jQuery file above was enqueued we used add_action() with the customize_preview_init hook, we’ll declare our actual customisations in the same way with a different hook. So let’s create a wrapper function and hook it in.

function sc_customizer($wp_customize){

add_action('customize_register', 'sc_customizer');

We will use the following 4 methods inside our function add_panel(), add_section(), add_setting(), add_control() and all of which can only be accessed via the $wp_customize object.

3) Creating a Panel

First we need to create a panel which will house our sections, controls and corresponding settings.

// Panel will not be shown until a section is added to it
$wp_customize->add_panel('sc_panel_1', array(
	'title'             => __('SC Customisations', 'sc'), // Visible name of panel
	'description'       => __(''Theme customisations.', 'sc'), // Descriptive text for administrators
	'capability'        => 'manage_options', // WordPress user type
	'theme-supports'    => '', // More useful for plugin developers
	'priority'          => '10' // Order within the customizer

Create a panel with a unique ID and pass in some further details.

4) Creating a Section

$wp_customize->add_section('sc_theme_logo', array(
	'title'            => __('Logo', 'sc'), // Visible name of section
	'description'      => __('Add a logo to your site.', 'sc'), // Descriptive text for administrators
	'priority'         => '10',
	'panel'            => 'sc_panel_1' // Which panel does this section belong to?

Add a section with a unique ID and add it to a specific panel. Add as many sections as you feel are appropriate to group your settings.

5) Adding a Setting

$wp_customize->add_setting('sc_site_logo', array(
	'default'      => get_bloginfo('template_directory').'/resource/img/stock/logo.png',
	'transport'    => 'postMessage' // Post via AJAX or set to default which is to refresh the iframe in the customizer

Much like add_panel() and add_section() we setup add_setting() with a unique ID and some key -> value pairs.

There will be no more to see visually whilst in the customizer until we add this setting to a control.

6) Adding the Control

$wp_customize->add_control(new WP_Customize_Image_Control($wp_customize, 'sc_site_logo', array(
	'label'          => __('Site Logo', 'sc'), // Visible label
	'section'        => 'sc_theme_logo', // Which section does this control belong to
	'settings'       => 'sc_site_logo',

Currently in the codex there are 6 control classes with sparse documentation,
the return values differ for each method.

7) Live Preview

To utilise 'transport' => 'postMessage' and not the default argument for the setting which was previously declared we can use jQuery to take the return value on the customize() method which is now available to our jquery.customizer.js file.

Let’s look at it a little closer.

wp.customize('sc_site_logo', function(value){
	$('header h1 a img').attr('src', value);

wp is a JavaScript object available to us when in WP-Admin, we can assign the object to the customize() method
and further allocate a specific setting to be watched(sc_site_logo) as a DOM element (I assume this as documentation for WordPress JavaScript is sparse at best).

Finally we select the DOM element to have it’s value updated from the return value et voila!

8) Front-end

At this point we’ve done pretty much everything we need to hand over configurations to a WordPress adminstrator, that’s great!

It’s useful to know that we can retrieve these settings and use in our themes at any given time. The following snippet is an example of how to do just that.

if(get_theme_mod('sc_site_logo')) :
    echo get_theme_mod('sc_site_logo');

Simple stuff, check if there is a value associated with the setting if so echo that otherwise use a default image for the logo example.

9) Conclusion

Customizer is a super way to include options and configurations with your theme.

Leave a Reply

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

Loading more content...
Minimum Requirements

Your device does not meet the minimum requirements to view this site, please considering increasing your device width to more than 300px.