* @output wp-admin/js/customize-controls.js
/* global _wpCustomizeHeader, _wpCustomizeBackground, _wpMediaViewsL10n, MediaElementPlayer, console, confirm */
var Container, focus, normalizedTransitionendEventName, api = wp.customize;
api.OverlayNotification = api.Notification.extend(/** @lends wp.customize.OverlayNotification.prototype */{
* Whether the notification should show a loading spinner.
* A notification that is displayed in a full-screen overlay.
* @constructs wp.customize.OverlayNotification
* @augments wp.customize.Notification
* @param {string} code - Code.
* @param {Object} params - Params.
initialize: function( code, params ) {
api.Notification.prototype.initialize.call( notification, code, params );
notification.containerClasses += ' notification-overlay';
if ( notification.loading ) {
notification.containerClasses += ' notification-loading';
* @return {jQuery} Notification container.
var li = api.Notification.prototype.render.call( this );
li.on( 'keydown', _.bind( this.handleEscape, this ) );
* Stop propagation on escape key presses, but also dismiss notification if it is dismissible.
* @param {jQuery.Event} event - Event.
handleEscape: function( event ) {
if ( 27 === event.which ) {
if ( notification.dismissible && notification.parent ) {
notification.parent.remove( notification.code );
api.Notifications = api.Values.extend(/** @lends wp.customize.Notifications.prototype */{
* Whether the alternative style should be used.
* The default constructor for items of the collection.
defaultConstructor: api.Notification,
* A collection of observable notifications.
* @constructs wp.customize.Notifications
* @augments wp.customize.Values
* @param {Object} options - Options.
* @param {jQuery} [options.container] - Container element for notifications. This can be injected later.
* @param {boolean} [options.alt] - Whether alternative style should be used when rendering notifications.
initialize: function( options ) {
api.Values.prototype.initialize.call( collection, options );
_.bindAll( collection, 'constrainFocus' );
// Keep track of the order in which the notifications were added for sorting purposes.
collection._addedIncrement = 0;
collection._addedOrder = {};
// Trigger change event when notification is added or removed.
collection.bind( 'add', function( notification ) {
collection.trigger( 'change', notification );
collection.bind( 'removed', function( notification ) {
collection.trigger( 'change', notification );
* Get the number of notifications added.
* @return {number} Count of notifications.
return _.size( this._value );
* Add notification to the collection.
* @param {string|wp.customize.Notification} notification - Notification object to add. Alternatively code may be supplied, and in that case the second notificationObject argument must be supplied.
* @param {wp.customize.Notification} [notificationObject] - Notification to add when first argument is the code string.
* @return {wp.customize.Notification} Added notification (or existing instance if it was already added).
add: function( notification, notificationObject ) {
var collection = this, code, instance;
if ( 'string' === typeof notification ) {
instance = notificationObject;
code = notification.code;
if ( ! collection.has( code ) ) {
collection._addedIncrement += 1;
collection._addedOrder[ code ] = collection._addedIncrement;
return api.Values.prototype.add.call( collection, code, instance );
* Add notification to the collection.
* @param {string} code - Notification code to remove.
* @return {api.Notification} Added instance (or existing instance if it was already added).
remove: function( code ) {
delete collection._addedOrder[ code ];
return api.Values.prototype.remove.call( this, code );
* Get list of notifications.
* Notifications may be sorted by type followed by added time.
* @param {Object} args - Args.
* @param {boolean} [args.sort=false] - Whether to return the notifications sorted.
* @return {Array.<wp.customize.Notification>} Notifications.
var collection = this, notifications, errorTypePriorities, params;
notifications = _.values( collection._value );
errorTypePriorities = { error: 4, warning: 3, success: 2, info: 1 };
notifications.sort( function( a, b ) {
var aPriority = 0, bPriority = 0;
if ( ! _.isUndefined( errorTypePriorities[ a.type ] ) ) {
aPriority = errorTypePriorities[ a.type ];
if ( ! _.isUndefined( errorTypePriorities[ b.type ] ) ) {
bPriority = errorTypePriorities[ b.type ];
if ( aPriority !== bPriority ) {
return bPriority - aPriority; // Show errors first.
return collection._addedOrder[ b.code ] - collection._addedOrder[ a.code ]; // Show newer notifications higher.
* Render notifications area.
notifications, hadOverlayNotification = false, hasOverlayNotification, overlayNotifications = [],
previousNotificationsByCode = {},
listElement, focusableElements;
// Short-circuit if there are no container to render into.
if ( ! collection.container || ! collection.container.length ) {
notifications = collection.get( { sort: true } );
collection.container.toggle( 0 !== notifications.length );
// Short-circuit if there are no changes to the notifications.
if ( collection.container.is( collection.previousContainer ) && _.isEqual( notifications, collection.previousNotifications ) ) {
// Make sure list is part of the container.
listElement = collection.container.children( 'ul' ).first();
if ( ! listElement.length ) {
listElement = $( '<ul></ul>' );
collection.container.append( listElement );
// Remove all notifications prior to re-rendering.
listElement.find( '> [data-code]' ).remove();
_.each( collection.previousNotifications, function( notification ) {
previousNotificationsByCode[ notification.code ] = notification;
// Add all notifications in the sorted order.
_.each( notifications, function( notification ) {
var notificationContainer;
if ( wp.a11y && ( ! previousNotificationsByCode[ notification.code ] || ! _.isEqual( notification.message, previousNotificationsByCode[ notification.code ].message ) ) ) {
wp.a11y.speak( notification.message, 'assertive' );
notificationContainer = $( notification.render() );
notification.container = notificationContainer;
listElement.append( notificationContainer ); // @todo Consider slideDown() as enhancement.
if ( notification.extended( api.OverlayNotification ) ) {
overlayNotifications.push( notification );
hasOverlayNotification = Boolean( overlayNotifications.length );
if ( collection.previousNotifications ) {
hadOverlayNotification = Boolean( _.find( collection.previousNotifications, function( notification ) {
return notification.extended( api.OverlayNotification );
if ( hasOverlayNotification !== hadOverlayNotification ) {
$( document.body ).toggleClass( 'customize-loading', hasOverlayNotification );
collection.container.toggleClass( 'has-overlay-notifications', hasOverlayNotification );
if ( hasOverlayNotification ) {
collection.previousActiveElement = document.activeElement;
$( document ).on( 'keydown', collection.constrainFocus );
$( document ).off( 'keydown', collection.constrainFocus );
if ( hasOverlayNotification ) {
collection.focusContainer = overlayNotifications[ overlayNotifications.length - 1 ].container;
collection.focusContainer.prop( 'tabIndex', -1 );
focusableElements = collection.focusContainer.find( ':focusable' );
if ( focusableElements.length ) {
focusableElements.first().focus();
collection.focusContainer.focus();
} else if ( collection.previousActiveElement ) {
$( collection.previousActiveElement ).focus();
collection.previousActiveElement = null;
collection.previousNotifications = notifications;
collection.previousContainer = collection.container;
collection.trigger( 'rendered' );
* Constrain focus on focus container.
* @param {jQuery.Event} event - Event.
constrainFocus: function constrainFocus( event ) {
var collection = this, focusableElements;
// Prevent keys from escaping.
if ( 9 !== event.which ) { // Tab key.
focusableElements = collection.focusContainer.find( ':focusable' );
if ( 0 === focusableElements.length ) {
focusableElements = collection.focusContainer;
if ( ! $.contains( collection.focusContainer[0], event.target ) || ! $.contains( collection.focusContainer[0], document.activeElement ) ) {
focusableElements.first().focus();
} else if ( focusableElements.last().is( event.target ) && ! event.shiftKey ) {
focusableElements.first().focus();
} else if ( focusableElements.first().is( event.target ) && event.shiftKey ) {
focusableElements.last().focus();
api.Setting = api.Value.extend(/** @lends wp.customize.Setting.prototype */{
* A setting is WordPress data (theme mod, option, menu, etc.) that the user can
* draft changes to in the Customizer.
* @see PHP class WP_Customize_Setting.
* @constructs wp.customize.Setting
* @augments wp.customize.Value
* @param {string} id - The setting ID.
* @param {*} value - The initial value of the setting.
* @param {Object} [options={}] - Options.
* @param {string} [options.transport=refresh] - The transport to use for previewing. Supports 'refresh' and 'postMessage'.
* @param {boolean} [options.dirty=false] - Whether the setting should be considered initially dirty.
* @param {Object} [options.previewer] - The Previewer instance to sync with. Defaults to wp.customize.previewer.
initialize: function( id, value, options ) {
var setting = this, params;
{ previewer: api.previewer },
api.Value.prototype.initialize.call( setting, value, params );
setting._dirty = params.dirty; // The _dirty property is what the Customizer reads from.
setting.notifications = new api.Notifications();
// Whenever the setting's value changes, refresh the preview.
setting.bind( setting.preview );
* Refresh the preview, respective of the setting's refresh policy.
* If the preview hasn't sent a keep-alive message and is likely
* disconnected by having navigated to a non-allowed URL, then the
* refresh transport will be forced when postMessage is the transport.
* Note that postMessage does not throw an error when the recipient window
* fails to match the origin window, so using try/catch around the
* previewer.send() call to then fallback to refresh will not work.
var setting = this, transport;
transport = setting.transport;
if ( 'postMessage' === transport && ! api.state( 'previewerAlive' ).get() ) {
if ( 'postMessage' === transport ) {
setting.previewer.send( 'setting', [ setting.id, setting() ] );
} else if ( 'refresh' === transport ) {
setting.previewer.refresh();
* Find controls associated with this setting.
* @return {wp.customize.Control[]} Controls associated with setting.
findControls: function() {
var setting = this, controls = [];
api.control.each( function( control ) {
_.each( control.settings, function( controlSetting ) {
if ( controlSetting.id === setting.id ) {
controls.push( control );
* @alias wp.customize._latestRevision
* Last revision that was saved.
* @alias wp.customize._lastSavedRevision
api._lastSavedRevision = 0;
* Latest revisions associated with the updated setting.
* @alias wp.customize._latestSettingRevisions
api._latestSettingRevisions = {};
* Keep track of the revision associated with each updated setting so that
* requestChangesetUpdate knows which dirty settings to include. Also, once
* ready is triggered and all initial settings have been added, increment
* revision for each newly-created initially-dirty setting so that it will
* also be included in changeset update requests.
api.bind( 'change', function incrementChangedSettingRevision( setting ) {
api._latestRevision += 1;
api._latestSettingRevisions[ setting.id ] = api._latestRevision;
api.bind( 'ready', function() {
api.bind( 'add', function incrementCreatedSettingRevision( setting ) {
api._latestRevision += 1;
api._latestSettingRevisions[ setting.id ] = api._latestRevision;
* Get the dirty setting values.
* @alias wp.customize.dirtyValues
* @param {Object} [options] Options.
* @param {boolean} [options.unsaved=false] Whether only values not saved yet into a changeset will be returned (differential changes).
* @return {Object} Dirty setting values.