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.
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.
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.
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.
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
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.
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.
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
Finally, paste the following into the
customizer.js file, within the closure.
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 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
At the end of this process you should see the blog title and description update as you type.
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.
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
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
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
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
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.
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.
If you’d like to get up to speed on everything that is the theme customizer take a look at the following links:
- Theme Customizations API
- What’s new in WordPress 4.7
- Customizer Improvements in WordPress 4.7
- Customization API Control Reference
- Tools For Improved Customizer UX
- The Customize API
- WP_Customizer_Control documentation