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
Any idea how I can reset the #WordPress Customizer. i.e. remove existing panels and controls before I add mine ?
— Per SÃ¸derlind (@soderlind) September 11, 2016
Fortunately,Â Weston came to the rescue :)
— Weston Ruter â¡ (@westonruter) September 11, 2016
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.
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.
Btw, any flaws in the plugin are mine.