Set/Get the current URL in the Theme Customizer

[TJNowell]

When opening the theme customiser, the url query parameter sets the page shown in the preview pane, however a user can navigate away by clicking links in the preview pane.

This is fine for global background colours, but becomes a problem if you try to do anything contextual with the customiser controls.

It would be useful to also set this URL. For example, if I have a control that configures the layout of the category archive, it would make sense to provide a means to navigate to a category archive automatically.

I would suggest this be done using PostMessage, and be implemented in the preview, so that calls like this:

api.instance('my_control').previewer.refresh();

could be used like this:

api.instance('my_theme_options[footer_image]').previewer.getURL();

[westonruter]

I think what is being requested here is actually already possible. In the context of a control, you can access the preview's current URL and update the preview's URL via the associated setting, and the setting's previewer value:

wp.customize.controlConstructor.foo = wp.customize.Control.extend( {
	ready: function() {
		var url, control = this;

		// Example: get the current URL
		url = control.getPreviewUrl();
		
		// Example: set URL of preview to homepage
		control.setPreviewUrl( location.protocol + '//' + location.host );
	},

	getPreviewUrl: function () {
		return this.setting.previewer.previewUrl();
	},

	setPreviewUrl: function ( url ) {
		this.setting.previewer.previewUrl( url );
	}
} );

[westonruter]

However, something that is currently not good in the Customizer is that the Previewer instance is stored in a variable contained within a closure. It gets exported when each setting is constructed, but outside the context of the settings the variable is not available (customize-controls.js):

$( function() {
    // ...
    previewer = new api.Previewer({ /* ... */ })

In the Widget Customizer, this has necessitated doing something ugly in customize-widgets.js:

	/**
	 * Capture the instance of the Previewer since it is private
	 */
	OldPreviewer = api.Previewer;
	api.Previewer = OldPreviewer.extend({
		initialize: function( params, options ) {
			api.Widgets.Previewer = this;
			OldPreviewer.prototype.initialize.call( this, params, options );
			this.bind( 'refresh', this.refresh );
		}
	} );

This then allows the Widget Customizer to access the Previewer instance irrespective outside the context of any settings.

Ideally, the instance of the previewer would be exported as a property of wp.customize, e.g. wp.cutomize.previewer. This would then allow any JS in the Customizer to directly access the URL of the current preview via:

url = wp.customize.previewer.previewUrl();

And to set it via:

wp.customize.previewer.previewUrl( url );

[westonruter]

Export Previewer instance to wp.customize.previewer, and utilize for Widget Customizer. Commits also pushed to GitHub: ​https://github.com/x-team/wordpress-develop/pull/15

[westonruter]

On a related note, I submitted #28536 and supplied a patch which adds browser history and deep linking for navigation in Customizer preview.

[SergeyBiryukov]

In 29048:

Customizer: Export Previewer instance to wp.customize.previewer, and utilize for Widget Customizer.

props westonruter.
fixes #27666.