Theme Customizer to the Rescue

Theme authors/tweakers: Your prayers have been answered.

There is now a really easy way to customize your theme, with not a lot of coding, by simply adding your customizations to the new Theme Customizer section in WordPress. This is a feature introduced in WordPress 3.4, so if you haven’t upgraded yet, besides the risk of being hacked and embarassing yourself and others when your site starts marketing viagra and porn, you now have an additional reason to go ahead and upgrade.

Where is the Theme Customizer?

The Theme Customizer can be accessed in a few different ways (and should probably be accessible from more; see this article for instructions on adding it to the Appearance menu in your admin area: “Theme Customizer Part Deux” ):

  • The mouseover menu at the top left of the admin bar (the black bar that appears when logged in), where the site name is displayed
  • The theme selection screen (Appearance -> Theme)
  • A button in one of the Dashboard widgets (if it’s not hidden)

What does the Theme Customizer do?

There is a little repetition in the Theme Customizer with some other sections, notably the Custom Header and Custom Background screens, which have their own entire pages under Appearance. It may seem like there are a few more options on the full Custom Header and Custom Background pages, but really they are just more spread out and perhaps a little easier to see. Really, I think it’s just more convenient to have all the stuff in one place, and the new Theme Customizer makes a fine place. The Theme Customizer also includes such things as a selector for the front page of one’s site (blog or static page). It’s really a nice addition.

Of course, if it just collected settings that can be modified in other places, that would be nice, but the real power of the Theme Customizer comes from the ease in which a theme programmer (even someone tweaking a theme with a custom theme) can add settings to this interface, and make lots of adjustments easily available to the users of that theme which previously might have required them to tinker with the code.

I’m intrigued; what can I actually change with the Theme Customizer?

There are two basic kinds of changes you might offer to the users of your theme: CSS changes and setting of options. (I’ll talk a little later about why both of these are really “setting options”, but I’ll save that for a little while.)

The Theme Customizer seems built primarily to allow the setting of various CSS values, as most of the tutorials and reference materials on it center around storing the values you want to insert into your CSS, and providing an easy, visual way to choose between them. However, if one takes more than a cursory look at the way the values are stored (in the Options table, along with a TON of other settings), it doesn’t take long to realize that the Theme Customizer isn’t limited to just CSS values. The only difference between setting CSS values (like choosing whether the background color is gold or white) and setting some other value (like whether a menu is horizontal or vertical) is where that value is retrieved. (If you’re changing a CSS value, you’ll retrieve the value in the middle of a CSS statement; if you’re changing a value used somewhere else, you’ll retrieve the value in the midst of anothe rpiece of code.)

Something like this:

CSS rule
#blogTitle { color:<?php echo get_option( esc_attr( ‘themename_theme_options[title_color]‘) ); ?>; }

