Integrating the Theme Customizer into Your WordPress Theme

The new Theme Customizer introduced with WordPress 3.4 brought with it the ability for users to easily modify the look and layout of their website’s theme. For advanced features to be modified, the theme customization API must be integrated into the theme settings. This advanced tutorial will cover the basics of what the Theme Customizer can do and how theme developers can integrate it into their WordPress themes.

You’ll Need

There are some things that you will need in order to get started with this tutorial, and they are:

  • Theme with settings to edit – it can be your own theme or a child theme. If the theme already has a settings page, then it should be ready to work with the Customizer.
  • Experience with PHP – Since WordPress runs on PHP, it’s needed. Experience with basic functions and object-oriented programming would be beneficial.
  • WordPress – If you want to use the Theme Customizer, then you need to have WordPress installed on your site. You’ll also need to be familiar with using WordPress’ API and how themes work in WordPress.

Why Bother with the Theme Customizer?

The Theme Customizer makes it extremely easy for end-users of a theme to make changes that they can instantly see reflected on their website. Every theme can have the Theme Customizer edit basic WordPress settings, but only themes that have integrated the Theme Customizer can let users make changes to more settings of their theme without having to deal with a settings page before refreshing their website.

What Can It Do?

The Theme Customization API allows for theme developers to make option sections in order to group related settings, make forms that allow users to modify theme settings, and allow for the API to get and set the settings for use by the Theme Customizer.

Give Me an Example

The Theme Customizer is featured in the Twenty Eleven theme, and that theme allows you to change every setting in two places: the theme options page and from within the Theme Customizer. We’ll use Twenty Eleven as our stating point in order to see some of what it can do.

theme customizer

Twenty Eleven with the Theme Customizer

The integration of the Theme Customizer into Twenty Eleven gives the option to users that can edit theme settings to see what they are doing as they are doing it. This instant feedback allows users to see what the effect of each setting is, and to revert any changes if they do not like what they see without doing any harm to their site. Viewers of their website will never know that the theme settings are being altered until the person making the changes chooses to set the new settings.

Alright, I’m Convinced. What Do I Need to Know?

The first step in integrating the Theme Customizer into your theme is to learn about the Theme Customization API and what it uses to get and set every option or theme modification.

Theme Modifications and Options

WordPress gives theme developers two methods of working with theme settings. One method, built just for the purpose of managing theme settings, is what are called “theme modifications.” Theme modifications are exactly what they sound like: a modification to the theme. The other method, which is used to work with every other option available by default in WordPress, is options. An option is data that stores various settings and controlled using the Settings API, which can work with the data in multiple ways. Each option for a theme can have its own name, and therefore its own row in the website’s database, or every theme option can be combined into one array to be processed and stored by a separate function defined by the theme itself.

For most theme developers, or just developers familiar with PHP, the theme modification method will work the best for this project. The Settings API can be learned faster, and WordPress has all of the functions that do the heavy lifting built into its code base.

Settings vs. Controls

Adding a place to edit theme settings within the Theme Customizer is easy, and that is the way the WordPress developers like it. But two of the three main functions may seem confusing due to an apparent similarity at first glance. Those two are WP_Customize_Manager’s add_setting() and add_control() functions.

add_setting() is used to tell WordPress that a certain setting will be available to be modified by the Theme Customizer, and allows WordPress to modify the saved settings for you. add_control(), on the other hand, is used in rendering the actual form item needed to control the setting. As you can see, they are related to each other, but they should not be confused.

Live Previews

The Theme Customizer allows those that are using it to modify theme settings do so through the use of a live preview of the theme. A live preview is where WordPress loads your theme and your website’s content into a sandbox environment, where any changes made there are reflected only within the preview window until the user decides to save the settings. This is when WordPress actually makes the changes to your theme’s settings.

The Theme Customizer can make the preview “live” in two separate ways. The first method is to simply refresh the preview pane while passing along the newly edited settings, which allows the theme’s PHP functions to process the data. The second method is to use Javascript to update the content in real-time, and this is the more “interactive” of the two, since the user can stay on the same page without having WordPress reload the preview several times. The default method used is to refresh the preview because many themes do not have the Javascript needed, and refreshing the preview does not burden the system more than a regular page view.

