Customize Update – 2016-09-08

This is the weekly update post for the customize component. It includes a summary of this week’s meeting, recent commits, and next week’s meeting agenda.

Weekly Customize Meeting Summary

On Monday we held our weekly 4.7 customize component meeting in #core-customize on Slack [logs]. Participants: @paaljoachim, @celloexpressions, @westonruter, @johnregan3, @clorith, @melchoyce. This summary also contains a few notes on action since the meeting.

4.7 Projects

  • Create page-based nav menus without leaving live preview – #37914#37915, #37916@celloexpressions
    • These follow up tickets are largely pending feedback from the Taxonomy component. We need to work with @boone to come up with master plan for previewing terms, and determine whether we can realistically add term-creating support in menus in 4.7.
    • @boone has this on his list for later this week.
    • We need one more follow up ticket to provide users with a path to adding content to newly-created pages; currently there is another usability dead end here (see #38002).
  • A new experience for themes in the customizer – #37661 –@celloexpressions
    • I added shiny updates and deletion, as well as refining the UI for users that can’t install themes this weekend, and posted a new patch. Also explored reviews, and we’ll need API support from .org if we want to load them inline in the future.
    • Only major development task remaining is shiny theme upload.
    • We discussed whether it might make sense to delete/uninstall themes if a user previews them and then moves on. Need to explore user expectations here as part of the testing and feedback processes, as this would be a change from the current core behavior.
    • @karmatosed had some trouble getting the style changes from the patch, once that’s resolved we’ll start the user testing and design iteration process.
    • @aaroncampbell is interested in helping out here. For everyone interested, please start looking at/testing the patch and reporting issues or ideas on the ticket or in #core-customize.
  • Code-editing gateways, via CSS – #35395 – @johnregan3
    • @johnregan3 brought up in the ticket, based on input from @joyously that it might make sense to allow theme-independent styles. We reached a consensus that theme-specific styles are more important for core for now, and plugins can add additional global CSS options. We can revisit this for core in the future.
    • @johnregan3 has created a code editor control leveraging the CodeMirror library that’s also used by Jetpack. The Custom CSS setting now saves to a post, and he’s working on updating the post when the customizer is saved. He shared an initial patch for review later this week.
  • Customizer browser history#28536 – @westonruter
    • No updates
  • Customize transactions#30937 – @westonruter
    • No updates
  • Refactoring sliding panels UI – #34391 – @delawski
    • @delawski has posted an updated patch for review. We’d like to get a first patch in soon so there’s plenty of time to test compatibility with third-party custom sections.
    • #34343 is related to improving the sliding panel experience, and @delawski is working on that next for 4.7.

Not every project needs to have an update every week; the primary purpose of our meetings is to make sure that no one gets stuck and to provide group feedback/decisions as needed. With about a month and a half before the merge deadline for 4.7, all of our 4.7-targeted projects are still on track for that milestone.

Future Release Project Updates

  • Customize Posts
    • @westonrtuer brought up an issue with adding a post parent control that let to an implementation of the dropdown-pages control that leverages Select2. This improvement could be implemented in the core control in 4.7. There is a feature plugin called Customize Object Selector that replaces the dropdown-pages control with this scalable multi-select control for the page on front and page for posts controls.
    • @clorith pointed out that accessibility concerns had previously stalled implementations of Select2 in core. We pinged @afercia to have the accessibility team review whether there are still issues with the newest version of Select2. Unfortunately, it has significant accessibility problems and the maintainers haven’t shown interest in resolving the.
    • We also discussed that work on Customize Posts has developed most of what’s needed to use JS templates for the base WP_Customize_Control UI. This will be implemented in #30738 for 4.7, along with support for setting values that are objects.

Additional Tickets Needing Attention

  • Improving contrast and UI consistency in the customizer – #29158needs-testing
    • @clorith really likes it and @westonruter thinks it looks nice but doesn’t have strong feelings. With no objections from the customize component, we’re waiting for the design team to approve or suggest additional revisions.
    • Discussed during the design meeting, and pending patch testing we’ll get the initial pieces in and continue iterating.
  • Improve custom background properties UI – #22058 – needs additional feedback on the latest proposal, and a patch. Also needs design decisions.
  • Appropriate means for themes to add top-level promotional links – #37335– needs input from theme review team
    • They discussed in their meeting last week, and it’s now pending additional investigation of alternative approaches for theme developers. We’ll follow up with the theme review team in a few weeks.
    • In the meantime, the theme review team is no longer allowing links to be added by injecting markup into the DOM with JS.
  • Customizer notifications – #35210 – needs UX feedback and a patch
    • @westonrtuer added clarifications to the ticket, and @afercia provided accessibility feedback there as well. We should be able to implement the accessibility changes, so we’re currently waiting for design feedback again.

Ticket Scrub

We reviewed the enhancement tickets in the Future Release milestone that have a patch.

  • #34747: Provide more flexibility for “You are customizing” text
    • This is pending the direction of the sticky-headers discussion, but we’re not all convinced that it should be able to be customized on the top level (it can already be changed in sections and panels).
  • #18584: Nav menus need more hooks for extensibility (on admin page & in customizer)
    • #30738 will introduce functionality that will help enable saving custom menu item fields. Once that’s in place, we can revisit how the API would work for plugin developers and determine whether there’s still time to get it in for 4.7.
  • #36175: Simplify the Customizer Image Control action buttons
    • We need to come up with an accessible solution and make sure the experience is consistent across the various media controls.
    • @melchoyce doesn’t want to continue owning the ticket for now but will take a look again later in the 4.7 cycle.
  • #31334: Customizer JS API should handle container removal from document
    • I had forgotten about this ticket and commented about this issue on #30741 recently.
    • We discussed the potential issues with using jQuery.remove(), and could potentially use jQuery.detatch() instead. However, menus and widget currently use remove() in core, so we should standardize the behavior and incorporate it into the API.
  • #32296: Allow the customizer to be made wider
    • I suggested that we likely won’t make a major change here until we make major changes to the customizer UI in general. However, there is a patch that makes the customizer proportionally wider on large desktop screens, and that could easily happen for 4.7 if others are okay with this approach in the interim.
  • #33064: Customizer: form inputs need a way to have hidden labels
    • I’m somewhat uncomfortable with adding a new class variable for this, and doing that means we also need to update all children of WP_Customize_Control to support it in core. However, this is an important feature to support in the API, so we’d like to get it in for 4.7.
  • #21627: Filter for custom-background CSS selector
    • This ticket seems to have been forgotten about, but adds a lot of flexibility to the custom background feature and would be nice for 4.7 alongside #22058. Moved to the 4.7 milestone.

Recent Customize Commits

Here are the customize-related commits for the past week:

  • [38513]: Customize: Fix php warning due to WP_Customize_Manager::prepare_setting_validity_for_js() incorrectly assuming that WP_Error will only ever have arrays in its $error_data.
  • [38520]: Accessibility: Improve the Customizer and Theme Installer initial focus.
  • [38577]: Customize: Prevent widget previewing logic from building invalid jQuery selectors when sidebars are registered without a class name in before_widget.

Big thanks to those who contributed to patches committed this week: @westonruter, @dlh, @afercia.

We’re always looking for more contributors; check out the open customize tickets and swing by #core-customize in Slack to get involved.

Agenda for 2016-09-12 Meeting

Our next regularly-schedule meeting is next Monday, September 12, 2016, 17:00UTC. Agenda:

4.7 Projects

Additional Tickets Needing Attention

  • Improving contrast and UI consistency in the customizer – #29158 – needs-testing
  • Improve custom background properties UI – #22058 – needs additional feedback on the latest proposal, and a patch
  • Customizer notfications – #35210 – needs UX feedback and a patch

Ticket Scrub

  • Identify tickets ready for commit consideration, and 4.7 milestoning from future release bugs with a patch.
  • We’ll pick a different query to triage each week. For example, bugs awaiting review (need verification).

We’ll see you next week!

#4-7, #customize

Customize Update – 2016-09-01

This is the weekly update post for the customize component. It includes a summary of this week’s meeting, recent commits, and next week’s meeting agenda.

Customize 4.7 Kickoff Meeting Summary

On Monday we held the customize component kickoff meeting in #core-customize on Slack [logs].

Potential 4.7 Projects

We started by identifying potential projects for 4.7, and people to lead them. The following projects are currently targeting merge for WordPress 4.7:

  • Create page-based nav menus without leaving live preview#34923 – @celloexpressions
    • @westonruter committed a first pass here, closing the primary ticket as fixed.
    • #37914, #37915, and #37916 have been created for follow up, and are currently in the 4.7 milestone. We need input from the taxonomy component to enable terms to be previewed before adding support for terms.
  • A new experience for themes in the customizer#37661 – @celloexpressions
    • There are a few more dev-heavy tasks but we’re ready for design feedback (@folletto will take a look when he has time) and user testing.
    • In the core dev chat, @karmatosed volunteered to coordinate user testing here.
  • Code-editing gateways, via CSS#35395 – @johnregan3
    • We decided that bundling CSSTidy (used by Jetpack) in core is the best solution for sanitizing CSS.
    • Syntax highlighting for a more proper code-editing experience is a nice-to-have but not required for a first pass.
    • CSS should be stored in a new custom post type (with revisions), with a distinct post for each theme (i.e., all CSS will be theme-specific here).
    • @johnregan3 volunteered to spearhead this project and expects to have it ready for 4.7.
  • Customizer browser history #28536 – @westonruter
    • Development is happening on github, and there is only one issue currently, with customize-loader.js. We discussed potentially eliminating the iframe aspect of the customize loader script eventually, as it has caused a lot of issues and doesn’t offer significant usability benefits.
    • We also need to investigate possible performance issues in conjunction with #37661.
  • Customize snapshots/transactions #30937 – @westonruter
    • We decided that the snapshots UI will remain in a plugin for now, but transactions themselves could potentially be ready for 4.7. Transactions allow for the customizer to be used to preview changes to REST API in headless sites.
    • @westonruter brought up a few concerns with the sequencing of transaction updates and selective refresh, which could result in two HTTP requests for the preview where there was previously one. Ensuring no degradation in performance is key here.
    • Transactions would complement #37661 nicely in 4.7 even without the snapshots UI, as theme customizations during the theme selection workflow could be saved without being published to the live site.
  • Customizer notifications #35210 – @westonruter
    • This needs more design feedback and a patch based on the latest proposal.
    • This is less of a project, so we’ll track it as a ticket moving forward.
  • Refactoring sliding panels UI#34391 – @delawski
    • @delawski will work to finish this up soon so that it can get into 4.7 relatively early.
    • We’ll need to coordinate this with the theme experience refresh in #37661, which bypasses the margin-top hacks.

Additional projects discussed:

  • Improve UI for linking preview elements to controls#27403
    • We might try to make some improvements here, but we aren’t currently targeting major changes for 4.7. This might change if more contributors contribute here, particularly on the design side.
  • Twenty Seventeen
    • @helen mentioned in the dev chat that information on Twenty Seventeen will be announced next week. Depending on the customize scope, we might want to have a dedicated person to help there and report back to the customize component meetings.
  • Customize Posts
    • Not targeting 4.7, but it would greatly benefit from a thorough UX review now that the majority of the functionality is in place.
    • We’d like to fix #30378 in 4.7, using JS templates for the base WP_Customize_Control UI, to support the plugin.
    • A new project to bring similar functionality to taxonomy terms is breaking ground.
  • Live Preview Feature Project
    • After 4.7, we’ll revisit this project to take a holistic look at how live preview works in core. The end result will likely be a UX strategy for introducing contextual live preview for posts and terms, likely leveraging the existing customizer API and technology developed in the Customize Posts plugin, but potentially with an entirely different user interface than what’s currently known as the customizer: namely, looking at ways the customizer framework can be bootstrapped onto the frontend along with inline editing.

Additional Tickets Needing Attention

We briefly drew attention to the following tickets needing feedback from other teams:

  • Improving contrast and UI consistency in the customizer – #29158needs-testing
  • Improve custom background properties UI – #22058 – needs additional feedback on the latest proposals, and a patch
  • Appropriate means for themes to add top-level promotional links – #37335 – needs input from theme review team
    • The theme review team agreed that this was probably a good solution, but wants to investigate other options for developers before moving in this direction. On the core side, we’ll wait for direction from them

Open Floor

We closed with an open floor in lieu of a ticket scrub, due to time.

  • @clorith brought up sticky panel headers/back buttons (#34343 and #35186)
    • @delawski would like to work on these tickets after finishing #34391. We’ll need additional design feedback here as well to decide the direction (probably one or the other of the tickets).

Recent Customize Commits

Here are the customize-related commits for the past week:

  • [38396]: Customize: Circumvent the customizer attempting to preview links to static assets (such as uploaded images).
  • [38436]: Customize: Allow users to more seamlessly create page-based nav menus during customization.
  • [38464]: Customize: Improve handling of active state for dynamically-created controls/sections/panels.
  • [38478]: Customize: Use new `$status_code` parameter for `wp_send_json_error()` instead of calling `status_header()` separately.
  • [38479]: Customize: Fix i18n by re-using the `add_new_item` post type label instead of using a post type name in a generic string, in [38436].
  • [38492]: Customize: Introduce `paneVisible` state and ensure pane is visible when a construct is expanded (or focused).
  • [38503]: Accessibility: Make links in the Customizer underlined by default.

Big thanks to everyone who contributed to patches committed this week: @Presskopp, @afercia, @westonruter, @celloexpressions, @valendesigns, @melchoyce, @mapk, @iseulde, @mrahmadawais, @sayedwp, @johnbillion, and @curdin.

We’re always looking for more contributors; check out the open customize tickets and swing by #core-customize in Slack to get involved.

Agenda for 2016-09-05 Meeting

We will have a meeting next week despite the holiday in the US; Monday, September 5 at 17:00 UTC. Agenda:

4.7 Projects

Additional Tickets Needing Attention

  • Improving contrast and UI consistency in the customizer – #29158needs-testing
  • Improve custom background properties UI – #22058 – needs additional feedback on the latest proposal, and a patch
  • Appropriate means for themes to add top-level promotional links – #37335 – needs input from theme review team
  • Customizer notfications – #35210 – needs UX feedback and a patch (and perhaps a clearer demonstration of the iteraction)

Ticket Scrub

  • Identify tickets ready for commit consideration, and 4.7 milestoning from future release tickets with a patch.
  • We’ll pick a different query to triage each week. For example, bugs awaiting review (need verification).

We’ll see you next week!

#4-7, #customize

Customize Kickoff and Weekly Meetings for 4.7

We’ll be holding weekly meetings for the Customize component during the 4.7 cycle, to discuss both larger projects and smaller tickets needed attention. Meetings will be held on Mondays at 17:00 UTC in #core-customize and will last up to one hour, with additional continuous discussion happening throughout the week in the channel and in tickets.

The first meeting, on Monday, August 29th, will also serve as a kickoff for the customize efforts in 4.7, following up on yesterday’s general 4.7 kickoff.

Agenda for 2016-08-29 Meeting

The goal of this kickoff meeting will be to identify scope for 4.7 for the customize component. Most importantly, we need to identify larger projects that shouldn’t be considered for 4.7 (such as the customize posts project), so that we can prioritize those efforts that could get into 4.7 from now until beta 1 hits. We will take some time to post any updates on future release projects each week.

Potential 4.7 Projects

  • Create page-based nav menus without leaving live preview – #34923
  • A new experience for themes in the customizer – #37661
  • Code-editing gateways, via CSS – #35395
  • Customizer browser history#28536
  • Customizer notifications center – #35210
  • Customize snapshots/transactions#30937
  • Refactoring sliding panels UI – #34391
  • Improve UI for linking preview elements to controls – #27403
  • Twenty Seventeen – the customize team should be involved with the new theme, so that we can build any new core API that can facilitate it. Since default themes should be “state of the art”, let’s make sure that every option can be previewed instantly with postMessage, and fully supports selective refresh.

Active Future Release Project Updates

Additional Tickets Needing Attention

  • Improving contrast and UI consistency in the customizer – #29158needs-testing
  • Improve custom background properties UI – #22058 – needs additional feedback on the latest proposal, and a patch
  • Appropriate means for themes to add top-level promotional links – #37335 – needs input from theme review team

Ticket Scrub

  • Identify tickets ready for commit consideration, and 4.7 milestoning from future release tickets with a patch.
  • We’ll pick a different query to triage each week. For example, bugs awaiting review (need verification).

We’re looking forward to seeing you at the meeting!

#4-7, #customize

Customize API Changes in 4.6

This post contains a summary of the developer-oriented changes and additions to the customize API in WordPress 4.6. View all 4.6 customize tickets here. The biggest new customize developer feature in 4.6 is setting validation, which has a dedicated post with details:

Clean up Customizer Media Control CSS (#30618)

When the customizer media controls were modernized in WordPress 4.1, timeline considerations required the improvements to ship with a confusing and untenable markup structure and the resulting requirement to use separate CSS selectors for each sub-control of WP_Customize_Media_Control.

In 4.6, the markup of the core media controls has been simplified and the CSS completely refactored to allow media controls to share common CSS selectors. As a result, custom controls that use part of the core UI and subclass WP_Customize_Media_Control no longer need to create their own CSS styles that duplicate core rules. Because the markup and styling has changed significantly, please test any custom controls, CSS, or JavaScript that is related to media controls in the customizer.

Customize Value Hook Receives Context (#36452)

The customize_value_{$id_base} filter now passes $this (the WP_Customize_Setting instance) as a second parameter, after the setting value. This provides access to all of the methods and parameters of the specific setting whose value is being filtered and brings this hook inline with the other hooks in WP_Customize_Setting.

Allow the Nav Menu Item Type Label (among other things) to be filtered (#35203)

The wp_setup_nav_menu_item filter is now applied consistently to all customizer settings representing nav menu items. The filter was previously used in WP_Customize_Nav_Menu_Item_Setting::value() but not in WP_Customize_Nav_Menu_Item_Setting::value_as_wp_post_nav_menu_item(), and is the same filter that’s used for the Menus screen in wp-admin.

Other Improvements

  • You can now use the Esc key to close the currently expanded section or panel (or widget/nav menu item control). See #22237.
  • The Custom Menu widget now includes a shortcut to edit a selected menu in the customizer. Navigating out of the nav menu section returns focus back to the Custom Menu widget where the shortcut button was clicked. See #32683.
  • When previewing a new theme in the customizer, clicking Activate will no longer result in being navigated out of the customizer and onto the frontend. See #35320.
  • The get_custom_logo filter now includes a blog parameter. See #36639.
  • The menu locations section in the customizer now includes buttons to edit each selected menu. See #36795.
  • There is now a link to the widgets panel in the menu locations section description. See #36796.

#4-6, #customize, #dev-notes

Feature Proposal: Content Authorship in Menus, with Live Preview

The current navigation menus system is built around a paradigm that every menu item must be associated with an existing piece of content. However, this is problematic for new users, who may find themselves with the opportunity to build a menu before creating any content. #34923 seeks to improve this experience and eliminate this usability “dead end” by adding the ability to create new post objects (most notably pages) within the menus interface in the customizer.


Purpose & Goals

While this feature is aimed primarily at new users setting up their site for the first time, it may also be useful for users that are restructuring a site, or even if they want to add a page here or there and add it to their menu before filling out its contents. It’s important to note that posts and pages added here are stubs – only their title is filled out, and the content will be added later via the post editor. For that reason, most existing sites would probably maintain their existing workflows to create new pages via the post editor, publish them, and then add them to menus. This is of course still fully supported and the new proposal seeks to provide an alternative approach that may be better for different use cases such as new sites.

Because the feature is proposed to be located in the customizer, it also fully supports live preview. The live preview component can build user trust and confidence by letting users preview and interact with their site as changes are made, before they’re published.

Technical Considerations

To allow new content to be created in the customizer, posts are created with the auto_draft status. When the user saves & publishes in the customizer, these newly-created posts are transitioned to be published. In the customizer preview, the status is modified to protected to allow the posts to be previewed.

Ideally, term creation should also be a part of the menus UI. Unfortunately, terms to not currently have a status field, and implementing that or looking at alternative approaches is something that will take more thought. Thus, this feature is being built with future support for terms in mind, but without support currently.

By default, the ability to add new content depends on the appropriate capabilities and the show_in_nav_menus parameter when registering post types. Additionally, a new filter is proposed to allow authorship in menus to be disabled on a per-post-type basis.


User testing has been requested and there are several tasks that could be tested:

  • Create a new menu for a brand new site by creating pages and adding them to a menu, assign the menu to a location and publish it.
  • On an existing site, create new pages to add to an existing menu.
  • On a complex site with multiple menus create a new page once then add it to multiple menus.
  • On sites with custom post types, create new custom posts for any of the scenarios above.

Test with the latest patch on #34923 and make sure the customize posts plugin is not activated (it has conflicts). If anyone is able to conduct user tests that would be much appreciated.

Customize Posts Plugin

Part of the inspiration for this feature comes from the Customize Posts plugin, which has the ability to live-preview posts and post meta in the customizer. Only a very small portion of the plugin would make its way into core as part of the nav menus content authorship feature. However, the proposal is currently to establish the wp.customize.Posts namespace for future expansions of post-related functionality in the customizer. The existing plugin would extend this core namespace, and other plugins could do so as well.

There are currently no plans to consider the Customize Posts plugin for full merge into core; however, stay tuned for an upcoming feature project kick-off that will seek to explore the future of live preview in WordPress at a broader level.

Feedback & Next Steps

The latest patch is currently seeking feedback for accessibility, design, code review, docs, and general comments. Please test it and leave your feedback as comments on this post or the ticket, #34923. Given current timing the ticket is likely to target the 4.7 milestone.

One remaining piece to implement is a mechanism to inform the user that their new posts have been published and provide links to edit the posts in the admin. This could take the form of a notifications area in the customizer or preview, or happen inline within the menus UI as a notice using the customizer setting validation feature that’s new in 4.6. UX feedback and ideas for the potential approach here are needed, and it could also probably work to ship without this part for now.

#customize, #menus, #proposal

Previewing Site Responsiveness in the Customizer

Note: This proposal was merged to core in [36532]. Download the latest nightly build and give it a try!

The customizer is a framework for live-previewing changes to WordPress sites. And by now, nearly every WordPress theme/site features responsive designs intended to look good on any device. Previewing site changes is just important on mobile as it is on desktop, to ensure that front-end user experience is exactly as intended.

Bringing these ideas together, #31195 proposes a new feature in the customizer that allows users to quickly preview their site on various device sizes. Here’s a quick walkthrough:


The proposed feature focuses on simplicity. The device previewer is in the customizer controls footer, near the “Collapse” button. Only three options are available by default, and they’re intentionally ambiguous. Rather than looking like specific devices, the intent is to understand what a site may look like on a roughly tablet-sized, portrait-orientation device or a roughly phone-sized device, in addition to the standard desktop view. A further extension in #34051 may allow larger screen sizes to be previewed on smaller devices with forced horizontal scrolling; for now, the feature is only available on larger devices.

For Developers

Along with this feature would come a couple of ways to customize the behavior. Please keep in mind that these are proposed and subject to change.

The new customize_previewable_devices filter lets you customize the devices available for preview. One use case may be to turn off this feature entirely:

add_filter( 'customize_previewable_devices', '__return_empty_array' );

Or, developers can add additional custom device preview buttons. The button element will be rendered and the appropriate JS applied to custom devices when the button is clicked; however, developers need to provide CSS to add an icon to the button and to react to the preview size changing.

In JavaScript, themes and plugins can react to changes in the device size being previewed with:

wp.customize.previewedDevice.bind( function( newDevice ) {
     // Do something to adapt to the new device being previewed.

This is particularly useful if your theme requires a JS trigger for responsive elements to apply, instead of using CSS solely.


Any feedback and testing is much appreciated. Device previews in the Customizer can be tested with the latest patch on #31195.

Comments are welcome on this post, the ticket (#31195), or our continuous chat in #core-customize on Slack.

#customize, #mobile, #needs-testing

Changes to Customizer Panels and Sections in 4.3

WordPress 4.3 contains some important changes to the Panels and Sections APIs. These won’t impact basic usage – add_section() and add_panel(), for example – but could potentially have compatibility issues for any custom panels or sections that override default methods. If you have themes or plugins that create custom sections or panels, please be sure to test with the latest 4.3 beta. Additionally, we’ve built out the API to support dynamically-added and more JS-driven panels and sections in 4.3. Details below.

Changes to the Default Panel & Section UI

Ticket #31336 introduced a new user experience for core Customizer sections, and made some adjustments to panels in the process. Sections in general now slide in sideways (like panels) rather than expanding open vertically in the “accordion” style. This change adds a heading within section containers that contains context for the user’s location within the Customizer hierarchy of sections/panels as well as the navigation back out of the panel.

If you have a custom section that overrides WP_Customize_Section::render(), you will probably need to add the new section header markup that has been added to the base section. Without at least the back button, users could potentially become stuck within an open section because of this core change. Additionally, the panel-back button has moved from a single button in the header (over the Customizer close button) to being contained within the panel header, similarly to the section header. If you’re overriding WP_Customize_Panel::render_content() in a custom panel, you’ll probably need to add the panel back button there. For panels and sections, if you’re overriding the onChangeExpanded method in JavaScript, you would need to implement the core changes there as well, although odds are your implementation is custom enough that the changes to the default objects won’t affect you. Because custom section and panel implementations will vary widely, your best bet is to look at the revised code in trunk and adjust your code accordingly (see wp-includes/class-wp-customize-section.php). However, for basic sections using a UI close to the default one, adding the following to your render_template() method within ul.accordion-section-content is likely to work (note this is a JS template; can be converted to a PHP template fairly easily):

<li class="customize-section-description-container">

	<div class="customize-section-title">
		<button class="customize-section-back" tabindex="-1">
			<span class="screen-reader-text"><?php _e( 'Back' ); ?></span>

			<span class="customize-action">
				{{{ data.customizeAction }}}
			{{ data.title }}


	<# if ( data.description ) { #>

		<div class="description customize-section-description">
			{{{ data.description }}}

	<# } #>

Note that custom sections and panels are generally designed to allow different UI implementations than the default behavior, so in many cases the changes to the default objects shouldn’t break your custom versions.

JavaScript-templated Panels and Sections

Building on the work done in 4.1 for controls, #30737 introduces JavaScript templates for panels and sections. The built-in core panel and section objects now use JS templates to render all instances by default. The PHP-rendered object API is still present and fully supported, but developers are recommended to strongly consider using JavaScript templates for control, section, and panel UI instead. These templates allow objects to be more easily created dynamically and improve performance by loading an object’s data (in JSON format) and a single template for the HTML structure rather than the complete fully-rendered HTML structure for repetitive (PHP-generated) UI.

Menus in the Customizer drove the completion of this API addition, and it facilitates the dynamic creation of Customizer sections and controls when creating new menus. Further plans in this area include using JS templates for the base WP_Customize_Control object by default ( #30738) and building out the API for dynamically-created controls by implementing container templates similar to what panels have ( #30741).

The remainder of this post will outline the various API additions that facilitate this, with code examples. Please review the initial post about JS templates and sections, as the new API for sections and panels is conceptually identical to what was introduced for controls in 4.1, taking a few more steps beyond it.

Registered Panel and Section Types

Similarly to the concept of registered control types introduced in 4.1, WP_Customize_Manager now supports registered section and panel types. For those that haven’t previously worked with custom sections or panels, they’re just like custom controls. You can override different pieces of the base object as needed to create custom UI. A great example in core is WP_Customize_New_Menu_Section, which is displayed as a button that toggles display of its controls inline, rather than a sliding panel.

Registering a section or panel type tells the Customizer to print one copy of the object’s JS template to the page, so that any object with this type can be rendered dynamically. Instances added in PHP will be automatically inserted into the DOM after being rendered from the JS template when ready, and the template can also be used when adding an instance dynamically in JS (for example, when adding a new section when a new menu is created).

Registering panel and section types works just like it does for controls:

add_action( 'customize_register', 'prefix_customize_register' );
function prefix_customize_register( $wp_customize ) {
  // Define a custom section class, WP_Customize_Custom_Section.
  // Register the class so that its JS template is available in the Customizer.
  $wp_customize->register_section_type( 'WP_Customize_Custom_Section' );


Sending PHP Data to JavaScript

Customizer panel and section data has been passed to the relevant JS models since 4.1, but you’re much more likely to need to send data down when working with JS templates. Anything that you would want access to in render_content() in PHP will need to be exported to JavaScript to be accessible in your section or panel template. Since JS templates are now used by default for sections and panels, most of the core class variables for these objects are passed already. To add custom ones, override WP_Customize_Panel::json()/WP_Customize_Section::json() in your custom subclass. In most cases, you’ll want to merge with the return value of the parent class’s json() method also, to ensure that all core variables are exported as well. Here’s an example from the core nav menu section class:

 * Get section parameters for JS.
 * @since 4.3.0
 * @access public
 * @return array Exported parameters.
public function json() {
	$exported = parent::json();
	$exported['menu_id'] = intval( preg_replace( '/^nav_menu\[(\d+)\]/', '$1', $this->id ) );
	return $exported;

Using JS/Underscore Templates

Once you’ve registered your custom section or panel class as a section or panel type and exported any custom class variables, you can create the template that will render the section or panel UI. This works slightly differently for sections and panels, because panels have a distinct container and content that can be overridden separately as needed.


For sections, you’ll override WP_Customize_Section::render_template() instead of WP_Customize_Section::render(). The render function is now empty in the base core control, so there’s no need to override it if you’re using a custom template. If you are using the existing PHP API, the JS template will not be used if content exists after running the render() function. The default section’s template looks like this in 4.3:

 * An Underscore (JS) template for rendering this section.
 * Class variables for this section class are available in the `data` JS object;
 * export custom variables by overriding WP_Customize_Section::json().
 * @since 4.3.0
 * @access protected
 * @see WP_Customize_Section::print_template()
protected function render_template() {

<li id="accordion-section-{{ }}" class="accordion-section control-section control-section-{{ data.type }}">

	<h3 class="accordion-section-title" tabindex="0">
		{{ data.title }}
		<span class="screen-reader-text"><?php _e( 'Press return or enter to open' ); ?></span>

	<ul class="accordion-section-content">

		<li class="customize-section-description-container">

			<div class="customize-section-title">
				<button class="customize-section-back" tabindex="-1">
					<span class="screen-reader-text"><?php _e( 'Back' ); ?></span>

					<span class="customize-action">
						{{{ data.customizeAction }}}
					{{ data.title }}


			<# if ( data.description ) { #>

				<div class="description customize-section-description">
					{{{ data.description }}}

			<# } #>




As you can see, Underscore-style templates are very similar to PHP. As more and more of WordPress core becomes JavaScript-driven, these templates are becoming increasingly more common. Besides the Customizer, sample template code in core can be found in media, revisions, the theme browser, and even in the Twenty Fifteen theme, where a JS template is used to both save the color scheme data and instantly preview color scheme changes in the Customizer. The best way to learn how these templates work is to study similar code in core.


Panels have two distinct pieces to their UI: the container, which is displayed in a list with other panels and sections at the top level of the Customizer UI, and the content, which is the context that the Customizer enters when the panel is opened. Note that this distinction is due to the philosophical design of Panels to be distinct contexts, rather than simply being a way to group related sections together. This is also based on the distinction between the container and the content in control objects. However, the distinction between panels and sections in terms of UI is less visually clear in WordPress 4.3.

Panel containers are rendered with the render_template() function, and the content template is inserted into the container in JS by looking for .accordion-sub-container. It will rarely be necessary to override the container template in a custom panel, as the custom UI will typically go in the content of the panel. The default panel template looks like this:

 * An Underscore (JS) template for rendering this panel's container.
 * Class variables for this panel class are available in the `data` JS object;
 * export custom variables by overriding WP_Customize_Panel::json().
 * @see WP_Customize_Panel::print_template()
 * @since 4.3.0
 * @access protected
protected function render_template() {

	<li id="accordion-panel-{{ }}" class="accordion-section control-section control-panel control-panel-{{ data.type }}">

		<h3 class="accordion-section-title" tabindex="0">
			{{ data.title }}
			<span class="screen-reader-text"><?php _e( 'Press return or enter to open this panel' ); ?></span>

		<ul class="accordion-sub-container control-panel-content"></ul>



Panel contents are rendered with the content_template() function, similarly to the way control templates work. In the future, this part of the API will be completed with the addition of container templates for controls, see #30741. The default panel content template in 4.3 looks like this:

 * An Underscore (JS) template for this panel's content (but not its container).
 * Class variables for this panel class are available in the `data` JS object;
 * export custom variables by overriding WP_Customize_Panel::json().
 * @see WP_Customize_Panel::print_template()
 * @since 4.3.0
 * @access protected
protected function content_template() {

	<li class="panel-meta customize-info accordion-section <# if ( ! data.description ) { #> cannot-expand<# } #>">
		<button class="customize-panel-back" tabindex="-1"><span class="screen-reader-text"><?php _e( 'Back' ); ?></span></button>

		<div class="accordion-section-title">
			<span class="preview-notice"><?php
				/* translators: %s is the site/panel title in the Customizer */
				echo sprintf( __( 'You are customizing %s' ), '<strong class="panel-title">{{ data.title }}</strong>' );
			<button class="customize-help-toggle dashicons dashicons-editor-help" tabindex="0" aria-expanded="false"><span class="screen-reader-text"><?php _e( 'Help' ); ?></span></button>

		<# if ( data.description ) { #>

			<div class="description customize-panel-description">
				{{{ data.description }}}

		<# } #>


In core, the nav menus panel, which adds screen options for the panel, is a good example of a panel with a custom content template.

#4-3, #customize, #dev-notes

New Customizer Media Controls in 4.3 and 4.2

Over the past several releases, the Customizer API has drastically improved its built-in media controls, empowering developers to leverage the power of the WordPress media management experience in themes and plugins with ease. WordPress 4.1 refactored the image and upload controls to leverage the media modal for the first time (see #21483). 4.2 abstracted this functionality to a new base media control class. And now in WordPress 4.3, we’ve added a control for cropped images. In this post, I’ll outline the recent changes in Customizer media controls and explain the differences between the available controls.


Before WordPress 4.2, all Customizer media controls saved the file url to their corresponding settings. While this facilitates quick access when using the value of the setting in themes and plugins, it makes it more difficult to access other information about that attachment, such as its title/caption, mime type, or in the case of images, accessing specific image sizes.

WP_Customize_Media_Control was introduced to allow this paradigm to change while maintaining backwards compatibility for the existing WP_Customize_Upload_Control and WP_Customize_Image_Control, which now extend the media control class (see #29215). The media control will save the attachment id for the selected media file to the Customizer setting, rather than the file URL. However, note that the default value of the setting must still be a URL, since a default attachment id doesn’t really make sense.

The media control can be used for any type of media, be it an image, audio, video, PDF document, or any other file format that your server supports. To restrict a media control instance to a particular type of content, use the mime_type parameter when adding the control:

$wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'audio_control', array(
	'label' => __( 'Media Control (audio)' ),
	'section' => 'media',
	'mime_type' => 'audio',
) ) );

When working with a setting corresponding with a media control, the sanitize_callback should generally be absint(), since a numerical id is expected. When using get_option() and get_theme_mod(), functions such as wp_get_attachment_url(), wp_get_attachment_image(), wp_get_attachment_image_src(), and even get_post() are useful depending on your needs, with each function taking the attachment id (value of the setting) as a parameter.

The full power of WP_Customize_Media_Control is realized when the control is extended to implement additional custom functionality in a custom child control. WP_Customize_Cropped_Image_Control is a great example of this in core. The core Customizer control classes provide several working examples of this; see wp-includes/class-wp-customize-control.php and wp-admin/js/customize-controls.js.


New in WordPress 4.3, WP_Customize_Cropped_Image_Control extracts functionality from the header image control to allow an image to be cropped to specific dimensions (see #29211). This offers a better user experience than automatic cropping in many cases when images of a certain size or aspect ratio are required in themes and plugins. In core, the new site icon feature relies heavily on the cropped-image control, implementing a child custom control to add additional site-icon-specific functionality.

The cropped image control comes with four custom parameters in addition to those available in the media control. These are used to specify the required (or recommended) image dimensions, as well as specifying whether alternative dimensions are allowed (the flex options). Here’s a typical usage when adding a cropped-image control:

$wp_customize->add_control( new WP_Customize_Cropped_Image_Control( $wp_customize, 'cropped_image', array(
	'section'     => 'background_image',
	'label'       => __( 'Croppable Image' ),
	'flex_width'  => true, // Allow any width, making the specified value recommended. False by default.
	'flex_height' => false, // Require the resulting image to be exactly as tall as the height attribute (default).
	'width'       => 1920,
	'height'      => 1080,
) ) );

The cropped-image control creates a child attachment of the original image attachment object for the cropped image, preserving the original version. The cropped-image attachment is given a context based on the control id (with _ replaced by -). The core control doesn’t currently use this, but it could be leveraged to query for previously-cropped images for a specific control to add a library feature in the future or in child controls. Be mindful that a version of the control id is stored in the database for cropped image attachments.

As with the media control, the cropped-image control saves the attachment id instead of the image URL. This can be useful for querying specific sizes of the image, but you’ll typically want the full size image at the cropped dimension. wp_get_attachment_image_src( absint( get_option( 'cropped_image_setting' ) ) ) should do the trick if that’s the case, when outputting the value of the setting.

#4-2, #4-3, #customize, #dev-notes, #media, #media-modal

Feature Plugin Merge Proposal: Menu Customizer

The Customizer team is proposing to merge the Menu Customizer plugin into core for WordPress 4.3. In this post, I’ll outline the purpose and history of this project, as well as highlighting the improvements that we have made.

Purpose & Goals

The purpose of the Menu Customizer project is to move navigation menu management from the WordPress admin to the Customizer. In the process, we hope to offer an updated design with improved user flow, a mobile-first interface, improved accessibility, rebuild the administration UI from the ground up to be JavaScript-driven, solve long-standing problems with the current implementation (#14134), and clarify the purposes and capabilities of the menus feature. Additionally, Menu Customizer contributes significantly to the long-term goal to move all appearance functionality and, really, everything that could benefit from live previewing, from the admin to the Customizer.


Menu Customizer started out as my Google Summer of Code 2014 Project. The initial proposal and revised schedule highlight the initial goals and provide good perspective for where we’ve come in the past year. See also the periodic posts here on make/core for updates. Development has happened on GitHub since the project opened to the community.

Core API Improvements

As I began developing this feature in plugin form, it became clear that the core Customizer API would need a lot of improvements to support something as complex as menus. Countless tickets have worked towards this goal over the past year, from the addition of the concept of Panels ( #27406) to JS/Underscore-templated controls ( #29572), and now, full support for dynamically-added sections and controls ( #30737, #30738, and #30741).

Developers are still realizing the full potential of the Customizer API, and Menu Customizer pushes the boundaries of what can be done here pretty far. One of the goals with our approach is to bring as much functionality that should be natively available in the API into core as possible. With the improvements made here already, as well as the future potential to continue abstracting functionality like the add-menu-items fly-out panel or the ability to add screen options in Customizer Panels, Menu Customizer broadens the potential for developers to extend the Customizer to do anything, in core, plugins, and themes.


In the initial GSoC project, I (@celloexpressions) developed the plugin from scratch, using Widgets in the Customizer as the design basis, with @ethitter and @obenland serving as my mentors. When the project was opened to the community for contributions, several designers and developers stepped up to help. Code contributors to date include @westonruter, @valendesigns, @voldemortensen, @adamsilverstein, and @kucrut. @designsimply and @folletto have also put in a tremendous amount of time helping with design and usability.

Plugin Overview

I highly recommend trying the plugin, which currently requires the latest version of 4.3 alpha. @designsimply has prepared a video demo:

I’ve posted a comparison of the mobile menus flow in the admin and the Customizer on make/flow, and @designsimply has also posted flows there (more flows with more recent versions of the plugin on trunk are still needed). Usability testing has been conducted on, with results posted on make/design. As further refinements are made, additional testing and feedback can be incorporated to make the new experience as polished as possible.

A couple of technical details: each menu is a Customizer section, and new menus can be added (dynamically adding new Customizer sections and controls in the process). Menu items are Customizer controls. To maximize scalability, menu items are all rendered using a single JS template, only when their containing menu section is expanded. The add-menu-item panel loads available menu items on an as-needed basis via ajax. The plugin uses several custom Customizer objects including a custom panel that implements screen options, two custom sections (menus, for lazy-loading of menu items, and new menus, which is rendered as a button toggle), and several custom controls. But everything is built off of the core Customizer API.

A summary of some key improvements that the plugin includes:

  • Modernized, simplified, and more compact UI
  • Mobile-first design that leverages the Customizer
  • Scalable, JavaScript-driven and avoids performance issues ( #14134)
  • All menus easily accessible in one place, without page reloads
  • Live previews of active menus as they are edited
  • Menu locations that can be set from the main panel or while editing
  • Global search that includes all post types and terms in all taxonomies
  • Quick-delete for deleting several items sequentially
  • “Original” item links open directly into the live preview
  • The Customizer API can be used to hook into the experience in countless ways with plugins. Support for additional menu item fields can be added much more easily now in a future release, potentially leveraging the Fields API

Core Tickets Fixed

Menu Customizer fixes numerous tickets on core trac. This is not an exhaustive list, but covers many bigger ones:

  • #14134: Menus item are limited to 16 item and will not save more than that
  • #28138: Updating menu item requires passing all of a menu item’s data to wp_update_nav_menu_item() (The plugin steps around this, we can actually fix it in core on merge)
  • #32218: Remove title attribute option in Menu Editor (off by default)
  • #19272: Add Filter to Nav Menu Support Themes Text (can modify via Customizer API)
  • #21603: Add ability to delete multiple menu items
  • #16828: Add filter on initial_meta_boxes for nav menu Probably fixed, all are shown currently, which could use improvement but it will default to more being shown at least
  • #19464: Auto add do_action for menu in admin (can use Customizer API)
  • #31391: Make the list of registered nav menus (locations) filterable (can use Customizer API)
  • #32440: on Menu page, turn posts by default on “view options”
  • #18517: Visual Feedback for Nav Menu UI

The Plan for the Menus Component

This project has a very explicit goal of not just adding menu management to the Customizer, but also removing the existing admin page in the process. The menu management screen has significant, fundamental problems in its implementation and will never scale (see #14134) without a significant refactoring along the lines of what we’ve done with the Customizer. Additionally, the new UI in the Customizer is considerably more polished than the admin screen and already includes numerous features and bugfixes proposed for core (see above). Ultimately, the new UI provides a much better experience for all users, including desktop, mobile, accessibility, etc.

The plan for the “removal” of the old menus admin screen is as follows:

  • Immediately and officially “deprecate” it: wind down any ongoing development efforts and focus all new administration-focused Menus component work on the new UI in the Customizer. Update trac tickets accordingly, and add a “Manage in Customize” link to the existing screen. Any existing tickets proposing enhancements or new features for menu administration would be required to be adapted to the Customizer version, with the (discouraged) option of also making changes to the old screen.
  • Point the “Menus” link in the admin bar to Menus in the Customizer in 4.3. Remove that menu from the admin bar in 4.4 in favor of a top-level Customize link, and put something more useful in its place (as all of its core links will point to the Customizer now).
  • Retain the admin screen codebase, along with existing links to it throughout the admin.
  • In WordPress 4.5 or 4.6, remove all core links (including admin menu) to the Menus admin screen, or point them to the Customizer. This would likely coincide with a similar change for Widgets and Themes to use the Customizer versions exclusively, once full feature-parity is achieved with the Customizer versions of the other features (Menus has it now). At this point the admin screen would be accessible only by plugin-added links or for users who cannot access the Customizer (no-js, IE7, IE8&9 with domain mapping, a very small percentage of users overall).
  • The admin screen and related code would likely not be removed entirely from core in the foreseeable future, and critical bugs or security issues would still be addressed. New feature development and enhancements would be restricted to the Customizer version.

The above plan is fairly aggressive, to eliminate any ambiguity about future plans and intentions and to avoid the potential for mass trac ticket rot. The fact that the Menus component has no maintainers and has not received significant attention since the 3.6 release indicates that there is a general lack of developer interest in dealing with the mess that the current system is. I am willing to step up as a component maintainer for Menus if the above plan is implemented.

Ongoing Work

We have a few issues left that work working on. Notably, @westonruter has proposed refactoring the way menu item settings are handled, along with menu creation and deleted, and has begun work there, but wouldn’t finish until after a core merge due to time constraints and integration with core code. @adamsilverstein is working on improving drag & drop to work with sub menus. There are also several minor issues remaining on GitHub, which would either be handled in the next couplle days or after merge (many issues have been punted to after a potential merge already).

#customize, #feature-plugins, #menu-customizer, #menus, #merge, #proposal

Customize Component Update – 5/25/15

The Customizer team has been busy working on some major user-facing and behind-the-scenes changes targeting WordPress 4.3. This update will provide an overview of our goals, current status, and pathways for contributors to get involved.

We’re planning on holding an extra meeting in #core-customize at 5pm PDT today, 5/25, (May 26, 00:00 UTC) to discuss progress and assignments/plans for the coming week-plus before the feature-plugin merge window opens. This time won’t work for our European contributors but hopefully more of us can make it than can make the old Friday time. (cc @westonruter, @valendesigns, @voldemortensen, @ocean90, @folletto).

Redesigned Customizer Flow/UX

Customizer mobile flow redesign walkthrough gif

New Customizer flow introduced in #31336, on a mobile viewport with a recent (not latest) patch.

#31336 introduces a re-imagined Customizer experience that clarifies the flow, distinguishes navigation from control UI, and improves design through careful adjustments to colors, contrast, and spacing. The primary changes are centered around removing the accordion UI in favor of panel-like horizontal sliding for sections, allowing us to introduce consistent headers across panels and sections to build on the work that was started in 4.2 with the new themes section. Design work for this change was started at the end of 4.0 last August, and @folletto has continued refining the flows since then while I’ve done most of the patching work.

At this stage, we’re trying to get a first-pass patch committed as soon as possible as it’s holding up some of our other priorities including #30737 and Menu Customizer work. We need help testing the patch on different browsers & devices, as well as for any further usability feedback. Once the initial patch is committed, it will be easier to contribute via additional smaller patches.

In addition to this broad UI/UX change, we have several other proposed UI changes being considered for 4.3. Icons for Customizer sections and panels are ready to go pending feedback ( #28504). If time allows and there is enough interest, we could also potentially introduce an improved collapsed mode ( #29949) and device-size preview for the Customizer preview ( #31195) in 4.3. We may also do a full accessibility audit and make fixes accordingly later in the release, per recent discussion on #31336.

Menu Customizer

I just pushed version 0.4, which includes:

  • In-Customizer previewing of “original” menu item links
  • A redesign of the screen options popup
  • The addition of theme location checkboxes within menu sections (which fully cross-sync with the menu locations section)
  • Theme locations listed within menu section names
  • Menus can only be deleted when they aren’t assigned to any locations
  • Available menu item searching, and a first-pass redesign of the available menu items panel to match the new look for core in #31336 (more to come here)
  • Integration of the existing theme location controls into the plugin
  • Also notable, I compiled a list of ~10 (and counting) core tickets that Menu Customizer fixes; most notably, #14134

Big thanks to @valendesigns, @folletto, and @voldemortensen for helping out with these changes. We have several major issues to fix still, so please jump in on GitHub if you’re interested in helping out.

Now is also the time for an extensive review process to begin on all fronts, so that we can address any issues in time to make core merge in just a few short weeks. We need several kinds of feedback:

  • General usability feedback
  • Usability testing
  • Accessibility review/feedback
  • Design/UI/UX feedback (test with #31336)
  • Inline documentation review (should be mostly there, but needs a thorough review and cleanup)
  • Code review/cleanup
  • Lead dev/committer review for additional issues

Note that testing should be done with the Menu Customizer plugin and WordPress 4.3 alpha, and that the patch on #31336 is currently a dependency for everything design-related. The plugin can be tested on 4.2 right now, but some pieces of the UI may be a bit off, and we’ll be breaking 4.2-compat in the near future as critical dependencies are merged into core. The most urgent dependencies are #31336 and #30737 (both of which require updates in the plugin and prevent key functionality from working). #30738 and #30741 would be really nice to have, but we can more comfortably hack around those issues at the time of core merge if we have to.

Partial Refresh

@westonruter has finished integrating partial refresh into Menu Customizer (it already worked for widgets), and is now abstracting it one layer further to be available for general use via the API. Partial refresh is an in-between option for setting previewing between doing a full refresh of the preview and fully implementing setting changes in JS via postMessage; settings are previewed by refreshing only part of the preview window.

Other Updates

We’ve made some changes to our component page. Customize is no longer a sub-component of Themes (note the URL change). I also added a summary of our major projects over the past several releases, as well as a brief roadmap/wishlist for future-release projects, and a few routes for getting involved in contributing. @valendesigns and I also triaged the roughly-20 tickets needed a response yesterday, as well as triaging a good chunk of the enhancement tickets in the component that haven’t had activity in more then 4 months. @valendesigns has also stepped up as another component maintainer, joining @westonruter, @voldemortensen, and myself.

#4-3, #customize, #menu-customizer, #menus