Navigating to a URL in the Customizer Preview when a Section is Expanded

On Otto’s What’s new with the Customizer post there’s a long-running comments thread in which a good question was raised by Jascha:

with the active callback you can show a section or panel depending on the URL you are looking at. But is it possible the other way around? Showing a different URL depending on the section you have currently selected. Have been searching for hours for a way to do it. I know that you can change the previewURL with wp.customize.previewer.previewUrl but I wasn’t able to find how to bind this to the currently selected section/panel.

The code required to do it is pretty straightforward. Here’s a useful example where the preview URL is changed to the homepage when you expand the “Static Front Page” section:

(function ( api ) {
	api.section( 'static_front_page', function( section ) {
		section.expanded.bind( function( isExpanded ) {
			var url;
			if ( isExpanded ) {
				url = api.settings.url.home;
				api.previewer.previewUrl.set( url );
			}
		} );
	} );
} ( wp.customize ) );

(This could be an alternate implementation for what was done in #30677.) Here’s a breakdown for what is happening in this code snippet:

1. Wrap code in an IIFE (optional):
   (function ( api ) { … } ( wp.customize ) );
2. Register a deferred callback to run when the Static Front Page section exists:
   api.section( 'static_front_page', function( section ) { … } );
3. Register a listener for when the section’s expanded state changes:
   section.expanded.bind( function( isExpanded ) { … } );
4. Set the preview URL to the homepage when expanded state is true:
   if ( isExpanded ) { api.previewer.previewUrl.set( api.settings.url.home ); }

This JS should be enqueued in the customize_controls_enqueue_scripts action with customize-controls as its dependency.

This concept of navigating to a URL in the preview when a section is expanded is something we’ve been exploring in the Customize Posts plugin as well. In Customize Posts, each post type gets its own panel, and these panels contain sections that correspond to posts of that type (i.e. pages or posts of any given custom post type); the post sections are added dynamically to the panel when posts are present in the preview. When you create a new post in the Customizer via the post type panel’s “Add New Post” button it creates a new auto-draft post; it then creates a Customizer section for it, expands the section, and then the post preview URL is navigated to in the preview so that you can see changes to the post as you fill out its fields. See relevant code.

In addition to dynamically (passively) adding and showing Customizer sections for posts that currently appear in the preview, we’re also exploring a way for Customize Posts to allow you to be more assertive about accessing the desired post. In a recent pull request there is a new Select2 dropdown that allows you to search through all posts of a given type, and then upon selection, add a Customizer section for that post (if it hasn’t already been added), and then both expand the section and navigate to the preview URL for that post in the Customizer preview if the post is not currently visible in the preview (and if the post type itself is public). See relevant code.

In summary, contextual Customizer panels and sections were added in #29758. This allowed you to add an active_callback to toggle the visibility of a panel or section based on the URL being previewed. If you had a Customizer section for managing the settings for a given area of your site, this would require that you first navigate to that area of the site in order for the section to be displayed. This isn’t optimal for discoverability in the Customizer, and so it seems useful to sometimes switch things around: always have the section visible (no active_callback) and then when that section is expanded automatically navigate to the relevant area of the site in the preview.

Addendum: Return Preview to Previous URL upon Section Collapse

Something else which may be useful beyond navigating to a URL when a section expands is to also return to the previous URL when that section collapses, as Andrew Taylor commented below. Doing this is straightforward as we just have to keep track of the preview URL before it was changed, and then restore the preview URL to this previous URL when the section is collapsed. As a further refinement, we can prevent this preview URL restoration if the user further navigates after the section is expanded, as it might be unexpected for the preview URL to change back in this case. Note that with #28536 (Add browser history and deep linking for navigation in Customizer preview) this may eventually be able to be simplified to doing history.back(). Here is amended code sample to restore the previous URL upon section collapse:

(function ( api ) {
	api.section( 'static_front_page', function( section ) {
		var previousUrl, clearPreviousUrl, previewUrlValue;
		previewUrlValue = api.previewer.previewUrl;
		clearPreviousUrl = function() {
			previousUrl = null;
		};

		section.expanded.bind( function( isExpanded ) {
			var url;
			if ( isExpanded ) {
				url = api.settings.url.home;
				previousUrl = previewUrlValue.get();
				previewUrlValue.set( url );
				previewUrlValue.bind( clearPreviousUrl );
			} else {
				previewUrlValue.unbind( clearPreviousUrl );
				if ( previousUrl ) {
					previewUrlValue.set( previousUrl );
				}
			}
		} );
	} );
} ( wp.customize ) );