It used to be that if you wanted to give users of your themes a way to customize aspects of their site or the theme, you’d create a theme options page. But now the best way (and the expected method for themes submitted to the theme directory) is to make use of the Customizer.

This is the second post in our WordPress Development for Intermediate Users series. This series follows on from our popular WordPress Development for Beginners tutorials, which introduced you to the fundamentals of developing websites with WordPress, how to get started coding with PHP, and building themes and plugins.

In this tutorial, I’ll show you how to add Customizer functionality to your theme. We’ll cover:

  • An overview of the Customizer and its default settings,
  • The hooks and functions you need to use to interact with the Customizer,
  • Adding sections to the Customizer,
  • Adding controls to your sections, including color, text and radio buttons, and
  • Implementing user inputs in your theme with settings.

We’ll also look at how you can let your users add text to their site and also how they can amend the styling by using a color picker in the Customizer.

Note: It’s important that you have a working knowledge of PHP as this is the foundational language of WordPress and I’ll be referring to code snippets throughout this series.

Let’s get started.

That’s right, tons of WordPress knowledge, peer review, instructor feedback and certification, for free for WPMU DEV membersStart Learning

What You’ll Need

To follow along with this part of the series, you’ll need a theme to work with. You can either use your own theme (which means you’ll need to adapt my code to make it work with your theme) or you can use the theme you worked on in part 1 of this series. If you want, you can download the final theme from Part 1 which is in the source files for this course.

You’ll also need a development site to work with (maybe on your local machine) and a code editor. Need some tips? Here’s how to set up a local environment on Windows, and how to do it on a Mac. You might also want to check out our guide 24 Best Text Editors for WordPress Developers.

What is the Customizer?

If you’ve developed your WordPress knowledge to the point that you’re studying this course, you should have used the Customizer before so you won’t need much of an introduction. The Customizer lets site admins make changes to the content or design of a site, as well as to add widgets, menus etc., with a live preview showing what’s happening as they work.

Here’s what the Customizer looks like for my demo site right now:

the default customizer

It’s currently got four default sections:

  • Site Identity – Where you can edit the site title and description.
  • Menus – Where you can add and edit menus.
  • Widgets – For adding widgets to the registered widget areas.
  • Static Front Page – Use this to set a static page as the home page.

These are added by WordPress and not by the theme – our theme doesn’t have any Customizer sections or controls added yet. In this part of the series, we’ll add two sections – one for header content and the other for colors.

The Classes, Hooks and Methods Used by the Customizer

The Customizer has its own API, with various classes, hooks and functions you’ll need to interact with and make use of to add Customizer functionality to your theme. Let’s take a look at some of these:

  • The customize_register action hook is the one you need to use to access the Customizer. Most of your Customizer functions need to be hooked to this.
  • You might also use the wp_head hook to add custom styling to the section of your site based on the settings in the Customizer – we’ll do that with colors in this part of the course.
  • The WP_Customize_Manager class defines how Customizer settings, controls and sections work. You use methods from this class when interacting with the Customizer.
  • There are also classes which apply to specific types of control, defining how they work by default. These include WP_Customize_Color_Control and  WP_Customize_Control classes. You can create your own class to extend these and define custom versions of the controls you’ll be using in your theme.
  • For creating sections, you use the $wp_customize->add_section() method. I’ll show you the parameters for this as we work through the process of adding it.
  • To add a control, you use the $wp_customize->add_control() method.
  • To add a setting which enables the control to do something in your them, use the $wp_customize->add_setting() method.

Note that the last three methods I’ve described are methods rather than functions because they are methods of a class, not standalone functions.

We’ll work through each of these as we set up Customizer sections, controls and settings in this part of the course.

Getting Started: Creating an Include File for the Customizer

Before we start adding code for the Customizer, let’s add a file containing all of the code. Instead of adding this to the theme’s functions.php file, let’s create an include file.

  1. In your theme folder, create a folder called includes.
  2. Inside that, create an empty file called customizer.php.
  3. Open your functions.php file. At the top, add this:
    .gist table { margin-bottom: 0; }
  4. Save and close your functions file.

Next, let’s start working in the new customizer.php file.

  1. Open your new customizer.php file and add an opening <?php tag to it.
  2. Below that, add this:
    .gist table { margin-bottom: 0; }
  3. Save the file.

You’re ready to get started.

Adding Sections

First, let’s add a couple of sections to contain our controls.

  1. Inside the wpmu_customize_register() function you’ve just added, type this:
    .gist table { margin-bottom: 0; }
    This adds the section for contact details, which we’re going to add to the header.
  2. Now below that, add this:
    .gist table { margin-bottom: 0; }
  3. Save the file.

If you go back to your site and take a look at the Customizer, you’ll find that no new sections have been added. Don’t worry! This is because if there are no controls inside your sections, WordPress doesn’t display them. Next, we’ll add those controls.

Adding Controls and Settings

Now we have sections in place, we need to add controls and settings to them. Let’s start with text controls.

Adding Text Controls and Settings

