How Bruce Wampler Migrated 600 Theme Options to the WordPress Customizer

photo credit: Matteo Bagnoli - cc
photo credit: Matteo Bagnolicc

When the WordPress theme review team announced it would require theme authors to use the customizer to build theme options, many voiced their displeasure in the comments. Bruce Wampler, lead developer of the Weaver Xtreme WordPress theme, commented that his theme received a death sentence due to the requirement.

Eight months later, Wampler has changed his tune and is now in favor of the customizer to display theme options to users, “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,” he said.

In a case study published on the Weaver Xtreme website, Wampler describes why he’s now a fan of the customizer and explains the process of migrating 600 options to it.

Live Updates

One of the most compelling reasons he adopted the customizer is experiencing the live preview feature, “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,” he said.

Serious Performance Improvements

During the migration process, Wampler discovered two serious speed issues. Since the customizer processing uses JavaScript, loading hundreds of options took 30 seconds or more depending on the user’s browser and CPU.

The second issue involved overriding original theme setting values versus new values. The customizer used a WordPress filter for each option. Unfortunately, the filters ran every time an option was configured creating an exponentially negative impact on performance. If 40 options were processed, it resulted in 1,600 executions of the filters.

Wampler worked with Weston Ruter, lead developer of the customizer component, who changed the algorithm to allow multidimensional settings to be scalable. Once the change was made, Wampler was able to load his theme options in one to two seconds. The fix is included in WordPress 4.4 and will help other theme authors who have more than 20 options in the customizer.

My Experience Using Weaver Xtreme

I installed Weaver Xtreme on a test site running WordPress 4.5 alpha to see what it’s like using the customizer when it has 600+ options. It took 6-10 seconds to initially load the customizer. Subsequent loading takes the same amount of time.

Weaver Xtreme's Customizer
Weaver Xtreme’s Customizer

I expected to see a lot of panels expand horizontally into the theme’s design, but Weaver Xtreme only uses one panel to prevent that from happening. Limiting options to one panel helps to prevent feeling overwhelmed.

Color changes happen instantaneously while other changes require the preview pane to refresh. Some of the refreshes take a few seconds to load. Overall, I found the experience to be better than configuring the theme from the WordPress backend using an options panel.

The Customizer is a Great Way to Learn JavaScript Deeply

The customizer is one of the newest components in WordPress. It uses object-oriented PHP and is primarily a JavaScript application. Ruter says it’s one of the best ways for theme authors to learn JavaScript deeply, “There is a lot to the customizer. It is a unique application with a lot of complexities. It uses JavaScript in some very unfamiliar ways to us who feel most comfortable in PHP, but this is good because it’s not just PHP written with JavaScript syntax; It’s a completely different language with different paradigms and ways to do things,” he told the Tavern.

Unlike many other areas of WordPress, there are not a lot of copy and paste solutions for the customizer. As a result of the WordPress Community Summit 2015, Ruter is making an effort to publish more articles on his company’s site that explain how to leverage specific features. For example, he recently published an article that explains how to implement selective refreshing.

Give Weaver Xtreme a Try

I encourage you to read the entire case study as there’s more to it than what’s written here. You should also try out Weaver Xtreme on a test site to experience what it’s like using the customizer with 600+ options. Wampler has proven that not only can the customizer scale with hundreds of options, it can do so at relatively fast speeds.


