Hostingheaderbarlogoj
Join InMotion Hosting for $3.49/mo & get a year on Tuts+ FREE (worth $180). Start today.
Advertisement

A Guide to the WordPress Theme Customizer: A Methodology for Sections, Settings, and Controls – Part 2

by
Gift

Want a free year on Tuts+ (worth $180)? Start an InMotion Hosting plan for $3.49/mo.

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 1
A Guide to the WordPress Theme Customizer: Advanced Controls

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.


A Reminder of Our Methodology

Recall from the last article, that our methodology is as follows:

  1. Define a Section
  2. Add a Setting to the Section
  3. Add a Control for the Setting
  4. Write the necessary JavaScript
  5. Make necessary calls To get_theme_mod

We'll be doing this for each of the new controls on the following settings and controls. When necessary, we'll talk about data validation and sanitization as needed.

Once we've reached the end of the article, a version of this article's code will also be available for download from GitHub.


Change the Color Scheme

Let's add a new option to the Theme Customizer that allows the user to choose between color schemes - one is the default black on white color scheme, the other will be the inverse.

1. Add a Setting to the Section

To do this, first we need to add a setting and a control to our tcx_register_theme_customizer function. Add the following two function calls below:

$wp_customize->add_setting(
	'tcx_color_scheme',
	array(
		'default'   => 'normal',
		'transport' => 'postMessage'
	)
);

$wp_customize->add_control(
	'tcx_color_scheme',
	array(
		'section'  => 'tcx_display_options',
		'label'    => 'Color Scheme',
		'type'     => 'radio',
		'choices'  => array(
			'normal'    => 'Normal',
			'inverse'   => 'Inverse'
		)
	)
);

Notice above that we're adding a new setting identified by the tcx_color_scheme ID and we're obviously using the postMessage transport type.

Secondly, notice that we've also provided a default value that's set to normal. This value is what brings us to the add_control call.

2. Add a Control for the Setting

Notice that we're binding it to the tcx_display_options that we defined in the last article. We've given it the label Color Scheme since that's obviously what it is that we're changing, and we're setting the type of control as a radio button.

In order to do this, we need to pass an array of choices where the first key is the value of the option and the second value is the label for the radio button.

This is why the default value for the add_setting call is set to normal.

Now, we should be able to save our work, refresh the Theme Customizer, and then see the new option.

But at this point, it still won't do much.

3. Write the Necessary JavaScript

Now, we need to hop over into js/theme-customizer.js and add the following block of code:

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

		if ( 'inverse' === to ) {

			$( 'body' ).css({
				background: '#000',
				color:      '#fff'
			});

		} else {

			$( 'body' ).css({
				background: '#fff',
				color:      '#000'
			});

		}

	});
});

This instructs the Theme Customizer to change the body's background color and the font color based on the setting of the radio buttons.

By implementing this code, you should be able to refresh the Theme Customizer and then see the changes occur. The thing is, the values aren't actually saved to the database.

4. Make the Necessary Calls to get_theme_mod

The final thing that we need to implement in order to make sure the data is read from the database to change the color scheme is add a style to the style block in the tcx_customizer_css function:

<?php if ( 'normal' === get_theme_mod( 'tcx_color_scheme' ) ) { ?>

	background: #000;
	color:      #fff;

<?php } else { ?>

	background: #fff;
	color:      #000;

<?php } // end if/else ?>
}

Easy enough to understand, right? It works the exact same way as our JavaScript code does except it actually applies to the theme when the page loads rather than just when previewing it.


Change the Font

Now, we'll continue the process by introducing another setting and another control using our methodology such that our users will be able to select a global font for their theme.

To do this, we'll be using a select element with a set of options from which the user can choose their desired front.

At this point, the methodology should be becoming very familiar.

1. Add a Setting To The Section

First, we'll define a setting for the tcx_font that we'll use to reference throughout the code a bit later:

$wp_customize->add_setting(
	'tcx_font',
	array(
		'default'   => 'times',
		'transport' => 'postMessage'
	)
);

Just like with the previous setting, we're provided default value that we'll be defining momentarily when we implement a new control.

2. Add a Control For The Setting

As previously mentioned, we're going to be giving the users the ability to select a font using a select element. This is very similar to how radio buttons work in that we'll provide an array with keys and values that define the font; however, the actual type of the element will be different.

So with that said, add the following code to the tcx_register_theme_customizer function:

$wp_customize->add_control(
	'tcx_font',
	array(
		'section'  => 'tcx_display_options',
		'label'    => 'Theme Font',
		'type'     => 'select',
		'choices'  => array(
			'times'     => 'Times New Roman',
			'arial'     => 'Arial',
			'courier'   => 'Courier New'
		)
	)
);

This will introduce a select element into the Theme Customizer with the following three options for fonts:

  1. Times New Roman
  2. Arial
  3. Courier New

And now, we need to write up the font options so that they dynamically change the font of the theme.

