Customizing Client Options Using the Theme Customizer

The WordPress Theme Customization API is one of my favorite built-in features. It gives users the ability to customize theme functionality and design based on what’s built into a given theme.

For theme developers, it’s one hell of a tool for taking themes to the next level. It’s even better for developers who create themes for individual clients. It allows them to make theme options extremely specific to the user’s needs.

Before reading this article, it’s important to understand how the theme customizer works… that way you know exactly what it can do for your theme.

For more information on how to set up the customizer, check out the How to Set Up the WordPress Theme Customizer article.

With that under your belt, let’s talk about building highly specified customizer options that make life easier for the end user.

Adjusting Default Customizer Sections

There are default sections that are almost always in the theme customizer.

  • Site Title & Tagline
  • Static Front Page
  • Menus

You may see other sections on basic themes here and there, but most of them are a result of other code placed into the theme.

For the three above sections, Site Title & Tagline and Static Front Page are always there while Menus is there as long as there’s at least one registered menu in the theme.

One of the first things you may want to do when building the customizer for a client is adjust these default sections before building your custom ones.

Let’s do that now for the Site Title & Tagline section.

Adjust the Section Title

User’s love logo uploaders… plain and simple. It’s probably one of the first things to get customized every time a new theme is installed.

I like to add a logo uploader to my Site Title & Tagline section, which we’ll go over later. But once that’s done, I feel like the title of that section is no longer an accurate description of what the section is used for.

I’d rather it read Site Title, Logo, & Tagline.

So in your customizer function, it’s important to know how to adjust those default titles, considering you didn’t write the code that set them. Here’s how it’s done.

$wp_customize->get_section( 'title_tagline' )->title = __( 'Site Title, Logo, & Tagline', 'bwpy' );

That one line of code does the job. It uses the get_section() method to set the section title equal to a string of your choice.

The key to targeting this specific section is the parameter in the method which specifies the section ID – title_tagline.

Here are the default section IDs.

Site Title & Taglinetitle_tagline
Static Front Pagestatic_front_page

Note: I would not suggest editing the Menus section as of WordPress 4.3. It is now more than just a way to set menus to menu locations. It is not the complete menu configuration area and therefor should be consistent across all WordPress installations.

Adjust the titles of any of those default sections by using the code snippet above with the correct section ID. Ensure that your section titles make sense based on the options you’ve added to them.

Speaking of adding options to default sections, let’s do it.

Add New Controls

As stated above, we’re going to add a logo uploader to our Site Title & Tagline section, now known as Site Title, Logo, & Tagline.

To add a control to a default section, again, knowing the section ID is important. Here’s what we’ll use.

// logo uploader
$wp_customize->add_setting( 'bwpy_logo', array( 'default' => null ) );
$wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'bwpy_logo', array(
	'label'		=> __( 'Custom Site Logo (replaces title)', 'bwpy' ),
	'section'	=> 'title_tagline',
	'settings'	=> 'bwpy_logo',
	'priority'	=> 20
) ) );

As you learned in the article on setting up the customizer, you have to have a section, setting, and control for each option you build.

Well, we already have our section – title_tagline. So what we did above was create a new setting with an ID of bwpy_logo and link that to our new control, titled “Custom Site Logo (replaces title).”

Like the section title snippet, this code goes into our customizer function. Just that easy, it adds an image uploader to the Site Title, Logo, & Tagline section.

You’ll notice that we specified a priority for our new control. Why?

Well, it only makes sense that the logo uploader appear below the “Site Title” field, and above the “Tagline” field since it interacts with the site title. So the uploader gets a priority of 20 and now we’ll adjust the default priorities of the Site Title and Tagline fields to 10 and 30, respectively.

Adjust the Order of Controls

This part is very similar to the adjustment of the section title. But instead of using the get_section() method to target a default section, we’ll use the get_control() method to target a default method. And again, we need to know the ID of the setting/control we’re targeting.

$wp_customize->get_control( 'blogname' )->priority = 10;

That’ll give the Site Title control, indicated by its ID of blogname, a new priority of 10.

We already gave our uploader a priority of 20. So now let’s adjust the Tagline field to be below that.

$wp_customize->get_control( 'blogdescription' )->priority = 30;

That’ll give the Tagline control, indicated by its ID of blogdescription, a new priority of 30.

site-title-logo-tagline

Now that’s all fine and dandy. The customizer options look cool. But our new control isn’t very useful yet. We need to set it up so that when an image is uploaded, it replaces the site title. Then, when the image is removed, the site title reappears.

To do that, we need to go to the template file that outputs the site title. For most themes, that’ll be a template file called header.php.

Here’s an example of what most site title code will look like.

<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
	<?php bloginfo( 'name' ); ?>
</a>

What we need to do is create a conditional using the data saved (or not saved) by our logo uploader that basically says, “If a logo image has been uploaded, output it using this HTML. Otherwise, output the site title.”

Here’s what we’ll use.

<?php if ( get_theme_mod( 'bwpy_logo' ) ) : ?>
	<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
		<img src="<?php echo get_theme_mod( 'bwpy_logo' ); ?>" alt="<?php echo get_bloginfo('name'); ?>">
	</a>
<?php else : ?>
	<a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home">
		<?php bloginfo( 'name' ); ?>
	</a>
<?php endif; ?>

Very simple logic here… if our bwpy_logo option has data saved to it, which would be the URL of the image, output the image. Otherwise, output our original site title HTML.

We’re good to go there. The last thing we may want to do to now that our section customization is complete is reorder it in relation to the rest of our sections that we might create. That’s easy too.

