Utilizing Theme Customization API- A Paradise for Developers

Being one of the well-known blogging platforms, WordPress has evolved into a full-fledged content management system that has been serving as the backbone for millions of websites prevalent over the world wide web. Every new version of WordPress brings along a variety of features and functions which serve as handy tools for enhancing and revamping the existing stature of WordPress powered websites. Theme Customization API is one such remarkable WordPress feature which has undoubtedly become one of the hottest topics of discussion among WP theme developers across the globe.


What’s in store for you in this post?


Well, this post allows you to dig deep into the remarkable possibilities available with WordPress Theme Customization API. Here, I’ll be covering the two-step process of utilizing this theme customization API available for WordPress enriched web portals. Also, as you read through this post, you’ll get to know how as a WordPress theme customization expert, you can make the most of this WordPress Theme Customization API.


To start off, let’s get to know the default sections and controls available on the WordPress Theme Customization Screen


WordPress themes installed in portals running on WordPress 3.4 and above come with a set of default controls and settings on the Theme Customization Screen. Some of the widely recognized ones include:


• Website Title
• Tagline
• Background Color
• Widgets
• Background Image
• Static Front Page and many more.


In addition to above, the default controls available in WordPress include the following:


•  Checkbox
•  Text-field
•  Color picker
•  Image Upload
•  Header Image
•  Select
•  Radio-button and many more.


That means, you don’t need to add any extra code for supporting the above mentioned theme customization settings and controls.


A closer look at WordPress Theme Customization API and the benefit it brings to the WordPress theme development community


Introduced along with the WordPress version 3.4, the theme customization API allows you (as a WP developer) to add new controls to the Appearance-> Customize admin page along with the flexibility of tweaking the existing ones. Whether you intend to moderate your theme settings, widgets, titles, logos or the color scheme, this WordPress Theme Customizer API will allow you to do all this and much more.


Talking about the benefits introduced for WordPress theme developers, you can easily avoid the hassles of writing lengthy code snippets for tweaking different assets of the installed theme. You can define a basic theme and on the basis of the installed theme’s design, you can use the control available in the back-end(this is the admin interface that becomes available after implementation of theme customization api) for performing minor and major tweaks to the WordPress theme. That means, you don’t have to start from scratch, everytime you plan to change something about your theme. The Theme Customization API would eliminate the need for any theme settings page. Instead, the developers would be able to use a simple theme customizer page which would include all the settings, sections and controls that need to be moderated as per the fluctuating requirements of the website owner.


Here is a screen-shot which displays the additional controls/settings available, post implementation of WordPress Theme Customization API:


WordPress Customization API


Let us now come to the process of equipping your theme customizer with add-ons


By default, WordPress Theme Customizer API comprises of three main components as explained below:


Section – It represents a group of settings. In other words, all the new settings and controls are being added to this section. However, you can also opt for adding the new settings and controls to the default sections available within WordPress Theme Customization screen.


Setting – It represents a customization option available for the installed WordPress theme.


Control – It is basically a HTML format element available on Theme Customizer page, allowing the website administrator to change a specific theme setting when previewed in real time.


As a WordPress theme developer, you can choose to add your own unique options to the WordPress theme customizer. For this, you’ll require 2 hooks which have been explained below:

– Use this hook for defining new Theme Customizer sections, settings and controls(Please refer the above paragraphs for a detailed understanding of the three)


Wp_head – Use this hook for outputting the custom-generated CSS, making the changes visible once the website becomes live.


In addition to the above two hooks, you may also use the customize_preview_init hook for enqueuing custom Javascript on the WordPress Theme Customizer page. Although Javascript can be effectively used for making the theme customizer more powerful and responsive, I would recommend skipping this step to avoid unnecessary complications.


And now, I come to the detailed explanation of two-step process that marks efficient utilization of Theme Customization API in WordPress:


Step 1- Define Sections, Settings and Controls


Every new Theme Customization setting, section or control will be defined from within the customize_register action which automatically loads the $wp_customize object. This object is an instance of WP_Customize_Manager class. So, let’s start with defining this customize_register action:


