Converting to the WordPress Customizer

Just where does one start in converting more than 600 options in a large existing code base to totally new code for the Customizer? First, it took some motivation. I already described my Eureka! moment at seeing the magic of colors instantly updating in from the customizer. Once I was hooked, it was really a matter of just doing the work. The conversion took a bit over 3 months, and involved something over 7000 lines of new code – this for mostly by a single programmer.

How Do You Organize 600 Options?

The WordPress Customizer interface has some significant design limitations. First, it is somewhat limited in how wide it can be in the left column. While one can make it wider, there still must be room for the site preview on the right. So, this limitation inherently translates to a bunch of options stacked vertically in the column. The traditional interface demonstrated in the image above allows one to see many options is a relatively small vertical space. The legacy Weaver interface relies on seeing a lot of options on a single screen, and the ability to visually locate relevant options via the icons. The Customizer, on the other hand, does not allow very many actual options to appear at once – all that information (value, label, explanation) that was available horizontally now must be vertically aligned.

The second issue is that the number of built-in controls supported by the Customizer is somewhat limited. In addition, there is an expected style to the options that is wise to use a guideline for other options. It is possible to fairly easily build some custom controls, but for consistency, it is also good design to use the standard controls. This limitation, however turns out not to be the real issue. The real limitation is the vertical space required for showing more than 3 or 4 options at a time.

Fortunately, this vertical space limitation really applies only to controls. The Customizer allows one to organize actual setting controls under single line menus. The Customizer has 3 levels of interface components: a top level Panel, which is really a somewhat standard vertical menu. So, you can get quite a few (10 to 15) top level menu items to fit quite nicely and visibly on the first level of the Customizer interface. The second level is called Sections, and those serve as a sub-menu to the Panels, with the same feature: 10 to 15 easily accessible menu items organized vertically. Each Section serves as a host for actual Controls to set option values. Controls are things like color pickers, checkboxes, text input, etc. When the user opens a Section menu, they are presented with a vertical display of some number of options. Depending on the option, and the need for an option description, any specific option will consume anywhere from 3 or 4 “lines” of space, up to the entire visible portion of the Customizer vertical space. There is a vertical scroll bar to scroll to any of the options displayed in the given Section.

So how does one get 600 options to fit into the Customizer architecture in a fashion that any specific option is at most 3 clicks away? Obviously, it involves somehow organizing the 600 options into groups that logically belong in a section of a top level panel.

The design breakthrough for me was to realize that rather than the “where” area-oriented organization of the legacy Weaver option design, a “what” based hierarchy worked much better. So the top level of Weaver’s customizer interface is organized by “WHAT” – what kind of option does the user want to change (e.g., colors, spacing, typography, and so on). Under each WHAT top level panel is a section menu listing WHERE the what can be changed. Each WHERE menu is virtually identical for each WHAT selection. And at the bottom level of the menu hierarchy are the specific options that apply to each WHAT:WHERE location. The number of options vary somewhat at the bottom, and range from just one or two, to a more typical 10 or so options. A few sections have many more options that apply to specific areas.

But in the end, it really is quite easy for the user to drill down to exactly the option needed. In essence there are really only about 20 choices for the user to learn: 11 WHATS, and the same 10 WHERES under each WHAT. Once the user is at the proper option section, the consistent Customizer control option interface is present. Note that the top level set of panels will also contain some of the “standard” WordPress option sets such as Custom Menus, or customizer options from other plugins.

For example, this is the menu hierarchy to get to the color options for the site header area. Note the use of Dashicons to help identify each WHAT option level (the brush for colors, for example).

Refinements

This option organization seems pretty good. There are still over 600 options, so it will still take a bit of a learning curve to find them all. But having the instant updating of the site preview makes the learning curve significantly easier than with the legacy theme options interface.

But this interface also demonstrates what is, in my opinion, a serious user interaction problem with the customizer interface. While it is easy to drill down to the options level, going back up the hierarchy can be somewhat difficult if the user needs to scroll down on the bottom options level – a very common occurrence. In that case, to go back up, the user must scroll the options section up, then click the < back button at the top of the column, then clikc once more to get back to the very top level of the Customizer hierarchy. This potentially means a scroll, click (up a level), click (up to the top level), click (down a level), and a final click to open the new options level – a somewhat tedious 5 operations. Most of this is caused by the up a level < button being scrolled off the top of the Customizer column.

To get around this annoyance, Weaver Xtreme has added a new “Quick Jump” menu at the top of the Customizer column on the “Save” bar. There is a new Menu button that opens a standard drop down menu with the standard top level WHAT items and the second level WHERE items that allows direct navigation to any set of options. As a side benefit, the Quick Jump menu also supports an alternative organization of navigation based on a WHERE/WHAT order.

Technical Details of the Conversion

This section is more oriented toward some of the technical issues involved with the conversion.

WordPress Customizer API Issue

From all indications, Weaver Xtreme, with its 600+ options, is making more use of the Customizer API than any other theme I can find. Certainly none of them even approach the total number of options supported. Not too far into the conversion, it became apparent that there was a serious code speed issue with the WP implementation.

There are actually two speed issues involved related to the total number of options included. One involved the fact that almost all the runtime  Customizer processing is via JavaScript. The impact of this is that when the Customizer first loads, there is a significant delay (up to 10 seconds depending on the client CPU and browser speed – Mac Safari is far faster than any other browser) actually loading the interface. But once loaded, the response is almost instant.

