Customizer Improvements in 4.0
Building on the addition of Widgets to the Customizer in 3.9, and alongside my GSoC Menu Customizer project, @westonruter, @ocean90 and I have been working on a series of Customizer improvements for 4.0. In this post, I’ll summarize the changes and proposed changes that we’d like to get in before beta. Anything with an asterisk (*) still needs to be committed but has a patch. Keep in mind that everything here is liable to change before 4.0 is released.
We currently have eight enhancements and feature requests that need to be completed before beta, but half of them are already marked for commit and all have patches. If you’re interested in helping out with these changes, we could still use help reviewing and testing many of them (especially for UI/UX). Huge thanks to everyone who’s helped out so far this cycle.
Terminology Notes
We recently renamed the Appearance trac component to Customize. I’d like to clarify a few things regarding terminology used to describe the Customizer:
- We’re shifting toward using “Customizer” rather than “Theme Customizer”, as it isn’t necessarily theme-specific (though most of its uses currently are).
- “Customize” is the action, “Customizer” is the thing. Most UI elements use “Customize” or “customizing”, but most documentation should probably use “Customizer”. If you’re questioning which to use, consider whether you’re looking for a noun or a verb and pick accordingly. Feel free to conjugate the verb form (eg. “customizing”).
- “Customize” could refer to anything. That’s the point; it could be used to customize any part of a site. The Customizer can be used for anything, and we’d like to encourage more experimentation with different uses of the Customizer.
UI Changes
In 4.0, most of the Customizer UI changes are for the Customizer itself; the user experience inside the Customizer. I’m expecting a focus on the experience of accessing and navigating through the Customizer in future releases. In 4.0:
- Widget areas are all grouped into a “Widgets” context, implemented via the new “Panels” API. Panels are a way to group Customizer sections, just like sections are a way to group controls. Panels slide over to the side, rather than expanding down, and contain vertically-expanding sub-sections. This could use some more work on the UI/UX side, see #27406 for details.
- Only show “You are previewing / [theme name]” and the theme details & screenshot section when the Customizer is previewing an inactive theme. Otherwise, show “You are customizing / [site title]“, with a short description of the customizer. This matches panel headings, which are displayed as “You are customizing / [panel title]“, with the panel description as that heading section’s contents. #28550.
- Replace Customizer close button with an “X” icon. This fits better with the arrow icon used to exit panels and makes the Customizer controls feel more like a modal/panel that is contextual to the front-end of the site, rather than a confusing mix between the admin and the front-end. We’d also replace the mess of buttons in the theme-install previewer (which looks like the Customizer) with icons and move them around. #28655.
- Prevent loss of unsaved changes in the Customizer by warning users with an AYS if they try to close the customizer and there are unsaved changes. #25439.
- Always return to the screen that the Customizer was opened from in the admin, like on the front-end. Look for more work here in the future. #25457.
- All core customizer controls now support descriptions (#27981), complementing the ability to add descriptions to sections and panels. We could potentially add descriptions to some core controls if they seem needed, might want to do a UI/UX audit of the core Customizer controls and/or user testing.
Here’s a screencast demonstrating some of these UI changes:
API Additions & Improvements
Customizer Panels
The Customizer now includes a new way to group options together: panels. Just like a section is a container for controls, a panel is a container for sections. This was implemented in #27406. The Panels API is easy-to-use and works almost identically to the existing customizer section API. Add a panel with the following, within the customize_register
action:
$wp_customize->add_panel( 'panel_id', array( 'priority' => 10, 'capability' => 'edit_theme_options', 'theme_supports' => '', 'title' => '', 'description' => '', ) );
As always, only use the arguments where you aren’t using the default values. Note that the panel will not be displayed unless sections are assigned to it. To add a section to a panel, just use the panel id for the new panel
argument:
$wp_customize->add_section( 'section_id', array( 'priority' => 10, 'capability' => 'edit_theme_options', 'theme_supports' => '', 'title' => '', 'description' => '', 'panel' => 'panel_id', ) );
You may notice that $wp_customize->add_panel
and $wp_customize->add_section
have the same arguments (other than panel, of course). This is because panels are a special type of section; technically speaking, WP_Customize_Panel
extends WP_Customize_Section
. Your sections are backwards-compatible: you can add the panel argument to existing sections without issues. However, you do need to check for the existence of WP_Customize_Manager->add_panel()
if you’re maintaining pre-4.0 compatibility. As with Customizer Sections, you can access and modify Panels via:
$wp_customize->get_panel( $id );
$wp_customize->remove_panel( $id );
New Built-in Customizer Controls
WordPress core now provides support for a much wider array of Customizer controls. Implemented in #28477, these changes eliminate the need to create custom controls for most common use cases. The textarea
type is now supported in core. For any type of input that uses an input element, you can simply specify the type
attribute using the type
parameter of $wp_customize->add_control()
.
Here’s an example:
$wp_customize->add_control( 'setting_id', array( 'type' => 'url', 'priority' => 10, 'section' => 'title_tagline', 'label' => 'URL Field', ) );
Which results in the following markup in the Customizer:
<li id="customize-control-setting_id" class="customize-control customize-control-url"> <label> <span class="customize-control-title">URL Field</span> <input type="url" value="" data-customize-setting-link="setting_id"> </label> </li>
This is pretty powerful, as you can now use the built-in WP_Customize_Control
for most common use-cases rather than creating a custom control. But what about input types like number
and range
that require additional attributes like min
, max
, and step
?
New Built-in Customizer Control Parameters
First of all, all of the built-in Customizer controls (including the custom controls such as WP_Customizer_Color_Control
) now support descriptions, just like Customizer sections have descriptions (see #27981). This was much-needed and allows for inline help text at the control level.
More interestingly, to complement the new support for arbitrary input types, a new input_attrs
parameter allows you to add attributes to the input
element (also implemented in #28477). This extends beyond just using min
, max
, and step
for number
and range
, to the ability to add custom classes, placeholders, the pattern attribute, and anything else you need to the input element. Here’s an example:
$wp_customize->add_control( 'setting_id', array( 'type' => 'range', 'priority' => 10, 'section' => 'title_tagline', 'label' => 'Range', 'description' => 'This is the range control description.', 'input_attrs' => array( 'min' => 0, 'max' => 10, 'step' => 2, 'class' => 'test-class test', 'style' => 'color: #0a0', ), ) );
Which results in the following markup in the Customizer:
<li id="customize-control-setting_id" class="customize-control customize-control-range"> <label> <span class="customize-control-title">Range</span> <strong><span class="description customize-control-description">This is the range control description.</span></strong> <input type="range" min="0" max="10" step="2" class="test-class test" style="color: #0a0;" value="" data-customize-setting-link="setting_id"> </label> </li>
Which displays as follows (in Chrome 35):
The ability to add classes is particularly useful if you need to target specific controls with CSS or JS, but you don’t need any special markup. I’m using this in the Menu Customizer for the Menu Name field, which is just an ordinary text control with a special setting type.
Contextual Controls
Customizer controls can now be displayed or hidden based on the Customizer’s preview context. For example, options that are only relevant to the front page can be shown only when the user is previewing their front page in the Customizer (see #27993). This is already implemented in core for Widgets; Widgets have always been contextually faded and shown/hidden based on their visibility in the preview, but this functionality is now built off of the core active_callback
API in both PHP and JS. There are three different ways to specify whether a given control should only be displayed in a certain context. The first, and most straightforward, is to use the active_callback
argument in $wp_customize->add_control()
.
$wp_customize->add_control( 'front_page_greeting', array( 'label' => __( 'Greeting' ), 'section' => 'title_tagline', 'active_callback' => 'is_front_page', ) );
Note that you may use either built-in conditional functions or a custom function. If you have a custom control (via a subclass of WP_Customize_Control
) and a custom callback function, you can skip the active_callback
argument and override the active_callback
method instead:
class WP_Greeting_Control extends WP_Customize_Control { // ... function active_callback() { return is_front_page(); } }
Finally, the customize_control_active
filter will override all of the other active callback options and may be a better solution in certain cases (note that this particular example will be avoidable with future work on expanding the Customizer’s JS API, and does not hide the title_tagline
section, only the controls in it):
function title_tagline_control_filter( $active, $control ) { if ( 'title_tagline' === $control->section ) { $active = is_front_page(); } return $active; } add_filter( 'customize_control_active', 'title_tagline_control_filter', 10, 2 );
In addition to the PHP API for contextual controls, you can override the control-visibility-toggle function on the JS side. By default, controls will slideUp
and slideDown
as they become visible or hidden when the Customizer preview is navigated. If you’re familiar with the Customizer control JS API (see wp-admin/js/customize-controls.js
, and wp.customize.Control
), the Widgets implementation of a custom toggle function is a good example:
api.Widgets.WidgetControl = api.Control.extend({ // ... /** * Update widget control to indicate whether it is currently rendered. * * Overrides api.Control.toggle() * * <a href='http://profiles.wordpress.org/param' class='mention'>@param</a> {Boolean} active */ toggle: function ( active ) { this.container.toggleClass( 'widget-rendered', active ); }, // ... ) }; /** * Extends wp.customize.controlConstructor with control constructor for widget_form. */ $.extend( api.controlConstructor, { widget_form: api.Widgets.WidgetControl, } );
Changes to the customize_update_ and customize_preview_ Actions
You probably already know that the Customizer supports both option and theme_mod types for settings. But did you know that you can register arbitrary types? Since this is generally undocumented, I’ll show how it works (this has been in place since 3.4):
$wp_customize->add_setting( 'setting_id', array( 'type' => 'custom_type', 'capability' => 'edit_theme_options', 'theme_supports' => '', 'default' => '', 'transport' => 'refresh', 'sanitize_callback' => '', 'sanitize_js_callback' => '', ) );
There are a few actions that you can use to handle saving and previewing of custom types (option
and theme_mod
are handled automatically). Namely, customize_update_$type
and customize_preview_$type
are useful here. Previously, the value of the setting was passed to these actions, but there was no context. In 4.0, via #27979, the WP_Customize_Setting
instance is passed to these actions, allowing more advanced saving and previewing operations. Here’s an example from my Menu Customizer project:
function menu_customizer_update_menu_name( $value, $setting ) { ... // Update the menu name with the new $value. wp_update_nav_menu_object( $setting->menu_id, array( 'menu-name' => trim( esc_html( $value ) ) ) ); } add_action( 'customize_update_menu_name', 'menu_customizer_update_menu_name' );
This part of the Customizer API is a bit too complex to fully explain here, as most of it already existed, but suffice it to say that the addition of the setting instance to these actions greatly expands the possibilities of working with custom setting types in the Customizer.
New “customize” Meta Capability
The Customizer has been essentially decoupled from edit_theme_options
in favor of a customize
meta capability (mapped to edit_theme_options
by default), which is assigned only to administrators by default. This allows for wider use of the Customizer’s extensive capability-access options, which are built into panels, sections, and settings. Additionally, this makes it possible to allow non-administrators to use the customizer for, for example, customizing posts. This change is an important step toward expanding the scope of the Customizer beyond themes. See #28605.
function allow_users_who_can_edit_posts_to_customize( $caps, $cap, $user_id ) { $required_cap = 'edit_posts'; if ( 'customize' === $cap && user_can( $user_id, $required_cap ) ) { $caps = array( $required_cap ); } return $caps; } add_filter( 'map_meta_cap', 'allow_users_who_can_edit_posts_to_customize', 10, 3 );
Customizer Conditional Function
The new is_customize_preview()
conditional function can be used to check whether the front-end is being displayed in the Customizer. The naming derives from the fact that the term “preview” applies to both theme previews and previewing changes before saving them. See #23509 for some sample use-cases from WordPress.com.
Future Work
Most of the changes in 4.0 focus on the Customizer’s PHP API and the user experience within the Customizer. In the next few releases, we’ll probably shift focus to building out the Customizer JS API (#28709) and work on the user experience of accessing and navigating through the customizer (potentially with something like #28602 and related), as well as improving the experience on mobile (#28784). The Customizer can be very slow currently but we’re exploring ways to improve performance; for example, controls could be dynamically loaded on an as-needed basis once a more complete JS API is in place (#28580). We’ll work on improving custom background images and potentially add menus and/or theme-switching to the Customizer eventually. We’ll also want to address what to do with screens that the Customizer effectively replaces (headers and backgrounds, maybe eventually widgets, menus, and themes). Check out the future release Customize component tickets for more ideas.
Thanks again to everyone who’s helped out with the Customizer in 4.0. If any of the outstanding items here pique your interest, feel free to jump in on trac!
Update: all UI changes have been committed. Additional work to improve focus styling will happen during beta, see #28267.
Update 2: everything here is in WordPress 4.0 beta 1, with the exception of the customize capability. The capability will most likely be implemented as a meta capability, not a primitive one, see #28605 for details.
Update 3: customize meta capability is now in trunk, will be in 4.0 beta 2. Added usage example.
prionkor 2:10 am on July 8, 2014 Permalink | Log in to Reply
>We’re shifting toward using “Customizer” rather than “Theme Customizer”, as it isn’t necessarily theme-specific (though most of its uses currently are).
Correct me if I am wrong. We are still on “Theme Customizer” stage as customizer settings (on save) only affects theme options.
Is there any plan for implementing Customizer with post meta in addition to the options? That is when we might truly customize things with the customizer.
Nick Halsey 2:31 am on July 8, 2014 Permalink | Log in to Reply
The short answer is that it depends on what plugins you’re using. You’d probably be interested in the Post Customizer plugin (also linked above).
However, note that many core (and plugin) options in the customizer are not theme-specific; for example, site title and tagline. That is, the settings are saved as options, not theme_mods, so they persist when switching themes. They’re just contextualized to being directly related to the theme in the customize context.
prionkor 2:40 am on July 8, 2014 Permalink | Log in to Reply
Ah I see. Missed that part of the article.
JakePT 3:50 am on July 8, 2014 Permalink | Log in to Reply
I’ve been digging into the customizer a lot lately, and I’m really loving it. It’s a great way to open up parts of a theme so low-tech clients can make certain changes without an extra options page or awkward single-purpose widget areas. I’m happy to see most of the limitations I ran into being addressed here.
The one thing that is apparently still missing that I really want is a proper Media control. The current one uploads files to the Media Library, but there’s no way to recover them in the customizer. If you upload 2 images, change your mind and want to go back to the first one, you have to upload it again and end up with duplicates in the media library. From a developer perspective, I’d also like it if it returned the attachment ID so I could do more with the file than just spit out the URL.
Weston Ruter 3:59 am on July 8, 2014 Permalink | Log in to Reply
JakePT: Yeah, that’s being worked on. Have you seen the new Header Image control? You can select any image from the Media Library via the Media Manager. This same ability is being worked on for background images.
JakePT 10:12 am on July 8, 2014 Permalink | Log in to Reply
No I haven’t. Thanks for pointing that out, I’ll take a look.
Honestly, the reason that I hadn’t is that I generally avoid the Custom Header because I find it kind of ambiguous. Maybe it’s just the sites my company and I develop, but the images near the top couldn’t really be described as being in the ‘Header’, which makes it confusing. What is in the header is usually a logo (these are generally business sites), and the Custom Header functionality doesn’t work perfectly for that since, again, ‘Header Image’ isn’t how I would describe it, and if I want to allow uploading of a High Res logo for Retina, I can’t easily create a second Header control (last time I tried, anyway).
But I’m glad to hear that it’s being enhanced in this way nonetheless, however I do hope that this enhancement eventually comes down to WP_Customize_Image_Control.
Nick Halsey 4:09 am on July 8, 2014 Permalink | Log in to Reply
The media thing really bugs me too. In fact, I almost worked up a patch to try to get into 4.0 this past weekend, but I didn’t have enough time to get very far with it.
What should (and probably eventually will) happen is that WP_Customize_Upload_Control should invoke the media library, and then the image and background controls would build off of it with slightly more specialized functionality. It should then be easy to create a custom control that extends this behavior to do all sorts of custom things with JS (like using other attachment metadata). Patches welcome on #21483.
Aristeides Stathopoulos 8:25 am on July 8, 2014 Permalink | Log in to Reply
This is really exciting!
It was about time this happened…
The thing that bugs me the most in the Customizer is the fact that it’s almost impossible to save an array as an option… It’s easy to create new controls, but it’s almost impossible to create a control like for example a multi-select control and save it as an array. Instead we have to do some voodoo to convert the array as csv and save it that way.
Any plans to change that soon?
Graham Armfield 10:21 am on July 8, 2014 Permalink | Log in to Reply
When you’re building your changes to the Customizer as proposed here, please ensure that everything is keyboard accessible and is also providing enough information for screen reader users – not everyone will be using a mouse.
The Customizer is currently pretty good from an accessibility perspective, and we wouldn’t want to see the Customize take a backward step with these changes.
Keyboard only testing you’ll be able to do yourself, but feel free to post on the Make WordPress Accessible blog if you need help and guidance with anything else.
Nick Halsey 2:30 pm on July 8, 2014 Permalink | Log in to Reply
Maintaining and improving accessibility is definitely a goal here. All of the new proposed icons (exiting panels, customizer close, etc.) have strong focus styling and use .screen-reader-text. I believe the focus indicators are sufficient even though the change is only color because the colors are inverted, with the darker color moving to the background and the lighter color for the icon. There is also an outstanding patch on #27406 that ensures that only visible elements are focus-able.
It would be great if the Accessibility team could do an audit of the Customizer’s accessibility, particularly for screen readers, once these changes are committed. We could also maybe fix #27591 in 4.0 if it gets a patch soon.
Graham Armfield 1:56 pm on July 10, 2014 Permalink | Log in to Reply
Nick, I’d like to have a look at the changes with a screen reader. Which ticket patches do I need to install to get the complete picture of the changes?
Nick Halsey 4:28 pm on July 10, 2014 Permalink | Log in to Reply
Excellent!
All of the user-facing changes are in WordPress 4.0 beta 1, so you should be able to test with that and won’t need any patches at the moment. The remaining known issue with accessibility is insufficient focus styling for Customizer sections and panel headings, which will be addressed in #28267. We’re definitely ready for an in-dept audit, keeping that in mind.
simplethemes 3:35 am on July 11, 2014 Permalink | Log in to Reply
Very nice!
Has anyone else noticed width issues with panels in Chrome (Testing in Version 35.0.1916.153)?
http://d.pr/i/j93I
No problems in latest Firefox.
nikeo 1:53 pm on July 15, 2014 Permalink | Log in to Reply
Panels => just what I needed
I also love the custom type and the context handling possibilities it creates with customize_update_$type, which I was ignorant of.
Looking forward to see the JS API enhancements!
Thanks for this overview @celloexpressions
Aniruddh 12:25 am on August 26, 2014 Permalink | Log in to Reply
I don’t know if I’m missing something here but do we have contextual sections, too?
Nick Halsey 12:56 am on August 31, 2014 Permalink | Log in to Reply
Not yet. There is currently no JS API for sections or panels, so there’s no good way to implement contextual sections. But this feature will be available in the future, once that’s in place. See #28709.
You might look at what Widgets do in core to make sections contextual by doing special handling with a contextual control within the section.
Scott Smith 12:33 am on August 31, 2014 Permalink | Log in to Reply
So is it possible to use the new ability to specify ‘type’ => ‘url’ in a way that’s compatible with WordPress 3.9 and lower?
Nick Halsey 1:07 am on August 31, 2014 Permalink | Log in to Reply
Unfortunately, no. But you can check for the existence of `$wp_customize->add_panel()` for a 4.0 check and then act accordingly (just use text instead of url as the type). And it won’t cause any critical issues, the control just wouldn’t be displayed.
It is forward compatible – if core implements something special for a specific html5 input type in the future, it will work with the current fallback input type handling back to 4.0.
kmavrov 11:43 am on September 5, 2014 Permalink | Log in to Reply
Hi there, is it possible to have an indicator next to the range slider, which shows the current value, like when you set min = 1, max = 5, step = 0.25, and to be able to see that the current value of the range slider is 3.75 ?
Nick Halsey 7:14 pm on September 5, 2014 Permalink | Log in to Reply
If you really want to do that, you could add some javascript that does that. But if you want the value to be displayed, you should really be using a `number` input (still with min, max, and step – which most browsers now support). The specs for the range input type specifically state that range should be used for inputs where the exact value is unimportant, and accordingly it wouldn’t make sense to display it. See also #28849. Core is unlikely to adopt this for the reasons above and because `range` doesn’t have to represent something numeric from a user’s perspective.
AxisThemes 5:04 pm on September 5, 2014 Permalink | Log in to Reply
Hi Nick, how could we make theme customizer panel support in 3.9 or 3.8 are there any core plugins. Please adapt changes for customizer how the MP6 was done and later release. If the customizer core WP plugin was started for adapting changes let me know.
Nick Halsey 8:46 pm on September 5, 2014 Permalink | Log in to Reply
Because the panel API is deeply integrated with core, it was developed directly in core instead of in a plugin. In fact, it was developed as part of my GSoC project to integrate Menus into the Customizer in a plugin, which required this functionality.
New features that can act as standalone plugins are developed as plugins (for example, the Widget Customizer and the Menu Customizer). Iterative enhancements to the central APIs in the Customizer are better developed directly in core. And any smaller feature or API change is best developed in core, only sweeping changes should happen via plugins first.
There’s pretty much no reason to be worried about supporting 3.8 and 3.9, because there’s pretty much no reason NOT to update to 4.0, since WordPress is backwards-compatible. If you need to use things that have been added in 4.0, simply require your users to update.
AxisThemes 10:40 pm on September 6, 2014 Permalink | Log in to Reply
Hello Nick, Could you please help me with this type of setting. I have gone through almost everything in this post but truly I could solve. So some bit of example for this will be great solution.
http://d.pr/i/xOBH
Tip: Until the users select the “Custom” from the ‘Header Size’ select option that range control should be hidden.
Nick Halsey 6:16 pm on September 9, 2014 Permalink | Log in to Reply
You can actually accomplish controls that are conditionally displayed based on the values of other controls with the new active_callback argument for controls. Pass in a custom callback function that checks the value of the other setting (with get_option or get_theme_mod) and return true or false whether to show the conditional control. See an example.