Advertisement

A Guide to the WordPress Theme Customizer: Advanced Controls

by
This post is part of a series called A Guide to the WordPress Theme Customizer.
A Guide to the WordPress Theme Customizer: A Methodology for Sections, Settings, and Controls – Part 2

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:

$wp_customize->add_section(
	'tcx_advanced_options',
	array(
		'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:

$wp_customize->add_setting(
	'tcx_background_image',
	array(
		'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:

$wp_customize->add_control(
	new WP_Customize_Image_Control(
		$wp_customize,
		'tcx_background_image',
		array(
			'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.

Advertisement