This post will explain how to easily implement the WordPress theme customizer in your WordPress theme by using the Theme Toolkit provided by Theme Foundation. If you’re not interested in saving time and energy by using the theme toolkit, please see my previous tutorial explaining how to implement the theme customizer from scratch. Let’s get started.
1. Get the Theme Toolkit
The Theme Toolkit can be downloaded from Github.
2. Load the required files
Once we’ve downloaded the toolkit, we can simply place the “toolkit” folder in our theme and add the following code to the theme’s functions.php file.
/**
* Loads the toolkit/toolkit.php file for adding toolkit feature support.
*
* @since toolkit 1.0
*/
function theme_toolkit_setup() {
// Adds theme support for toolkit features.
add_theme_support( 'toolkit-theme-customizer' );
// Loads the toolkit setup file.
require_once 'toolkit/toolkit.php';
// Initializes the theme toolkit.
theme_toolkit_init();
} // End function thtk_setup()
add_action( 'init', 'theme_toolkit_setup', 1 );
This function adds theme support for the toolkit theme customizer. It them loads the toolkit.php file, which in turn will load any other files required to implement the theme customizer. Finally, it initializes the theme toolkit.
If we save the functions.php file and go take a look at the WordPress admin area, we’ll see that there is a new page titled “Customize” located in the “Appearance” menu. We haven’t added any new settings to the theme customizer, but WordPress has a few settings built in. For example, if the theme supports custom backgrounds, WordPress will automatically add the corresponding settings to the theme customizer.
Once this initial section of code is in place, we interact with the theme toolkit using filters. For example, those of you who would like to change the title of the “Customize” menu item can do so by simply placing the following code in your functions.php file and changing “New Title” to whatever you’d like the new title to be.
function example_customizer_title() {
return 'New Title';
}
add_filter( 'thtk_theme_customizer_title', 'example_customizer_title' );
For those of you who are not familiar with WordPress filters, the following documentation and tutorials should be helpful:
- Of course, the WordPress Codex
- Tom McFarlin’s “The Beginner’s Guide to WordPress Actions and Filters” on WPTuts.
- Gennady Kovshenin’s “Inside WordPress Actions And Filters” on Smashing Magazine.
3. Define the customizer array
When using the theme toolkit, all customizer sections and settings are defined in an array. This array is passed to the toolkit using another filter. The following code adds two new sections to the theme customizer (“Example Settings” and “More Settings”). These sections contain all the input types currently available through WordPress and the theme toolkit.
/**
* Defines theme customizer arrays
*/
function thtk_example_customizer() {
$prefix = 'example_';
$customizer_section[] = array(
'section_id' => 'example_settings', // Settings section ID.
'section_title' => 'Example Settings', // Settings section title.
'section_description' => 'Section description...', // Optional. Adds descriptive title text to section title (only visible on mousover). Default: none.
'section_priority' => 200, // Optional. Determines placement in customizer panel. Default: 10.
'section_settings' => array(
array(
'id' => $prefix . 'textbox', // Form element ID.
'title' => 'Text box', // Form element label.
'type' => 'text', // Type of form input field.
'default' => 'Default content', // Optional. Default form field value. Default: blank.
'valid' => 'text', // Optional. Determines which sanitization callback function to use. Default: text.
'priority' => 5, // Optional. Determines display order of customization options. Default: 10.
'transport' => 'refresh', // Optional. Determines how to transport the data to the theme customizer. Default: refresh.
//'valid_js' => '' // Optional. Corresponds with the (largely undocumented) sanitize_js_callback setting callback.
),
array(
'id' => $prefix . 'checkbox',
'title' => 'Checkbox',
'type' => 'checkbox',
),
array(
'id' => $prefix . 'radio_buttons',
'title' => 'Radio Buttons',
'type' => 'radio',
'default' => 'left',
'choices' => array( // Array of id/label pairs.
'left' => 'Left',
'right' => 'Right',
'center' => 'Center',
),
),
array(
'id' => $prefix . 'select_list',
'title' => 'Select list',
'type' => 'select',
'default' => 'two',
'choices' => array( // Array of id/label pairs.
'one' => 'Option 1',
'two' => 'Option 2',
'three' => 'Option 3',
),
),
array(
'id' => $prefix . 'textarea',
'title' => 'Textarea',
'type' => 'textarea',
),
)
); // End $customizer_section[]
$customizer_section[] = array(
'section_id' => 'more_settings',
'section_title' => 'More Settings',
'section_theme_supports' => 'widgets', // Optional. Only show section if theme supports this feature. Default: none.
'section_settings' => array(
array(
'id' => $prefix . 'pages',
'title' => 'Pages',
'type' => 'dropdown-pages',
'valid' => 'integer',
),
array(
'id' => $prefix . 'color',
'title' => 'Color picker',
'type' => 'color',
'valid' => 'color',
),
array(
'id' => $prefix . 'file',
'title' => 'File uploader',
'type' => 'upload',
),
array(
'id' => $prefix . 'image',
'title' => 'File image',
'type' => 'image',
),
)
); // End $customizer_section[]
return $customizer_section;
} // End function thtk_example_customizer()
add_filter( 'thtk_customizer_filter', 'thtk_example_customizer' );
Here we created the function that will hold the customizer array and attached it to the thtk_customizer_filter filter hook. Inside this function we have a variable named $prefix. This is an optional variable that can be used as a prefix for the settings IDs to ensure they are unique.
Next there is an array named $customizer_section. Each item in this array will define one section of the theme customizer.
Please note: If the section_settings array is not populated, the section itself will not be visible in the theme customizer.
| section_id | string | The unique ID of this section. |
| section_title | string | The section title. |
| section_settings | array | Array of settings to add to this section. |
| section_description | string | Optional. Adds descriptive title text to section title (only visible on mousover). Default: none. |
| section_priority | integer | Optional. Determines placement in customizer navigation panel. Default: 10. |
| section_theme_supports | string | Optional. Only show section if theme supports this feature. Default: none. |
Finally, there is the section_settings array which holds all the settings that belong in the particular section.
| id | string | The unique ID of this setting. |
| title | string | The setting title. |
| type | string | The type of form input. For example: text, checkbox, radio, select… |
| choices | array | Array of id/label pairs for multiple choice options such as radio buttons and select lists. |
| default | string | Optional. Default form field value. Default: blank. |
| valid | string | Optional. Determines which sanitization callback function to use. Default: text. |
| valid_js | string | Optional. Corresponds with the (largely undocumented) sanitize_js_callback setting callback. |
| priority | integer | Optional. Determines display order of customization options. Default: 10. |
| transport | string | Optional. Determines how to transport the data to the theme customizer. Default: refresh. |
If you have any comments, questions, or suggestions, please let me know via twitter.