Configuring Appearance Using WP Theme Customization API

The WordPress Theme Customization API allow developers to enable a Customizer Page to their Themes. It is recommended that developers should provide Theme Customization Options in the Theme Customizer page rather than Theme Options page. It will allow users to change the appearance of their theme and edit settings via WordPress Theme Customizer page. As a result, making the theme easy to use and appear professional.

Theme Customization API

Theme Customization API enable developers to build controls and settings option in the Customize section found in the Appearance menu of WordPress Dashboard. The Theme Customization screen (or Theme Customizer Page) allow website administrators to modify theme settings, color schemes, widgets, titles and logos, to name a few of the common examples. This also provides a preview of those changes in real-time.

Previously, wp community members provided a theme option page for users to tweak their theme, which was far less user friendly because users had to refresh their site after making changes to see them taking the effect.

Default Controls on the Theme Customizer Page

Every WordPress Theme that is installed in the latest version of WordPress (i.e 3.4 and above) is provided with some default settings and controls on the Theme Customizer Page such as Site Title, Tagline, Background Color, Background Image, Widgets and Static Front Page. You don’t have to add any code to support these basic customization settings and controls.

Sections, Settings and Controls

Sections represent a group of settings. When you define new settings and controls, they must be added to a section. You can also add new settings and controls to default sections.

A Setting represents a customization option of a Theme.

A Control is an HTML form element on the Theme Customizer page. It allows the admin to change settings on real time preview. Controls are linked to a single setting, and a single section.

Creating a Section

Use $customizer_object->add_section to create a section named as ads. Name the default sections as:

  1. title_tagline
  2. colors
  3. header_image
  4. background_image
  5. nav andstatic_front_page

Creating a Setting

Use $customizer_object->add_setting to create a setting named as ads_code.

Transport argument supports two values; Refresh and postMessage. Refresh indicates that changes will take place when the Theme Customizer page is saved by clicking Save and Publish button and then refresh. However, postMessage indicates that the changes will take place in real time, as it happens. Site visitors will not be able to see the changes until site admin clicks Save and Publish button.

Creating a Control

To create a control, use $customizer_object->add_control($controller_object) method to create a new setting.

There are various controller objects, depending on what kind of control you need. WP_Customize_Control is used to display input fields such as text area, text, checkbox, radio and color. There are other controller objects such as WP_Customize_Color_Control, WP_Customize_Upload_Control and WP_Customize_Image_Control for color input, file upload and image input respectively.

Output Settings Value

The way of echoing the settings value depends on transport argument of the add_settings function.

If the value of transport argument is refreshing then this is the code to echo ads_code setting value in your theme. get_theme_mod is used to retrieve value of Theme Customization API. If the transport argument is postMessage then you also need to use the above code for echoing.

To implement a live preview, you need to write some JavaScript code so that you can fetch the new value on changing the previous value from settings. You can create a JavaScript file in your theme’s directory referring it as theme-customizer.js by adding the following code:

You can also enqueue the above script by using the following code:

User Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

    Get in Touch