WordPress Customizer: Supporting 600 Theme Options – a Case Study

Converting 600 Theme Options to the WordPress Customizer

This post describes the process of converting the traditional WordPress “Theme Option” interface of the Weaver Xtreme WordPress theme to the WordPress customizer interface. Beginning in the fall of 2015, the WordPress.org theme standards require that themes use the Customizer interface rather than the long-time, traditional theme Settings API for theme options.

When this change was announced in early 2015, there was a huge outcry of protest. Arguments against ranged from the difficulty in converting a lot of existing work, to the many perceived limitations of the Customizer interface, most especially the limited width and limited number of standard controls supported.

I must admit that I was among the many objectors to this requirement. After all, my theme has over 600 options, and that is a lot of code conversion. There is a “loophole” in the requirement – theme developers are allowed to use the legacy theme options interface via a theme support plugin.

That was my plan – add a few options via the Customizer interface to meet the basic requirement, but keep the legacy option interface via a plugin. In the end, that plan turned out to be only half right. You still can use the Weaver Xtreme Theme Support plugin to get the legacy interface. But, in the process of trying a few basic settings with the Customizer, I was converted, and ended up moving the entire option interface to the Customizer.

The newly released Weaver Xtreme Version 2.0 theme supports every single theme option using the Customizer. What happened? How did I go from one of the most strident objectors to the new requirement to become a total advocate? Well, as Samuel Wood (aka, Otto) put it in an e-mail to me – “It is one of those things you can’t un-see.” Bottom line, it is the WYSIWYG design paradigm, especially with “live update” options, of the Customizer that have become totally compelling to me. Moving the mouse over the color selector and watching it change instantly on the site preview is just something you can’t give up once you’ve seen it. Compared to the set a value, switch browser tab, refresh the page approach required to use the legacy theme options interface, watching your site instantly update is something that becomes impossible to live without.

The rest of this article describes the process of converting over 600 theme options to use the Customizer process. It definitely was not an easy process. The shear volume of Weaver options also exposed a serious problem with the pre-WordPress 4.4 code that led to a major change in the core customizer code for WP 4.4 that will greatly improve the Customizer performance of all themes using it. I also will address some other issues I have with the Customizer, and some solutions I was able to implement.

First, a little history of Weaver.

Weaver Theme – Let the user control the design

I created the first version of the Weaver WordPress theme back in 2010 based on one simple idea: any WordPress site creator should be able to totally control the design of their site without needing to know how to create custom CSS rules,  write PHP code to create child themes, or understand the core WordPress code interface.

There are a whole lot of WP designers out there that think that that 600 options is completely out of line – that anything beyond a nicely designed basic theme should require the services of a professional designer who can create a custom theme requiring custom CSS and PHP code. I don’t agree. That approach can produce great sites, but if you look at a sample of the many thousands of Weaver sites, you’ll can see just how creative even a novice can get with a complete set of options.

Over the years, the original Weaver 2010 theme has evolved into the current Weaver Xtreme theme. In the process, a very large and devoted following for Weaver has developed, and there are probably over 100,000 sites using either the previous Weaver II version, or the current Weaver Xtreme version.

From perhaps a hundred or so options in Weaver 2010, with a steady stream of suggestions and requests from the Weaver user community, the latest version of Weaver Xtreme has over 600 selector, color picker,  checkbox , or fill-in-the-blank options. That is a lot, and certainly has presented an interface design challenge on my part.

The Weaver Legacy “Theme Options” Interface

Ever since the beginning, Weaver has supported a traditional interface from the Appearance -> Theme Options menu. The options are organized into a section of tabs. The core set of options are on the “Main Options” tab, with further options placed on sub-tabs generally based on a “where” organization: Wrapping Areas, Sidebars, Header, Menus, Content, Posts, and the Footer. Under each of those area tabs, the options are organized into additional sub-areas and a menu at the top to jump to a sub-area. Finally, the actual options controlling “what” would be set are grouped under each sub-area. Almost all of the “what” options include an icon in the left column to help find the correct option.

