In the third part of the Theme Customizer series, we introduced the Theme Customizer Boilerplate, which simplifies the code that handles your theme options. By passing an array of option fields, the boilerplate takes care of registering Theme Customizer sections, settings, and controls behind the scenes. The boilerplate allowed users to use text fields, checkboxes, radio buttons, and select fields in Theme Customizer. In this article, we will show you how to extend it.
Before proceeding, please download the latest version of the WordPress Theme Customizer Boilerplate from its Github repository. We have made some improvements since the last tutorial, and it is important that your code is up to date. Once you copy the boilerplate to your theme folder, you don’t need to edit its files at all. All the editing is done using filter and action hooks.
There are several action and filter hooks in the WordPress Theme Customizer Boilerplate. You can hook into any one of them from your theme’s functions.php file by using add_action and add_filter functions:
– ‘thsp_cbp_directory_uri’ – Filter hook defined in helpers.php, allows you to change the location of Customizer Boilerplate in your theme folder.
– ‘thsp_cbp_menu_link_text’ – Filter hook defined in helpers.php, lets you change Menu text link.
– ‘thsp_cbp_capability’ – Filter hook defined in helpers.php. Allows you to change default required capability used in $wp_customize->add_setting method.
– ‘thsp_cbp_option’ – Filter hook defined in helpers.php. If you’re using ‘option’ in your settings arguments, use this hook to change the name of the entry your theme settings values will be stored under in wp_options table.
– ‘thsp_cbp_options_array’ – Filter hook defined in options.php, you MUST hook into it and replace the default options array (containing sample options) with options that are used in your theme.
– ‘thsp_cbp_custom_controls’ – Action hook defined in custom-controls.php, by hooking into it you can create your own custom controls.
– ‘tshp_cbp_remove_sections’, ‘tshp_cbp_remove_controls’ and ‘tshp_cbp_remove_settings’ – Filter hooks defined in customizer.php. You can pass them arrays of built-in section IDs (or controls IDs, or settings IDs) to remove some of the built-in sections, controls or settings.
The updated version of Theme Customizer has a few more controls you can use — textarea field, HTML5 number field, and images field, which is basically a fancy version of radio buttons. These custom controls are defined in custom-controls.php. You can add a number field control to the array that holds all your options by using the following code:
‘new_number_field’ => array(
‘setting_args’ => array(
‘default’ => ”,
‘type’ => ‘option’,
‘capability’ => $thsp_cbp_capability,
‘transport’ => ‘refresh’,
),
‘control_args’ => array(
‘label’ => __( ‘Number’, ‘my_theme_textdomain’ ),
‘type’ => ‘number’, // Textarea control
‘priority’ => 8
)
)
If you ever need to add your own custom controls, you can do it by using the ‘thsp_cbp_custom_controls’ action hook. Make sure you prefix your custom control class with something unique, so its name doesn’t clash with another class.
In the next article, we will take a look at how to add “conditional theme options” – ones that will only appear if a certain plugin is active and help you keep Theme Customizer screen de-cluttered. If you have any feedback or ideas on how to improve the Customizer Boilerplate, please let us know.
