The WordPress Customizer does not have a built-in control for setting background images. The background feature simply consists of four different controls:

• background_image (WP_Customize_Background_Image_Control)
• background_repeat (radio)
• background_position_x (radio)
• background_attachment (radio)

For this feature, the Customizer also loads javascript that reveals the radio fields once an image has been uploaded. And on the front-end, inline styles are used to apply the background image to the body tag.

If a developer wanted to build additional background image options, the simplest option would be to take the same route: register four settings, load four controls, add custom javascript to show/hide fields if an image is set. Repeat as needed.

However, I started experimenting with a single control and thinking through how that could be implemented.

Issues with Current Implementation

Trac is a great place to find feedback on a particular WordPress feature, and there were a number of suggestions for background enhancements:

• Support background-size
• Support background-position-y (and perhaps a better UI)
• Support background cropping
• Support retina images

Prior Art

The Make Theme by Theme Foundry implements some of these suggestions, including UI changes:

The Kirki Toolkit also implements a background control, which supports repeat, size, attach and position.

Custom Background Control

I haven’t completely finished the custom background control I’ve been working on, but I feel like it’s time to share and open it up for collaboration. Here’s what it does now:

• A single control generates all the field markup (image, repeat, size, attach, position)
• The control also saves an attachment ID if a setting is defined (making it easier to generate alternate sizes)
• The control automatically loads the javascript to hide/show the select fields

At the moment, six settings need to be registered (with their defaults and sanitization) if all the fields are going to be displayed. This still feels like a lot of syntax and I’d like to simplify it further- perhaps by saving all the data into a single serialized array for the theme_mod or option setting that is registered.

It also doesn’t address cropping, alternate UI ideas, or retina- mainly just because I haven’t had a chance to explore it yet. But it does have support background-position-y (added to the position field) and background-size (new select field).

I’d love for other people to take a look at this control and give me any thoughts, feedback, or pull requests. You can find the Custom Background Control on GitHub along with all its documentation.

Check out the project here.

Sometimes it’s really useful to be able to output HTML in the Customizer that’s not a label or description for a specific control. You may want to output a line break, an image, a button, or simply some additional text.

There isn’t a native Customizer control in WordPress to do this, but you can add your own custom control to output arbitrary HTML. This was a request for the Customizer Library, and the GitHub issue explains the thought process behind the code. Continue reading →

Adding custom links or markup to the theme customizer can be a bit difficult since everything is injected with javascript rather than the normal PHP toolkit. However, there are a number of use scenarios where this might be useful.

One common use case for theme authors might be to add a documentation link or an upsell link so users can find out about theme features.

The approach I like the best is one I first saw employed by the Theme Foundry with their theme “Make”. Their upsell link is prominent, but it doesn’t detract too much from the theme customization experience or take up too much space in the limited UI.

This tutorial takes a similar approach, but shows how to add a styled link to the “Active Theme” section. Continue reading →

I’ve been working on a new theme that allows users to select certain pages in the customizer, and then display those pages out on a “showcase” template. I think this is pretty useful functionality and wanted to share how I implemented it.

Add Settings, Controls and Sanitization

First, we’ll need to the page select boxes to the customizer. In the code below, I add a new customizer section called “Showcase”. Then, I loop through the add_setting / add_control functionality in order to display four distinct page select boxes.

I’ve also created a function called “prefix_get_pages_array” which returns an array of all the pages to be used both by the controls and the sanitization function. You’ll notice it sorts the pages alphabetically, and indents sub-pages slightly with an em dash when output in the select box. Continue reading →

One neat “feature” introduced in WordPress 4.1 was the removal of the background and header admin screens in favor of the customizer (see ticket). Now if you click to customize one of those items, it links directly to the customizer and opens the appropriate panel.

If your plugin or theme adds customizer options, you can also link to those. Just use:

admin_url( 'customize.php?autofocus[control]=control-name' )

Replace “control-name” with the name of the control you’d like to link to. Continue reading →

WordPress 4.0 introduced a few new features for the customizer, including panels and input field types. This post on the Core Make blog explains the updates well- but since I was experimenting with it today I thought I’d post a few more examples.

I put together a code snippet that registers a custom panel, section, and then displays a few of the new field types: url, e-mail, password, textarea, date, and range. Arguably the only real useful ones are textarea and range as you’ll see in the notes below. Continue reading →