Creating Cool Custom Controls for the WordPress Theme Customizer
In a recent article about creating theme options with the WordPress theme customizer, we looked at how you can use the Theme Customization API to create awesome WordPress-standard options to support your theme.
Today we’re going to take things to the next level and look at how we can add our own custom controls to the customizer.
By default, the only controls the API offers are text field, checkbox, radio, select and dropdown pages. By creating our own control class, we can step beyond these boundaries and create even more controls, including implementing number box, a page template selector, a Google Font selector, a yes/no button and even a range selector.
In this article, we’re going to create a simple text area and a more complex latest post selector.
Using Included Controls
WP_Customize_Control class is responsible for generating all the controls you see in the theme customizer. When you use the basic set (text field, checkbox, etc.) you don’t have to use this class, it is abstracted away.
As a reminder, let’s take a look at how to create a simple control. For more information about where to put this code, check out our customization API tutorial mentioned above.
There is no trace of
WP_Customize_Control here. WordPress creates the object for you, and as the Codex puts it:
Alternatively, it is not required to instantiate a WP_Customize_Control object. WordPress will check to see if you are passing in an object and, if absent, will create a new WP_Customize_Control object with the arguments you have passed in.
Based on this, the following code is equivalent to the snippet above, but it uses
To create our own controls we can extend the
WP_Customize_Control class, adding some of our own functions. Let’s make one together, a simple text box which is – surprisingly – not available by default. Thanks to the theme customizer snippets for this example.
One question I get asked a lot is how do we know which functions need to be defined? The simple answer to that is to look at a few examples others have written. The more complex one involves looking at the source code for the base class. If you have a look in the WordPress Github Repo you can see the code for this class.
For example, in the base class the public variable
$type is defined as
text. Looking at the code of the class there is no setter method which has the task of setting the value of this property. This is why, when extending the class, we define it ourselves. The
render_content() method defines controls, which is why the example above has added this function.
It’s important to note that
$this->value() can be used to retrieve the value of the setting we are manipulating.
There are others methods we can – and will – use to enqueue styles and do other tidbits, but for our simple example will suffice.
Once we have defined our textarea control type we can now use it in a control like so:
Latest Posts Dropdown
So let’s take what you’ve learned so far and create another relatively simple control. This time, we’re going to create a dropdown that lists our latest 10 posts:
Here’s what our dropdown looks like on the frontend:
The process is much the same, the only addition here is a custom loop used to display the posts. One way we could improve our work considerably is to easily modify the posts in the query. We could use this same control to show pages, or draft posts or even custom post types. Let’s modify how we add our control and then update our class to work:
To use this new post type control we must define it as a public variable in our class. The way the base class (
WP_Customize_Control) works is that it looks at the defined variables and parses all data from the given arguments into them.
As a result, we only need to modify two lines in our class. Keep an eye out for the definition of the post type variable at the top and the usage of
$this->post_type in our query:
Creating custom controls takes a bit of extra time, but don’t forget that the better your controls, the more time you save for your users. Saving a minute of time for a single user could translate to hundreds of hours if your theme has a couple of thousand downloads.
Ultimately, the goal should be to create controls that fit a specific setting. If you need to select a range, why create two text fields when a jQuery range slider could do the job much better?
If you’d like to get your hands on some great custom controls, Paul Underwood has kindly released 12 custom controls. Use these to your heart’s content!
Have you created custom controls? Share your ideas in the comments below.