In addition to the option values themselves, each option also includs a fairly detailed description of what the option does. Many closeley related “what” options such as font settings are combined into a tightly grouped set of related options. All of the options are laid out using the full width of the screen.

Legacy Options

Legacy Theme Option Interface

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).

weaverx-customizer-top-level weaverx-customizer-second-level weaverx-customizer-bottom-level


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



Beyond “Responsive” Design for Mobile Devices

As mobile web devices are increasingly used to access almost any web site, the need to have a site display properly on a small screen has become an essential part of any site design.

One very good technique used to achieve attractive displays on mobile devices is known as Responsive Design. A pure Responsive Design will be based strictly on using flexible CSS rules (e.g., max-width, or using relative sizes such as %), as well as using @media CSS sections for specific sized device.

A second approach (and one I don’t like) is to use a completely different design for a mobile site. These designs typically present a completely different organization to the site, and tend to use horizontal bars that will open or close sections. This certainly can work well, but the visitor is left with a totally different experience of visiting the site than when viewing from a desktop browser.

Ideally, any visitor to a site will get a similar experience no matter which browser is being used. The site will share a general look and feel, as well as have the same organization. Content such as videos will be displayed appropriately on both the desktop view, and the mobile view. Mobile views will have features that make it easier to navigate the site such as different menu operational design (the traditional pull-down menu does not work very well on phone sized screens, for example), or different handling of links (the hover capabilities doesn’t work very well on many mobile devices, for example).

While a pure responsive approach can indeed lead to sites that work well on mobile devices, I contend that this approach is not enough. In order to get the ideal view on both desktop and mobile browsers, I believe it is critical to include features in the site design that will display the site differently depending on the specific device being used to view the site.

Here are some things that can’t be done  or done efficiently with a strictly responsive design:

  1. Switching between the mobile view and a full desktop sized view.
  2. Displaying different menus depending on the device.
  3. Selectively displaying non-responsive content (e.g., external ads) on desktop, and providing alternative responsive content for mobile devices (e.g., alternate ad).
  4. Selectively displaying Flash or alternative media for desktops, Android, or iOS devices.
  5. Taking advantage of device specific capabilities (Android, iOS).
  6. Selectively displaying large amounts of content depending on device (e.g., a full sidebar for desktop, or a smaller, alternative sidebar for mobile).
  7. Dynamically adjusting viewing size of YouTube or Vimeo videos.
  8. Dynamically adjusting iframes.

Some of these technically could be done with a responsive design, but involve sending more than one alternate block of content (e.g., a different menu for desktop and mobile device), and then selectively adjusting the “display” attribute. This works, but involves sending extra content to the device. On the other hand, capabilities such as dynamically showing different content for Android and iOS devices cannot be handled.

My Weaver II WordPress theme incorporates features that allow “Beyond Responsive” site design. It implements a basic browser model that accounts for four general types of devices: desktops, small screen phone like devices, small tablets (like the Kindle Fire or B&N Nook), and large tablets.

There are features included with the theme that allow different content to be directed to each of these devices. For example, a different menu is used for phones, a modified pull-down for small tablets, and a standard pull-down menu for large tablets and desktops. Mobile devices will automatically display links differently because the traditional mouse-over hover effects often used on desktop browsers don’t work that well on touch devices. Videos (from YouTube, for example) are automatically displayed in the correct size. These features all happen automatically. While many of these features could be done by strictly responsive design, others (such as YouTube video sizing) require more active, device specific measures.

There are other features that allow the content creator to manually control content display for different devices. For example, the standard WordPress sidebars are automatically hidden, but an alternative sidebar is provided for more appropriate display on small screens. The creator can also selective display one kind of externally provided content (ads, for example) that still is often not responsive on desktops, while providing an alternative version for mobile devices – perhaps a fixed ad or other non-rotating but responsive content.

Weaver II Security

From time to time, someone asks about how Weaver handles web security. Weaver and Weaver II share their security code, and it has been scrutinized by both the WordPress theme review teams, and the Weaver user community. Over time, the … Continue reading →