WordPress Customize API

Summary: Learning about the WordPress Customize API and its components like Panels, Sections, Settings and Controls.

The Customize API is object-oriented. There are four main types of Customizer objects Panels, Sections, Settings, and Controls. Settings associate UI elements with settings that are saved in the database. Sections are UI containers for controls, to improve their organization. Panels are containers for sections, allowing multiple sections to be grouped together.

To add, remove, or modify any Customizer object, and to access the Customizer Manager, use the customize_register hook.

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

Settings

Settings handle live-previewing, saving, and sanitization of our customizer objects. Each setting is managed by a control object.

There are two primary types of settings options and theme modifications. Options are stored directly in the wp_options table of the WordPress database and apply to the site regardless of the active theme. Themes should rarely if ever add settings of the option type. Theme mods, on the other hand, are specific to a particular theme. Most theme options should be theme_mods.

$wp_customize->add_setting( 'setting_id', array(
  'type' => 'theme_mod', 
  'capability' => 'edit_theme_options',
  'theme_supports' => '',
  'default' => '',
  'transport' => 'refresh', 
  'sanitize_callback' => '',
  'sanitize_js_callback' => '', 
) );

Controls

Controls are the primary Customizer object for creating UI.  Specifically, every control must be associated with a setting, and that setting will save user-entered data from the control to the database in addition to displaying it in the live-preview and sanitizing it. 

$wp_customize->add_control( 'setting_id', array(
  'type' => 'date',
  'priority' => 10, 
  'section' => 'colors', 
  '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',
) );

Sections

Sections are UI containers for Customizer controls. While we can add custom controls to the core sections if we have more than a few options we may want to add one or more custom sections. 

$wp_customize->add_section( 'custom_css', array(
  'title' => __( 'Custom CSS' ),
  'description' => __( 'Add custom CSS here' ),
  'priority' => 160,
  'capability' => 'edit_theme_options',
) );

Panels

Customizer Panels API allows us to create an additional layer of hierarchy beyond controls and sections. More than simply grouping sections of controls, panels are designed to provide distinct contexts for the Customizer, such as Customizing Widgets, Menus, or perhaps in the future, editing posts. There is an important technical distinction between the section and panel objects.

$wp_customize->add_panel( 'menus', array(
  'title' => __( 'Menus' ),
  'description' => $description, 
  'priority' => 160, 
) );
$wp_customize->add_section( $section_id , array(
  'title' => $menu->name,
  'panel' => 'menus',
) );

Custom Controls, Sections, and Panels

Custom Controls, Sections, and Panels can be easily created by subclassing the PHP objects associated with each Customizer object: WP_Customize_Control, WP_Customize_Section, and WP_Customize_Panel this can also be done for WP_Customize_Setting.

class WP_New_Menu_Customize_Control extends WP_Customize_Control {
  public $type = 'new_menu';

  public function render_content() {
  ?>
    <button class="button button-primary" id="create-new-menu-submit" tabindex="0"><?php _e( 'Create Menu' ); ?></button>
  <?php
  }
}

Preview JS and Controls JS

The customizer app is currently split into two distinct areas the customizer controls “pane” and the customize preview. The preview is currently in an iframe, meaning that all JS runs either in the controls pane or in the preview. The postMessage API is used to communicate between the preview and the controls.

wp.customize(
	'page_for_posts',
	function( setting ) {
		setting.bind( function( pageId ) {
			pageId = parseInt( pageId, 10 );
			if ( pageId > 0 ) {
				api.previewer.previewUrl.set( api.settings.url.home + '?page_id=' + pageId );
			}
		});
	}
);

Models for Controls, Sections, and Panels

As in PHP, each Customizer object type has a corresponding object in JavaScript. There are wp.customize.Control, wp.customize.Panel, and wp.customize.Section models, as well as wp.customize.panel, wp.customize.section, and wp.customize.control collections that store all control instances. 

wp.customize.panel.each( function ( panel ) { /* ... */ } );
wp.customize.section.each( function ( section ) { /* ... */ } );
wp.customize.control.each( function ( control ) { /* ... */ } );