The Complete Guide to the WordPress Theme Customizer

The Complete Guide to the WordPress Theme Customizer

WordPress 4.7 was released with a ton of great new features (which you can check out here), including some user experience and user interface upgrades to the theme Customizer.

In case you’re hearing about the Customizer for the first time, it’s a feature in the WordPress admin (go to Appearance > Customize) that allows users to tweak theme settings using a WYSIWYG interface and customize a theme’s colors, fonts, text, and pretty much anything else you want to change.

In this post, I’ll walk you through how the Customizer can be used in themes to create a better user experience and all the new awesomeness that WordPress 4.7 has introduced.

An Introduction to the Theme Customizer

The theme Customizer was first introduced in WordPress 3.4 and allows you to live preview changes you make to your theme. You can play around all you like without modifying your live site. And when you’ve made your changes, simply click Save and everything is applied instantly.

WordPress Theme Customizer
The WordPress theme Customizer in action.

As developers, we have access to core functionality such as the editing of the site title or header image, and we can also build custom controls for anything we’d like through the Theme Customizations API.

Developing for the Theme Customizer

There are three areas of interest when coding for the customizer. You’ll need to create the controls for the customizer, the CSS and/or logic that implements the settings in the theme and – optionally – the live preview functionality that provides a better user experience.

First Steps

Before we begin, let’s create an environment we can work in. For this tutorial let’s create a brand new, very simple theme. In fact, it won’t even qualify as a proper theme, I’ll just be using a simple index.php file to create a landing page.

Initial theme for our customize project
My initial theme for this Customizer project.

You can download the starter theme I’m using or follow along with the code on Github to make it yourself.

If you visit the Customizer in the WordPress admin, you can already control the site title, description and additional CSS (the final one being a new feature in 4.7) of your website. This is because by default the Customizer displays changes by refreshing the whole page. We’ll make this a lot smoother a bit later but for now this will do.

Additional CSS In The Theme Customizer
Adding additional CSS in the theme Customizer

Laying the Foundation

Let’s begin by laying the groundwork for our customization efforts. I’ll create a customizer.php file and make sure to require it in the functions.php file.

The Customizer file will begin with a hooked action that contains all our sections, settings and controls.

Sections, Settings and Controls

Sections represent the navigation within the Customizer. You should already see four of them: Site Identity, Menus, Static Front Page and Additional CSS. By defining a section we can create a new entry within the navigation and fill it up with controls.

Controls are the visual elements – the user interface – that allow us to manipulate settings. These may be input fields, text areas, color selectors and other types of controls that serve to create a better user experience.

Settings represent the data that we want our theme to accept and use. We create controls to allow users to manipulate settings easily.

Creating a Section

To add a new section we’ll use the $wp_customize->add_section() method. It takes two arguments: a section identifier and an array of additional options like the visible section title and its position within the section list.

Don’t forget that the code above and any other code that creates sections, controls or settings should be placed in the cd_customizer_settings() function.

Our section is now registered, but it won’t show up until we add a control to it.

Creating a Setting

Settings inform WordPress that our theme will be using a value that can be modified by the user. They are added using the $wp_customize->add_setting() method that takes two parameters: the identifier for the setting and an array of options that contain information such as the default value.

The transport actually defaults to refresh but I’ve added it since we’ll be modifying it later on. Refresh means that when the setting is modified, WordPress should refresh the view. More sophisticated Customizer implementations allow for live previews that only modify the affected element as opposed to the whole page.

Creating a Control

Controls tie settings to user input. They are added with $wp_customize->add_control() method. Argument-wise this method is a bit more complex than the previous ones.

If the first argument is a control object then only one argument is required, an instance of the object. The object will likely have its own additional arguments.

The first argument can also be an identifier, in which case a second argument of options is required.

In our case we’ll be using the WP_Customize_Color_Control class to create a color selector element.

The first parameter of this object should be the $wp_customize object itself, the second should be the controls id. I tend to make this the same as the setting it controls. The third array contains some options like the label, the id of the section it will be placed in and the id of the setting it controls.

We now have a complete setting-control pair which will show up in our new section. It doesn’t do anything just yet, but the setting is there and its value is actually changing.

Color Setting In The Customizer
The color settings in the Customizer.

Generating The CSS

To make this actually work we’ll need to apply the value of the setting to our theme. In this case, we want to make sure that the body always has the background color value as our new setting.

Note that this code should not be placed inside the cd_customizer_settings() like we did with controls, sections and settings.

This is all pretty standard stuff, the only thing to note is how the value is retrieved. The get_theme_mod() function will retrieve the current theme’s settings; the first parameter is the name of the setting, the second is the default value.

The function can – of course – be used in the theme’s code to modify the functionality. We could – and soon will – create a control and setting that can be used to hide/display the button. We’ll use the get_theme_mod() will be used in the index.php file to selectively show/hide the button.

Live Previews