I Understand. Now How Do I integrate this into my Theme?

If you truly want to add the ability to use the Theme Customizer with your theme, this is where you will be getting into the code.

Setting Up

To prepare your theme to use the Theme Customizer, you have to make sure that you have the wp_head hook included in your theme’s header and a function to hook into customize_register.

Including the wp_head hook into your theme’s header is as simple as copying and pasting into the header.php file, or whichever file the header is in, removing the PHP tags if necessary.

To creating a custom function to hook into customize_register is the same process as any other hook. Just copy and paste the following code into your theme’s functions.php file.

function mytheme_customize_register( $wp_customize )
{
   // Code for integrating the Theme Customizer will go here
}
add_action( 'customize_register', 'mytheme_customize_register' );

Doing so will give you a place for all of the code needed later on to initialize and fully integrate the Theme Customizer with your theme.

Adding Sections

If you want to be able to have people change settings of your theme, then you need to provide a place for them to do so. The Theme Customizer provides a collection of “sections,” or groups of related settings, to allow your theme’s users to modify the theme settings. You have the option of creating new sections within the Theme Customizer, or you can tie into already existing sections.

If you do not have any sections specific to your theme predefined, as using the add_theme_support() function to allow for custom headers and backgrounds would create, then the choice should be to make a new section.

In order to know what sections need to be created and what order they should be in, you will need to decide how to split and organize the settings that you have previously instructed WordPress to allow users to manage. After you have done so, the first step is to copy the code below into the function that you have already placed into your theme’s functions.php. The ‘mytheme_section_id’ variable that is passed should be altered to be a unique section ID relevant to your theme and what it will contain, as this is how WordPress will know where to put each control when you add them later.

$wp_customize->add_section( 'mytheme_section_id' , array(
	'title'      => __('Section Name','mytheme'),
	'priority'   => 10,
	'description'   => 'Section Description'
) );

The title key within the array of arguments to be passed is what will be the name displayed in the list of sections. The priority key will determine in which order the sections will appear. Setting a priority of 10 will put this new section at the top of the list, while anything above 120 will put it below all of the default sections. The description key will become the section name’s “title” attribute, and the text entered will be what the user will see when he or she hovers over the section’s name.

Adding Settings

Before working on anything else, you should tell WordPress which settings you want the user to control. This needs to be done before adding a control for each setting, otherwise the PHP functions will find no data to use and return false, which means that the user will not be able to edit the settings that you want them to edit. Since you figured out which settings to include in the last section, this step involves less planning and more doing.

The code below should be inserted just below the section that you want it to appear in, since it will make it easier for you to follow which setting belongs to which section when we add in the controls later. The ‘mytheme_setting_id’ variable, just like the section ID, should be set as a unique ID.

$wp_customize->add_setting( 'mytheme_setting_id' , array(
	'default'		=> '#000000',
	'type'		=> 'theme_mod',
	'capability'	=> 'edit_theme_options',
	'transport'	=> 'refresh'
) );

The function to add a setting supports several arguments being passed, and they are what the default value should be, if this setting is a theme modification or an option, and what capability a user needs to have in order to edit this setting.

Adding Controls

To actually allow your theme’s users to edit theme settings using the Theme Customizer, you need to add some controls that will get a setting’s current value and display it in a manner that makes sense for the type of setting and based on what your theme will allow. Adding a control is more complicated than adding a section or setting due to the amount of possible types of controllers that can be made. There is a default PHP class for most options, but WordPress also has five other classes available for handling colors, uploads, general images, background images, and header images.

There will be two examples of code below. The first one will be for controlling an option that does not need to use one of the special classes, while the second one will be for controlling the color of some element.

$wp_customize->add_control( 'mytheme_setting_id', array(
	'label'		=> 'Controller Name',
	'section'		=> 'mytheme_section_id',
	'type'    		=> 'text',
	'choices'    	=> $choices
	) );

The type of form element that will be used is determined by the “type” key, and can be:

  • text
  • checkbox
  • radio
  • select
  • a drop-down of pages (which should be entered as dropdown-pages).

