WordPress Customizer API: How to Use WP Customizer Objects

We can access the Customization screen by heading over to WordPress dashboard > Appearance > Customize.

There you will see various settings to customize your WordPress theme.

As developers, we can also add our own Customizer Objects to customize different parts of the theme.

These objects can be added using the WordPress Theme Customization API.

What Exactly is Theme Customization API?

Theme Customizer API was added in WordPress 3.4 and it’s recommended a way to add customization options in WordPress theme.

There are four types of customizer objects available in the Theme options: Panels, Sections, Settings, and Controls.

Each of those customizers objects is presented by a PHP Class and using the Customize Manager class we can manage all of those.

  • Sections: The Sections is the group of settings. When we add new settings and control, these needed to add into a section.
  • Settings: Settings are the customizations option of your theme.
  • Panels: Panels allows theme developers to create a additional layer of hierarchy beyond controls and sections.
  • Controls: A control is a HTML Form element that would see on the theme customizer page.

Customizer Objects in Detail

Whenever we need to Edit, Add, Remove any of the Customizer objects we use customize_register hook, something like this:

function themeslug_customize_register($wp_customize){
	// Add your code for $wp_customize, WP_Customize_Manger object here.
}
add_action('customize_register', 'themeslug_customize_register');

The Get, Add and Remove methods are available for each of the customizer objects:

  • add_ : Using this method we can add a customizer object.
  • get_ : This method allows us to to direct modification of parameters specified.
  • remove_: This mehod is for remove customizer object.

Here is the Example code using each of those methods for each type of customizer object:

add_action('customize_register','my_customize_register');
function my_customize_register( $wp_customize ) {
    
  // For Panels
  $wp_customize->add_panel();
  $wp_customize->get_panel();
  $wp_customize->remove_panel();
 
   // For Sections
  $wp_customize->add_section();
  $wp_customize->get_section();
  $wp_customize->remove_section();
    
 //For Settings
  $wp_customize->add_setting();
  $wp_customize->get_setting();
  $wp_customize->remove_setting();
 
   // For Controls
  $wp_customize->add_control();
  $wp_customize->get_control();
  $wp_customize->remove_control();
}

Settings

For Creating the Settings we need to use $customizer_object and than add_setting method.

The Settings handle live-preview, Saving, and sanitization of our customizer objects.

While adding a new setting we can use different parameters available:

$wp_customize->add_settings('setting_id', array(
	'type': 'theme_mod', // or 'option'
    'capability' => 'edit_theme_options',
    'theme_supports' => ' ', // Rarely needed.
    'default' => '',
    'transport' => 'refresh', // or postMessage
    'sanitize_callback' => ' ',
    'sanitize_js_callback' => ' ',  // Basically to_json.
));

There are 2 main types of settings:

  • Options: These are stored directly in wp_options table of your WordPress database. It will applied to site no matter which theme is activated. To add this define type => 'option',
  • Theme Modifications: Theme Modifications also called theme options or theme_mod are only for specific theme only. It applied to Current thme where you add code. Once you switch theme these options no longer applicable but will be back when activate the same theme again. To add this define type => 'theme_mod',

Controls

Controls are main Customizers Objects for Creating user interface.

Controls do not work alone, it must be associated with the settings.

The linked settings will save the user-entered data along with sanitizing it and showing it on the live preview.

Just like settings controls are added using Customizer manager.

Here is the example code:

$wp_customize->add_control( 'setting_id', array(
  'type' => 'date',
  'priority' => 10, // Within the section.
  'section' => 'colors', // Required, core or custom.
  'label' => __( 'Date' ),
  'description' => __( 'This is a date control with a red border.' ),
  'input_attrs' => array(
    'class' => 'my-custom-class-for-js',
    'style' => 'border: 1px solid #900',
    'placeholder' => __( 'mm/dd/yyyy' ),
  ),
  'active_callback' => 'is_front_page',
) );

