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.
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.
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
$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', ) );
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
option, the default is
theme_modsettings 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_modfunction with an argument of the name of of a specific setting. Notice that the
get_theme_modfunction 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_modfunction get data from the
theme_mods_twentyelevenoption, and the
theme_mods_twentytenoption if we use the Twenty Ten theme.
- On the other hand,
optionsettings 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_hashthat is used to check data input is a hex color without a hash.
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.
So the reason that WordPress has these two ways to transport data (
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
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
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;
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
settingsproperty 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
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
select- Rendering a select setting option list. Like
radio, its option list needs to be passed through the
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
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.
Ideas: Components are objects, working under classes. So we could extend these classes to modify or customize them in our own way. By default, Wordpress also has some extra components extending in this way. I will walk through them in later parts of this series.
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!