Tag Archives: feature-selective-refresh

Weston Ruter 12:50 am on March 22, 2016
Tags: , , , feature-selective-refresh   

Implementing Selective Refresh Support for Widgets

WordPress 4.5 includes a new CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. framework called selective refresh. To recap, selective refresh is a hybrid preview mechanism that has the performance benefit of not having to refresh the entire preview window. This was previously available with JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors.-applied postMessage previews, but selective refresh also improves the accuracy of the previewed change while reducing the amount of code you have to write; it also just makes possible to do performant previews that would previously been practically impossible. For example, themes often include some variation of the following PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher and JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. to enable performant previewing of changes to the site title:

function mytheme_customize_register( WP_Customize_Manager $wp_customize ) {
	$wp_customize->get_option( 'blogname' )->transport = 'postMessage';
}
add_action( 'customize_register', 'mytheme_customize_register' );

function mytheme_customize_preview_js() {
	$handle = 'mytheme-customize-preview';
	$src = get_template_directory_uri() . '/js/customize-preview.js';
	$deps = array( 'customize-preview' );
	$ver = '0.1';
	$in_footer = true;
	wp_enqueue_script( $handle, $src, $deps, $ver, $in_footer );
}
add_action( 'customize_preview_init', 'mytheme_customize_preview_js' );

( function( $, api ) {
	api( 'blogname', function( setting ) {
		setting.bind( function( value ) {
			$( '.site-title a' ).text( value );
		} );
	} );
} ( jQuery, wp.customize ) );

In 4.5, the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. themes now utilize selective refresh for previewing the site title and tagline. This allows the above code to be replaced with the following PHP:

function mytheme_customize_register( WP_Customize_Manager $wp_customize ) {
	$wp_customize->selective_refresh->add_partial( 'blogname', array(
		'selector' => '.site-title a',
		'render_callback' => function() {
			bloginfo( 'name' );
		},
	) );
}
add_action( 'customize_register', 'mytheme_customize_register' );

So as you can see, not only is the amount of code more than cut in half (also eliminating the JS file altogether), it also ensures that when a site title change is previewed it will appear with all of the PHP filters applied from core and plugins: for example wptexturize will apply so that curly quotes and dashes will appear as expected. In REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. parlance, selective refresh enables the Customizer preview to show title.rendered instead of just title.raw. (For more on this change to previewing the site title and tagline, see #33738. The previous JS-based previewing is retained for an instant low-fidelity preview while the selective refresh request returns.) Selective refresh is also the mechanism used for previewing the new custom logo feature in 4.5, ensuring that the logo image is rendered re-using the image_downsize logic in PHP without having to re-implement it in JS (keeping the code DRY).

With that recap of selective refresh out of the way, let’s turn to the focus of this post: selective refresh for widgets. When widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. management was added to the Customizer in 3.9, every change to a widget required a full page refresh to preview. This resulted in a poor user experience since a full refresh can take awhile, especially on weighty pages. So selective refresh of widgets is a key usability experience improvement for widget management in the Customizer in 4.5. However, as live postMessage updates to the site title and tagline have required supporting theme code (see above), so too will theme support be required for widgets, as noted in the Selective Refresh of Widgets section from the previous post on this topic:

Selective refresh for nav menus was enabled by default in 4.3. While some themes needed to add theme support for any dynamic aspects (such as the expanding submenus in Twenty Fifteen), generally nav menus seem to be fairly static and can be replaced in the document without needing any JS logic to be re-applied. Widgets, on the other hand, have much more variation in what they can display, since they can in fact display anything. For any widget that uses JavaScript to initialize some dynamic elements, such as a map or gallery slideshow, simply replacing the widget’s content with new content from the server will not work since the dynamic elements will not be re-initialized. Additionally, the sidebars (widget areas) in which the widgets are displayed may also have dynamic aspects associated with them, such as the Twenty Thirteen sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. which displays widgets in a grid using Masonry. For this theme, whenever a widget is changed/added/removed/reordered, the sidebar needs to be reflowed.

In order to allow themes to reflow sidebars and widgets to reinitialize their contents after a refresh, the selective refresh framework introduces widget-updated and sidebar-updated events. Additionally, since re-ordering widgets in a sidebar is instant by just re-ordering the elements in the DOM, some widgets with dynamically-generated iframes (such as a Twitter widget) may need to also be rebuilt, and for this reason there is a partial-content-moved event.

For the above reasons, I believe it will be much more common for widgets (and sidebars) to need special support for selective refresh, and so I think that at least for 4.5 the selective refresh should be opt-in for widgets (and perhaps in themes for sidebars). See theme support for Twenty Thirteen and plugin support for a few widgets in Jetpack (which won’t be part of the merge). At last week’s Core dev meeting, it was suggested that we add the opt-in for widget selective refresh at RCrelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta)..