function originaltheme_customize_register( $wp_customize ) {
//All the new sections, settings, and controls will be added here
add_action( ‘customize_register’, ‘originaltheme_customize_register’ );


On observing the above code carefully, you’ll find that $wp_customize object is passed to the function automatically. Plus, all the customizations made to the Theme Customization Page will be performed using the methods defined for the $wp_customize object.


Adding a new Setting


In order to add a new setting to your WordPress Theme Customizer, all you need to do is simply call the $wp_customize->add_setting() method. Here is the code snippet associated with the same:
$wp_customize->add_setting( ‘footer_textcolor’ , array(
‘default’ => ‘#000000’,
‘transport’ => ‘refresh’,
) );


Adding a new Section


All the newly defined controls need to be added to a section. In order to add a new section to your Theme Customizer, you simply need to call the $wp_customize->add_section() method. The code for the same is shown below:
$wp_customize->add_section( ‘originaltheme_new_section_name’ , array(
‘title’ => __( ‘Visible Section Name’, ‘originaltheme’ ),
‘priority’ => 20,
) );


Apart from the above process of adding a new section, if you’re interested in using any of the built-in sections, then you don’t need to declare the same with the above explained add_Section() method. Here is a list of few built-in sections available on WordPress Theme Customizer Page:


Colors – this section includes controls for altering colors used in the installed theme.
Background_image – this section includes controls for altering the background image.
title_tagline – this section includes controls for altering the website title and tagline
Nav – this section includes controls for altering the website navigation
Header_image – this section includes controls for altering the header image
Static_Front_page – this section includes controls for altering the static front page


Adding a new Control


Assuming by now you’re well familiar with the functioning of a control, I would like you to know how you can add a new control to your Theme Customizer. Just call the $wp_customize->add_control() method for the same. The code snippet associated with addition of a new control to a particular theme section is shown below:
$wp_customize->add_control( new WP_Customize_Nav_Control( $wp_customize, ‘link_nav’, array(
‘label’ => __( ‘Website Navigation’, ‘originaltheme’ ),
‘section’ => ‘your_section_id’,
‘settings’ => ‘your_setting_id’,
) ) );


Step 2- Generate Live CSS


As the second and the final step, you’re just required to fetch the settings, followed by outputting any vital CSS styles into your header. For instance, as in this tutorial, I’ve defined the settings within the ‘customize_register’ action, it would become quite comfortable for me to fetch the setting values. The process would be as simple as outputting the css using ‘wp_head’ action, followed by fetching the values using get_theme_mod().


Here is an example:

I have a setting called ‘footer_color’ which looks exactly similar to this:

$wp_customize->add_setting( ‘footer_color’ , array(
‘default’ => ‘#000000’,
‘transport’ => ‘refresh’,
) );

Now, the code to output the CSS into the header will look like this:

function originaltheme_customize_css()

h1 { color:; }

add_action( ‘wp_head’, ‘originaltheme_customize_css’);


If you have a look at the page source, you’ll see the below HTML code in the footer:

.h1 {color:#000000;}


In the above source code, you can see the default value for color set as #000000. You may choose to change this value via the customizer. Let’s consider a scenario, if you want to change the footer color to red. All you need to do is go to your theme customizer, insert the hex value for red i.e. #ff0000 and finally hit the Save and Publish button.


The new HTML code for footer as displayed within the source code will look like this:


.h1 {color:#ff0000;}

Here, you need to ensure that the live theme customization options are fully functional, unless the settings defined in step 1 explicitly use ‘transport ‘=>’ postMessage’.


So that’s it for this tutorial!


Final Thoughts


Perhaps serving as one of the most brilliant options for adding some custom settings and controls to your WordPress theme, the Theme Customization API available with WP 3.4 version and above works as the best match for WP site owners who’re into the habit of moderating the look and feel of their website on a frequent basis.


Please check the video below by LuckyWabbitWebDesign – Customize any WordPress Theme (Part 1)





Thanks for staying tuned to this post. Hope it would serve as a handy guide during your forthcoming WordPress theme customization endeavors.

15610 1 Views Today

Mike Swan

Mike Swan is an experienced PSD to WordPress service provider, and a web designer for Markupcloud. She loves to share her thoughts on web design and web development trends.