WordPress Theme Customizer: First Steps
I've already explained how to create a theme options page quickly and easily. Creating a custom page for theme options is optimal if you want to offer your users many features. But there's another way of realizing a page for theme options. For a while now, WordPress has been offering the theme customizer. This is perfect if your theme doesn't offer too many options. The customizer's big advantage is its live preview. Every change made to the theme can be checked out before you transfer it to the website. This article shows you how to "feed" the Customizer with your features. Creating theme options with the Theme Customizer is relatively easy and offers its users the big advantage of a live preview before saving the changes. The Theme Customizer got introduced with WordPress version 3.4.
Important to Know: No More Theme Options Pages for WordPress.org ThemesWhen you want to create a theme for the WordPress.org theme index, you have to use the Theme Customizer. Theme options pages are not allowed anymore since the 21st of October of last year.
Creating Theme Options for the Theme CustomizerOur example theme is the Ari theme by Elmastudio. It only provides the predefined options and can thus be extended nicely in the course of this tutorial. In the following, we'll create an entirely new Theme Customizer page for the theme. Important: All of the following code snippets can be clicked on to download the code directly from GitHub.
The Four Methods of the $wp_customize Object
The Predefined SettingsWordPress comes with some default settings that don't need to be defined.
- title_tagline - Website Title and Tagline
- colors - Colors
- header_image - Header Image
- background_image - Background Image
- nav - Navigation
- static_front_page - Static Front Page
The Transport Versions - refresh vs. postMessageHowever, if you want some of these features to be visible before saving them, you need to add them to the Theme Customizer feature. You can assign two "transport" versions. Refresh means that after entering your settings within the Theme Customizer, the preview page is updated directly. After that, the new settings are visible. PostMessage however, means real-time changes. When you change the blog name in the Theme Customizer, for example, the entered letters are visible immediately. For the transport method postMessage, you need an additional, small jQuery file.
Important to Know: WordPress' Standard FeaturesThe screenshot shows the standard features of the transport method »refresh«. However, you can also configure them for a real-time view as pictured.
Creating Theme Options With the Theme CustomizerPlease set up a new file named customizer.php in your theme's main index. You can either create the file in a pure text editor like TextEdit or an HTML Editor. Paste the following code into the customizer.php: First, an own class is distributed, and then the features are registered. Every code that we'll write now belongs into this function.
Letting the User Adjust the ColorsWe're setting up a section for the colors that users are supposed to be able to choose from later. The link and the text colors can be edited. The code needs to be copied into the function that we just set up. In this case, we'll access the transport method »refresh«, which doesn't need to be defined as it's the WordPress standard, as an example. First of all, the code describes the options that can be altered by the user, like link and text colors. Furthermore, a standard, which is already defined in the theme's CSS stylesheet, is set for each of the two options. This way, you don't need to define the settings for each of the color options. The settings that the user can modify in the Theme Customizer are defined this way as well. Without this configuration, a new section in the setting options won't appear in the customizer. Finally, the code also defines the audits that allow for these settings. Here, new WP_Customize_Color_Control activates the color picker that enables you to determine the custom colors. By the way, I didn't have to set up a "colors" section, as this happens automatically when audits are defined within that section. Now, our Theme Customizer looks like this: You can also adjust the colors with a color picker, but no changes will be made to the theme yet. To allow the changes to be applied to the theme, you need to adjust the theme's header.php. Thus, copy the following code directly at the top of the finishing </head> tag in the header.php: Once you've done that, the color adjustments are directly visible in the customizer, before clicking »Save & Publish«. Immediately after choosing a new color, the page is refreshed, and the changes in color choice become visible. The two variables take the changes from the customizer and transfer the values to the small inline CSS, which is responsible for the display of the new colors.
Showing the Options in the ThemeHere, we differentiate between the features provided by WordPress by default and the one's we defined ourselves.
Implementing an Advertisement BlockIn this case, it won't be as easy as it was when editing the colors. More code is necessary. To begin, a new section has to be set up so that the new menu item can be displayed. To do that, we're using the $customizer_object->add_section method. The priority determines where the new menu item is displayed. The smaller the number, the closer to the top the menu item will be placed.
Defining the SettingsHere is where the $customizer_object->add_setting method comes into play.
Creating the Input for the SettingsTo create the control that is responsible for the display of the setting options in the customizer, we need the $customizer_object->add_control($controller_object) method. There are many different controller objects, depending on what you need. Here, we have used WP_Customize_Control, which is useful for input boxes. You can use it to create a text area, a text zone, check boxes, radio elements, and colors. There are also other controller objects such as WP_Customize_Color_Control, WP_Customize_Upload_Control, and WP_Customize_Image_Control to enter colors or upload a file or image.
The Provisional Result in the Customizer
The Result in the Theme - Advertising BlockThe newly defined advertising block can now be placed everywhere in the theme, filled with text, banners, or advertisements.
Activating the Ari Theme's Dark ThemeAri also offers a dark version that can be activated on the theme options page. But as we only want to learn about the Customizer, we will realize the switch option for the WordPress Customizer. The real-time view makes little sense here, as the changes are visible instantly upon refreshing the page even before saving. Thus, we'll use the standard method »refresh« for the code. I've chosen a checkbox for the activation of the dark Ari theme. By placing a checkmark, you'll activate the dark theme. Of course, the colors of the texts and links should be adjusted afterward, as we've already done above.
The Needed Adjustments in the Theme - header.phpA small change has to be made in the theme's header.php, so that the dark theme can be activated. The code makes sure that the stylesheet of the dark theme only appears in the <head> area when needed.
The WordPress Default Settings in Real TimeWe'll now realize two of WordPress' default settings, being the blog name and the description, in real time using the transport method »postMessage«. To do so, the following two lines of code are required: Additionally, a little jQuery is needed for real-time display.
Changes in the header.phpOnce again, the theme's header.php has to be edited. We need to add a CSS class each for the website title and the description to access the elements easier with jQuery.
The Result in the Customizer
The Complete Files and the Edited Theme to DownloadTo better understand how everything fits together and works, you can find the downloads to the complete files here.
- The customizer.php file download at GitHub
- The theme-customizer.js file download at GitHub
- The optimized header.php file of the Ari theme download at GitHub
- The complete, working and modified Ari-Theme as a .zip file
ConclusionThe Theme Customizer surely is an interesting thing that every developer has to deal with when wanting to offer themes in the official index. This will inevitably cause new, high-quality themes of the large providers not to be listed there anymore. That's because large providers like WooThemes, Krisi and Co. still prioritize their own theme options page as it's the only way to realize the vast amount of settings that today's premium themes come with. Of course, the professionals that provide themes on WordPress, will be able to solve many things more elegantly than I did in this article. However, this article was mainly about the basic knowledge of the Customizer; about first, fast success. And this is provided.
- WordPress: Theme Customization API
- WordPress Theme Review Team: Details on the new theme settings (customizer) guideline
- Tuts+: A Guide to the WordPress Theme Customizer - 7-part series
- Smashing Magazine: The WordPress Theme Customizer
- Narga: Comprehensive Guide to make WordPress Theme Options with Customization API
- WordPress Theme Review Team: Customizer tutorials and documentation
- WordPress Theme Handbook: Theme Options – The Customizer API
- Justin Tadlock: Multiple checkbox customizer control