Firstly, let’s set up our own class with a generic text control. This means we don’t need to define our text control every time we add a new one.

  1. Inside your function, below the setting you just added, type this:
    .gist table { margin-bottom: 0; }
  2. Save your file.

That’s our default control set up. We’ll use this next when defining each of our text controls. We’re going to add three: address, telephone number and email address. Later on we’ll output each of these in the theme’s header.

  1. Below the class you just defined, add the code for the address text area:
    .gist table { margin-bottom: 0; }
  2. Next, add the code for the phone number:
    .gist table { margin-bottom: 0; }
  3. Finally, add the email address text area:
    .gist table { margin-bottom: 0; }
  4. Now save your file.

In each case, we’ve added two things: the setting and the control. The setting is what WordPress stores in the database, while the control is the interface that your users will type their text into.

The $wp_customize->add_setting() method has two parameters:

  • A unique ID for the setting
  • The default value

The $wp_customize->add_control() method has one parameter, new wpmu_Customize_Textarea_Control, which tells WordPress that we’re creating a new instance of the class we already created. The new class has three parameters:

  • $wp_customize, the object of this class.
  • A unique ID for the setting.
  • An array of values:
    • A label, which is ready for translation (more of which in a later part of this course).
    • The section which this control will be in.
    • The setting that it sends data to, which is the unique ID of the setting you already created.

Now if you go back to the Customizer in your site and refresh the screen, the Contact Details section will be displayed:

The Customizer with a contact details section added

And if you click through to that section, you’ll see your controls:

Text controls in the Customizer

At the moment, if you type anything into those controls they won’t show up in the site, but we’ll fix that in a bit. First, let’s add some controls to our second section.

Adding Color Controls and Settings

Next up, let’s add some color controls that site admins can use to amend the theme’s color scheme. Because we’re adding four controls here, I’m going to set up a $textcolors variable and then use that to work through each of the colors we want to add and create a control for each of them.

First, let’s set up that variable.

  1. Below the code you just added for the text controls, add this:
    .gist table { margin-bottom: 0; }
  2. Save the file.

This creates a $textcolors variable that contains an array of values: wpmu_color1, wpmu_color2, wpmu_links_color1 and wpmu_links_color2.  For each of these, there is another second level array, with the slug, the default color and the label.

Pat yourself on the back – you’ve just used a new PHP technique: Nested arrays inside a variable!

Now, let’s create the controls. Instead of creating a new one for each of our four colors, we’ll use foreach() to loop through the four colors we’ve already defined in our variable.

  1. Below the code you just added to set up the variable, add this:
    .gist table { margin-bottom: 0; }
  2. Save your file.

This loops through each of our colors and adds the following:

  • A setting, with two parameters:
    • The unique ID, which uses the slug from the variable array
    • An array of values including the default value, again taken from the variable array, and the type of control, which is an option.
  • A control, using new WP_Customize_Color_Control with three parameters:
    • $wp_customize
    • The unique ID, using the slug
    • In an array, the label, section and setting.

This is very similar to what we did for the text controls but uses values from the array we already defined using the $textcolors variable. If you want to, you might want to try going back and applying the same technique to the text controls and settings you already added.

Now take a look at the Customizer in your site. You’ll see a Color Scheme section with four color controls:

the color controls section in the Cusotmizer

As with the text controls, if you pick a new color using the color picker it won’t make any difference to your site yet. So let’s go ahead and change that.

Implementing Customizer Controls and Settings in the Theme

Adding controls and settings to the Customizer is a great first step, but you need to get them to work, which means adding code to your theme which will take the values for your settings that WordPress saves in the database, and outputting them in your theme.

We need to do two things:

  • For the contact details, add a hook to the header where we can output the text.
  • For the colors, create styling which we hook to the wp_head hook to amend color values for given classes in the theme.

First, the contact details.

Adding Text to the Theme

We write the function which outputs text in our customizer.php file, inside a function which we’ll hook to an action hook. That means we need to create another action hook in our theme, inside the header.

  1. Open your theme’s header.php file.
  2. Find the 
    line, and add this immediately below it:
    .gist table { margin-bottom: 0; }
  3. Save and close the header.php file.

Now we have a hook that we can hook our function to. Let’s create that function.

  1. In customizer.php, add the empty function:
    .gist table { margin-bottom: 0; }
  2. Inside your function, add the following:
    .gist table { margin-bottom: 0; }
  3. Save the file.

This has added four things to the markup:

  • An address element containing everything else
  • A paragraph with the address
  • A paragraph with the phone number
  • A paragraph with the email address, inside a link to that address.

To do this, we’ve used the get_theme_mod() function, which fetches the data stored against the relevant setting by the Customizer. This has two parameters: The ID of the setting and a default value.

Now, if you look at your site you’ll see the default text in the header:

contact details displayed in the header of the live site

Because the text inside the element with the header-right class has right alignment already defined by the theme’s stylesheet, our text is already aligned correctly for us. You might want to adjust the margin underneath the in header widget area to add some space under that search box (or maybe adjust the margin below the containing header element).

Now try editing the text in the Customizer:

editing contact details in the customizer

