The WordPress Customizer has consistently evolved since its inception, with ongoing development in its API, including the JavaScript aspect. However, it remAIns one of the least documented APIs in the WordPress Codex. Despite this, there are some detailed resources that dEMOnstrate how to utilize the JavaScript API effectively. Using the Customizer’s JavaScript API can enhance the live eDiTing experience for theme customization beyond simply projecting changes to the preview window. You might be familiar with projecting changes in real-time by setting the transport mode to ‘postMessage’ and adding corresponding JavaScript code, like this:
“`javascript
WP.customize(‘blogname’, function(value) {
value.bind(function(to) {
$(‘site-title a’).text(to);
});
});
“`
But you can expand the API’s capabilities further, such as hiding, showing, or rearranging sections, panels, and controls based on another setting’s value, or interconnecting the preview and controls for interactive experiences. This tutorial will delve into these advanced techniques.
**Getting Started**
We’ve covered the WordPress Customizer extensively through articles and Series. detailing the Customizer API, including core concepts like panels, sections, settings, and controls. If you’re not already familiar with these, it’s highly recommended to explore our tutorials and video courses before proceeding.
**WordPress Theme Customizer Guide**
In this tutorial, we’ll focus on the Website title. We have two controls: the default WordPress “Site Title” input field and a custom checkbox to enable or disable the “Site Title.” Both controls are within the “Site Identity” section, and a preview is displayed on the right, rendering the “Site Title.”
Additionally, in the “Colors” section, we have two more controls to change the site title’s color and its hover state color.
**Underlying Code**
Our theme is based on Underscore, where all Customizer-related code resides in `inc/customizer.php`. Here’s a snippet of the code:
“`php
function tuts_customize_register($wp_customize) {
$wp_customize->get_setting(‘blogname’)->transport = ‘postMessage’;
$wp_customize->get_setting(‘blogdescription’)->transport = ‘postMessage’;
$wp_customize->get_control(‘blogdescription’)->priority = “12”;
$wp_customize->get_setting(‘header_text_color’)->default = ‘#f44336’;
$wp_customize->get_setting(‘header_text_color’)->transport = ‘postMessage’;
// Display Blogname Checkbox
$wp_customize->add_setting(‘display_blogname’, array(‘transport’ => ‘postMessage’));
$wp_customize->add_control(‘display_blogname’, array(
‘label’ => __(‘Display Site Title’, ‘tuts’),
‘section’ => ‘title_tagline’,
‘type’ => ‘checkbox’,
‘priority’ => 11,
));
// Add Main Text Color Setting and Control
$wp_customize->add_setting(‘header_text_color_hover’, array(
‘default’ => ‘#C62828’,
‘sanitize_callback’ => ‘sanitize_hex_color’,
‘transport’ => ‘postMessage’,
));
$wp_customize->add_Control(new WP_Customize_Color_Control($wp_customize, ‘header_text_color_hover’, array(
‘label’ => __(‘Header Text Color: Hover’, ‘tuts’),
‘section’ => ‘colors’,
‘priority’ => 11,
)));
}
add_Action(‘customize_register’, ‘tuts_customize_register’);
“`
We’ve made modifications to the code to meet the requirements of this tutorial. We’ve lowered the priority of the built-in `blogdescription` to 12, moving the `display_blogname` checkbox below the “Site Title” input. A new control named `display_blogname` is created with a priority of 11, positioning it between the “Site Title” and “tagline” inputs. The default color for `header_text_color` is set to `#f44336`, and the transport type is set to `postMessage`. We also create a new setting `header_text_color_hover`. Similarly, we set its priority to 11, placing it below the `header_textcolor` setting. All these settings are set to be updated via `postMessage`, allowing asynchronous value transfer and real-time display in the preview window. However, we need to write our own JavaScript to handle these changes.
To load the JavaScript, we’ll create two files: `customizer-preview.js` to handle the preview and `customizer-control.js` to manage controls.
“`
js/
├── customizer-preview.js // 1. For handling Preview
├── customizer-control.js // 2. For handling Controls
├── navigation.js
└── skip-link-focus-fix.js
“`
In `customizer-preview.js`, include the following code:
“`javascript
(function($) {
// Code goes here.
})(jQuery);
“`
This is currently an empty closure function. In the next tutorial of this series, we’ll discuss how to preview changes in the preview window in more detail.
In `customizer-control.js`, add:
“`javascript
(function($) {
WP.customize.bind(‘ready’, function() {
var customize = this;
// Code goes here.
});
})(jQuery);
“`
This code will wrap inside the `customizer-ready` event in this file, ensuring everything in the Customizer, including settings, panels, and controls, is ready before executing any custom functionality.
Finally, after adding these codes, we’ll load both JavaScript files in two different locations:
“`php
// 1. customizer-preview.js
function tuts_customize_preview_js() {
wp_enqueue_script(‘tuts_customizer_preview’, get_template_directory_uri() . ‘/js/customizer-preview.js’, array(‘customize-preview’), null, true);
}
add_action(‘customize_preview_init’, ‘tuts_customize_preview_js’);
// 2. customizer-control.js
function tuts_customize_control_js() {
wp_enqueue_script(‘tuts_customizer_control’, get_template_directory_uri() . ‘/js/customizer-control.js’, array(‘customize-controls’, ‘jquery’), null, true);
}
add_action(‘customize_controls_enqueue_scripts’, ‘tuts_customize_control_js’);
“`
`customizer-preview.js` will be loaded into the Customizer preview window through the `customize_preview_init` action hook, while `customizer-control.js` will be loaded in the Customizer backend, making its settings and control elements accessible via the `customize_controls_enqueue_scripts` action hook.
**What’s Next?**
Since WordPress’s inception, a significant Investment.has been made in PHP, and it’s no surprise that most developers supporting the ecosystem are more proficient with the PHP API than the JavaScript API. Recently, WordPress has integrated JavaScript extensively through the Customizer and WP-API. Mastering the JavaScript API in WordPress Customizer can be quite a challenge due to its limited documentation. In this series, we’ll dive deep into this topic.
In the meantime, if you’re looking for other utilities to enhance your growing WordPress toolkit or want to improve your coding skills in WordPress, don’t forget to explore Envato Market, where we offer a range of resources.
Here, we’ve laid the groundwork for using the WordPress JavaScript API. That’s it for now. In the next part of the series, we’ll explore more about the JavaScript API in WordPress and start writing functions that can be immediately implemented in your themes. Stay tuned!
相关文章