The “choices” key should be passed for the radio or select form element through a variable containing each possible choice as a simple array using the ID for each element as the key and the text to display as the key’s value.

$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'mytheme_setting_id', array(
	'label'		=> __( 'Setting Name', 'mytheme' ),
	'section'		=> 'mytheme_section_id'
	) ) );

This code snippet allows the controller to use the built-in color picker to allow users to either pick the color of a setting using a color disc or by manually entering in the HTML, or Hex, color code.

Using Settings With Your Theme

Your theme should now have a means for users to use the Theme Customizer to modify your theme’s settings, but you need to know how to implement those settings if your theme does not already. Assuming you made WordPress use theme modifications to work with your theme’s settings, although using options will work just as well with the same syntax in this step, you will have to get your theme’s settings in order to work with them. In order to get a particular theme modification, all you have to do is call get_theme_mod( $name, $default ); where you intend to use the setting. The name variable is the ID of the setting that you want, and the default variable is what the default should be in case the setting is not set in the database.

You know how to get the setting’s value, but now your theme needs to know what to do with that information. If you want to use the setting as a part of an “if statement”, then follow the example in the code below. If you want to condense your code, you can use the get_theme_mod( $name, $default ); function within the if statement in place of the variable.

<?php
$setting = get_theme_mod( $name, $default );
if ($setting !== 'false')
{
	// Some action
} else {
	// Another action
}
?>

If you are modifying a style using CSS that uses a theme setting to determine the value a specific property, then the following code should be put into your theme’s functions.php file.

function mytheme_customize_css()
{
    ?>
         <style type="text/css">
             h1, h2, h3, h4, h5 { color:<?php echo get_theme_mod('setting_id'); ?>; }
         </style>
    <?php
}
add_action( 'admin_head', 'mytheme_customize_css');

You can even use theme settings to allow users to set custom data to be displayed on their website. To do that, inline PHP will do what you want. In this example, theme modifications allow the user to set a custom link within the footer of their website, and should be put in your theme’s footer.php file in an appropriate location and styled properly with CSS, if necessary.

<a href="<?php echo get_theme_mod('mytheme_footer_link'); ?>" title="<?php echo get_theme_mod('mytheme_footer_link_title'); ?>"><?php echo get_theme_mod('mytheme_footer_text'); ?></a>

These three settings will need to be added and controlled from within the Theme Customizer in order for the user to set them while using a live preview of their website, and may be placed into their own section.

Summary

If you have a theme that you allow others to download, and wanted to give your theme’s users the ability to use the Theme Customizer introduced in WordPress 3.4, there is not that much work involved if you already have a system set up for handling theme settings. WordPress will do most of the work for you and only requires that you tell it what settings should be controlled, how to control them, and where to put those controls. The ability of the Theme Customizer to allow a website’s owner to alter theme settings while being able to view the alteration within a sandbox gives a lot more power to the users with less knowledge about how to run a website. Making the process of integrating itself with a theme’s settings extremely easy also makes it easy for a beginner theme developer to get started with adding modifications to the theme for its users to edit.

Additional Resources

Link: Theme Customization API in the WordPress Codex

Link: Theme Modification API in the WordPress Codex

Link: Option Reference in the WordPress Codex

About 

Chris Ellison is a web developer living in the United States, and has been working with WordPress since 2009. He owns Abbson Studios, a design studio where he is free to experiment with new ways of molding WordPress into whatever he wants or his clients need.

3 thoughts on “Integrating the Theme Customizer into Your WordPress Theme

  1. Nice article. A couple of errors:

    Snippet two description incorrect should be single quoted.
    $wp_customize->add_section( ‘mytheme_section_id’ , array(
    ‘title’ => __(‘Section Name’,’mytheme’),
    ‘priority’ => 10,
    ‘description’ => ‘Section Description’
    ));

    Snippet four missing coma on fourth line.
    $wp_customize->add_control( ‘mytheme_setting_id’, array(
    ‘label’ => ‘Controller Name’,
    ‘section’ => ‘mytheme_section_id’,
    ‘type’ => ‘text’
    ‘choices’ => $choices
    ));

Comments are closed.