Context-aware WordPress Customizer

Nov 16, 2017

The WordPress Theme Customization API is an incredibly powerful tool, enabling folks of all skillsets to dive in and customize their websites — if their current theme supports it.

Having worked quite a bit with extending the WordPress Customizer at ThemeBeans, I started production on a newly minted Customizer-dependant commercial plugin, coined Login Designer.

Login Designer leans heavily on the Theme Customization API to bring real-time live previewing to WordPress login page styling. Among other exciting Customizer tidbits, I’ve been experimenting with contextually displayed options, custom edit shortcuts, and context-aware previews.

This post defines exactly what WordPress Customizer context-aware previews are, and why they can lead to a fantastic user experience. Then we’ll dive into real-world code examples from Login Designer.

What exactly are context-area previews?

In the context of the WordPress Customizer, context-aware previews are events triggered by the Customizer, which navigate the preview window.

Let’s look at Login Designer as an example:

The plugin creates and adds a “Login Designer” panel to the current theme’s Customizer instance. Once the Login Designer panel is opened, the context-aware preview event is fired and the preview window loads the login styler.

And to clean everyone up, once a user backs out of the “Login Designer” panel, the preview window returns back to the home page. Pretty cool ‘eh?

Why are they so fantastic?

Let’s think of different ways the application of context-aware previews would work phenomenally in the WordPress Customizer:

When editing home page options, the preview shows you the home page
When editing portfolio options, you’re looking right at the portfolio
When configuring display options for the 404 page, you see it in action

Context-aware previews mitigate the number of clicks a user has to perform when utilizing the Customizer. Users will have to navigate just the Customizer, not the Customizer and the preview window.

Adding your first context-aware preview

There are three steps to adding a context-aware preview to a WordPress theme or plugin — if the plugin leverages the Customizer.

Enqueuing the controls javascript, to trigger the action
Enqueuing the preview javascript, to listen and perform the action
Localizing any page data needed for the scripts

Here is a collection of gists deployed within Login Designer to enqueue the necessary scripts for the plugin’s context-aware previews.

Looking at the gists, you’ll see that I’ve enqueued both the preview and controls scripts accordingly. Then I made Login Designer’s styler page data available to the controls script via localization. That’s it!

Within the controls script, the Customizer is checking on the status of the plugin’s login_designer top-level Customizer panel. It then communicates with the preview script via login-designer-open-designer, dependent on whether or not the preview window is already on the page requested.

The preview script listens and sends the preview window to the specified location when needed. Simple enough!

Closing

Sure, these kind of user experience improvements are not 100% necessary, but they do make WordPress much more exciting and intuitive to work with. In all, WordPress themes and WordPress plugins both can benefit from taking full advantage of the Theme Customization API.

It’s a wonder more developers have not leveraged the WordPress Customizer to improve their products. Why do you think that is?

Responses

Bheem

August 5, 2018

That’s a fantastic post right there. I was satisfied with just the contextual controls with active_callback lately, but this is really thought provoking.

I have one question though, how would I implement to customize settings for archives, single post, pages, or even custom post types?

Thanks a lot for sharing the knowledge.

Reply
1. Rich Tabor
  
  August 5, 2018
  
  Awesome! I’m glad you’re liking it!
  
  For general options, you could create additional sections and panels as you see fit. And for Custom Post Types, you could do the same, but have a conditional in place to check first if the post type exists. That way the custom post type’s options do not show, if the site does have not deploy them.
  
  Reply
  1. Bheem
    
    August 16, 2018
    
    Hello there, Rich!
    
    Thanks a lot for taking time to post a reply 🙂
    
    I totally got you with creating sections and panels, and then specifying a check for post-type(s) before having the previewer change the location. It does make sense.
    
    The thing that is keeping me stuck: I’m kinda looking for a change of preview from the current previewer location, to a post when the “post layout” panel or section gets expanded.
    
    It looks like I’m almost there with using “api.settings.url.home”, but have to couple it with something hard-coded (eg. “?p=1”, which may not be existing in case of every other WordPress-based site).
    
    I’m not sure where I’m missing it. What are your thoughts about?
  2. Rich Tabor
    
    August 20, 2018
    
    Yea, you’re close! You need to pass the URL like I’m doing here, here, and then look for that in the Customizer preview file — like I have here.
    
    I do the same thing on my Tabor WordPress theme, where opening the 404 Settings panel opens up a 404 page (though that code is not public).
    
    Maybe this helps!
Bheem

August 16, 2018

Well, Rich, what I think about developers still not leveraging the Customizer completely is perhaps because of the Option Panel culture.

Customizer has been around for a while now. It was introduced when almost every WordPress theme developer was settled with an option panel of their own or someone else’s.

More than the end-users, it’s the developers who should take an initiative; as clearly, option panels are meant for plugins and Customizer is the way to do it for themes.

Cheers to the WordPress Customizer!
(Greetings from India)

Reply
1. Rich Tabor
  
  August 20, 2018
  
  I totally agree mate! I’d even go as far to say that plugins should utilize the Customizer as well (where it makes sense). For example, WooCommerce has started moving many of it’s display related options inside the Customizer.
  
  Reply