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.

Here are two WordPress themes on GitHub that use the Customizer and have authors who know a lot about the Customizer: Hybrid Core by Justin Tadlock; Oenology by Chip Bennett.

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.

In a Stack Exchange answer, Weston Ruter discusses the JavaScript alternative to active_callback.

WPShout covers partial refresh and active_callback in their follow-up to the general tutorial.

The Future: More JavaScript, Less PHP

Right now you can avoid JavaScript entirely provided you don’t mind the entire preview refreshing to update and you don’t want to hide and show controls dynamically. Since WordPress is great about back-compatibility, that probably will always be true. However, the future of the Customizer is in JavaScript. [Since the Customizer is pointless without JavaScript even my progressive-enhancement-obsessed soul can’t object.] Here are four links about using JavaScript for everything:

Weston Ruter in Make WordPress Core on how things work and where they’re going, October 2014.

Nick Halsey also in Make WordPress Core on rendering custom controls with JavaScript, in particular; November 2014.

Justin Tadlock has also written about rendering custom controls with JavaScript.

Finally, if you have a lot of options in the Customizer (the wisdom of that may be debatable) and they are injected with JavaScript, you may find your script is noticeably laggy. Here’s an article by Layers on speeding up the Customizer via delayed loading of controls.

I haven’t tried to implement a JavaScript-only Customizer in Amalgamation yet, but it’s on the list.

The post WordPress Customizer resources appeared first on rweber.net.

After the basics were in place, I started adding to Amalgamation (this site’s theme) to make it customizable for someone who might want, say, different pages featured in the front page’s panels. The correct place to put appearance-affecting settings is now the Customizer, which meant a lot of new learning.

It was not without its swearingdifficulties, and for a while I had a nice little hack in place (labeled as such) but I got a handle on it and thought I’d write a bit about the parts that took me while to figure out or were difficult to find information on. This isn’t intended as a self-contained tutorial; I’ll follow this post up with a post of resources. Edit 3/12: The Customizer resource post is up now.

Customizer PHP

In Amalgamation, this is all in customizer.php.

Underscores is a good start on the Customizer, especially for mimicking JavaScript syntax, but begins quite light on the PHP side. All it does is implement partial refresh for a few of the built-in settings. I wanted to add a bunch of new settings and also remove the irrelevant defaults, which you can see near the beginning of amalgamation_customize_register().

There were two things I remember giving me pause when adding settings (see code on Pastebin):

The first was keeping the pieces straight, including what needed the same name. The setup is a little convoluted; sections and controls are UI entities – they are about what appears and how in the Customizer pane. Settings are data entities – they hold the values you use controls within sections to select. That’s why they don’t exist within sections like controls do, and why the label and description are set within the control definition. They are, however, tightly coupled to controls, which is why they both get the same label as their first parameter.

The other mild slowdown was not knowing how to define a radio button selection, but hopefully my example makes it clear: in the choices array it is ‘setting’s value’ => ‘value’s description’.

WordPress has a page dropdown included, but I wanted to allow posts as well so I needed a custom control. I began by using a post select dropdown from Paul Underwood, but changing the selection didn’t alert the Customizer that a change had been made – the Save button remained grayed out. Since I didn’t need the flexibility of that control I switched to one by Tom Rhodes that has since disappeared from his GitHub. That one worked, and I’ve since determined that the key was in the select element having the attribute data-customize-setting-link="<?php echo $this->id; ?>". When I added that attribute to Paulund’s code, it worked as desired.

Note that the definition of the custom control needs to be accessible from within the function that’s adding the custom control. The easiest way to do that is to define it within the function, whether directly or via an include statement.

Using the settings in your theme is easy: get_theme_mod( 'setting_name' ); returns (rather than echoes) the value.

Customizer JavaScript

This is in two files in Amalgamation: customizer.js and customizer-controls.js; the enqueuings are in customizer.php.

JavaScript is currently optional for the Customizer but developers are encouraged to use it for essentially all the functionality. I did not (though I intend to at least try it out in the future) but I made good use of JavaScript for dynamic display of controls in the sidebar and for partial refresh in the preview so a small change did not require the whole thing to reload.

The first thing to note is that there are two different actions to hook your script enqueue functions into, depending on whether the script affects the sidebar or the preview pane. The preview is in an iframe so it is effectively a completely separate website; scripts that live in one location can’t affect elements in the other.

For dynamic controls, the enqueue command is this (view on Pastebin):

You can code these as you would any other show/hide commands, but I found I needed to enclose them in an extra $(function(){}); to delay execution and prevent them being overridden. The necessary ids for your elements will be generated following a standard pattern and are easy to find in the web inspector.

For preview AJAX, the enqueue command is this (view on Pastebin):

Note that I’m localizing the script also, as in my previous post about AJAX in WordPress. This of course is only necessary if you actually plan to make AJAX calls. Within the script you have to follow the pattern

wp.customize( 'setting_name', function (value) {
    value.bind(function (to) {
        // your css/html change or ajax call
    });
});

If you leave out value.bind it won’t work. From what I understand, “value” here is the fact of the change, and “to” is the result or contents of the change (e.g. the color code, text of the byline, or id of the page you selected from the dropdown). Once you’re inside you can do whatever you want; it’s no different from JavaScript written from scratch to enact a change on the page. In particular AJAX works the same way as in WP at large.

There’s my contribution for now. Stay tuned for the resource post. Edit 3/21: My selection of customizer resources is posted now.

Marionette photo by Jürgen Howaldt (Own work (selbst erstelltes Foto)) [CC BY-SA 3.0 de], via Wikimedia Commons.

The post Learn by doing: the WordPress Customizer appeared first on rweber.net.