Theme Development

A Guide to the WordPress Theme Customizer: Advanced Controls


Throughout this series, we've been taking a look at the Theme Customizer, how to implement it in our themes, how to save, serialization, retrieve settings, and how to implement the options so that they automatically refresh whenever the options are updated.

As we begin to wind down the series, we're going to be taking a look at the advanced controls offered by WordPress, and how to implement one of them in our theme. Then we'll be reviewing some of the resources that are available for those of you who opt to consider researching, implementing, and leveraging the Theme Customizer in your day-to-day work.

But first, let's begin by taking a look at some of the controls that are offered natively with WordPress.

Advanced Theme Customizer Controls

Perhaps a more suitable answer to theme particular controls is simply native Theme Customizer controls. The truth is that they are a set of controls that are bundled with WordPress that allow us to take advantage of them.

I'm simply referring to them as the advanced controls mainly because they offer more functionality than the usual set of select boxes, input elements, radio buttons, and checkboxes.

Note that at the time of writing this article, there isn't as much code documentation around some of the controls, but we'll do what we can to document each, show how to implement one of them, and then fill in the rest with the final article in the series.

The Plain Text Input

If you want to introduce the ability to implement an input box for capturing text - such as the site title and/or the site description - then you may be interested in using the WP_Customize_Control.

Though this isn't officially documented in the Codex, it's intended to be used to capture input from users in plain text. Note that if you opt to use a control like this, then you'll want to sanitize the data that's being saved to the database before actually saving it so that nothing dangerous is saved and ultimately retrieved.

Finally, for those who are object-oriented developers, then it's worth mentioning that this call is the base class for all controls that will be discussed throughout the rest of this article.

The Color Picker

The color picker is officially known as the WP_Customize_Color_Control. We saw this earlier in the series when we implemented the feature for selecting the color of the anchors in our theme.

WP Customize Color Control

In short, this allows us to select a color from the palette of available colors and then serialize the value to the database for retrieval later when using the theme.

Of course, this isn't limited to applying it globally to anchors or text, but it can be applied to anything with which you can access using a CSS selector.

The File Upload Control

One of the more common, yet potentially confusing, controls is the file upload control. You can find its page in the Codex at  WP_Customize_Upload_Control. Though there are other controls for uploading files such as images - one that we'll implement momentarily - this gives some flexibility in uploading a variety of different files.

That said, this control is typically implemented within the context of other controls - such as an Image Upload control - to make file uploads easier.

Of course, if there is a case in which you need to upload a more generic file such as a PDF, CSV, or something else, then the control provides a nice interface for doing so.

The Image Control

The WP_Customize_Image_Control is an easy way to implement functionality for allowing users to upload a generic image. Later in this article, we'll be implementing this control to upload a background image.

Of course, this control is more generic and can be used to upload other images for something such as a logo, an image for the footer, or something else.

The Background Image Control

The WP_Customize_Background_Image_Control is designed to let users upload a background image. This control complements the custom background functionality that was introduced in WordPress 3.4.

The control itself looks much like the other image upload control but it's designed specifically for implementing the background image.

The Header Image Control

Finally, the WP_Header_Image_Control is used - just the Image Control and the Background Image Control - to make it easier for users to upload header images.

The unique thing about this particular control is that it provides the ability for users to crop, resize, and manipulate the image just like the custom header functionality does that was introduced in WordPress 3.4.

Implementing an Advanced Control

Now that we've covered the advanced - or the native controls - let's implement the WP_Customize_Image_Control into our theme. This particular feature will require the following:

  • Introduce a new section called Advanced Controls
  • Add a new setting for the custom image
  • Use the image as the background image for the theme

Since we've already got our methodology in place, we can continue with introducing the new feature just as we've done with the past features, as well.

The New Section

In functions.php, add the following block of code:

		'title'     => 'Advanced Options',
		'priority'  => 201

This will introduce the Advanced Options section into the Theme Customizer, and its priority will place it directly below our previous section.

However, since we haven't actually implemented any sections or settings, the section won't show up in the customizer just yet.

The New Setting and the Control

Next, we'll introduce the new setting and we'll give it the tcx_background_image ID so that we can refer to it in functions.php, throughout the theme, and in the JavaScript.

To do this, add the follow right after the code that we defined above:

		'default'      => '',
		'transport'    => 'postMessage'

Notice that we've also defined the transport to be postMessage so that we can asynchronously show the changes as the user uploads an image.

