tl;dr - The commented demo plugin is available at GitHub.
I've wanted to add a customizer to my Read Offline plugin for a long time, letting the user easily change the PDF and ePub design. As I like to write a demo plugin before adding new functionality, here's my take on adding WordPress customizer to a plugin.
Understanding how the customizer works wasn't easy.
Understanding how the customizer works wasn’t easy. I’ve read the documentation and read a lot of source code. After viewing the loopconf presentation Patrick Rauland held last year, I asked him and got an early beta version of the WooCommerce Email Customizer plugin. I’ve also followed the work Weston Ruter and XWP have done and have skimmed through their customizer plugins, I’ve also viewed tickets and followed the discussions on Slack.
The thing I found hardest was understanding how to remove the other sections from the customizer, so I asked on Twitter
Fortunately, Weston came to the rescue :)
The important parts
Timing is everything.
Timing is everything, and so is understanding when parts of the code is used. WordPress customizer relies on ajax for communication between the controls and the preview, and customizer uses ajax for saving settings.
“Blank Slate” loads at a priority of 1, so the Plugin Customizer must load after it, but if it’s loaded at the default priority of 10, it will not be available. As shown below, I add the customizer_register at priority 9.
So, everything looked fine, but I couldn’t save the settings (!!), and the only error message I got was a 500 Server error. I understood that when saving & publishing the customizer settings, admin-ajax.php expects to find the settings, and if I removed the bailout test everything worked fine.
The problem was that I couldn’t “see” the solution. When I removed the bailout test, Plugin Customizer sections would pop up in the default Appearance -> Customize, and if I added the bailout test, I couldn’t save the settings.
Now, after the problem is solved, it’s a simple fix (isn't it always). Register the customizer settings before the bailout test and register the customizer sections and controls after the bailout test.
Adding a preview
Weston describes how to add a preview in Navigating to a URL in the Customizer Preview when a Section is Expanded. I’ve extended his code to add a template per section.
Loading the template, I tested the hooks template_redirect and template_include, but I ended up creating a permalink. It fitted well to script above.
Like to learn how to create a custom permalink? I’ve written another demo plugin that shows you how to do it.
The Plugin Customizer demo plugin is available at GitHub. The code is documented. If you find logical flaws, typos etc, please contribute.
I couldn’t, at least not in the near future, have developed this plugin without the help from Patrick Rauland and Weston Ruter.
Btw, any flaws in the plugin are mine.