We’ve got a neat system but it would be a lot smoother if color changes and other edits would be instantaneous. Live previews allow us to use Javascript to selectively modify elements.

To get started, let’s create a customizer.js file and make sure it is enqueued.

The contents of this file should be a very simple closure, we’ll place all our code within it.

Next, make sure the value of the transport option of the setting is set to postMessage.

Finally, paste the following into the customizer.js file, within the closure.

The customize() function takes two parameters, the name of the setting to listen to, and a function that performs an action. The function in turn fires another function that binds the value of our setting and allows us to use it at our leisure. Here I’ve used it to modify the CSS of the body element. Colorful fun ensues:

Live Preview Color Change
Oooh… pretty colors!

Live Preview for Core Functionality

The ability to modify the title and blog description already exists due to the magic of core code. Let’s apply the live preview to these elements as well.

While we didn’t define these options and controls we do still have the means to modify them. We’ll use the get_setting() method from the customizer class to get and modify options for a setting.

The code above should be added within the cd_customizer_settings() function. The final step is to add the Javascript code that will be fired whenever the setting’s value is changed.

At the end of this process you should see the blog title and description update as you type.

Updating Text With The Customizer
Updating Text With The Customizer

Further Examples

There is so much you can do with the customizer, I thought it would be a good idea to include some more examples. Let’s begin with some controls that govern the behavior of the button.

Showing/Hiding Sections

To show/hide an element I’ve chosen to create a radio button element. We’ll be using two parameters for the add_control() which means that the first one is a simple string, not a control object. The second parameter will have all the details the control needs to build the UI. Here’s the full code which should be placed in the cd_customizer_settings() function.

In index.php I wrap the button in a conditional statement that checks the value of the setting and displays the button appropriately.

Note that for now I’ve set the transport method to refresh. When the button is hidden it is not loaded at all on the page so we’d need to do more than just show/hide an element via JavaScript. We’ll learn how to do this even better soon!

Showing And Hiding A Button With The Customizer
Showing and hiding a button with the Customizer.

Text Modifications

Continuing on with our button modifications, let’s make the text editable. We already have the button section, all we need is a setting and a simple text field control.

To build the option into the theme we’ll replace the hard-coded text with the get_theme_mod() function and define an appropriate default.

Finally, lets take care of the live preview in the customizer.js file.

Using Partials and Edit Shortcuts

When we looked at the button display option we used refresh because it seemed that using JavaScript alone wasn’t really possible. When the button is hidden it isn’t loaded, so we can’t simply show it with Javascript by making it visible.

This is where partials come in. They allow you to write more modular code that lends itself to theme creation and customization alike. Instead of refreshing the whole page when the element changes, you can refresh that single element.

Let’s start by generating our button with the help of a function. I’ve created the cd_show_main_button() and used it in the main index file, wrapping it in a container.

The function itself is exactly like our code looked before but it can now be reused elsewhere.

The last step is telling WordPress to selectively refresh the element. Set the transport property of the cd_button_display setting to postMessage and add the following within the cd_customizer_settings() function.

This tells WordPress that we want to selectively refresh when the cd_button_display setting changes. The selector within which we want to refresh everything is given in the second argument and the function that generates the content is also defined.

If you try the Customizer now you’ll see that the button becomes opaque, then loads the correct content, as opposed the whole site being refreshed.

The good news is that edit shortcuts will be added automatically for you. In fact, if you simply need edit shortcuts, this is the way to go.

Adding a Range Slider

The customizer has plenty of controls, from simple text fields to image uploads. If you’re working on a large-scale application you may need fancier inputs like a range slider, or even something completely custom.

The Customizer allows you to create your own UI elements easily by defining control classes. Let’s create our own range slider that enables users to select values with a little handle mechanism. Let’s build the control:

We must first check for the existence of the WP_Customize_Control class because it isn’t always loaded when all our options are. We then extend the class with our own, declaring the $type property and the render_content() function. We need to output an HTML control, taking care to use $this->value() when we need the current value and $this->link() in place of the name parameter.

I’ve created a very simple slider implementation with a bit of jQuery magic to make sure the value is visible in a text field and modifying the text field will also affect the slider.

I added some options (min, max, step) to the slider which I assigned to properties in the constructor.

To test it out I’ll create a little counter that shows the number of photos currently on the site. In the index.php file I’m adding the following.

Now it’s time to create the setting and the control. The control will use our newly created range slider.

Creating the live preview is almost trivial now, all I need to do is make sure the correct element get overwritten by the JavaScript code.

Theme Customizer Slider
The theme Customizer slider in action.

Get Customizing!

You should now be able to work within the theme customizer to create better controls for your themes. It’s extremely important to make theme usage easy and intuitive and the customizer provides a great foundation for that.

Reading List

If you’d like to get up to speed on everything that is the theme customizer take a look at the following links:

Daniel Pataki
Have you created any great custom controls or a full Customizer experience? Let us know in the comments below!