Today we’ll take a look customizing the Customizer user experience. Say that 5 times fast!
It is important to note that the following code snippets will function if placed in a child theme, however they are only presented as examples and may not be ready for production environments. If you’re planning on using these examples in a plugin or theme, you’ll want to make the necessary modifications (i.e. prefixing functions and variables, optimizing code snippets, etc…).
In our previous posts, we’ve covered communication between the Previewer window and the Customizer, as well as adding helpful buttons to the Previewer. Today we’ll discuss more practical uses for these buttons and ways that you can customize the user experience within the Customizer.
In this post, you’ll learn how to open the Customizer Sidebar, open the Widgets Panel, open the Primary Sidebar Section, and open the Add a Widget “Panel”. We’ll be building off of the scripts that we created in the previous posts.
Preface: WordPress 4.1 Customizer API Updates
With the release of WordPress 4.1, there was a shift towards improving Customizer functionality. These new improvements help us greatly when it comes to interacting with the Customizer.
Previously, in Conductor, we had to create our own logic to open Panels and Sections. In WordPress 4.1, we can use new functionality built into the Customizer JavaScript API to accomplish a lot of these tasks. Kudos to the core WordPress development team!
Please Note: Some of the following code snippets will only work with WordPress 4.1 and above.
More Helper Buttons
If you’ve been following along, we currently have two helper buttons that are added to the Previewer via JavaScript. To kick off this tutorial, we’re going to add a few additional helper buttons to the Previewer. The first button that we are going to add is a button to open the Customizer Sidebar. The other buttons will open a Panel within the Customizer, open a Section within a Panel, and allow a widget to be added to a sidebar.
Add the following code to the ‘active’ event callback function in the customizer-previewer.js script:
Triggering the Events
Now we have to listen for touch/click events on these new buttons. Just like we did in the last post, we’ll listen to the document and then send the event over to the Customizer upon click.
Add the following code to the ‘active’ event callback function in the customizer-previewer.js file after the first snippet above:
If you were to load the Customizer with these scripts in place, you’d see the new buttons added to the end of the page in the Previewer window. As with the previous post, these buttons will be pretty useless at this point in time since we haven’t set up the event listeners on the Customizer. We’ll fix that in the next step.
“Open Customizer Sidebar” Event Listener
The first event listener that we’ll add functionality for is for the “Open Customizer Sidebar” event. The Customizer Sidebar is one of the only aspects of the Customizer that doesn’t currently have a “state” attached to it so we cannot use built-in functions to expand/collapse it. Instead, we’ll use our own logic to open the sidebar.
Add the following snippet to the ‘init’ function in the myCustomizerPreviewer object in the Customizer (customizer.js) script:
The code above will open the Customizer Sidebar if it is not already open or will pop up an alert() if the sidebar is already open.
“Open Widgets Panel” Event Listener
Next we’ll add an event listener for the “Open Widgets Panel” event. Since Panels are stored in a collection, we can access them using API functionality.
Add the following snippet to the ‘init’ function after the snippet above:
The code above will open the Widgets Panel if it is not already open or will pop up an alert() if it is already open.
“Open Primary Sidebar” Event Listener
This bit of code assumes your WordPress instance has a sidebar with an ID of primary-sidebar registered. Since Sections have been stored in a collection prior to WordPress 4.1, we can also access them using API functionality. One of the cool things about a nested Section (a Section within a Panel) is that once they are expanded (.expand()), their parent (Panel) is also expanded when using the Customizer JavaScript API.
Add the following snippet to the ‘init’ function after the snippet above:
The code above will open the Primary Sidebar Section and the Widgets Panel if they are not already open.
“Add a Widget Panel” Event Listener
The last event listener that we have to listen for is the event that will open the Add a Widget “Panel”. To accomplish this, we need to pass a sidebar Control to the availableWidgetsPanel view’s open() method. We luck out again because the controls are also stored in a collection and we can reference them when we need to.
Add the following snippet to the ‘init’ function after the snippet above:
The code above will open the Add a Widget “Panel” if it is not already open or will pop up an alert() if it is open.
Bonus: The “Open Everything” Event
Technically you could stop at the last event listener, but to make these examples even more practical, why not have a button that triggers an “open everything” event? This is how our “Add Widget” helper button in Conductor functions.
This final event listener will open the Customizer Sidebar, the Widgets Panel, the Primary Sidebar Section, and the Add a Widget “Panel” all in one click.
Add the following snippet to the ‘init’ function after the snippet above:
All that’s left to do now is give it a go! Take a look at the completed functions below for reference.
Here’s the Complete ‘Active’ Event Callback Function
Here’s the Complete Customizer Init Function
Wrapping Up
You may notice that some of the buttons in our example may not work correctly at times. For instance, if the Customizer Sidebar is closed, the “Open Add a Widget Panel” button will open the panel, but not the sidebar.
In Conductor we’re making sure that the Customizer Sidebar is open before any of our event functionality is triggered to ensure the user experience makes the most sense. The snippets above could be easily modified to open the Customizer Sidebar before executing. You might want to add logic to your code to check the various “states” of different Customizer elements depending what you’re trying to accomplish.
The core WordPress development team has added some pretty neat enhancements to the Customizer Javascript API recently. These improvements will surely lead to more dynamic Customizer controls and settings in the future, but you can use them in your projects now.
In the next post we’ll talk about optimizing the code that we’ve created so far and making it more efficient. That’s all for now. Thanks for following along!