Web/ Design/ Vista

Resources for Designers & Developer

Add Custom Theme settings using WordPress theme customizer API

WordPress theme customization Api is a set of functions and methods which comes inbuilt since WordPress version 3.4

These functions and methods allow theme developers to add settings to their custom themes. These custom settings can be accessed through Appearance -> Customize admin screen in WordPress dashboard.

This Api should not be confused with WordPress theme settings Api which was added in version 2.7. Though you can use the settings Api to achieve the same results, using theme customization Api is the preferred way to add custom settings to your theme.

The reason is – theme customization Api provides a much more secured and integrated way to create theme options than the settings Api. Theme customization Api does not create extra admin page, it just adds new panels, sections and settings to already existing Appearance -> Customize admin screen.

So why do you need custom theme options at all? Let me explain.

Consider a real estate theme. As the theme developer you would like to give an option to site admin to display different headers based on his/her preference. The admin has to just open a page on the WordPress dashboard and select a header type and voila! it is changed! How would you create that option? That is where theme customization Api comes handy.

To use this api your WordPress installation should be at least version 3.4, older versions do not have the customizer api.

Theme customizer Api is already bundled with several default theme options which allow the developers a lot of control on the look and feel of the site. In this tutorial we are going to skip the inbuilt options and create a few custom ones.

You may want to note that customizer Api is for changing the “look and feel“, if your custom options are doing something that effect the functionality of the site, then you are better off adding or creating a plugin.

Panels, Sections, Controls, Settings

The customizer API exposes 4 main objects which can be used to create panels, sections, controls and settings.

A panel is the topmost layer in customizer window. It holds other sub-panels, sections and controls. Note that the panel Api was introduced in WordPress version 4.0

A section is a container for controls. Typically a section will have more than one control.

 

A section and a panel are similar in appearance. The layout and stacking up is same for both objects.

To know which one is section and which one is panel, you will need to look at page source – the html code. A panel will have an id with keyword panel in it and a section will have an id with keyword section in it.

 

Page source

 

A control is the UI associated with a setting. Typically it is an HTML form element – select/ checkbox/ radio/ input which represents a theme setting.

 

A setting is a variable that represents a theme option. Its value is saved in database in wp_options table.

Settings, controls, section and panels are all objects of type customizer. To add, remove or update any of these objects, use the customize_register hook.

function nexmag_customize_register( $wp_customize ) {
  // Do stuff with $wp_customize, the WP_Customize_Manager object.
}
add_action( 'customize_register', 'nexmag_customize_register' );

nexmag_customize_register is the callback function for this action hook customize_register and takes one parameter, $wp_customize which is the customizer manager object. This function name is arbitrary, but using the theme slug in function name is the convention.

Creating a panel

A panel can be created with the following minimal code

$wp_customize->add_panel('demo_panel_id',array(
        'title'=>'Demo panel title'
    ));
Creating a section

A section can be created with the following minimal code

 $wp_customize->add_section('demo_section_id',array(
        'title'=>'Demo section title'
    ));
Creating a setting

A setting can be created with the following minimal code

 $wp_customize->add_setting('demo_setting_id',array(
        'default'=>'',
    ));
Creating a control

A control can be created with the following minimal code. It requires the type, section id and settings id.

  $wp_customize->add_control('demo_control_id',array(
        'type'=>'text',
        'section'=>'demo_section_id',
        'settings'=>'demo_setting_id',
    ));
Complete code for adding a minimal theme setting
function nexmag_customize_register( $wp_customize ) {

$wp_customize->add_panel('demo_panel_id',array(
        'title'=>'Demo panel title'
 ));
    
    
$wp_customize->add_section('demo_section_id',array(
        'title'=>'Demo section title'
));
    
    
$wp_customize->add_setting('demo_setting_id',array(
        'default'=>'',
));

$wp_customize->add_control('demo_control_id',array(
        'type'=>'text',
        'section'=>'demo_section_id',
        'settings'=>'demo_setting_id',
));

}
   
add_action( 'customize_register', 'nexmag_customize_register' );
    

Note that a panel/section is not visible till it is associated with a control which in turn must be associated with a setting.

A panel may contain multiple sections and a section may contain multiple controls.

Updating settings via customizer

Settings created though customizer like the example above are very easy to update.

For example – let us take a text control created using the cuzomizer Api.

    $wp_customize->add_control('demo_control_id',array(
        'label'=>'Demo Control Label',
        'type'=>'text',
        'section'=>'demo_section_id',
        'settings'=>'demo_setting_id',
    ));

A control generated this way will not show any submit option. But that is fine! Just hit the publish button at the top and the setting associated with that control will be saved to database. Next time you load this control from customizer screen the updated value will be there.

Similarly for other controls, you do not need to add any save/update button or add any validation code. All you need to do it create the settings/controls/sections/panels using proper Api calls. WordPress generates the submit buttons if needed, takes care of sanitization and validation ans also saves the data to $wp_options table automatically.

How to retrieve theme settings

To retrieve settings, you can use either get_theme_mod() or get_option() depending on the type you set when creating the setting.

# A theme setting using the 'option' type
$wp_customize->add_setting('demo_setting_id',array(
        'default'=>'',
        'type' => 'option'
));

The above setting can be retrieved and used in a template using get_option()

<?php echo get_option('demo_setting_id'); ?>

If type is not set then it defaults to theme_mod

# A theme setting without a type, it defaults to type theme_mod
$wp_customize->add_setting('demo_setting_id',array(
        'default'=>''
));

So the above setting can be accessed with get_theme_mod()

<?php echo get_theme_mod('demo_setting_id'); ?>