If you’re a theme author running a WordPress website, then you’ll probably want to make some adjustments to your theme’s settings page to enhance its capability. This is where WordPress Theme Customization API comes in handy. It was introduced in WordPress in 3.4, giving developers the ability to make tweaks to their Theme Customization screen (also referred to as Theme Customizer).
Assuming that you have knowledge about theme development, writing plugins, and familiarity with the WordPress Settings API, this post will throw light on the remarkable possibilities available with the Theme Customization API. The post will cover the following process where you can utilize the WP theme customization API, for improving your theme’s capability in the dashboard.
Getting Started
The Theme Customization API, in essence, allows developers to add a “Customizer Page” to their theme to tweak its appearance and edit/add theme settings. It enables theme developers to build settings option and add more controls to the “Customize” admin screen available on the “Appearance” menu in the WordPress dashboard.
With the “Theme Customization screen” (or Theme Customizer Page) developers or website administrators alike can make changes to a theme’s settings, titles and color schemes, to name a few. The best part is that the theme customizer page offers a real-time preview of the changes that have been made.
Before proceeding any further, it is very important for you to know about the default settings and controls that are available on the Theme Customizer Page, as listed below:
1. Set Title and Tagline
2. Background Color
3. Header Image
4. Widgets
5. Static Front Page and more.
Understanding How Theme Customizer Works
The Theme Customizer is divided into three different components such as:
1. Section – It shows a group of settings. All your new settings and controls should be added to the section area of the Theme Customization screen. However, you can even add new settings and controls to the default sections.
2. Setting – It helps to show a theme’s customization option.
3. Control – It is a HTML form element that can be found on the Theme Customizer page, allowing site admins to manipulate a specific theme setting when previewing it in real-time.
Now if you want to add your own options to the WordPress Theme Customizer Page from the dashboard, you’ll have to use 2 hooks as follows:
customize_register: Using this hook, you can define new sections, settings, and controls on the Theme Customizer Page.
wp_head: This hook can be used for outputting custom-generated CSS, so that the changes become visible on the website in the correct manner.
Using WordPress Theme Customization API
Now let us talk about the process following you can use the WordPress Theme Customization API.
Step 1 – Register Theme Customizer Page To the Admin Menu
In order to add any new Theme Customizer settings, sections, or controls, you’ll first have to register the theme via the customize_register action hook. To do so, simply add the below given code in your theme’s functions.php:
| 123456 | function yourtheme_customize_register($wp_customize){ // Add all your settings, sections and controls} add_action('customize_register', 'yourtheme_customize_register'); |
In this code, the function yourtheme_customize_register() will help add sections, settings, etc. to the $wp_customize (the theme customizer manager). The methods of $wp_customize will be used to perform any customizations to the Theme Customization page. Next, you will have to define new settings, followed by sections and then controls.
Adding a New Setting
To add any new theme settings to the Theme Customization Page, simply call the “$wp_customize->add_setting()” method. To better understand how this works, let us take an example, where we need to a new setting: header_textcolor to our theme.
| 123456 | $wp_customize->add_setting( 'header_textcolor' , array( 'default' => '#d3d3d3','transport' => 'refresh',// this is optional) ); |
In the above code, the setting ‘header_textcolor’ will enable you to change the color of your theme’s header using the customizer.
Adding a New Section
You need to add the newly defined controls to a section. If you’re interested in adding a new section to the Theme Customization Page, where you’ll want to add the controls, then you will have to call the “$wp_customize->add_section()” method as shown in the following code:
| 12345 | $wp_customize->add_section( 'yourtheme_new_section_name' , array('title' => __( 'Visible Section Name', 'yourtheme' ),'priority' => 30, ) ); |
Note: WordPress comes with some existing default sections. So, if you need to add the controls to the default sections, you don’t have to use the above mentioned add_section() function to declare them. In fact, you can refer to the built-in sections just by name. Below is the list of built-in sections:
1. title_tagline – Helps to alter the title and tagline of your site
2. colors – It can be used to change the color of your theme
3. header_image – Allows changing the header image of the installed theme
4. background_image – This section can be used to change the background image
5. nav – It alters the navigation of your website
6. static_front_page – It comes with controls that can be used to tweak the Static Front Page
Adding a New Control
To add controls, you will have to call the method $wp_customize->add_control(). Take a look at the code snippet below that clearly defines how you can add a new control to a specific theme section:
| 1234567 | $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array( 'label' => __( 'Header Color', 'yourtheme' ),'section' => 'your_section_id','settings' => 'your_setting_id', ) ) ); |
Step 2 – Generating Live CSS
In the second and final step, you’ll have to fetch the setting (i.e. header_textcolor in our case), and then you just need to output any required CSS styles to that setting. Since we have defined the setting in the ‘customize_register’ action (as discussed in the “adding new settings”), we can easily fetch the values for the settings using the get_theme_mod() method. Below is an example that demonstrates the same:
| 12345 | $wp_customize->add_setting( 'header_color' , array('default' => '#d3d3d3','transport' => 'refresh',)); |
Now that we’ve a setting named ‘header_color’, let us now write a code for outputting the CSS into your theme’s header:
| 123456789 | function yourtheme_customize_css(){?><style type="text/css">h1 { color:<?php echo get_theme_mod('header_color', '#d3d3d3'); ?>; }</style><?php}add_action( 'wp_head', 'yourtheme_customize_css'); |
After this code gets executed, you can see that the color of the header is set to gray. However, you can change the default header_color from gray to red. To do this, you just need to access your Theme Customizer Page and change the hex value from #d3d3d3 to #ff0000.
Here’s how your HTML will be displayed in the page’s source code:
| 123 | <style type="text/css">.h1 {color:#ff0000;}</style> |
Wrapping Up!
Hope this post serves as a helpful guide to help you get familiar with the WordPress Theme Customization API. It will also help you learn how to create your own set of custom settings and controls using the WordPress Theme Customization screen.