37 responses to “How Bruce Wampler Migrated 600 Theme Options to the WordPress Customizer”

  1. I have been a Weaver theme user and fan for several years. Not only is it the THE most customizable theme out there, the support is mind boggling.

    Add to that the conversion of Weaver’s theme options to the WordPress Customizer and you have a theme you won’t stop using.

  2. I too hated customizer till a few months ago, but then came the nice good image controls and I started exploring it. To be honest, customizer is easy to use not only for users but for developers too. It provides a great experience.

    I still feel that the core lacks a few basic controls ( Like radio image for layout, range slider etc). There are themes( Like Justin’s Hybrid, ThemeFoundry’s make) and plugins (Kirki) that provide these custom controls. Making it available in the core will be awesome.

    Also the statement

    It is a unique application with a lot of complexities. It uses JavaScript in some very unfamiliar ways to us who feel most comfortable in PHP, but this is good because it’s not just PHP written with JavaScript syntax; It’s a completely different language with different paradigms and ways to do things

    May not be entirely correct. Customizer does not need you to be a JavaScript expert or something. If you know how to traverse DOM using jQuery and apply css( that will take 10/15 mins to learn for anyone familiar with coding), You are good to go.

    Customizer is the future, and I believe(from my personal experience), The only reason people fear the implementation is because they never explored it. Once you explore it, It makes the things fun and you start wondering why didn’t I do it earlier.

    • For the general case of implementing postMessage preview of settings, the Customizer doesn’t require you to be a JS expert. You’re right. The code snippet required by the theme is easy to work with. But to understand how the Customizer works and to build extensions on top of it, you have to know JavaScript deeply.

      • I completely agree with you on that. But that is not an obstacle for people trying to implement customizer in their themes. I had to spend time on understanding the js template for registering new controls types and that may be a little bit advance. Still, if someone is trying to implement customizer for their theme, most of the time, this is not going to be a hindrance.

      • Exactly. I was able to mostly use the “standard” set of options (partly to keep things consistent), but had a few use cases that needed more than the basics.

        I’ve been reading and re-reading the Customizer JS, and it is pretty deep. Right now, the documents refer readers to some of the custom code in Twenty Fifteen or Sixteen. I’d really like to see a well documented case study of implementing a single custom control via the JS interfact – say a custom labelled push-buttons on a row alternative to vertically stacked radio buttons. (Such a control would be really nice for things like font controls, or bg image layouts).

        But mostly, it is getting me to finally get beyond the basics of JS (which really are plenty for most postMessage based Customizer controls.) Gotta look into that selective refreshing….

  3. Thanks for the post.

    It took 6-10 seconds to initially load the customizer. Subsequent loading takes the same amount of time. […] how to implement selective refreshing. […] not only can the customizer scale with hundreds of options, it can do so at relatively fast speeds.

    Note that selective refresh (#27355) will greatly improve the speed yet further. If a theme implements support for selective refresh (for settings which cannot be sanely updated by JS via postMessage) then each setting change would just result in refreshing just one individual part of the page instead of refreshing the entire page. This is what was implemented for menus in the Customizer in 4.3. If any of you theme/plugin developers could try your hand at implementing selective refresh, Derek Herman (valendesigns) has a pull request for a framework to make it easy:

    We’re looking for feedback from developers on the selective refresh API.

  4. I’m glad that some performance issues were found and addressed because of this, but everything else… Man. I just can’t.

    • I’m with you!

      Apparently, if you want to do something faintly ridiculous with a theme, then the Customizer is just the job!

  5. I guess my question is, why does a theme have 600 options in the first place? That just seems like a better question to start with than drying to accomplish such a feat of engineering. I mean, kudos to the folks who pulled it off, it just seems like it was way too complex to begin with.

      • +1.

        I remember that the WP community says something “decisions, not options”. Sometimes, too many options confuse users. If a user can understand all CSS options, then he should make the theme himself :D.

    • The number of options is an old, and settled question when it comes to this theme. The answer is simple, as I noted in my case study: 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.

      After working with tens of thousand of users over five years, it is perfectly clear that many many folks want to be able to design a site that looks like THEY want it to, not how someone who is a WP coder/designer thinks it should look. You might be amazed at the level of fine tuning Weaver users have asked for over years. You also might be amazed at the number of totally different terrific looking sites that are out there using Weaver – all without requiring the web designer needing to learn the WP API, PHP, or even advanced CSS.

      That’s why a whole lot of people like 600 options!

      • “…many many folks want to be able to design a site that looks like THEY want it to, not how someone who is a WP coder/designer thinks it should look.”

        Exactly. I could not have said it better. Way to go, Bruce! I was a staunch believer in Weaver from way back – and recommended it to all my clients, most of whom are DIYers (I teach WordPress). I can go back to recommending it again.

    • My question, why are there so few customization options within WordPress itself? And why are other themes so limited?

      If child themes were better supported by WordPress and if I were an expert at coding, then a customizable theme would be completely unnecessary. Until then, it’s Weaver Xtreme for my website(s).

      Many of the 600 options are rather minor. Colors for every last detail, shadowing, rounding corners, fonts, etc. But when combined, all of these small adjustments make a big difference in creating a unique website.

      Other options are functionally critical such as the ability to choose the number and location of menus, number and layout of sidebars, responsive layout options, and a method of entering custom CSS that won’t be over-written when the theme is updated. I’m surprised how many themes lack these basic features.

      Additionally, not all of the 600 options are for website design. Weaver Xtreme provides some important management features such as downloading and uploading theme option backups.

    • Hi Ryan,

      To me , moving from css/html sites into a wordpress environment, the Weaver theme looked like a miracle when I discovered it.
      I would never have opted for WP (or any similar CMS) if I hadn’t found the Weaver theme with it’s incredible options.

      Bruce Wampler made a dream come true ;)

      Have a nice day.

  6. This post title is hilarious :D TGIF! @Bruce Wampler More power to you man, but you should consider refactoring (again). I just scrapped thousands of lines of code to get speeds in the milliseconds. It pissed me off to do so, but afterwards, my theme runs silky smooth and buttery. Your goal is cool for your end-users, but I suggest you do more research on IA, UI, UX and fundamental design principles. THEN, revisit the Customizer and execute your new gameplan. Good luck!

    • Not everyone want bare bones themes (which I’m assuming yours is one of).

      We have enough bland sites using 2015 and now 2016 etc. I’m constantly amazed at the total lack of design ability among the WP dev community.

      Thank God for Elegant Themes. :)

    • @Tai –

      I really don’t understand your somewhat egotistical comment. If you actually read my post, you’ll see that I readily admin that I need to be much better at JS. My understanding is that to get the Customizer interface to load quickly, one needs to use PHP templates for custom JS code to implement the controls. And as Weston noted earlier, all that code goes beyond basic JS – it is not trivial.

      So, as far as needing to really getting deep into unconventional JS design, yeah, I probably need to do that. Perhaps I can shave a few seconds off the Customizer load time.

      But that has absolutely nothing to do with “IA, UI, UX and fundamental design principles”. I’m already pretty good at that. I think it is a pretty major accomplishment to make any of the 600 options available in at most 3 clicks.

      While I’d like the JS interface to load in a second or two, a few seconds really isn’t that bad since that is a one-time deal for each session. I do stand by my contention that the basic Customizer tools available to any theme designer with good PHP fundamentals, and perhaps just basic JP competency allow for building pretty good interfaces that will work in reasonable time.

      • @Bruce Criticism amongst peers is a powerful luxury—if you use it to your advantage. All I stated was I just went through an arduous task of refactoring, and it produced great results. In hindsight: I had to ditch code *I thought* was solid, but was actually way too mushy. No ego here. Also, I stood-up your beta and then posted my comments. If you think your theme doesn’t lack in any area I mentioned, then again, I bid you good luck and may the Force be with you! Drink time! Laterz.

        • @Tai –

          I think I understand a bit of what will be required to get the Customizer JS structure to load faster, but I’m sure the entire community would really appreciate more details about what your experience was, and what tricks you used to get the blazing speed you mention.

          To me, one of the biggest weaknesses of the Customizer – lack of really good examples and accompanying tutorial documentation.

  7. Jeff, please fix the spelling of Bruce’s last name in this post: s/wambler/wampler/

    Bruce, way to go converting Weaver Xtreme to the customizer and working with the customizer team to drive performance improvements. It must have been a major effort. Sharing your experience in a case study is icing on the cake.

    As a loyal customer of Aspen Themeworks, I was disappointed to see you bemoan the original move to requiring the customizer. Your willingness to persevere, ultimately to the benefit of your customers, is commendable, and I thank you.

    We have a number of client sites still running on Weaver II Pro, which we were planning to migrate away. Your conversion of Weaver Xtreme to the customizer forces me to rethink this decision.

    • Actually, the original, Legacy Theme Options interface won’t go away – it does require adding a plugin, but it is only used when the admin is opened. I know some people still prefer that method. And the Weaver Xtreme Legacy Theme Options interface was the result of plenty of experience and feedback. And because I know it so well, I do use it myself for tweaks to existing sites. But I’m working on a new site, and I’m finding the Customizer version much better for doing new layouts.

      As always, my own philosophy is to provide a tool that works the way the user wants – all the options needed, and whatever interface is preferred.

  8. Bruce, you are an example for the entire WordPress developer community. You always put your users first, but at the same time, always work to implement best practices, even if it means great personal effort to do so. I respect that, immensely.

    Knowing what you went through here, this is one heck of an accomplishment. Thank you for sharing.

  9. In the last few weeks I started to use the costumizer and have to admit that right now for me it is the best thing that happened in wordpress for some time. In retrospect I don’t get all the complains that were surrounding the decisions to use it more and downplay the importance of the relevant admin pages.

    +1 for all the people that work to improve things instead of just complaining about performance or ease of use.

  10. Bruce, I’ve been a fan of your theme for years, and used it to make some amazing jobs without writing a single line of code, including css. The best use that I’ve made of your theme has been to convert websites from other CMS or plain html to WordPress and maintain the exact same design. I don’t know of any other theme that would allow that without writing any code

  11. An amazing job, indeed. I too had to migrate my theme options to the Customizer, which in itself posed quite anumber of issues.

    Still, in hindsight it was worth it. The customizer is more standarized, and overall a better way of lumping every styling option in one single place. It’s not the perfect tool and it still needs some refinement, but definitely a step in the right direction.

    That being said… I am not a fan of humongous option pages. I think 600 is way too much, even for a multipurpose-class theme. While users should be able to have their way with a theme, so many options can end hurting them in the process.

    I say this coming from a web consulting background, and many people want to have total control– problem is, it’s not what they actually *need*. I’d rather have a theme that enforces some designer-level best practices rather than let users end up with a broken design.

  12. Awesome work, Bruce! While I’m no fan of tons of options (you probably know that), it is a niche that needs to be filled simply because there are users who want that type of modification power.

    Now, I’m off to look through your code. :)

  13. It took 6-10 seconds to initially load the customizer. Subsequent loading takes the same amount of time.

    Is it just me? I fail to see how that is an acceptable loading time.


Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: