Visible Edit Shortcuts in the Customizer Preview

#27403 added visible edit shortcuts to the customizer preview, making it easier to see which elements of your site are editable in the customizer and how to edit them. Here’s a demo with Twenty Fifteen (note that the ability to toggle icons off has since been removed):

Implementation: Selective Refresh Partials

Visible edit shortcuts are an extension of the existing “shift-click-to-edit” functionality built into customizer partials. Partials are sections of the front end of the site, in the customizer preview, that are associated with customizer settings. When settings change, their associated partials are selectively refreshed via an Ajax call without reloading the entire preview. Partials are to the customizer preview what controls are to the customizer editing pane: a visual representation of a setting.

Buttons are now injected into partials within the preview to expose this relationship visually and to users of all input modes. However, the role of the customizer preview is to provide an accurate representation of the frontend of the site as it’ll appear once changes are published. Accordingly, visible edit shortcuts pose a challenge as they have the potential to significantly hamper the preview-ability of the preview.

To balance between discoverability and providing an accurate preview, the initial core iteration showed a flash of the buttons when the preview first loads, then hid them. To show the shortcuts, or to toggle them on and off, you could click/tap anywhere in the preview (except on a link or button). Keyboard users had a screen-reader-text button (visible on focus) to toggle the shortcuts on and off. This functionality was removed in [39131] and icons are currently persistently visible when customizing but hidden when the controls are collapsed, and supplemental usability testing validated this decision.

Background & Prior Implementations

Shift-click to edit an element in the customizer preview was first implemented with the widget customizer project in WordPress 3.9. Visual approaches to exposing this functionality were explored, but left for a future release. Selective refresh was also first proposed, and put on hold pending development of the concept.

The first core implementation of selective refresh came with menu management in the customizer in WordPress 4.3. Menus include shift-click-to-edit on a per-menu-item bases, further demonstrating the powerful potential of associating portions of the customizer preview with their associated settings and controls.

WordPress.com currently supports a similar feature with visible edit icons in the customizer. This approach serves as the inspiration for the final UI being introduced in core, with additional UX adjustments and a complete rewrite of the implementation to make it compatible with as many themes as possible.

Adding Theme Support

Theme support for this feature is all about supporting selective refresh, which was added in WordPress 4.5. In some cases, a small amount of additional CSS will be required to ensure that the shortcuts are positioned properly. Edit shortcuts will be enabled by default for all themes, but are contingent on themes supporting selective refresh.

Selective Refresh for Widgets

See the post from WordPress 4.5 for adding support for selective refresh for widgets. In most cases, add_theme_support( 'customize-selective-refresh-widgets' ) is the only requirement:

Implementing Selective Refresh Support for Widgets

Selective Refresh for Menus

Menus support selective refresh out of the box unless: a custom nav menu walker is used, the echo argument is false, or wp_nav_menu isn’t used. In those cases, you’ll need to add support directly. Some themes may still be missing full support for selective refresh of menus, which has been enabled by default since WordPress 4.3.  Reference the post for details, but note that it predates the core implementation of an API for selective refresh:

Fast previewing changes to Menus in the Customizer

Selective Refresh for Custom Options

Custom logo (since 4.5) and header video (since 4.7) support selective refresh automatically if you use the core features via add_theme_support. Other core options such as the site title and tagline or header images can support selective refresh if you register partials for them and set their settings’ transport argument to postMessage. Here’s an example from Twenty Fifteen:

$wp_customize->get_setting( 'blogname' )->transport        = 'postMessage';
$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';

$wp_customize->selective_refresh->add_partial( 'blogname', array(
	'selector' => '.site-title a',
	'render_callback' => 'twentyfifteen_customize_partial_blogname',
) );
$wp_customize->selective_refresh->add_partial( 'blogdescription', array(
	'selector' => '.site-description',
	'render_callback' => 'twentyfifteen_customize_partial_blogdescription',
) );

Where the render callbacks call bloginfo( 'name' ); and bloginfo( 'description' ); For more details on adding support for selective refresh for custom theme options, reference the official customizer documentation.

Support in Default Themes

Twenty Eleven through Sixteen support selective refresh as of WordPress 4.5, and also support edit icons for most of their features as a result. Twenty Fourteen and Sixteen require a few very minor positioning tweaks to ensure that all of the icons are visible. This is typical of what most themes could expect needing to add.

Twenty Seventeen will be a great showcase for this new functionality, as the first theme to ship natively with selective refresh support and with visible edit shortcuts. A few additional adjustments in this new theme will ensure that every option can be previewed with selective refresh and provides visible edit shortcuts where appropriate.

Limitations & Future Iterations

The biggest limitation of the current approach is that implementation is entirely dependent on themes supporting it. However, unlike with many other theme-supported features, there is no add_theme_support for visible edit shortcuts. Where themes are already using selective refresh, shortcuts will be available out of the box in WordPress 4.7. To add theme support for edit shortcuts, themes need to add theme support for selective refresh, another newer customizer feature that allows the customizer preview to update granularly. Selective refresh provides superior user experience to the default refresh behavior because the preview context is not lost when changes are made.

Edit shortcuts currently rely on the presence of selective refresh partials for every setting that needs an icon. Some settings may be previewed exclusively with JavaScript via postMessage. Icons also aren’t needed for every option; for example, layout or color options are broader than a specific area of the site, so they aren’t associated with a particular edit icon in the preview. In the future, a structured JavaScript API for partials in the customizer preview could facilitate adding icons to JS-previewed settings that don’t use selective refresh.

Visible edit shortcuts are also the first step toward exploring the potential to edit elements of a site directly within the customizer preview. For this to be fully investigated, it’s imperative that a majority of themes and customizer option support selective refresh so that areas of the preview are associated with the appropriate customizer settings and so that context-disrupting full page reloads can be minimized.

Contributors & Call for Help

@sirbrillig led development of the feature for core based on the equivalent feature on WordPress.com. Core props went to @sirbrillig, @mattwiebe, @celloexpressions, @melchoyce, @westonruter, and @afercia. Thanks to everyone who has contributed so far!

Now, your help is needed! Here’s what you can do to make this feature shine in WordPress 4.7:

  • Theme authors: add support for selective refresh to your themes. Start with widgets and make sure it’s working for menus, then make sure you’re using the core custom logo feature. Then, add selective refresh to the site title and tagline, header images, and any custom options with associated regions on the frontend.
  • Theme authors: adjust icon positioning in your theme’s CSS. You can add styles to.customize-partial-icon button to adjust all icons, and scope that to a specific container or even .customize-partial-icon-setting_id to adjust a particular edit icon. Note: these were updated with [39136].
  • Everyone: test edit shortcuts with your current theme with WordPress 4.7 Beta 1 (or newer). Most themes should be able to support them on widgets, menus, and logos with minimal effort. Contact your theme’s developer with any bugs or missing edit icon support, refer them to this post, and ask them to add support for visible edit shortcuts.
  • Everyone: test as many themes as possible and look for anywhere the shortcuts don’t display as expected, or at all. Contact the theme author with your findings, refer them to this post, and ask them to improve support for visible edit shortcuts in their themes.