In the first part of this series, I introduced the Theme Customizer feature, and showed the reasons why it is useful. We already know that the Theme Customizer has 4 main components: Settings, Sections, Controls and the one which controls the others is the Manager who's important variable is $wp_customize. We also know the way to invoke this variable for using later. In this tutorial, I plan to go deeply into these components, figure out their properties and how to register or remove components and the way to configure them as you want.

Manager

As said in the first part, this is an important component with the main task of managing the others. It initializes all necessary things, sets things up, and integrates the default components to the Theme Customizer. As it is an instance of the WP_Class_Customize_Manager class ( located in wp-includes/wp-class-customize-manager.php ), it has some useful methods:

Get all sections, settings or controls list:

$wp_customize->sections(); // return an array with the id is the id of section/setting/control,
$wp_customize->settings(); // and the value is Section/Setting/Control object.
$wp_customize->controls(); //

For getting a component, we could use:

$wp_customize->get_section( 'id' );
$wp_customize->get_setting( 'id' ); // Remember to pass the id as argument.
$wp_customize->get_control( 'id' );

Or remove components:

$wp_customize->remove_section( 'id' );
$wp_customize->remove_setting( 'id' ); // Remember to pass the id as argument.
$wp_customize->remove_control( 'id' );

Manager also has some other important methods including:

$wp_customize->add_section( 'id', array() ); // The first argument is the id of component
$wp_customize->add_setting( 'id', array() ); // The second one is an array of property-value pairs
$wp_customize->add_control( 'id', array() ); // passing to component object.

We will focus on these methods in the next sections.

Section

As its name suggests, this component categorizes all settings into groups. Each section can contain one or many settings. This is the simplest component. Some methods that work with sections are add_section, get_section and remove_section:

$wp_customize->add_section( 'id', array(
	'title' => '',
	'description' => '',
	'priority' => ''
) );

• id - A unique identity name, which will then be used with Settings and Controls.
• title - The title of the section for display in the menu.
• description - A short description about this section.
• priority - The sequence or order of sections displayed in the menu, the lower the number, the higher it will display.

You notice that every section is an instance of the WP_Class_Customize_Section class ( located in wp-includes/class-wp-customize-section.php ), so if you use get_section, that method will return an object which is an instance of that class.

To get an available setting, just use get_section, this method returns a setting object.

$wp_customize->get_section( 'id' );

And the last method is remove_section, it simply removes any section we want to remove:

$wp_customize->remove_section( 'id' );

For example, if I would like to add a new section to use later, the following code is what I would do:

$wp_customize->add_section( 'wp_tuts', array(
	'title' => 'WpTuts',
	'description' => 'An example for Theme Customizer',
) );

Setting

These are components which control options, each handles a specific option. They're inside of sections and under the WP_Customize_Setting class ( located in wp-includes/class-wp-customize-setting.php ). The main task of this component is defining the way a setting is stored and where it should be saved. The following code is the syntax for this method:

$wp_customize->add_setting( 'id', array(
	'default' => '',
	'theme-supports' => '',
	'type' => '', // Default is "theme_mod"
	'capability' => '', // Default is "edit_theme_options"
	'sanitize_callback' => '',
	'sanitize_js_callback => '',
	'transport' => '', // Default is "refresh"
) );

• default - The default value of the input setting field.
• theme-supports - Check whether the current theme supports the given theme feature, if not, this setting is no longer available.
• type - Define a setting's type, either theme_mod or option, the default is theme_mod.
  • theme_mod settings are only available in the current theme, they are all settings that maintain the current theme, and they are special for each theme. To get the value of specific settings, you might use the get_theme_mod function with an argument of the name of of a specific setting. Notice that the get_theme_mod function will change where it fetches data from every time we change themes, it also means that function is dependent on the theme we use. Say for example, when we use Twenty Eleven, the get_theme_mod function get data from the theme_mods_twentyeleven option, and the theme_mods_twentyten option if we use the Twenty Ten theme.
  • On the other hand, option settings will available everywhere, as you know, it's option that we usually use. To get the value, we use get_option: function, presumably you know this.
• capability - The capability required for current settings to be displayed to the user. Read more about Roles and Capabilities
• sanitize_callback - The callback function that sanitizes data input. Theme Customizer has an available function called sanitize_hex_color_no_hash that is used to check data input is a hex color without a hash.
• sanitize_js_callback - The callback function that sanitizes data used for Javascript.
• transport - The way data will be transported, can be either refresh or postMessage.
  • refresh - Every time there is something changed in the setting options, the Theme Customizer forces the Preview frame to reload, so the content in Preview frame will be totally refreshed.
  • postMessage - Instead of refreshing the whole Preview frame when something changes, the new data will be transported instantly to the Preview frame using JavaScript techniques.

So the reason that WordPress has these two ways to transport data (refresh and postMessage), is for the changes that have less impact on the page structure, or for simple changes (maybe add/remove something or change the value of some properties of HTML/CSS). We should use postMessage for these as they can be processed with JavaScript instantly and easily, without the need to reload the whole page. Conversely, if new changes to settings will effect the page structure, or are difficult for Javascript to do effectively, it's better to use refresh. Also let me know your thoughts about this by leaving your comments.

The following is a simple example of adding a new Setting:

$wp_customize->add_setting( 'blogname', array(
	'default' => get_option( 'blogname' ),
	'type' => 'option',
) );

Same as Section, we also have get_setting and remove_setting for Settings:

$wp_customize->get_setting( 'id' );
$wp_customize->remove_setting( 'id' );
// Ex: Get value of setting
$wp_customize->get_setting( 'blogname' )->value(); // Return website's name;

Control

This component will arrange settings for proper sections, define the type of settings, and then render their content. Each control is an instance of the WP_Class_Customize_Control class ( located in wp-includes/class-wp-customize-control.php ).

$wp_customize->add_control( 'id', array(
	'label' => '',
	'settings' =>  // Default is id property.
	'section' => '',
	'type' => '', // Default is "text"
	'choices' => '', // This is optional, depending on type's value.
	'priority' => '', // Default is 10.
) );

• id - A unique id for control, also to be used as the name of the setting option if the value of the following settings property is not defined.
• label - The label of setting.
• settings - The name of the setting option that is handled. If leaving blank, the value of above id will be used.
• section - The section that the setting belongs to.
• type - The type of setting option will be rendered. The Theme Customizer has some default values that you can use:
  • text - The kind of input setting option will be a text input type. This is also the default value if you don't pass anything for the type property.
  • checkbox - Rendering a checkbox setting option.
  • radio - Rendering a list of checkbox setting options. You need to pass an array of value/title pairs for each radio input as choices
  • select - Rendering a select setting option list. Like radio, its option list needs to be passed through the choices attribute.
  • dropdown-pages - It's a select list, however, was built for displaying the website's pages list option.
• choices - List of setting options for the radio and select types.
• priority - Used to specify the order in which a setting is displayed. Lower numbers correspond with earlier execution, and settings with the same priority are executed in the order in which they were added.

Getting and removing a control, just do as follows:

$wp_customize->get_control( 'id' );
$wp_customize->remove_control( 'id' );
// Ex: get value of setting that control manage
$wp_customize->get_control( 'blogdescription' )->value(); // Get website's description.

Conclusion

In this series, I intended to show every single component along with its examples in action. However, it's hard to explain everything thoroughly because of the strict connection of components. So finally I decided to show the necessary informations for each component first, then give examples in action later, in the next part. Hope it don't make you feel boring. Again, I'm looking forward to hearing your comments, any and all feedback is much appreciated. Thank for reading!