3. Write The Necessary JavaScript

To do this, open js/theme-customizer.js and then add the following block of code. Note that this is going to be a little more complicated than what we're used to doing in the Theme Customizer JavaScript.

First, make sure that you have var sFont defined at the top of the JavaScript file just above the first call to wp.customize.

Next, add the following block of code:

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

		switch( to.toString().toLowerCase() ) {

			case 'times':
				sFont = 'Times New Roman';
				break;

			case 'arial':
				sFont = 'Arial';
				break;

			case 'courier':
				sFont = 'Courier New, Courier';
				break;

			case 'helvetica':
				sFont = 'Helvetica';
				break;

			default:
				sFont = 'Times New Roman';
				break;

		}

		$( 'body' ).css({
			fontFamily: sFont
		});

	});

});

Though the function is slightly longer, it's actually quite simple: We're taking the incoming value and then using a switch/case to determine which font was selected. Based on the selected value, we're assigning it to the sFont variable.

And, for defensive coding purposes, if one isn't defined or something goes wrong during the transport, then we are going to default to Times New Roman.

Finally, the then apply the value of sFont to the font-family attribute of the body element using jQuery's css function.

4. Make The Necessary Calls To get_theme_mod

Now, in keeping consistent with our methodology, we need to update our tcx_customizer_css function so that the font is properly applied to the body.

This is actually a simple call:

font-family: <?php echo get_theme_mod( 'tcx_font' ); ?>

Done.


Customize The Copyright Message

Finally, let's allow the user to adjust the copyright message that appears at the bottom of the footer template.

Let's adjust the template now. Currently, it should look like this:

<div id="footer">
	&copy; <?php echo date( 'Y' ); ?> <?php bloginfo( 'title' ); ?> All Rights Reserved
</div><!-- /#footer -->

But let's update it to look like this:

<div id="footer">
	&copy; <?php echo date( 'Y' ); ?> <?php bloginfo( 'title' ); ?> <span id="copyright-message"><?php echo get_theme_mod( 'tcx_footer_copyright_message' ); ?></span>
</div><!-- /#footer -->

Though this is getting a little ahead of our methodology, it's necessary for us to define so that the Theme Customizer can take advantage of the new span element, and so that we can display the copyright message as defined by the user.

1. Add a Setting To The Section

First, we'll introduce our final setting:

$wp_customize->add_setting(
	'tcx_footer_copyright_text',
	array(
		'default'            => 'All Rights Reserved',
		'sanitize_callback'  => 'tcx_sanitize_copyright',
		'transport'          => 'postMessage'
	)
);

But notice here, there's one thing that's different than the previous inputs and that's the "sanitize_callback" key and value. This defines a function to fire when the data is being serialized to database - after all, we don't illegal content making it into the database.

So, do to this, we'll define a function called tcx_sanitize_copyright that will strip out any tags, slashes, and other illegal tags that should be serialized to the database:

function tcx_sanitize_copyright( $input ) {
	return strip_tags( stripslashes( $input ) );
}

We simply return the value of the sanitized input.

2. Add a Control For The Setting

Next, it's time to add the actual control for the setting.

$wp_customize->add_control(
	'tcx_footer_copyright_text',
	array(
		'section'  => 'tcx_display_options',
		'label'    => 'Copyright Message',
		'type'     => 'text'
	)
);

Here, again, we're binding it to the tcx_display_options section and we're giving it the label "Copyright Message" for the users to be table to read. Finally, we've defined this as a text input.

Of course, at this point in time, you know that we're unable to actually do anything with the control until we've wired it to the JavaScript.

3. Write The Necessary JavaScript

The JavaScript for this is very easy, especially if you've given the span element a unique ID as we did above.

wp.customize( 'tcx_footer_copyright_text', function( value ) {
	value.bind( function( to ) {
		$( '#copyright-message' ).text( to );
	});
});

Essentially, it takes the value of the to argument and then sets it as the value of the span's text.

4. Make The Necessary Calls To get_theme_mod

And finally, though we've already done it in the template, we'll go ahead and review the code here:

<div id="footer">
	&copy; <?php echo date( 'Y' ); ?> <?php bloginfo( 'title' ); ?> <span id="copyright-message"><?php echo get_theme_mod( 'tcx_footer_copyright_text' ); ?></span>
</div><!-- /#footer -->

Notice that we're reading the value of tcx_footer_copyright_text and then we're printing that value out to the screen.


Up Next...

And for now, that's it! We've taken a look at some of the basic controls, given the user a significant amount of control over the look and feel of this albeit very basic theme, and we've covered how to introduce data sanitization along with the serialization process.

The only thing that's left to cover are some of the more advanced, built-in controls that WordPress offers. So in the next article, we'll take a look at some of those features and how to implement them, as well.

In the meantime, download the latest version of our theme, study it, customize it, and get ready for the next article!

Advertisement