Javascript code:
ddsmoothmenu.init({ mainmenuid: “<?php  //Menu DIV id if ( ( get_theme_mod( ‘ddsm_menu_direction’ ) ) == ‘h’ ) { echo ‘hnav’; } else echo ‘vertnav’; ?>”,

Note the use of data validation in the first example. Data validation is basically just a way to make sure that the type of input or output you’re expecting is the only thing that’s actually accepted. In a nutshell, if you offer an input field for someone to type in the title of a post, and they instead type in a really awful SQL query (no, I’m not going to give an example), simply don’t accept it. At the very least, if your field is supposed to accept any arbitrary text that the user might want to enter, at least tell WordPress to “escape” the special characters, so they are just printed on the screen, not executed as code. (If a user to your site is upset or mischievous enough to type a database query for “delete all tables”, simply print the “delete all tables” command on the screen if you can’t just throw it away, instead of treating like instructions to your site.)

There are tons of data validation functions for various purposes. If you’re writing anything that puts something in the database, or gets something from the database and puts it on the screen, it would be a good idea to get familiar with the WordPress Codex article on Data Validation. This topic will get its own post soon…

Why would I want to use this in my theme?

Well, there are a surprising number of people who don’t get the concept of the child theme, or just don’t want to be bothered to create one. (Some of the users of your theme may not even have permission to create a child theme, or upload new files to one once it has been created.) The Theme Customizer gives them a way to alter some aspects of your site, without having to program a single line of PHP or CSS. If there are some settings that most people want to customize, consider putting these into the Theme Customizer. Suddenly, your theme is more useful, and many of the people who might have otherwise needed a child theme to make the tweaks they wanted can now just click a couple of buttons, and focus on the content of their articles.

Ok, sounds good; let’s see some code examples!

I’m not going to try to out-do the various tutorials on the Theme Customizer that are already out there. Unfortunately, they are not all collected in the WordPress Codex like with most things, but with a little studying, it’s not too hard to get a grasp on the technique. However, I’ll try to break it down a little, and introduce some of the various explanations of how to actually use the Theme Customization API.

Theme Customization API

The Theme Customization API article at the Codex is basically an overview of the entire process, with some good code examples, description of the usage and parameters, and links to some other related articles. While you might have to look at some of the other articles I link here to get all the code you need to build out your form, this is a good place to start.

customize_register

This is really the heart of Theme Customization (though it can also be used by plugins, if you don’t have a ton of settings to change in your plugin, and want to skip writing your own settings page). Everything you do with the Theme Customizer is going to be wrapped up in one form or another of this function.

The Function Reference for customize_register has a great deal of information about the various types of controls you might want to use (like a file upload button, a color picker, a drop down box or others). Even after you understand what the Theme Customization API is all about, you might still be struggling to find just the perfect control to pur on your form. If you can’t find it on this page, you might need to take a look at some of the stuff at OttoPress…

OttoPress Articles

For those of you haven’t had the pleasure to meet Otto, he’s one of the core developers of WordPress, has an amazing grasp on what’s happening behind the scenes, and is a really nice guy who’s very willing to share his time and knowledge. He saw that there wasn’t a lot of documentation on Theme Customization, so he wrote several great posts on one of his blogs, ottopress.com:

How to leverage the Theme Customizer in your own theme

This article is another overview of the Theme Customizer, from a slightly different perspective (a little more technical) than the one in the WordPress Codex (though it’s actually linked from there because it does a nice job of filling in the gaps). It includes a few more examples of special controls, and dives into the discussion of theme_mod versus “serialized options” techniques for storing the values entered on the form in the database. (I’ll weigh in on this a little later…) It also gives an excellent explanation of how to use javascript to make the preview window show your changes without waiting for a screen refresh.

Theme Customizer Part Deux: Getting rid of options pages

This article starts off with a bit more of the “why”, but also digs into the “how” as well. As I mentioned before, the Theme Customizer can actually be used for plugins as well as themes, and could come in very handy if you only have a small number of options, and don’t feel like writing your own Settings page. (You can easily make your own Section in the Theme Customizer.)

 Making a custom control for the Theme Customizer

This article is pretty straightforward; if you can’t find an existing control for the Theme Customizer to do what you want, write your own. Be warned that this article gets a little heavy if you’re not at all familiar with object-oriented programming. Still, if you’re doing something really specific and can’t find the control you need for the Theme Customizer form, you’re probably doing some complex stuff, so this might be what you need. (I think it will be quite rare that you can’t find an existing control to do what you need. There are a ton of them listed in these various articles.)

So… theme_mod or “serialized theme options”?

As you might have noticed by now, there are a couple of main ways that appear in these examples for storing (and getting) the values from the Theme Customizer form. Although Otto states very clearly in the first article I link above that the “serialized theme options” method is the preferred way, because it stores all the values on one row of the options table, some of his examples still use the theme_mod method (the default method used in the wp_customize_register function, unless the type is set to ‘option’.)

Otto says that “serialized theme options” is the recommended and preferred method by the Theme Review Guidelines and the theme reviewers. While Otto is clearly much better at this than I, and more closely in touch with the theme review folks, I have to say, I don’t see this born out in the guidelines themselves.

From the Theme Review Guidelines:

“Themes are required to save options in a single array, rather than create multiple options for its settings page. Use of set_theme_mod and get_theme_mod handles this for you, as does using the Settings API.”

There you have it. The theme_mod technique is just as sanctioned as the Settings API method (AKA “serialized theme options” in many of Otto’s articles). To be honest, there may be nuances about the two approaches that differ more than I’m representing here, and I’m just ignorant of the finer details, but I don’t see any reason to not use the theme_mod method. The clincher for me: the theme_mod method is much less typing! Also, if you’re thinking that perhaps you should use the “serialized theme options” because it will create less database bloat, you may want to take a look at your database tables (CAREFULLY) and see that you probably already have at least one or two theme_mod lines in your options table, for the theme you’re currently using, and maybe even one for Twenty Twelve or whatever default theme was installed when you started the site.

Theme_mod still serializes your values (basically, puts an array of values into one line in the options table), is less typing, and seems to satisfy the Theme Review guidelines (in case you ever want to distribute your theme at wordpress.org, or just want to keep everything high quality.)

The most recent version of my theme, WF College One Pro has some theme options, which will hopefully make it easier to change several things, without having to learn any CSS or make a child theme.

Related Posts: