I’ve spent a lot of time recently in the WordPress Customizer for this theme and a client theme, and have found it slow to locate helpful references and tutorials. Part of that was not learning until recently that you can put a single word in quotation marks to keep Google from helpfully trying other word forms and synonyms to get you more results (“custom” and “customize” are far from interchangeable with “Customizer” in this context, so thank you SearchReSearch for the trick), but some of it was a lack of good material.
On with the show…
The fundamental source is the Customizer page in the WordPress Developer Handbook. What it covers it does well, but it is pretty cursory. In some ways I find the old Customizer information in the Codex easier to read.
Other General Tutorials and Examples
WPShout is a reliable source for entry-level tutorials that aren’t shallow, and you may find their Customizer introduction and overview helpful.
Tom McFarlin wrote a tutorial series for WPTuts+ that is well-explained. You can find an index for the WPTuts+ series on his blog.
The WPTuts+ series is a few years old, as is this Theme Foundation Customizer tutorial, which moves a little faster but is a little more comprehensive. However, the basic syntax is largely unchanged.
There’s a general introduction on Noupe that covers some of the same ground, but in a different way and with some different inclusions.
Tom McFarlin has suggestions on organizing your code for maintainability that will already be the case if you are working from Underscores.
Adding Custom Controls
WordPress provides a number of control types: checkbox, radio button, select box, textarea, dropdown of pages, color picker, and media selector. You can add your own on top of these.
If you are adding controls, whether custom or built-in, the input needs sanitation; ThemeShaper has an article on validation and sanitation for the Customizer.
Otto has a good introduction to custom controls that is a little old but still relevant.
WPMU DEV has another intro, including the built-in controls, that might be good for a second explanation.
Justin Tadlock has a tutorial on a control that replaces radio buttons with images but still acts as a radio button control.
I found it easiest to understand custom controls via example. There are lots of collections of premade custom controls on GitHub that you can use and learn from, with a variety of authors: the WordPress Theme Review Team, Paul Underwood, and Frank Bültge for three (but see last week’s post for a caveat). Braad Martin has a control for a color picker with alpha. You can also see custom controls in action in the WP Customize Posts plugin by Weston Ruter.
Contextual Controls and Partial Preview Refresh
Contextual controls are those that appear and disappear based on what you’re previewing or what choices you’ve made in other controls. It and partial refresh are frequently covered in the same articles so I grouped them together. I discuss both in last week’s post, for one.
Otto talks about active_callback for contextual controls in a post about recent changes to the Customizer as of May, 2015.
WPShout covers partial refresh and active_callback in their follow-up to the general tutorial.
Weston Ruter in Make WordPress Core on how things work and where they’re going, October 2014.