The other, far more serious, problem involved a very elegant but flawed method of overriding the original theme setting values vs. the new, trial settings as set in the Customizer interface. Each option used by the Previewed view of the site is filtered to return the new value, and those new values sanitized. The original Customizer core implementation used a standard WP filter for each option. While elegant, the ALL filters were run every time an option was used. This turned out to be an exponentially growing computation. So, with say 40 options processed, that would result in 1,600 executions of the filters. A hundred options would be 10,000 executions, and so on. Thus, each refresh of the preview window would take longer and longer as more options were added to the Customizer interface. We’re talking about over 30 seconds of real time computation per refresh as the number of options went over about 300. Fortunately, there was a way to override the responsible Customizer PHP class for at least part of this behavior, and I was able to get the 600 options to refresh in just 7 or so seconds. Fortunately, after I reported this issue, the main WP core Customizer developer, Weston Ruter, found an alternate algorithm for this process, and the refresh panel now refreshes essentially instantly (a second or two) no matter how many options there are. This new code will be available in WP 4.4. Even though it was Weaver’s 600 options that demonstrated the need for a fix, the fix really helps all themes with more than even 20 customizer options, so this was big win for everyone, and will in the end save uncountable hours of combined time of users waiting for the preview to update. Thanks, Weston!

Live Update vs. Refresh

One of the features of the Customizer is that it supports two kinds of updating when a user changes a value of an option. The easiest is the Refresh method, which causes a full refresh of the preview window whenever a value is changed. This is often okay. But the Live Update (postMessage) method is just so much better for the user. Values change in essentially real time, so a color or margin or font family will change instantly. This is the real Wow factor in the Customizer.

For many options, it is fairly easy to implement Live Update via a bit of boilerplate jQuery code. Of course, with so many options in Weaver, this still amounts to thousands of lines of code to implement. And depending in the complexity of the option, it is not always possible to use jQuery to make the required live updates to the preview window, and the full refresh method is required. For example, the layout of sidebars requires extensive revision of the generated HTML output of the site, and refresh was the only reasonable way to accomplish this.

Even so, I made a huge effort to make as many options a possible to use Live Update. While this is really nice for colors, margins, font options, and others, it is especially useful for Weaver’s more advanced users who add their own custom css rules. Watching a custom CSS rule live update as you type the rule into the custom CSS box is just amazing.

Customizer Features

Converting from Theme Options

For all the whining there was going on about the new required use of the Customizer, in the end, I personally found most of the complaints not really all that on target. Perhaps the most relevant was the need to rewrite any option interface to work with the Customizer. That indeed takes a lot of time to do right to take full advantage of the Customizer. In some ways, maximizing support for Live Preview was the most difficult, but also the most important.

But as far as limitations on the kinds of controls, or the width of the column, in the end I found these to be pretty much irrelevant. The real solution to making an interface work with the Customizer is to get a really good organization of the menu structure. Fortunately, after 5 years of input from thousands of users, I was able to build what I think is a logical and easy to learn option structure. I’ve looked at many other themes, and think that many of them could use a bit of revision in the logical structure of the menus to better take advantage of the Customizer.

And since most themes don’t have hundreds of options, I think the time to rewrite an options interface will not really be that long for most themes, while efforts to add full live preview will  be well worth the effort. Live preview supported by the Customizer is really at the heart of an enhanced user experience, and its uses should be the main goal of any theme using the customizer.

Inherent Navigation Usability Issue

As I described earlier, the Customizer has an inherent design/usability issue. While it is fairly easy to navigate down the menu once on the top level, it can be quite tedious to navigate back up and then back down again. This is mostly caused because the “back” button scrolls off the top of the Customizer window if the user has scrolled down to look at options. What would help would be to have the back button on the top Save bar, or to not have the Back button scroll off. As noted, my solution was to add a complete “Quick Jump” drop-down menu at the top. I think a menu like this could easily be dynamically generated based on the current panel/section/options hierarchy, and something like it would greatly enhance the usability of the interface.

Initiating non-Customizer Actions from inside Customizer

One of the very frustrating missing features of the Customizer control API is an easy way to initiate “outside”, non-Customizer actions from within the Customizer interface. Weaver Xtreme has an excellent example of this – saving and restoring settings to/from the user’s computer. This is not particularly difficult, but does require the proper response to clicking a Save or Restore button in the interface. Finding a work around for this was quite complex, involving dynamically creating forms via jQuery, creating custom nonces, and triggering a full browser refresh.

I’m sure there are many other instances of a need to do something outside the Customizer while staying withing the Customizer’s interface. It would be most helpful if there were a “Button” control that could interface to PHP or JavaScript callbacks automatically.

While it may be possible to accomplish this with the existing Customizer API, it is not easy, and there is what I think is a serious lack of complete documentation, and real world examples of just how to use the full JavaScript based Customizer API. I consider myself a top of the line PHP programmer, a pretty competent CSS programmer, but just okay with JavaScript. Most of the existing Customizer API documents do target develpers with just limited JavaScript skills, but I think there are many little gems hidden within the API that are beyond my skills. (Edit: see the little gem described in the next section!) I don’t think it is optimal to require developers to open and read the Customizer JavaScript code to be able to use some of the more advanced features. They should be documented, and documented in a way for just average JavaScript programmers to understand. It is hard to be able to be great at PHP, CSS, WordPress API, JavaScript, jQuery, and the WP JavaScript API all at the same time.

Hybrid Preview Refresh

There are instances where a live (postMessage) update works really well, and easily most of the time, but on some special cases is unable to easily modify the DOM correctly. It would be really great to have a way to force a preview refresh from the postMessage jQuery script in some instances. The transport would be ‘postMessage’, but the actual ‘postMessage’ hander should be able to trigger a refresh as needed.

EDIT: This functionality is available now. Please see this article: Implementing Selective Refresh in the Customizer