Refresh parts of a Customizer preview instead of reloading the entire page when a setting changed without transport=postMessage.

Contributors: xwp, westonruter
Tags: customizer, customize, preview
Requires at least: 4.1
Tested up to: 4.3
Stable tag: trunk (master)
License: GPLv2 or later

This is a feature plugin proposed for WordPress 4.4

The WordPress Customizer is a framework for previewing any change to a site. By default, settings exposed in the Customizer use a refresh transport, meaning that in order for a setting change to be applied, the entire preview has to reload, which has a huge performance hit. The result is a preview that is anything but live. To remedy this poor user experience of a laggy preview, the Customizer allows settings to opt-in to using a postMessage transport. This relies on JavaScript to apply the changes live without doing any server-side communication at all: changes are applied instantly.

There is a major issue with settings using the postMessage transport, however: any logic used in PHP to render the setting in the template has to be duplicated in JavaScript. Thus the transport is not DRY, and so it is really only suitable for simple text or style changes that involve almost no logic, and this is commonplace in themes.

What the Customizer needs is a middle-ground between refreshing the entire preview to apply changes with PHP and applying the changes exclusively with JavaScript. The partial preview refresh is one solution, and is proposed in #27355.

Partial preview refreshing was first explored when Customizer widget management was being developed for the 3.9 release. It was added to the Widget Customizer plugin, and described in a Make Core post. But we decided to remove the feature in favor of having a better generalized framework for partial refreshes in a future release. Partial preview refreshing has been added in 4.3 for changes to menus which can now be managed in the Customizer.

This plugin first focuses on resurrecting partial preview refreshes for widgets. We can then explore adding partial refresh support to other object types, such as menus, inline styles, and especially to provide an API for developers to register arbitrary regions as being partial-refreshable, in part by associating a CSS selector with a given Customizer setting.

Blue sky: If we can eliminate full-page refreshes, we can start to introduce controls inline with the preview (e.g. widget controls appearing with their widgets), and even eliminate the Customizer iframe altogether since the Customizer pane could then slide-in on any existing frontend page the user is on without having enter into a completely different Customizer state; when done, they can just collapse the Customizer away and continue on their way browsing the site.

To opt-in to partial preview refreshes for a theme, add:

add_theme_support( 'customize-partial-refresh-widgets' );

When this is done, widgets in Core will automatically use partial refreshes. To opt-in to partial refreshes for other widget types, use this to opt-in for a specific widget:

add_filter( "customize_widget_partial_refreshable_{$id_base}", '__return_true' );

And use this to opt-in everything:

add_filter( 'customize_widget_partial_refreshable', '__return_true' );

• Fix PHP 5.2 compatibility.
• Fix support for subdirectory installs.

• Fix typo causing twentyten, twentyeleven, and twentytwelve not being enabled for widget partial refresh.

• Remove partial refresh functionality since it is now moved over to Menu Customizer directly.

• Add integration for Menu Customizer.
• See all changes: 0.3...0.4

• Use trigger_error instead of error_log; do nothing on WPCOM
• Introduce widgetsExcludedForPostMessage stop gap
• Communicate to pane all widgets rendered, not just main one
• See all changes: 0.2...0.3

• Fix partial refresh during theme preview (PR #9)
• Eliminate remaining direct calls to parent window, use postMessage only (PR #8)
• Allow inactive widgets to be rendered if sidebar is specified (PR #10)
• Add initial support for plugins to support custom sidebars
• Various other fixes and hardening, see 0.1...0.2.

• Resurrect Widget Customizer partial refreshes.