So as noted, selective refresh for widgets will be opt-in as of 4.5 RC1 (see #35855).

What do themes and widgets need to do to opt-in for selective refresh support?

Selective refresh will be used for previewing a widget change when both the theme and the widget itself indicate support as follows:

Adding Theme Support

If your theme does not do anything fancy with its sidebars (such as using Masonry to lay out widgets), then all that you need to do is add the following to your theme:

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

On the other hand, if the theme is rendering a sidebar in a unique way, then to add a bit of logic to handle the changes properly. For example, as noted previously the footer area in Twenty Thirteen consists of a sidebar that is laid out using Masonry. When a widget is added, removed, or updated, the Masonry logic needs to be re-run to update the positioning of the widgets in the sidebar. The following highlighted code is what handles this:

jQuery( function( $ ) {
	var widgetArea = $( '#secondary .widget-area' );
	widgetArea.masonry( {
		itemSelector: '.widget',
		columnWidth: columnWidth,
		gutterWidth: 20,
		isRTL: body.is( '.rtl' )
	} );
	
	if ( 'undefined' !== typeof wp && wp.customize && wp.customize.selectiveRefresh ) {
		wp.customize.selectiveRefresh.bind( 'sidebar-updated', function( sidebarPartial ) {
			if ( 'sidebar-1' === sidebarPartial.sidebarId ) {
				widgetArea.masonry( 'reloadItems' );
				widgetArea.masonry( 'layout' );
			}
		} );
	}
} );

Update 2016-07-17: Added the jQuery() DOM ready wrapper around this logic to ensure it runs after the DOM has been fully loaded, and thus ensuring the wp.customize.selectiveRefresh object exists if it is going to be loaded. See ​#37390 as this also turned out to be broken in Twenty Thirteen.

Note the if statement is there so the code will only run in the Customizer preview and if selective refresh is available (that is, if they are running 4.5 or later).

Adding Widget Support

If your widget lacks any dynamic functionality with JavaScript initialization, adding support just requires adding a customize_selective_refresh flag to the $widget_options param when constructing the WP_Widget subclass. If you are enqueueing any CSSCSS Cascading Style Sheets. for styling the widget, you’ll also want to enqueue this unconditionally in the Customizer preview (if is_customize_preview()) so that a widget can be added to the preview and be styled properly without doing a full page refresh. For example, note these highlighted lines in a sample widget:

class Example_Widget extends WP_Widget {

	public function __construct() {
		parent::__construct(
			'example',
			__( 'Example', 'my-plugin' ),
			array(
				'description' => __( 'Selective refreshable widget.', 'my-plugin' ),
				'customize_selective_refresh' => true,
			)
		);

		// Enqueue style if widget is active (appears in a sidebar) or if in Customizer preview.
		if ( is_active_widget( false, false, $this->id_base ) || is_customize_preview() ) {
			add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_scripts' ) );
		}
	}

	public function enqueue_scripts() {
		wp_enqueue_style( 'my-plugin-example-widget', plugins_url( 'example-widget.css', __FILE__ ), array(), '0.1' );
	}

	/* ... */
}

On the other hand, as with sidebars in a theme, if a widget uses JavaScript for initialization, you’ll need to add logic to make sure re-initialization happens when the widget is selectively refreshed. So in addition to the above example, you must:

  1. Enqueue any dependent JS logic if is_customize_preview() just as noted above for enqueueing any CSS stylesheet.
  2. Add a handler for partial-content-rendered selective refresh events to rebuild a widget’s dynamic elements when it is re-rendered.
  3. As needed, add a handler for partial-content-moved selective refresh events to refresh partials if any dynamic elements involve iframes that have dynamically-written documents (such as the Twitter Timeline widget). (Adding this event handler should normally not be required.)

The Twitter Timeline widget in the Jetpack pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party is a good example for how to write these event handlers:

jQuery( function() {
	// Short-circuit selective refresh events if not in customizer preview or pre-4.5.
	if ( 'undefined' === typeof wp || ! wp.customize || ! wp.customize.selectiveRefresh ) {
		return;
	}

	// Re-load Twitter widgets when a partial is rendered.
	wp.customize.selectiveRefresh.bind( 'partial-content-rendered', function( placement ) {
		if ( placement.container ) {
			twttr.widgets.load( placement.container[0] );
		}
	} );

	// Refresh a moved partial containing a Twitter timeline iframe, since it has to be re-built.
	wp.customize.selectiveRefresh.bind( 'partial-content-moved', function( placement ) {
		if ( placement.container && placement.container.find( 'iframe.twitter-timeline:not([src]):first' ).length ) {
			placement.partial.refresh();
		}
	} );
} );

(This is adapted from a pending PR for Jetpack.)

Conclusion

All core themes and core widgets will have support for selective refresh in 4.5. Now it’s up to theme and plugin authors to also add support to also start taking advantage of these drastic performance improvements for previewing widget changes.

#4-5, #customize, #dev-notes, #feature-selective-refresh

Weston Ruter 8:25 am on February 16, 2016
Tags: , , feature-selective-refresh   

Selective Refresh in the Customizer

This proposal was merged to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.Core Core is the set of software required to run WordPress. The Core Development Team builds WordPress. in [36586]. Download the latest nightly build and give it a try!

The Customizer is our framework for live previewing changes. However, settings edited in the Customizer get sent to the preview via the refresh transport by default, meaning that in order for a setting change to be applied, the entire preview has to reload: this refresh can be very slow and 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 which relies on JavaScript to preview the change instantly without doing any server-side communication at all. This provides for a great user experience.

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. This means that the postMessage previewing logic violates the DRY (Don’t Repeat Yourself) principle, and so it is really only suitable for simple text or style changes that involve almost no logic (e.g. site title or background color). Even in this case, it is often not possible to fully re-implement the PHP logic in JS, since as in the example of #33738 there may be an unknown number of PHP filters that get applied to the setting’s value (such as the site title) when rendering the content on the server.

What the Customizer needs is a middle-ground between refreshing the entire preview to apply changes with PHP and between applying the changes exclusively with JavaScript. The selective refresh is the solution proposed in #27355, and this post is about documenting the feature, as it was approved for core merge in 4.5. Selective refresh also appears on the proposed Customizer roadmap.

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 it was decided to remove the feature in favor of having a better generalized framework for partial refreshes in a future release (which is now). In 4.3, nav menus were added to the Customizer and with this the first core implementation of selective refresh, as described in Fast previewing changes to Menus in the Customizer. (For more background, see Implementing Selective Refresh in the Customizer.)

With the shipped example of selective refresh of nav menus in the Customizer, and an initial implementation of selective refresh for widgets, work progressed to generalize a selective framework that would support the complicated examples of nav menus and widgets, but also to support simpler use cases such as letting the server render the updated site title so that wptexturize and other filters can apply. The generalized framework has been implemented in the Customize Partial Refresh feature plugin, which also re-implements selective refresh of nav menus and introduces selective refresh of sidebars and widgets.

To see a simple example of selective refresh, see the Site Title Smilies plugin showing wptexturize and emoji applying to site title updates in the preview:

Note in this example that the standard postMessage updating of the site title in the header is still in place and so the change appears immediately. It gets followed, however, by the content being rendered by the partial on the server. This allows for JS to apply a quick low-fidelity preview for a setting change until the server can respond with the high-fidelity preview.

Selective Refresh Architecture

This plugin introduces a selective refresh framework which centers around the concept of the partial. A partial is conceptually very similar to a Customizer control. Both controls and partials are associated with one or more settings. Whereas a control appears in the pane, the partial lives in the preview. The fields in a control update automatically to reflect the values of its associated settings, and a partial refreshes in the preview when one of its settings is changed. The name “partial” is derived from  get_template_part(), which is a natural function to use in a partial’s  render_callback.

In addition to a partial being associated with one or more settings, a partial is also registered with a jQuery selector which identifies the partial’s locations or “placements” on the page, where the rendered content appears. For example, a partial can be registered for the site title to update the header as well as the document title via:

function my_register_blogname_partials( WP_Customize_Manager $wp_customize ) {

	// Abort if selective refresh is not available.
	if ( ! isset( $wp_customize->selective_refresh ) ) {
		return;
	}

	$wp_customize->selective_refresh->add_partial( 'header_site_title', array(
		'selector' => '.site-title a',
		'settings' => array( 'blogname' ),
		'render_callback' => function() {
			return get_bloginfo( 'name', 'display' );
		},
	) );

	$wp_customize->selective_refresh->add_partial( 'document_title', array(
		'selector' => 'head > title',
		'settings' => array( 'blogname' ),
		'render_callback' => 'wp_get_document_title',
	) );
}
add_action( 'customize_register', 'my_register_blogname_partials' );

When a setting (like blogname here) is modified, each registered partial is asked on the client whether it isRelatedSetting(). If that method for a partial returns true, then the partial’s refresh() method is invoked and a request is queued up to render the partial via the requestPartial() function. Calls to this function are debounced and multiple simultaneous partials being changed will be batched together in a single Ajax request to the server.

When the server receives a request to render partials, it will receive the list of partials as well as all of the modified settings in the Customizer. Partials need not be all registered up front: as settings support the customize_dynamic_setting_args and customize_dynamic_setting_class filters, so too partials support the customize_dynamic_partial_args and customize_dynamic_partial_class filters. These filters allow partials to be added on demand to support the partials being requested to render.

If there is no registered partial for the request, or if the partial’s render_callback returns false, then false will be returned in the response as the content for that partial, and the default fallback() behavior in the client-side Partial object is to requestFullRefresh(). On the other hand, if the request recognizes the partial and the render_callback returns content, then this content is passed along to the Partial instance in the client and its renderContent() method then follows through to update the document with the new content.

As noted previously, the location in the document where a partial renders its update is called a placement. A selector may match any number of elements, and so too a partial may update multiple placements. A partial’s placements in the document may each have different sets of context data associated with them. This context data is included in the partials request and is passed along to the render_callback so that the content can vary as needed, for example a widget appearing in two different sidebars would have different sidebar_id context data, which would then determine the before_widget and after_widget args used.

Partial placements may also be nested inside other placements. For example, a Custom Menu widget is rendered as a placement which then contains another placement for a nav menu. The nav menu placement is updated independently from the parent widget placement. This being said (and this is advanced usage), a selector does not need to be supplied when registering a partial: alternatively to a top-down selector, the placement for a partial can be declared from the bottom-up by adding a data-customize-partial-id attribute to any container element. Whenever a partial is re-rendered, any nested partials will be automatically recognized. (As noted above, each placement can have a different associated context, and this is indicated by JSON object in a data-customize-partial-placement-context HTML attribute.)

Aside: The architecture of the Infinity Scroll module in Jetpack mirrors Selective Refresh framework in several ways.

Linking Partials to Controls

Since each partial is associated with at least one setting, shift-clicking on the placement for a partial will attempt to focus on the related control in the pane. This was already implemented for widgets since 3.9 and recently for nav menu items as well, but now the functionality is available to partials generally.

Selective Refresh of Widgets

Selective refresh for nav menus was enabled by default in 4.3. While some themes needed to add theme support for any dynamic aspects (such as the expanding submenus in Twenty Fifteen), generally nav menus seem to be fairly static and can be replaced in the document without needing any JS logic to be re-applied. Widgets, on the other hand, have much more variation in what they can display, since they can in fact display anything. For any widget that uses JavaScript to initialize some dynamic elements, such as a map or gallery slideshow, simply replacing the widget’s content with new content from the server will not work since the dynamic elements will not be re-initialized. Additionally, the sidebars (widget areas) in which the widgets are displayed may also have dynamic aspects associated with them, such as the Twenty Thirteen sidebar which displays widgets in a grid using Masonry. For this theme, whenever a widget is changed/added/removed/reordered, the sidebar needs to be reflowed.

In order to allow themes to reflow sidebars and widgets to reinitialize their contents after a refresh, the selective refresh framework introduces widget-updated and sidebar-updated events. Additionally, since re-ordering widgets in a sidebar is instant by just re-ordering the elements in the DOM, some widgets with dynamically-generated iframes (such as a Twitter widget) may need to also be rebuilt, and for this reason there is a partial-content-moved event.

For the above reasons, I believe it will be much more common for widgets (and sidebars) to need special support for selective refresh, and so I think that at least for 4.5 the selective refresh should be opt-in for widgets (and perhaps in themes for sidebars). See theme support for Twenty Thirteen and plugin support for a few widgets in Jetpack (which won’t be part of the merge). At last week’s Core dev meeting, it was suggested that we add the opt-in for widget selective refresh at RC.

Update: See follow-up post on Implementing Selective Refresh Support for Widgets.

Selective Refresh API

What follows is a list of aspects of the API that should be more commonly used. For full documentation, see the inline docs in the plugin source.

PHP

I suggest that Selective Refresh be added as a new Customizer component to be accessed via $wp_customize->selective_refresh which is where the methods for partials(), add_partial(), get_partial(), remove_partial(), and others would be accessed.

New classes:

  • WP_Customize_Selective_Refresh
  • WP_Customize_Partial

New filters:

  • customize_partial_render
  • customize_partial_render_{$partial->id}
  • customize_dynamic_partial_args
  • customize_dynamic_partial_class
  • customize_render_partials_response

New actions:

  • customize_render_partials_before
  • customize_render_partials_after

JS

Namespace: wp.customize.selectiveRefresh

New classes:

  • wp.customize.selectiveRefresh.Partial
  • wp.customize.selectiveRefresh.Placement
  • wp.customize.navMenusPreview.NavMenuInstancePartial
  • wp.customize.widgetsPreview.WidgetPartial
  • wp.customize.widgetsPreview.SidebarPartial

New properties:

  • wp.customize.selectiveRefresh.parital (collection)
  • wp.customize.selectiveRefresh.partialConstructor

Events (triggered on wp.customize.selectiveRefresh):

  • render-partials-response
  • partial-content-rendered
  • partial-placement-moved
  • widget-updated
  • sidebar-updated

The Future

If we can eliminate full-page refreshes from being the norm for the Customizer, we can start to introduce controls inline with the preview. If the entire preview does not reload, then the inline controls won’t get destroyed by the refresh with each change. For example, consider a widget control floating immediately next to the widget in the sidebar it is editing. With selective refresh, it will then also be possible to eliminate the Customizer altogether. The Customizer could be available to anyone who is logged in, with the controls being bootstrapped on demand when a user wants to edit a given element. There would be no need to navigate way from a page on the frontend to enter a unique Customizer state: the Customizer would come to the user. Any controls not relevant to being inline could remain in the Customizer pane, but it could slide in only as needed instead of appearing by default. That is to say, selective refresh makes the Customizer a much better framework for implementing frontend editing.

Feedback

There is just over a week until the first beta for 4.5. I’d like to get any final feedback on the feature as soon as possible before committing it to trunk. The plugin is on GitHub and the plugin directory. Feedback should be left on #27355. Note that the plugin depends on 4.5-alpha-35776 to run.

#4-5, #customize, #feature-selective-refresh

Weston Ruter 10:45 pm on July 29, 2015
Tags: , , , , feature-selective-refresh, , , , ,   

Fast previewing changes to Menus in the Customizer

The foundation of the CustomizerCustomizer Tool built into WordPress core that hooks into most modern themes. You can use it to preview and modify many of your site’s appearance settings. is built on the concept of the “setting”, an abstract representation of anything in WordPress: options, theme mods, posts, terms, and so on. Settings are linked to controls which are responsible for manipulating them. When a setting is changed it gets pushed into the preview window so that the modification can be reviewed before being published live. There are two ways (transports) for how a setting can be pushed into the preview: refresh and postMessage. The refresh transport does a full page refresh with the modified settings applied, and so it relies on PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher to apply the setting changes. The refresh transport is designed to be compatible with all themes, but for heavy sites refresh can be excruciating slow and taxing on the server. For this reason, the postMessage transport was introduced for previewing changes. This transport uses JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. to apply the changes instantly in the preview without any Ajax requests or PHP calls. This is great, but themes have to opt-in to postMessage transport for settings because they must also include JavaScript code which duplicates the logic which is already being executed on the server by PHP. The postMessage transport violates the DRY principle. With that background out of the way…

Partial Refresh of Menus

In WordPress 4.3 menu management is being added to the Customizer, extending the types of objects that the Customizer can manipulate to include nav_menu taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. terms and nav_menu_item posts. We wanted this menu management experience to be fast so it had to avoid the slow full-page refresh transport. Nevertheless, the postMessage transport wasn’t possible to use either since we wouldn’t be able to duplicate all of the PHP menu walker logic and theme/pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party extensions for rendering menus purely in JavaScript. We also wanted to enable fast previewing of menu changes by default. So we implemented a postMessage/refresh hybrid approach which uses postMessage to sync the menus settings to the preview, and then the preview does an Ajax request to render just the contents of the menu container, and this Ajax response is then inserted into the DOM to replace the previous menu container. The technical name for this approach we have been calling “partial refresh”, but you can call it “fast preview”. When the Customizer determines it can’t do a partial refresh, it falls back to performing a full page refresh. Conditions for why a menu change will get a full page refresh include:
  • if the menu was just assigned to a location for the first time or removed from being assigned to a location, since the theme may have some changes to the layout that it may need to perform;
  • or if wp_nav_menu() is called with with echo being false, since the theme may be doing some string replacement in this case which we can’t replicate in the partial-refresh Ajax request;
  • or if wp_nav_menu() is called with with a non-JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. serializable fallback_cb, such as a closure or a object method—this arg has to be empty or a string;
  • or if wp_nav_menu() is called with with a walker object instance, as opposed to a class name string;
  • or if wp_nav_menu() is called without a theme_location arg and the menu arg is not an term ID or a menu object;
  • or if the menu selected in a Custom Menu widgetWidget A WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user. is changed, since partial refresh for widgets is not yet supported (however, see feature plugin)—subsequent changes to the menu will result in fast partial refreshes if the above conditions
When a menu is being updated via partial refresh, the menu container will receive a classname customize-partial-refreshing, which by default changes the opacity to 25%.

Theme Support

The fast preview for menu changes is being enabled by default so that theme authors don’t have to opt-in to the functionality like they do for instant preview (postMessage transport). In general this should be fine. However, if the theme includes some JavaScript which dynamically manipulates the rendered menu container, such as adding event handlers for expanding/collapsing submenus, then the theme would need to include some JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. to re-apply the modifications once the menu is partial-refreshed, as the old DOM for the menu container gets replaced. The Twenty Fifteen theme actually uses JS to expand/collapse submenu items, so it needed a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. in 4.3 to re-setup a partial-refreshed main nav menu. In addition to firing the menu container DOM setup logic once at jQuery.ready(), it now invokes the functionality whenever the menu is partial-refreshed. See the initMainNavigation() JS function. So in general, if your theme needs to dynamically initialize menus with JavaScript, the pattern for the initialization code should be: 
jQuery(function($) {
	function initMainNavigation( container ) {
		/* set up container... */
	}
	initMainNavigation( $( '.main-navigation' ) );

	$( document ).on( 'customize-preview-menu-refreshed', function( e, params ) {
		if ( 'primary' === params.wpNavMenuArgs.theme_location ) {
			initMainNavigation( params.newContainer );
			/* optionally sync a previous menu state from params.oldContainer... */
		}
	});
});
The params being passed to the event handler consists of the following properties:
  • newContainer: jQuery object containing the new menu container element retrieved from Ajax; this is what you would manipulate to initialize.
  • oldContainer: the previous jQuery object holding the element for the replaced menu container; this is useful if there is any state in the old menu that should persist in the new menu, such as which submenus are expanded (as in Twenty Fifteen).
  • wpNavMenuArgs: The array of arguments passed to wp_nav_menu() in the template, such as template_location.
  • instanceNumber: The index for which wp_nav_menu() call being updated.

The Future

Partial refresh is an “experimental transport” introduced here specifically for menus. In 4.4 we hope to generalize the framework so that any setting can be setup for fast preview, starting with widgets (see #27355). There is a Customize Partial Refresh feature pluginFeature Plugin A plugin that was created with the intention of eventually being proposed for inclusion in WordPress Core. See Features as Plugins. that implements widget partial refresh in a betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. state. This partial refresh functionality I’ve also identified as being critical for Customizer Transactions.

#4-3, #customize, #dev-notes, #feature-plugins, #feature-selective-refresh, #kickoff, #menu-customizer, #menus, #partial-refresh, #proposal

Weston Ruter 11:04 am on January 26, 2015
Tags: , feature-selective-refresh, , , ,   

Proposal: Customizer Transactions

Note: This post has been superseded by Customize Changesets (formerly Transactions) Merge Proposal. See also Customize Changesets Technical Design Decisions.

You may be familiar with transactions in a database context. The idea is simple: once you start a transaction, any change made to the database in the current session will not be applied to other database sessions until a transaction COMMIT is done. Changes performed when the transaction is open will be reflected in any SQL SELECT queries made, and if you decide that you do not want to persist the changes in the transaction in the database, you can simply do ROLLBACK and the changes will be discarded. And actually WordPress already uses MySQL transactions, but only in unit tests: a rollback is done after each test is torn down to restore the database state for the next test.

The parallels between database transactions and the WordPress Customizer are clear. When you open the Customizer you are starting a “settings transaction”. Any changes made to the settings in the Customizer get reflected in the preview only, and they get written (committed) to the database only when the user hits “Save & Publish”.

As good as the Customizer currently is, the way it has been implemented means that there are limitations on what we can do with it.

Current Limitations

The existence of modified settings in the Customizer is restricted to the life of a browser window. When a user changes a control in the Customizer and a setting is modified (with transport=refresh), an Ajax request is made with the changed settings data POSTed to the previewed URL. The Customizer then boots up and adds the setting preview filters based on what it sees in $_POST['customized'] so that the changes are reflected when WordPress builds the page. When this Ajax response is received, the Customizer JS code then writes the response to the iframe via document.write().

There are a few downsides to this current approach:

One problem is that if the user navigates away from the Customizer, they lose their drafted settings. To get around this, an AYS dialog was added in #25439, but this still doesn’t account for browser crashes or system failures. It would be ideal if the settings could persist in the same way as when drafting a post.

Another downside is that whenever the preview needs to refresh it has to re-send all the modified settings so that the Customizer preview will have them available to add to the filters, since the Customized settings data is not persisted in WordPress in any way. There’s a performance hit to continually send all data with each request, which was partially improved with #28580.

Additional problems stem from the Ajax POST + document.write() approach to refreshing the preview. Since the Customizer iframe starts out at about:blank and the HTML is written to from the document at customize.php, much of the context for the document in the iframe gets inherited from the parent window. This means that window.location in the preview window is the same as in the parent window: /wp-admin/customize.php. Needless to say, this means that JavaScript code running in the Preview will not run as expected (e.g. #23225).

The Customizer preview intercepts all click events and sends the intended URL to the parent window so that the Customizer can initiate the request to refresh the preview. The only way to change the current page in the preview is by clicking a standard links with a URL; any form submissions in the preview are completely disabled, resulting in the search results page not being reachable from within the preview (#20714). Any navigation system that uses JavaScript to change the window’s location also will fail, for instance using a dropdown.

The current unique method for refreshing the preview worked fine when the Customizer was limited to a handful of settings. But now as more and more of WordPress is being added to the Customizer, and now that themes are increasingly leveraging JavaScript, we need a more robust approach to implementing the Customizer which will solve the above challenges and provide new opportunities.

Customizer Transactions

The proposal is that we introduce persisted Customizer settings, in other words “Customizer transactions”. Here’s how it may work:

When opening the Customizer for the first time, a transaction UUID is generated. Whenever a setting changes, an Ajax request sends the updated setting to WordPress to be persisted in a wp_transaction post which has a post_name corresponding to that UUID (or such a transaction post is created on the fly if not existing already). Any changes made in the Customizer then get amended to the same wp_transaction post, which has a key/value JSON blob as its post_content.

When a user hits the Save & Publish button, the underlying wp_transaction post gets a post status change to publish. When transitioning into this status, each of the settings in the transaction at that point get saved to the database—they get committed.

Instead of using an Ajax POST to send the customized settings to the preview, we then only have to reference the transaction UUID when loading URLs into the Customizer preview. What this means is that we no longer have to use a blank iframe but can load the window with the natural URL for what is being previewed (#30028), but just with the transaction UUID query parameter tacked on.

When this transaction UUID query parameter is present, filters get added to amend all URLs generated in the preview to also include this UUID, so the transaction context is persisted as the user navigates around the site in the preview window. Forms also get this transaction UUID added as another input element, so any form submissions will also keep the preview inside the transaction. Additionally, WP Ajax requests are intercepted to tack on the transaction UUID so that now even Ajax requests can be previewed in the Customizer without any extra work.

Now that the document in the preview window is actually at the URL being previewed (as opposed to about:blank), refreshing the preview is greatly simplified: instead of capturing scroll position, doing Ajax POST, writing the response with document.write(), and restoring the scroll position—now the preview window just has to do a simple location.reload(). JavaScript now runs in the expected context, and full JS applications can be previewed in the Customizer.

As noted above, each time the Customizer is opened and a setting is updated the first time, a wp_transaction post is created with a draft status, and this post gets updated each time a setting is changed during that Customizer session. You also can open the Customizer as a whole (at customize.php) with this transaction UUID supplied and that settings in that existing transaction draft will be loaded. This means you can draft Customizer settings and return to them later, or make some changes and then send it along to another user to finalize (realtime collaboration would be possible as well with some heartbeat integration, or else a locking mechanism would make sense). The capability to publish wp_transaction posts could be restricted to an administrator role, with other roles being able to save posts with a pending status to submit for review.

Also as noted above, the point at which the settings in a transaction get saved (committed) to the database is when the wp_transaction post transitions to a publish status. This being the case it naturally allows for transaction posts to be scheduled to apply in the future. If you want to make a bunch of changes to your site appear at midnight on Saturday, you could go in on Friday and add/remove widgets, change background images, and do anything else the Customizer allows and then have this transaction be scheduled for the desired time. When it publishes, all of the settings would go live on the site. This resolves #28721.

With each Customizer session resulting in a new transaction post being created, then there is automatically a Customizer revision history (see #31089). Every transaction that has a publish post status is a change that went live on the site.

Another side benefit to reworking the Customizer preview to load via a natural URL with the transaction UUID supplied is that there aren’t any intrinsic capabilities needed to preview a transaction on the site. A setting change gets authorized at the time of the change, and the sanitized setting is then persisted in the transaction post. The preview then just applies the pre-authorized and pre-sanitized settings. The interesting side-effect of this is that it means Customizer previews (frontend URLs with the transaction UUID amended) can be shared with anonymous users to review. You can pop open the URL in the preview iframe into a new window and share it with any user for review, and they don’t need the capability to customize.

Lastly, something else that motivated my investigation into Customizer transactions is thinking about how the Customizer will relate to the upcoming REST API. How can the REST API be improved with the Customizer? Where do they intersect? If the REST API provides a transactions endpoint for doing CRUD operations on Customizer settings, and if the REST API also has global recognition for a customize_transaction_uuid query parameter in all requests, then it becomes possible for the Customizer to be used to preview changes in applications that merely interact with the JSON REST API, as long as they include the transaction UUID in the requests.

Partial Refresh

There’s one drawback I’ve encountered when implementing a patch for what I’ve described above. As noted above, when a setting has a refresh transport, the preview window now does a regular location.reload(). When this happens, there is a momentary “flash of unloaded content” (white screen) which currently doesn’t happen when document.write() is employed to refresh the preview window. I’m not sure why this is, other than maybe document.write() initiates a synchronous DOM operation, whereas doing location.reload() initiates an asynchronous one. I’ve tried doing output buffering as well, to try to make sure the response gets sent all at once. But I haven’t had success. This is the current refresh behavior:

If no solution can be found for the white-screen-flash-during-reload issue, there is an alternative (besides the postMessage transport) which would provide an even better experience than even now with the “seamless” full page refresh: partial refresh (#27355).

When a setting change can’t be previewed purely with JavaScript (via postMessage), or it doesn’t make sense to re-implement all of the PHP logic in JS (which is not DRY), the Customizer currently necessitates a full refresh of the entire page. With the proposed partial refresh transport, however, only the container element(s) in which the setting appears in the preview would get fetched from the server via Ajax and inserted into the DOM. This is much faster than having to refresh the entire page, and it retains the overall document state (e.g. whether the sidebar is expanded or not).

There are challenges for implementing partial refresh in a way that it can be enabled by default, however. When implementing partial refresh support for widgets in the Widget Customizer feature-as-plugin for 3.9, I found that themes had to explicitly opt-in to partial-refreshed widgets because a widget could be inside a sidebar that has a dynamic layout (e.g. jQuery Masonry) or the widget may have JS-driven functionality that has to be re-initialized when updated partial is injected. So partial refresh for widgets was removed from being included in WordPress 3.9, but the functionality has recently been resurrected in the Customize Partial Refresh plugin. More research is needed into how much partial refresh we can have enabled by default, and where we need explicit opt-in.

Call for Feedback

So there’s a lot of exciting possibilities introduced with Customizer transactions. I’d love to hear what you think. I have an working patch written and it exists in a pull request on GitHub. I welcome comments there on the PR. Naturally, the changes would need to be split up into smaller patches for committing to SVN.

Related tickets:

  • #30937: Add Customizer transactions (main ticket)
  • #30028: Load Customizer preview iframe with natural URL
  • #30936: Dynamically create WP_Customize_Settings for settings created on JS client
  • #27355: Customizer: Add framework for partial preview refreshes
  • #20714: Theme customizer: Impossible to preview a search results page
  • #23225: Customizer is Incompatible with jQuery UI Tabs.
  • #28721: Scheduled changes for the customizer
  • #31089: Customizer revisions
  • #31517: Customizer: show a notice after attempting to navigate to external links in live previews

Appendix: Why not just use MySQL transactions?

Something interesting to investigate for the future would if we could take this another (lower) level and actually use MySQL transactions for the Customizer. This would make the Customizer much easier to extend beyond options and theme mods, as the Customizer could just start a MySQL transaction and when a setting is changed, just keep a log of any INSERT/UPDATE/DELETE statement performed during a MySQL transaction. They can then be re-played whenever the preview reloads, and then followed by a COMMIT when the Customizer is saved. These SQL statements can be saved in the wp_transaction post, as opposed to the JSON blob containing the key/value settings data. Or the use of MySQL transactions could go deeper and the SAVEPOINT could be utilized to store the transaction natively in MySQL.

But there are some concerns about using MySQL transactions: first, there’s the question of compatibility and whether MySQL transactions would be available on the wide array of hosting environments where WordPress runs, and what MySQL storage engines are used. Then there’s the question of how conflicts would be resolved when the auto-incremented IDs in the transaction diverge from those outside. And also there’s the concern of storing SQL statements the wp_transaction post’s post_content, and how this might introduce vulnerabilities. Lastly, if we use MySQL transactions as opposed to storing the staged settings in a wp_transaction post, then we’d miss out on being able to inspect the contents of a transaction to see what changes are contained within it.

In any case, using MySQL transactions would be an interesting alternative to the current WP_Customize_Setting abstraction.

#customize, #feature-selective-refresh, #javascript, #json-api, #partial-refresh, #rest-api