Adjust the Section Priority

Just like we adjusted the section title, we can adjust the section priority. Here’s how.

$wp_customize->get_section( 'title_tagline' )->priority = 50;

We used the get_section() method again to target the priority and adjust it. This is extremely handy as you create your own new sections and give them a priority. As long as you know the section IDs of the default sections, you can order your new sections to logically mix with them… as you should.

With the above knowledge under your belt, let’s move on to some control techniques for user focused customizer options.

Excerpts or Full Posts

One of my favorite options to build is a checkbox that allows users to toggle between displaying excerpts and full posts on their blog.

Here’s the code we’ll use to build a new section called “Content Options.” In that section, we’ll add a checkbox control that let’s us toggle between excerpts [checked] and full posts [unchecked].

function bwpy_customizer( $wp_customize ) {

	// add "Content Options" section
	$wp_customize->add_section( 'bwpy_content_options_section' , array(
		'title'      => __( 'Content Options', 'bwpy' ),
		'priority'   => 50,
	) );
	
	// add setting for excerpts/full posts toggle
	$wp_customize->add_setting( 'bwpy_excerpts', array( 
		'default' => 1 
	) );
	
	// add checkbox control for excerpts/full posts toggle
	$wp_customize->add_control( 'bwpy_excerpts', array(
		'label'     => __( 'Show post excerpts?', 'bwpy' ),
		'section'   => 'bwpy_content_options_section',
		'priority'  => 10,
		'type'      => 'checkbox'
	) );
}
add_action( 'customize_register', 'bwpy_customizer' );

With that code in place, we have a new section in our customizer that has one checkbox control labeled “Show post excerpts?” and checked by default.

Now in the theme files, we have to create a conditional that outputs either the_excerpt() or the_content() based on whether or not the box is checked.

Find your theme template file responsible for outputting posts on your blog home and then find the code that either outputs excerpts or the content.

Replace it with a conditional along these lines.

if ( get_theme_mod( 'bwpy_excerpts' ) == 1 ) :
    the_excerpt();
else :
	the_content();
endif;

Checkbox options are true boolean options. You either have one value or another… checked or unchecked. Checked equals “1” while unchecked equals “0.”

That said, our conditional simply checks to see if our control value equals “1” (checked) and if so, calls the the_excerpt() function. Otherwise, it calls the the_content() function because the only other option that could be selected is “0,” unchecked.

WordPress Page Comments

Typically, only single WordPress posts host comments. However, comment functionality can easily be used on pages.

Because it’s not ideal, I like to offer page comments as an option. Here’s the code I use to add it to the customizer under the same section I created above (so this will just include the setting and control, not a new section).

$wp_customize->add_setting( 'bwpy_page_comments', array( 'default' => 0 ) );
$wp_customize->add_control( 'bwpy_page_comments', array(
	'label'		=> __( 'Display Comments on Standard Pages?', 'bwpy' ),
	'section'	=> 'bwpy_content_section',
	'priority'	=> 20,
	'type'      => 'checkbox',
) );

Our new setting/control is a checkbox that has an ID of bwpy_page_comments and a default value of “0” which is unchecked.

With a priority of 20, this checkbox displays below our post excerpt option. Now we just have to adjust the theme to respect our new option.

On your theme’s page template (usually page.php) the comments are usually output with something like this.

if ( comments_open() || '0' != get_comments_number() ) :
	comments_template();
endif;

Though we could just hack into the conditional you already see there, for the purpose of clarity we will just wrap the entire block of code in our new conditional based on the page comments options.

if ( get_theme_mod( 'bwpy_page_comments' ) == 1 ) :
	if ( comments_open() || '0' != get_comments_number() ) :
		comments_template();
	endif;
endif;

Now if our option is checked, which equals a value of 1, the comments template will show. If the value does not equal 1, which leaves nothing but 0 (unchecked), the condition is not met and the comments will not show.

Add Body Classes Based On Option

Another thing I like to do is add classes to the <body> of the theme using customizer options.

Understand that with each option you create, you can do multiple things my sources. So if you have an option that removes the sidebar from single posts, you can also make that very same option add a class of “no-sidebar” to the body.

That said, here’s how you’d use an option’s value to do its original job and add a class to the body.

Assuming your customizer option is already built and it’s a checkbox with an ID of bwpy_remove_sidebar, you’d wrap the call to the sidebar in a conditional in your single.php file like so.

if ( get_theme_mod( 'bwpy_remove_sidebar' ) != 1 ) : 
	get_sidebar();
endif;

That code simply says to call the sidebar template file only if our option is not checked.

With that in place, here’s what we’d use in our functions file to add a class to the body for when our option is checked.

if ( get_theme_mod( 'bwpy_remove_sidebar' ) == 1 ) :		
	$classes[] = 'no-sidebar';
endif;

Simple stuff, right?

The Bottom Line About Customizer Options

The thing to understand is that customizer options save values and those values can be used to follow any type of PHP logic you’d like.

Combine them with WordPress Conditional Tags, basic PHP functionality, or whatever you’d like to customize the theme in a way that makes things easier on the user.

That’s the goal here. Use common sense and your own usage habits to determine what makes sense and what doesn’t.

Then, with a limitless mindset, customize your options to meet the needs of your client. The customizer is so easy to build with, there’s no reason why users shouldn’t get a unique experience.

3 Comments:
  1. Thanks for these posts about using the theme customizer they have helped me a lot and given me ideas of things I could add to my theme

Leave a Reply

Your email address will not be published. Required fields are marked *

*