The Parameter that we used above determines what type of UI the customizer will display in the customization screen.

Here are a few of those built-in control types that we can use:

  • checkbox
  • textarea
  • radio
  • select
  • dropdown-pages

The next thing we need to do is add controls to the section, also sections must be controls as well.

For example here is the code for adding basis Textarea control:

$wp_customize->add_control( 'custom_theme_css', array(
  'label' => __( 'Custom Theme CSS' ),
  'type' => 'textarea',
  'section' => 'custom_css',
) );

Sections

Sections are like UI containers for our customizer controls.

In case we have more than a few options we can group them together in the custom sections.

To add a new section we use add_section method of WP_Customize_Manger object:

$wp_customize->add_section( 'custom_css', array(
  'title' => __( 'Custom CSS' ),
  'description' => __( 'Add custom CSS here' ),
  'panel' => '', // Not typically needed.
  'priority' => 160,
  'capability' => 'edit_theme_options',
  'theme_supports' => '', // Rarely needed.
) );

We need to add only those fields which you want to override.

In case we prefer the default values there is no need to include them in this method.

So following this logic, most of you can add a section just by adding two parameters, something like this:

//To add a copyright information section

$wp_customize -> add_section('footer', array(
	'title' => __('Footer', 'themename'),
    'priority'=> 105, // Before Widgets.
)); 

Panels

Panels allow us to create an additional layer of hierarchy beyond controls and sections.

Panel exists to provide context for customizers providing distinct context for the customizers like Widgets, menus.

Here are the few things that we should remember about panels:

  • The Themes should not register their own panels, atleast in majority of cases.
  • Sections do not need to be under a panel since each section generally have multiple controls in it.
  • Panels are not the wrappers for generic sections but it it is more like providing context for Widgets, Menus or posts.
  • Panels must have atleast one section and sections should have atleast one control to be apear in customizer.

API for Panels are identicals to the Sections, Here is how it can be added:

$wp_customize->add_panel( 'menus', array(
  'title' => __( 'Menus' ),
  'description' => $description, // Include html tags such as <p>.
  'priority' => 160, // Mixed with top-level-section hierarchy.
) );
$wp_customize->add_section( $section_id , array(
  'title' => $menu->name,
  'panel' => 'menus',
) );

Createing Custom Controls, Sections and Panels

By subclassing the PHP objects: WP_Customize_Control, WP_Customize_Section, and WP_Customize_Panel or WP_Customize_Setting we can create our own Custom controls, Section, and panels.

Here is the Basic custom control example code:

class WP_New_Menu_Customize_Control extends WP_Customize_Control {
  public $type = 'new_menu';
  /**
  * Render the control's content.
  */
  public function render_content() {
  ?>
    <button class="button button-primary" id="create-new-menu-submit" tabindex="0"><?php _e( 'Create Menu' ); ?></button>
  <?php
  }
}

By subclassing the base control class we can add our own custom functionality or use the core functionality.

For example by Overriding functions such as render_content() we can create our own custom UI with HTML.

We can add Custom Customizer, just how we can add the default controls, sections, and panels:

$wp_customize->add_control(
  new WP_Customize_Color_Control(
    $wp_customize, // WP_Customize_Manager
    'accent_color', // Setting id
    array( // Args, including any custom ones.
      'label' => __( 'Accent Color' ),
      'section' => 'colors',
    )
  )
);

Customizers UI Standards

While Customizing controls, sections, and panels we should always follow the core UI practices.

Here is Some Customizer UI Standards:

  • White background colors are used only to indicate navigation and actionable items (such as inputs)
  • The general #eee background color provides visual contrast against the white elements
  • 1px #ddd borders separate navigational elements from background margins and from each other
  • 15px of spacing is provided between elements where visual separation is desired
  • 4px borders are used on one side of a navigation element to show hover or focus, with a color of #0073aa
  • Customizer text uses color: #555d66, with #0073aa for hover and focus states on navigation elements

Leave a Comment