* @output wp-includes/js/customize-selective-refresh.js
/* global jQuery, JSON, _customizePartialRefreshExports, console */
/** @namespace wp.customize.selectiveRefresh */
wp.customize.selectiveRefresh = ( function( $, api ) {
var self, Partial, Placement;
editShortcutVisibility: new api.Value(),
_.extend( self, api.Events );
* A partial provides a rendering of one or more settings according to a template.
* @memberOf wp.customize.selectiveRefresh
* @see PHP class WP_Customize_Partial.
* @augments wp.customize.Class
Partial = self.Partial = api.Class.extend(/** @lends wp.customize.SelectiveRefresh.Partial.prototype */{
containerInclusive: false,
fallbackRefresh: true // Note this needs to be false in a front-end editing context.
* @param {string} id - Unique identifier for the partial instance.
* @param {Object} options - Options hash for the partial instance.
* @param {string} options.type - Type of partial (e.g. nav_menu, widget, etc)
* @param {string} options.selector - jQuery selector to find the container element in the page.
* @param {Array} options.settings - The IDs for the settings the partial relates to.
* @param {string} options.primarySetting - The ID for the primary setting the partial renders.
* @param {boolean} options.fallbackRefresh - Whether to refresh the entire preview in case of a partial refresh failure.
* @param {Object} [options.params] - Deprecated wrapper for the above properties.
initialize: function( id, options ) {
partial.params = _.extend(
options.params || options
partial.deferred.ready = $.Deferred();
partial.deferred.ready.done( function() {
_.each( partial.placements(), function( placement ) {
$( placement.container ).attr( 'title', self.data.l10n.shiftClickToEdit );
partial.createEditShortcutForPlacement( placement );
$( document ).on( 'click', partial.params.selector, function( e ) {
_.each( partial.placements(), function( placement ) {
if ( $( placement.container ).is( e.currentTarget ) ) {
* Create and show the edit shortcut for a given partial placement container.
* @param {Placement} placement The placement container element.
createEditShortcutForPlacement: function( placement ) {
var partial = this, $shortcut, $placementContainer, illegalAncestorSelector, illegalContainerSelector;
if ( ! placement.container ) {
$placementContainer = $( placement.container );
illegalAncestorSelector = 'head';
illegalContainerSelector = 'area, audio, base, bdi, bdo, br, button, canvas, col, colgroup, command, datalist, embed, head, hr, html, iframe, img, input, keygen, label, link, map, math, menu, meta, noscript, object, optgroup, option, param, progress, rp, rt, ruby, script, select, source, style, svg, table, tbody, textarea, tfoot, thead, title, tr, track, video, wbr';
if ( ! $placementContainer.length || $placementContainer.is( illegalContainerSelector ) || $placementContainer.closest( illegalAncestorSelector ).length ) {
$shortcut = partial.createEditShortcut();
$shortcut.on( 'click', function( event ) {
partial.addEditShortcutToPlacement( placement, $shortcut );
* Add an edit shortcut to the placement container.
* @param {Placement} placement The placement for the partial.
* @param {jQuery} $editShortcut The shortcut element as a jQuery object.
addEditShortcutToPlacement: function( placement, $editShortcut ) {
var $placementContainer = $( placement.container );
$placementContainer.prepend( $editShortcut );
if ( ! $placementContainer.is( ':visible' ) || 'none' === $placementContainer.css( 'display' ) ) {
$editShortcut.addClass( 'customize-partial-edit-shortcut-hidden' );
* Return the unique class name for the edit shortcut button for this partial.
* @return {string} Partial ID converted into a class name for use in shortcut.
getEditShortcutClassName: function() {
var partial = this, cleanId;
cleanId = partial.id.replace( /]/g, '' ).replace( /\[/g, '-' );
return 'customize-partial-edit-shortcut-' + cleanId;
* Return the appropriate translated string for the edit shortcut button.
* @return {string} Tooltip for edit shortcut.
getEditShortcutTitle: function() {
var partial = this, l10n = self.data.l10n;
switch ( partial.getType() ) {
return l10n.clickEditWidget;
return l10n.clickEditTitle;
return l10n.clickEditTitle;
return l10n.clickEditMenu;
return l10n.clickEditMisc;
* Return the type of this partial
* Will use `params.type` if set, but otherwise will try to infer type from settingId.
* @return {string} Type of partial derived from type param or the related setting ID.
var partial = this, settingId;
settingId = partial.params.primarySetting || _.first( partial.settings() ) || 'unknown';
if ( partial.params.type ) {
return partial.params.type;
if ( settingId.match( /^nav_menu_instance\[/ ) ) {
if ( settingId.match( /^widget_.+\[\d+]$/ ) ) {
* Create an edit shortcut button for this partial.
* @return {jQuery} The edit shortcut button element.
createEditShortcut: function() {
var partial = this, shortcutTitle, $buttonContainer, $button, $image;
shortcutTitle = partial.getEditShortcutTitle();
$buttonContainer = $( '<span>', {
'class': 'customize-partial-edit-shortcut ' + partial.getEditShortcutClassName()
$button = $( '<button>', {
'aria-label': shortcutTitle,
'class': 'customize-partial-edit-shortcut-button'
$image = $( '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M13.89 3.39l2.71 2.72c.46.46.42 1.24.03 1.64l-8.01 8.02-5.56 1.16 1.16-5.58s7.6-7.63 7.99-8.03c.39-.39 1.22-.39 1.68.07zm-2.73 2.79l-5.59 5.61 1.11 1.11 5.54-5.65zm-2.97 8.23l5.58-5.6-1.07-1.08-5.59 5.6z"/></svg>' );
$button.append( $image );
$buttonContainer.append( $button );
* Find all placements for this partial in the document.
* @return {Array.<Placement>}
var partial = this, selector;
selector = partial.params.selector || '';
selector += '[data-customize-partial-id="' + partial.id + '"]'; // @todo Consider injecting customize-partial-id-${id} classnames instead.
return $( selector ).map( function() {
var container = $( this ), context;
context = container.data( 'customize-partial-placement-context' );
if ( _.isString( context ) && '{' === context.substr( 0, 1 ) ) {
throw new Error( 'context JSON parse error' );
* Get list of setting IDs related to this partial.
if ( partial.params.settings && 0 !== partial.params.settings.length ) {
return partial.params.settings;
} else if ( partial.params.primarySetting ) {
return [ partial.params.primarySetting ];
* Return whether the setting is related to the partial.
* @param {wp.customize.Value|string} setting ID or object for setting.
* @return {boolean} Whether the setting is related to the partial.
isRelatedSetting: function( setting /*... newValue, oldValue */ ) {
if ( _.isString( setting ) ) {
setting = api( setting );
return -1 !== _.indexOf( partial.settings(), setting.id );
* Show the control to modify this partial's setting(s).
* This may be overridden for inline editing.
showControl: function() {
var partial = this, settingId = partial.params.primarySetting;
settingId = _.first( partial.settings() );
if ( partial.getType() === 'nav_menu' ) {
if ( partial.params.navMenuArgs.theme_location ) {
settingId = 'nav_menu_locations[' + partial.params.navMenuArgs.theme_location + ']';
} else if ( partial.params.navMenuArgs.menu ) {
settingId = 'nav_menu[' + String( partial.params.navMenuArgs.menu ) + ']';
api.preview.send( 'focus-control-for-setting', settingId );
* Prepare container for selective refresh.
* @param {Placement} placement
preparePlacement: function( placement ) {
$( placement.container ).addClass( 'customize-partial-refreshing' );
* Reference to the pending promise returned from self.requestPartial().
_pendingRefreshPromise: null,
* Request the new partial and render it into the placements.
* @this {wp.customize.selectiveRefresh.Partial}
* @return {jQuery.Promise}
var partial = this, refreshPromise;
refreshPromise = self.requestPartial( partial );
if ( ! partial._pendingRefreshPromise ) {
_.each( partial.placements(), function( placement ) {
partial.preparePlacement( placement );
refreshPromise.done( function( placements ) {
_.each( placements, function( placement ) {
partial.renderContent( placement );
refreshPromise.fail( function( data, placements ) {
partial.fallback( data, placements );
// Allow new request when this one finishes.
partial._pendingRefreshPromise = refreshPromise;
refreshPromise.always( function() {
partial._pendingRefreshPromise = null;
* Apply the addedContent in the placement to the document.
* Note the placement object will have its container and removedNodes
* @param {Placement} placement
* @param {Element|jQuery} [placement.container] - This param will be empty if there was no element matching the selector.
* @param {string|Object|boolean} placement.addedContent - Rendered HTML content, a data object for JS templates to render, or false if no render.
* @param {Object} [placement.context] - Optional context information about the container.
* @return {boolean} Whether the rendering was successful and the fallback was not invoked.
renderContent: function( placement ) {
var partial = this, content, newContainerElement;
if ( ! placement.container ) {
partial.fallback( new Error( 'no_container' ), [ placement ] );
placement.container = $( placement.container );
if ( false === placement.addedContent ) {
partial.fallback( new Error( 'missing_render' ), [ placement ] );
// Currently a subclass needs to override renderContent to handle partials returning data object.
if ( ! _.isString( placement.addedContent ) ) {
partial.fallback( new Error( 'non_string_content' ), [ placement ] );
/* jshint ignore:start */
self.orginalDocumentWrite = document.write;
document.write = function() {
throw new Error( self.data.l10n.badDocumentWrite );
content = placement.addedContent;
if ( wp.emoji && wp.emoji.parse && ! $.contains( document.head, placement.container[0] ) ) {
content = wp.emoji.parse( content );
if ( partial.params.containerInclusive ) {
// Note that content may be an empty string, and in this case jQuery will just remove the oldContainer.
newContainerElement = $( content );
// Merge the new context on top of the old context.
placement.context = _.extend(
newContainerElement.data( 'customize-partial-placement-context' ) || {}
newContainerElement.data( 'customize-partial-placement-context', placement.context );
placement.removedNodes = placement.container;
placement.container = newContainerElement;
placement.removedNodes.replaceWith( placement.container );
placement.container.attr( 'title', self.data.l10n.shiftClickToEdit );
placement.removedNodes = document.createDocumentFragment();
while ( placement.container[0].firstChild ) {
placement.removedNodes.appendChild( placement.container[0].firstChild );
placement.container.html( content );
placement.container.removeClass( 'customize-render-content-error' );
if ( 'undefined' !== typeof console && console.error ) {
console.error( partial.id, error );
partial.fallback( error, [ placement ] );
/* jshint ignore:start */
document.write = self.orginalDocumentWrite;
self.orginalDocumentWrite = null;
partial.createEditShortcutForPlacement( placement );
placement.container.removeClass( 'customize-partial-refreshing' );
// Prevent placement container from being re-triggered as being rendered among nested partials.
placement.container.data( 'customize-partial-content-rendered', true );
* Note that the 'wp_audio_shortcode_library' and 'wp_video_shortcode_library' filters
* will determine whether or not wp.mediaelement is loaded and whether it will
* initialize audio and video respectively. See also https://core.trac.wordpress.org/ticket/40144
wp.mediaelement.initialize();
wp.playlist.initialize();
* Announce when a partial's placement has been rendered so that dynamic elements can be re-built.