Adding Styling to the Theme

Next, let’s create the function for the color scheme. Before adding the code, let’s identify what we want to target for each color.

  • The first color (wpmu_color1) will apply to headings, links in the navigation menu and the footer background.
  • The second color will apply to the navigation background.
  • The third color will apply to links which in the link or visited states.
  • The fourth color will apply to links in the hover or active states.

You might want to apply your color scheme to different elements, or add more colors for additional elements or classes. Before we add the styling, we need to create the function.

  1. In customizer.php, add this function:
    .gist table { margin-bottom: 0; }
  2. Save the file.

This is hooked to the wp_head action hook, so the contents of the function will be added to the section of each page. This isn’t ideal, as adding CSS to each page isn’t as good practice as using a stylesheet. But this is the only way to do it, because each color is added by a function, and you can’t code PHP functions into a stylesheet.

Note that I’ve added an opening <?php tag at the end of my function but not at the beginning. This is because I’ll be adding a closing tag inside the function – read on and it will make sense.

Now, let’s create a variable for each of the colors.

  1. Inside your function, add this:
    .gist table { margin-bottom: 0; }
  2. Save the file.

So we now have four variables we can use to define colors inside a element. Let’s add that.

  1. Below your variables, but still inside the function, add this:
    .gist table { margin-bottom: 0; }
    There’s that closing PHP tag, followed by a element for our styles.
  2. Next, add the styling for the first color:
    .gist table { margin-bottom: 0; }
  3. Now the second color:
    .gist table { margin-bottom: 0; }
  4. And finally, the two link colors:
    .gist table { margin-bottom: 0; }
  5. Save the file.

You might want to make some tweaks to the elements and classes you target, depending on your theme.

Now if you go to the Customizer in your site admin, you can start tweaking your color scheme. Here’s mine with a very garish scheme!

the Customiser with colors edited

This probably isn’t a color scheme you’d choose to use in your site but it shows you how the colors are implemented in the theme. I’ll try something more tasteful and then save and publish it:

a more tasteful color scheme (shades of blue and gray) on the front end of the site

Now your users can amend the color scheme in their site using the Customizer.

Challenge: Add Your Own Settings and Controls

Now that you’ve added some text controls and a color scheme, why not try adding some more settings and controls to your theme, putting in place the techniques you’ve learned so far.t Possibilities include:

  • Media upload – To do this, you create a new instance of the WP_Customize_Image_Control class, in a similar way as you did with the color control class already. You then need to add the image to the site (maybe a logo in the header?) using a hook, in a similar way as you’ve already done for contact details.
  • Image styling – If you add media upload, you could then create some options for styling that image, such as floating a logo to the left of the site title or using it to replace the site title. For the controls, you could use radio buttons, by defining 'type' => 'radio' in the parameters for your $wp_customize->add_control() method. Then you’d use a variable to store the selected styling option using get_theme_mod(), in a similar way as you did for colors above. Finally, you’d add styling for each of those options to your stylesheet or via a function hooked to wp_head. The reason you can use the stylesheet is that you’re using the option to add a class in your template files, not to add styling to that class in your stylesheet.
  • Page layout – Try adding page layout options such as full width, columnar or with or without a sidebar. You could do this for a particular content type (such as single posts or pages) using a conditional tag in the function that you attach to wp_head with the relevant styling added. Again, you’d use radio buttons and set styling using the get_theme_mod() function.
  • Position of elements – You could add the option of moving the sidebar to the left or right or moving a header image above or below the menu or site title. Again you’d need radio buttons and a variable which you use to define styles, using get_theme_mod().
  • More text options – Try creating sidebar or footer text that users can edit in the Customizer, hooked to the hooks you already added in the theme’s sidebar.php and footer.php files.
  • Call to action button – You could use text controls to create an editable call to action button, along with radio buttons to define whether it’s activated and where it appears. Then use a conditional tag in your function that adds the box (via a hook) to check whether it should be added in that location.

These are just some of the possibilities available to you. Why not try some them out? If you’re needing more inspiration for Customizer controls, try looking at some of the great customizable themes available on the theme directory and seeing if you can recreate what they’ve done. Don’t overdo it though – you don’t want to overwhelm your users!

If you want to check out the code you’ve created in this part of the series, don’t forget to get a copy of the theme from the series source files on Github. If you get stuck at any point, or your code doesn’t work, please check the code before posting a question here. The best way to learn is by working it out for yourself!

The Customizer is a Powerful Tool

The Customizer is a great tool for letting users of your theme make changes to their site without writing any code. If you’re creating themes for others to use on their site, it gives them more flexibility and control over how their site looks. And if you’re creating sites for clients, the Customizer is a great way for them to edit content such as contact details and sidebar text without having to write any code (or get you to do it).

Hopefully, this part of the series has given you a grounding in how the Customizer works and how you add settings and controls to it, and provided you with inspiration for adding it to your own themes. Have fun experimenting!

That’s right, tons of WordPress knowledge, peer review, instructor feedback and certification, for free for WPMU DEV membersStart Learning

View @ WPMU DEV

Leave a Reply