Next, we need to add the control and bind it to the new setting. To do that, we'll add the following:

	new WP_Customize_Image_Control(
			'label'    => 'Background Image',
			'settings' => 'tcx_background_image',
			'section'  => 'tcx_advanced_options'

By this point, it should be clear exactly how we're wiring up controls, but to be clear we're connecting the control by setting its settings value equal to that of the setting, and the section value equal to that of the Advanced Settings section ID.

Hooking Up the JavaScript

Since we've defined the transport, let's now update theme-customizer.js element's background image.

wp.customize( 'tcx_background_image', function( value ) {
	value.bind( function( to ) {

		0 === $.trim( to ).length ?
			$( 'body' ).css( 'background-image', '' ) :
			$( 'body' ).css( 'background-image', 'url( ' + to + ')' );


Above, we're using the ternary operator to determine if the to parameter is an empty string. If it is an empty string, then we remove the background-image property; otherwise, we set it to the URL that's set to that variable.

Updating the Theme

The last thing that we need to do, is update the style block in the tcx_customizer_css function so that we can retrieve the background image after it has been serialized.

To do that, add the following code to the style block:

<?php if ( 0 < count( strlen( ( $background_image_url = get_theme_mod( 'tcx_background_image' ) ) ) ) ) { ?>
	background-image: url( <?php echo $background_image_url; ?> );
<?php } // end if ?>

Essentially, this does the exact same thing that the above JavaScript does: If the tcx_background_image value isn't empty, then we'll set its value equal to that of the background-image CSS property.

Up Next...

In the next article, we're going to review a collection of resources that provide a significantly advanced look at the WordPress Theme Customizer.

We'll also wrap up development of our theme, but until then you can download version 0.6.0 of the theme to take a look at the source code before we finish up in the next article.

Related Posts
  • Code
    Theme Development
    Custom Controls in the Theme CustomizerTheme customizer custom control 400
    In the last article, we explored the advanced controls available in the Theme Customizer, and how to implement them. We’re going to look at how to create our own custom control, allowing you to choose which Category of Posts are displayed on the home page. To get started, download version 0.6.0 of our Theme Customizer Example.Read More…
  • Code
    Creative Coding
    Using WordPress For Web Application Development: Available Features, Part 5 - Retrieving DataApplication foundation 400
    By now, you know that the purpose of this series is to demonstrate how WordPress can be used as a foundation for web application development. We started by taking a high-level look at many web application design patterns, how WordPress differs, and why WordPress should be considered to be more of a foundation rather than a framework.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: A Methodology for Sections, Settings, and Controls – Part 2Theme customizer 400
    In the last article, we defined a simple methodology for everything that's required to establish a new Section, Settings, and Controls within the Theme Customizer. In this article, we're going to continue with doing more of the same; however, we're going to be adding new settings and controls into the existing section, but we're going to be looking at a variety of different options such as radio buttons, select boxes, and input boxes. So with that said, let's continue.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: A Methodology for Sections, Settings, and Controls - Part 1Theme customizer 400
    At this point in the series, we've covered everything from understanding why the Theme Customizer is beneficial to those of us who are designers and developers, how to implement it in our theme, and understanding the relationship between sections, settings, and controls. We've also taken a look at how to implement our own setting and control into one of WordPress' predefined sections. In this article, we're going to take a look at what's required to introduce our own section and a variety of settings and controls. This article will cover a methodology that can be followed for implementing new settings and controls, and how to apply this methodology for introducing a new section, setting, and control. We'll expand on this topic in the second part of this article by introducing additional controls. But, for now, let's take a look at the methodology, and let's introduce a new setting into the Theme Customizer.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: Adding a New SettingTheme customizer 400
    By now, we've taken a look at what the Theme Customizer is, how it works, and the components that are unique to it. We've even discussed how options are serialized into the database so that we may retrieve them later when using our theme. To that end, it's time for us to begin doing our own work with the Theme Customizer. In this article, we're going to take a look at transports, how they work, and the difference in their two primary methods. Additionally, we're going to introduce our own control into one of WordPress' existing sections and see how it works with the various transport models.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: Sections, Settings, and ControlsTheme customizer 400
    In the last article, we created a very basic theme that included the Theme Customizer so that we could see how it looks within the context of the WordPress Dashboard. After tinkering around with the provided options, it's easy to see just how powerful this particular feature can be. Generally speaking, this single feature can allow us to steer users away from complicated options pages and allow them to see the result of their changes as soon as they make them without having to hop back and forth between the dashboard and the public-facing side of the site. And as much fun as it is to begin writing code to bring new features to life, it's important to understand what we're working with before we begin actually doing work with it, right? So in this article, we're going to take a survey at what goes into working with the WordPress Theme Customizer. By the time you finish this article, you should have a clear understanding of the Theme Customizer, and how to begin introducing your own settings into existing sections, creating new sections, as well as some of the built-in controls that are available for us to use in our work.Read More…