Introduction to WordPress Theme Customization API

As a WordPress user, you’d already be familiar with the impressive features that the CMS brings along. Theme Customization API is one such feature that has taken the WordPress theme customization world by a wave.

In this tutorial, you’ll get to know about the utilization of WordPress Theme Customization API that has been introduced in WordPress 3.4 and since then has been serving as one of the finest tools for tweaking the WordPress themes.

WordPress Theme Customization API

Understanding WordPress Theme Customization API (Application Programming Interface)

Added in WordPress 3.4, WordPress Theme Customization API allows you to add new controls and customize settings available for Appearance-> Customize admin page.

As a WP theme developer, you can have a separate Theme Customization Screen, also called Theme Customizer which will aid you in tweaking the theme’s color scheme, widgets, settings etc. with an added flexibility of previewing the changes in real-time.

Prerequisites for using Theme Customization API

In order to add new options to WP theme customizer, you need to have 2 hooks viz:

customize_register – It allows you to define the Theme Customizer sections, settings and controls.

wp_background – With this hook, you can output custom-generated CSS in order to make the changes visible on the site once it’s live.

Steps involved with appropriate utilization of WordPress Theme Customization API

Define Settings, Controls and all other elements needed for customizing the WP theme.

  1. You can define a new setting, section or control from within the customize_register action which will automatically load the $wp_customize object (an instance of WP_Customize_Manager class).
  2. Define the customize_register action like this:
    
    function customtheme_customize_register( $wp_customize ) {
       //Here, all the sections, settings, and controls will be added.
    }
    add_action( 'customize_register', 'customtheme_customize_register' );
    
  3. In the above code, the $wp_customize object has been passed automatically to the function. Also, all moderation done for the Theme Customization are handled through method defined in $wp_customize object.
Adding a new Setting

Just call the $wp_customize->add_setting() method for adding a new setting to the Theme Customizer.

Here is the code associated with the same.


$wp_customize->add_setting( 'background_textcolor' , array(
    'default'     => '#000000',
    'transport'   => 'refresh',
) );

In the above code snippet, the transport argument is optional and has a default value ‘refresh’.

You can choose to set the value for this argument as postMessage which would allow you to handle styling updates manually with the help of JavaScript.

Adding a new Section

All new controls need to go into a section. So, in order to add a new section to the Theme Customizer, just call the $wp_customize->add_section() method. The code for the same is shown below:


$wp_customize->add_section( 'customtheme_new_section_name' , array(
    'title'      => __( 'Visible Section Name', 'customtheme' ),
    'priority'   => 40,
) );

Apart from above, you may also opt for using any of the WordPress built-in sections mentioned below:

  1. colors
  2. background_image
  3. header_image
  4. nav
  5. static_front_page
Adding a new Control

Just call the $wp_customize->add_control() method for adding a new control to the Theme Customizer.

Further, you can choose to link this control to a single setting and/or a single section. The code associated with the same is shown below:


$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'link_color', array(
			'label'    => __( 'Background Color', 'customtheme' ),
			'section'  => 'your_section_id',
			'settings' => 'your_setting_id',
		)
	)
);

Generate Live CSS

Now that you’re done with adding new settings, sections and controls; it’s time to ensure that you’re fetching the settings, followed by outputting the necessary CSS in your background.

For instance, if you have added a new setting called ‘background_color’ which looks like this:


$wp_customize->add_setting( 'background_color', array(
		'default'   => '#000000',
		'transport' => 'refresh',
	)
);

So, the code for outputting the CSS into background will look like this:


function customtheme_customize_css()
{
    ?>
         <style type="text/css">
             h1 { color:<?php echo get_theme_mod('background_color', '#000000'); ?>; }
         </style>
    <?php
}
add_action( 'wp_background', 'customtheme_customize_css');

So, now when you view the page source, a code similar to this one will be displayed in your background:
[css]
<style type=”text/css”>
.h1 {color:#000000;}
</style>
[/css]

We’re done!

Conclusion

With such insights available on WordPress Theme Customization API, I’m sure you’d have got all excited about exploring the feature for your WordPress powered site.

So, get going and take full advantage of this WP utility which is specially meant for WordPress users who like changing their site’s theme settings on a regular basis.

Don’t miss out!
Subscribe to My Newsletter
Invalid email address