--- a/wp/wp-admin/js/customize-controls.js Tue Oct 22 16:11:46 2019 +0200
+++ b/wp/wp-admin/js/customize-controls.js Tue Dec 15 13:49:49 2020 +0100
@@ -25,7 +25,7 @@
* @since 4.9.0
*
* @param {string} code - Code.
- * @param {object} params - Params.
+ * @param {Object} params - Params.
*/
initialize: function( code, params ) {
var notification = this;
@@ -55,7 +55,7 @@
* @since 4.9.0
*
* @param {jQuery.Event} event - Event.
- * @returns {void}
+ * @return {void}
*/
handleEscape: function( event ) {
var notification = this;
@@ -94,11 +94,11 @@
* @constructs wp.customize.Notifications
* @augments wp.customize.Values
*
- * @param {object} options - Options.
+ * @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.
*
- * @returns {void}
+ * @return {void}
*/
initialize: function( options ) {
var collection = this;
@@ -137,7 +137,7 @@
*
* @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.
- * @returns {wp.customize.Notification} Added notification (or existing instance if it was already added).
+ * @return {wp.customize.Notification} Added notification (or existing instance if it was already added).
*/
add: function( notification, notificationObject ) {
var collection = this, code, instance;
@@ -174,7 +174,7 @@
* Notifications may be sorted by type followed by added time.
*
* @since 4.9.0
- * @param {object} args - Args.
+ * @param {Object} args - Args.
* @param {boolean} [args.sort=false] - Whether to return the notifications sorted.
* @return {Array.<wp.customize.Notification>} Notifications.
*/
@@ -211,7 +211,7 @@
* Render notifications area.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
render: function() {
var collection = this,
@@ -304,7 +304,7 @@
* @since 4.9.0
*
* @param {jQuery.Event} event - Event.
- * @returns {void}
+ * @return {void}
*/
constrainFocus: function constrainFocus( event ) {
var collection = this, focusableElements;
@@ -362,10 +362,10 @@
*
* @param {string} id - The setting ID.
* @param {*} value - The initial value of the setting.
- * @param {object} [options={}] - Options.
+ * @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.
+ * @param {Object} [options.previewer] - The Previewer instance to sync with. Defaults to wp.customize.previewer.
*/
initialize: function( id, value, options ) {
var setting = this, params;
@@ -398,7 +398,7 @@
* @since 3.4.0
* @access public
*
- * @returns {void}
+ * @return {void}
*/
preview: function() {
var setting = this, transport;
@@ -419,7 +419,7 @@
* Find controls associated with this setting.
*
* @since 4.6.0
- * @returns {wp.customize.Control[]} Controls associated with setting.
+ * @return {wp.customize.Control[]} Controls associated with setting.
*/
findControls: function() {
var setting = this, controls = [];
@@ -495,9 +495,9 @@
* @since 4.7.0
* @access public
*
- * @param {object} [options] Options.
+ * @param {Object} [options] Options.
* @param {boolean} [options.unsaved=false] Whether only values not saved yet into a changeset will be returned (differential changes).
- * @returns {object} Dirty setting values.
+ * @return {Object} Dirty setting values.
*/
api.dirtyValues = function dirtyValues( options ) {
var values = {};
@@ -528,14 +528,14 @@
* @since 4.7.0
* @access public
*
- * @param {object} [changes] - Mapping of setting IDs to setting params each normally including a value property, or mapping to null.
+ * @param {Object} [changes] - Mapping of setting IDs to setting params each normally including a value property, or mapping to null.
* If not provided, then the changes will still be obtained from unsaved dirty settings.
- * @param {object} [args] - Additional options for the save request.
+ * @param {Object} [args] - Additional options for the save request.
* @param {boolean} [args.autosave=false] - Whether changes will be stored in autosave revision if the changeset has been promoted from an auto-draft.
* @param {boolean} [args.force=false] - Send request to update even when there are no changes to submit. This can be used to request the latest status of the changeset on the server.
* @param {string} [args.title] - Title to update in the changeset. Optional.
* @param {string} [args.date] - Date to update in the changeset. Optional.
- * @returns {jQuery.Promise} Promise resolving with the response data.
+ * @return {jQuery.Promise} Promise resolving with the response data.
*/
api.requestChangesetUpdate = function requestChangesetUpdate( changes, args ) {
var deferred, request, submittedChanges = {}, data, submittedArgs;
@@ -578,7 +578,8 @@
return deferred.promise();
}
- // A status would cause a revision to be made, and for this wp.customize.previewer.save() should be used. Status is also disallowed for revisions regardless.
+ // A status would cause a revision to be made, and for this wp.customize.previewer.save() should be used.
+ // Status is also disallowed for revisions regardless.
if ( submittedArgs.status ) {
return deferred.reject( { code: 'illegal_status_in_changeset_update' } ).promise();
}
@@ -735,7 +736,7 @@
*
* @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} a
* @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} b
- * @returns {Number}
+ * @return {number}
*/
api.utils.prioritySort = function ( a, b ) {
if ( a.priority() === b.priority() && typeof a.params.instanceNumber === 'number' && typeof b.params.instanceNumber === 'number' ) {
@@ -753,7 +754,7 @@
* @since 4.1.0
*
* @param {jQuery.Event} event
- * @returns {boolean}
+ * @return {boolean}
*/
api.utils.isKeydownButNotEnterEvent = function ( event ) {
return ( 'keydown' === event.type && 13 !== event.which );
@@ -768,17 +769,17 @@
*
* @param {Array|jQuery} listA
* @param {Array|jQuery} listB
- * @returns {boolean}
+ * @return {boolean}
*/
api.utils.areElementListsEqual = function ( listA, listB ) {
var equal = (
- listA.length === listB.length && // if lists are different lengths, then naturally they are not equal
- -1 === _.indexOf( _.map( // are there any false values in the list returned by map?
- _.zip( listA, listB ), // pair up each element between the two lists
+ listA.length === listB.length && // If lists are different lengths, then naturally they are not equal.
+ -1 === _.indexOf( _.map( // Are there any false values in the list returned by map?
+ _.zip( listA, listB ), // Pair up each element between the two lists.
function ( pair ) {
- return $( pair[0] ).is( pair[1] ); // compare to see if each pair are equal
- }
- ), false ) // check for presence of false in map's return value
+ return $( pair[0] ).is( pair[1] ); // Compare to see if each pair is equal.
+ }
+ ), false ) // Check for presence of false in map's return value.
);
return equal;
};
@@ -795,14 +796,14 @@
* @since 4.9.0
*
* @param {jQuery} button - The element to highlight.
- * @param {object} [options] - Options.
+ * @param {Object} [options] - Options.
* @param {number} [options.delay=0] - Delay in milliseconds.
* @param {jQuery} [options.focusTarget] - A target for user focus that defaults to the highlighted element.
* If the user focuses the target before the delay passes, the reminder
* is canceled. This option exists to accommodate compound buttons
* containing auxiliary UI, such as the Publish button augmented with a
* Settings button.
- * @returns {Function} An idempotent function that cancels the reminder.
+ * @return {Function} An idempotent function that cancels the reminder.
*/
api.utils.highlightButton = function highlightButton( button, options ) {
var animationClass = 'button-see-me',
@@ -849,7 +850,7 @@
*
* @since 4.9.0
*
- * @returns {int} Current timestamp.
+ * @return {number} Current timestamp.
*/
api.utils.getCurrentTimestamp = function getCurrentTimestamp() {
var currentDate, currentClientTimestamp, timestampDifferential;
@@ -868,8 +869,8 @@
*
* @since 4.9.0
*
- * @param {string|int|Date} datetime - Date time or timestamp of the future date.
- * @return {int} remainingTime - Remaining time in milliseconds.
+ * @param {string|number|Date} datetime - Date time or timestamp of the future date.
+ * @return {number} remainingTime - Remaining time in milliseconds.
*/
api.utils.getRemainingTime = function getRemainingTime( datetime ) {
var millisecondsDivider = 1000, remainingTime, timestamp;
@@ -893,7 +894,7 @@
*
* @ignore
*
- * @returns {string|null} Normalized `transitionend` event name or null if CSS transitions are not supported.
+ * @return {string|null} Normalized `transitionend` event name or null if CSS transitions are not supported.
*/
normalizedTransitionendEventName = (function () {
var el, transitions, prop;
@@ -939,7 +940,7 @@
* @borrows wp.customize~focus as focus
*
* @param {string} id - The ID for the container.
- * @param {object} options - Object containing one property: params.
+ * @param {Object} options - Object containing one property: params.
* @param {string} options.title - Title shown when panel is collapsed and expanded.
* @param {string} [options.description] - Description shown at the top of the panel.
* @param {number} [options.priority=100] - The sort priority for the panel.
@@ -947,7 +948,7 @@
* @param {string} [options.type=default] - The type of the panel. See wp.customize.panelConstructor.
* @param {string} [options.content] - The markup to be used for the panel container. If empty, a JS template is used.
* @param {boolean} [options.active=true] - Whether the panel is active or not.
- * @param {object} [options.params] - Deprecated wrapper for the above properties.
+ * @param {Object} [options.params] - Deprecated wrapper for the above properties.
*/
initialize: function ( id, options ) {
var container = this;
@@ -1014,7 +1015,7 @@
* Get the element that will contain the notifications.
*
* @since 4.9.0
- * @returns {jQuery} Notification container element.
+ * @return {jQuery} Notification container element.
*/
getNotificationsContainerElement: function() {
var container = this;
@@ -1025,7 +1026,7 @@
* Set up notifications.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
setupNotifications: function() {
var container = this, renderNotifications;
@@ -1054,9 +1055,9 @@
*
* @since 4.1.0
*
- * @param {String} parentType
- * @param {String} childType
- * @returns {Array}
+ * @param {string} parentType
+ * @param {string} childType
+ * @return {Array}
*/
_children: function ( parentType, childType ) {
var parent = this,
@@ -1128,7 +1129,8 @@
}
if ( ! $.contains( document, headContainer.get( 0 ) ) ) {
- // If the element is not in the DOM, then jQuery.fn.slideUp() does nothing. In this case, a hard toggle is required instead.
+ // If the element is not in the DOM, then jQuery.fn.slideUp() does nothing.
+ // In this case, a hard toggle is required instead.
headContainer.toggle( active );
if ( args.completeCallback ) {
args.completeCallback();
@@ -1152,9 +1154,9 @@
/**
* @since 4.1.0
*
- * @params {Boolean} active
- * @param {Object} [params]
- * @returns {Boolean} false if state already applied
+ * @param {boolean} active
+ * @param {Object} [params]
+ * @return {boolean} False if state already applied.
*/
_toggleActive: function ( active, params ) {
var self = this;
@@ -1173,7 +1175,7 @@
/**
* @param {Object} [params]
- * @returns {Boolean} false if already active
+ * @return {boolean} False if already active.
*/
activate: function ( params ) {
return this._toggleActive( true, params );
@@ -1181,7 +1183,7 @@
/**
* @param {Object} [params]
- * @returns {Boolean} false if already inactive
+ * @return {boolean} False if already inactive.
*/
deactivate: function ( params ) {
return this._toggleActive( false, params );
@@ -1198,10 +1200,10 @@
/**
* Handle the toggle logic for expand/collapse.
*
- * @param {Boolean} expanded - The new state to apply.
+ * @param {boolean} expanded - The new state to apply.
* @param {Object} [params] - Object containing options for expand/collapse.
* @param {Function} [params.completeCallback] - Function to call when expansion/collapse is complete.
- * @returns {Boolean} false if state already applied or active state is false
+ * @return {boolean} False if state already applied or active state is false.
*/
_toggleExpanded: function( expanded, params ) {
var instance = this, previousCompleteCallback;
@@ -1238,7 +1240,7 @@
/**
* @param {Object} [params]
- * @returns {Boolean} false if already expanded or if inactive.
+ * @return {boolean} False if already expanded or if inactive.
*/
expand: function ( params ) {
return this._toggleExpanded( true, params );
@@ -1246,7 +1248,7 @@
/**
* @param {Object} [params]
- * @returns {Boolean} false if already collapsed.
+ * @return {boolean} False if already collapsed.
*/
collapse: function ( params ) {
return this._toggleExpanded( false, params );
@@ -1259,7 +1261,7 @@
* @private
*
* @param {function} completeCallback Function to be called after transition is completed.
- * @returns {void}
+ * @return {void}
*/
_animateChangeExpanded: function( completeCallback ) {
// Return if CSS transitions are not supported.
@@ -1362,7 +1364,7 @@
* @since 4.7.0
* @access public
*
- * @returns {jQuery} Detached content element.
+ * @return {jQuery} Detached content element.
*/
getContent: function() {
var construct = this,
@@ -1407,7 +1409,7 @@
* @since 4.1.0
*
* @param {string} id - The ID for the section.
- * @param {object} options - Options.
+ * @param {Object} options - Options.
* @param {string} options.title - Title shown when section is collapsed and expanded.
* @param {string} [options.description] - Description shown at the top of the section.
* @param {number} [options.priority=100] - The sort priority for the section.
@@ -1416,7 +1418,7 @@
* @param {boolean} [options.active=true] - Whether the section is active or not.
* @param {string} options.panel - The ID for the panel this section is associated with.
* @param {string} [options.customizeAction] - Additional context information shown before the section title when expanded.
- * @param {object} [options.params] - Deprecated wrapper for the above properties.
+ * @param {Object} [options.params] - Deprecated wrapper for the above properties.
*/
initialize: function ( id, options ) {
var section = this, params;
@@ -1479,7 +1481,7 @@
});
} );
} else {
- // There is no panel, so embed the section in the root of the customizer
+ // There is no panel, so embed the section in the root of the customizer.
parentContainer = api.ensure( section.containerPaneParent );
if ( ! section.headContainer.parent().is( parentContainer ) ) {
parentContainer.append( section.headContainer );
@@ -1511,7 +1513,7 @@
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
return;
}
- event.preventDefault(); // Keep this AFTER the key filter above
+ event.preventDefault(); // Keep this AFTER the key filter above.
if ( section.expanded() ) {
section.collapse();
@@ -1543,7 +1545,7 @@
*
* @since 4.1.0
*
- * @returns {Boolean}
+ * @return {boolean}
*/
isContextuallyActive: function () {
var section = this,
@@ -1562,7 +1564,7 @@
*
* @since 4.1.0
*
- * @returns {Array}
+ * @return {Array}
*/
controls: function () {
return this._children( 'section', 'control' );
@@ -1573,7 +1575,7 @@
*
* @since 4.1.0
*
- * @param {Boolean} expanded
+ * @param {boolean} expanded
* @param {Object} args
*/
onChangeExpanded: function ( expanded, args ) {
@@ -1695,8 +1697,8 @@
* @since 4.9.0
*
* @param {string} id - ID.
- * @param {object} options - Options.
- * @returns {void}
+ * @param {Object} options - Options.
+ * @return {void}
*/
initialize: function( id, options ) {
var section = this;
@@ -1718,12 +1720,12 @@
var inject,
section = this;
- // Watch for changes to the panel state
+ // Watch for changes to the panel state.
inject = function( panelId ) {
var parentContainer;
api.panel( panelId, function( panel ) {
- // The panel has been registered, wait for it to become ready/initialized
+ // The panel has been registered, wait for it to become ready/initialized.
panel.deferred.embedded.done( function() {
parentContainer = panel.contentContainer;
if ( ! section.headContainer.parent().is( parentContainer ) ) {
@@ -1737,7 +1739,7 @@
} );
};
section.panel.bind( inject );
- inject( section.panel.get() ); // Since a section may never get a panel, assume that it won't ever get one
+ inject( section.panel.get() ); // Since a section may never get a panel, assume that it won't ever get one.
},
/**
@@ -1745,7 +1747,7 @@
*
* @since 4.2.0
*
- * @returns {void}
+ * @return {void}
*/
ready: function() {
var section = this;
@@ -1758,17 +1760,17 @@
return;
}
- // Pressing the right arrow key fires a theme:next event
+ // Pressing the right arrow key fires a theme:next event.
if ( 39 === event.keyCode ) {
section.nextTheme();
}
- // Pressing the left arrow key fires a theme:previous event
+ // Pressing the left arrow key fires a theme:previous event.
if ( 37 === event.keyCode ) {
section.previousTheme();
}
- // Pressing the escape key fires a theme:collapse event
+ // Pressing the escape key fires a theme:collapse event.
if ( 27 === event.keyCode ) {
if ( section.$body.hasClass( 'modal-open' ) ) {
@@ -1797,7 +1799,7 @@
*
* @since 4.2.0
*
- * @returns {Boolean}
+ * @return {boolean}
*/
isContextuallyActive: function () {
return this.active();
@@ -1808,7 +1810,7 @@
*
* @since 4.2.0
*
- * @returns {void}
+ * @return {void}
*/
attachEvents: function () {
var section = this, debounced;
@@ -1818,7 +1820,7 @@
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
return;
}
- event.preventDefault(); // Keep this AFTER the key filter above
+ event.preventDefault(); // Keep this AFTER the key filter above.
section.collapse();
});
@@ -1949,19 +1951,19 @@
*
* @since 4.2.0
*
- * @param {Boolean} expanded
+ * @param {boolean} expanded
* @param {Object} args
- * @param {Boolean} args.unchanged
+ * @param {boolean} args.unchanged
* @param {Function} args.completeCallback
- * @returns {void}
+ * @return {void}
*/
onChangeExpanded: function ( expanded, args ) {
- // Note: there is a second argument 'args' passed
+ // Note: there is a second argument 'args' passed.
var section = this,
container = section.contentContainer.closest( '.customize-themes-full-container' );
- // Immediately call the complete callback if there were no changes
+ // Immediately call the complete callback if there were no changes.
if ( args.unchanged ) {
if ( args.completeCallback ) {
args.completeCallback();
@@ -1976,7 +1978,7 @@
section.loadThemes();
}
- // Collapse any sibling sections/panels
+ // Collapse any sibling sections/panels.
api.section.each( function ( otherSection ) {
var searchTerm;
@@ -2043,7 +2045,7 @@
*
* @since 4.9.0
*
- * @returns {jQuery}
+ * @return {jQuery}
*/
getContent: function() {
return this.container.find( '.control-section-content' );
@@ -2054,7 +2056,7 @@
*
* @since 4.9.0
*
- * @returns {void}
+ * @return {void}
*/
loadThemes: function() {
var section = this, params, page, request;
@@ -2123,7 +2125,8 @@
_.delay( section.renderScreenshots, 100 ); // Wait for the controls to become visible.
- if ( 'local' === section.params.filter_type || 100 > themes.length ) { // If we have less than the requested 100 themes, it's the end of the list.
+ if ( 'local' === section.params.filter_type || 100 > themes.length ) {
+ // If we have less than the requested 100 themes, it's the end of the list.
section.fullyLoaded = true;
}
} else {
@@ -2163,9 +2166,9 @@
* Loads controls into the section from data received from loadThemes().
*
* @since 4.9.0
- * @param {Array} themes - Array of theme data to create controls with.
- * @param {integer} page - Page of results being loaded.
- * @returns {void}
+ * @param {Array} themes - Array of theme data to create controls with.
+ * @param {number} page - Page of results being loaded.
+ * @return {void}
*/
loadControls: function( themes, page ) {
var newThemeControls = [],
@@ -2194,7 +2197,7 @@
* Determines whether more themes should be loaded, and loads them.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
loadMore: function() {
var section = this, container, bottom, threshold;
@@ -2202,7 +2205,9 @@
container = section.container.closest( '.customize-themes-full-container' );
bottom = container.scrollTop() + container.height();
- threshold = container.prop( 'scrollHeight' ) - 3000; // Use a fixed distance to the bottom of loaded results to avoid unnecessarily loading results sooner when using a percentage of scroll distance.
+ // Use a fixed distance to the bottom of loaded results to avoid unnecessarily
+ // loading results sooner when using a percentage of scroll distance.
+ threshold = container.prop( 'scrollHeight' ) - 3000;
if ( bottom > threshold ) {
section.loadThemes();
@@ -2216,7 +2221,7 @@
* @since 4.9.0
*
* @param {string} term - The raw search input value.
- * @returns {void}
+ * @return {void}
*/
filterSearch: function( term ) {
var count = 0,
@@ -2260,7 +2265,7 @@
* @since 4.9.0
*
* @param {wp.customize.ThemesSection} section - The current theme section, passed through the debouncer.
- * @returns {void}
+ * @return {void}
*/
checkTerm: function( section ) {
var newTerm;
@@ -2277,7 +2282,7 @@
*
* @since 4.9.0
*
- * @returns {void}
+ * @return {void}
*/
filtersChecked: function() {
var section = this,
@@ -2320,7 +2325,7 @@
*
* @param {string} newTerm - New term.
* @param {Array} newTags - New tags.
- * @returns {void}
+ * @return {void}
*/
initializeNewQuery: function( newTerm, newTags ) {
var section = this;
@@ -2353,7 +2358,7 @@
*
* @since 4.2.0
*
- * @returns {void}
+ * @return {void}
*/
renderScreenshots: function() {
var section = this;
@@ -2407,7 +2412,7 @@
*
* @since 4.9.0
*
- * @returns {int} Visible count.
+ * @return {number} Visible count.
*/
getVisibleCount: function() {
return this.contentContainer.find( 'li.customize-control:visible' ).length;
@@ -2418,7 +2423,7 @@
*
* @since 4.9.0
*
- * @returns {void}
+ * @return {void}
*/
updateCount: function( count ) {
var section = this, countEl, displayed;
@@ -2448,7 +2453,7 @@
*
* @since 4.2.0
*
- * @returns {void}
+ * @return {void}
*/
nextTheme: function () {
var section = this;
@@ -2464,7 +2469,7 @@
*
* @since 4.2.0
*
- * @returns {wp.customize.ThemeControl|boolean} Next theme.
+ * @return {wp.customize.ThemeControl|boolean} Next theme.
*/
getNextTheme: function () {
var section = this, control, nextControl, sectionControls, i;
@@ -2486,7 +2491,7 @@
* Advance the modal to the previous theme.
*
* @since 4.2.0
- * @returns {void}
+ * @return {void}
*/
previousTheme: function () {
var section = this;
@@ -2501,7 +2506,7 @@
* Get the previous theme model.
*
* @since 4.2.0
- * @returns {wp.customize.ThemeControl|boolean} Previous theme.
+ * @return {wp.customize.ThemeControl|boolean} Previous theme.
*/
getPreviousTheme: function () {
var section = this, control, nextControl, sectionControls, i;
@@ -2524,7 +2529,7 @@
*
* @since 4.2.0
*
- * @returns {void}
+ * @return {void}
*/
updateLimits: function () {
if ( ! this.getNextTheme() ) {
@@ -2543,7 +2548,7 @@
*
* @deprecated
* @param {string} themeId Theme ID.
- * @returns {jQuery.promise} Promise.
+ * @return {jQuery.promise} Promise.
*/
loadThemePreview: function( themeId ) {
return api.ThemesPanel.prototype.loadThemePreview.call( this, themeId );
@@ -2554,9 +2559,9 @@
*
* @since 4.2.0
*
- * @param {object} theme - Theme.
+ * @param {Object} theme - Theme.
* @param {Function} [callback] - Callback once the details have been shown.
- * @returns {void}
+ * @return {void}
*/
showDetails: function ( theme, callback ) {
var section = this, panel = api.panel( 'themes' );
@@ -2591,7 +2596,7 @@
*
* @since 4.2.0
*
- * @returns {void}
+ * @return {void}
*/
closeDetails: function () {
var section = this;
@@ -2606,7 +2611,7 @@
* @since 4.2.0
*
* @param {jQuery} el - Element to contain focus.
- * @returns {void}
+ * @return {void}
*/
containFocus: function( el ) {
var tabbables;
@@ -2614,15 +2619,15 @@
el.on( 'keydown', function( event ) {
// Return if it's not the tab key
- // When navigating with prev/next focus is already handled
+ // When navigating with prev/next focus is already handled.
if ( 9 !== event.keyCode ) {
return;
}
- // uses jQuery UI to get the tabbable elements
+ // Uses jQuery UI to get the tabbable elements.
tabbables = $( ':tabbable', el );
- // Keep focus within the overlay
+ // Keep focus within the overlay.
if ( tabbables.last()[0] === event.target && ! event.shiftKey ) {
tabbables.first().focus();
return false;
@@ -2647,7 +2652,7 @@
*
* @since 4.9.0
*
- * @returns {void}
+ * @return {void}
*/
initialize: function() {
var section = this;
@@ -2662,7 +2667,7 @@
*
* @since 4.9.0
*
- * @param {Boolean} expanded - The expanded state to transition to.
+ * @param {boolean} expanded - The expanded state to transition to.
* @param {Object} [args] - Args.
* @param {boolean} [args.unchanged] - Whether the state is already known to not be changed, and so short-circuit with calling completeCallback early.
* @param {Function} [args.completeCallback] - Function to call when the slideUp/slideDown has completed.
@@ -2757,14 +2762,14 @@
* @since 4.1.0
*
* @param {string} id - The ID for the panel.
- * @param {object} options - Object containing one property: params.
+ * @param {Object} options - Object containing one property: params.
* @param {string} options.title - Title shown when panel is collapsed and expanded.
* @param {string} [options.description] - Description shown at the top of the panel.
* @param {number} [options.priority=100] - The sort priority for the panel.
* @param {string} [options.type=default] - The type of the panel. See wp.customize.panelConstructor.
* @param {string} [options.content] - The markup to be used for the panel container. If empty, a JS template is used.
* @param {boolean} [options.active=true] - Whether the panel is active or not.
- * @param {object} [options.params] - Deprecated wrapper for the above properties.
+ * @param {Object} [options.params] - Deprecated wrapper for the above properties.
*/
initialize: function ( id, options ) {
var panel = this, params;
@@ -2797,7 +2802,7 @@
embed: function () {
var panel = this,
container = $( '#customize-theme-controls' ),
- parentContainer = $( '.customize-pane-parent' ); // @todo This should be defined elsewhere, and to be configurable
+ parentContainer = $( '.customize-pane-parent' ); // @todo This should be defined elsewhere, and to be configurable.
if ( ! panel.headContainer.parent().is( parentContainer ) ) {
parentContainer.append( panel.headContainer );
@@ -2821,7 +2826,7 @@
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
return;
}
- event.preventDefault(); // Keep this AFTER the key filter above
+ event.preventDefault(); // Keep this AFTER the key filter above.
if ( ! panel.expanded() ) {
panel.expand();
@@ -2833,7 +2838,7 @@
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
return;
}
- event.preventDefault(); // Keep this AFTER the key filter above
+ event.preventDefault(); // Keep this AFTER the key filter above.
if ( panel.expanded() ) {
panel.collapse();
@@ -2870,7 +2875,7 @@
*
* @since 4.1.0
*
- * @returns {Array}
+ * @return {Array}
*/
sections: function () {
return this._children( 'panel', 'section' );
@@ -2881,7 +2886,7 @@
*
* @since 4.1.0
*
- * @returns {boolean} Whether contextually active.
+ * @return {boolean} Whether contextually active.
*/
isContextuallyActive: function () {
var panel = this,
@@ -2900,15 +2905,15 @@
*
* @since 4.1.0
*
- * @param {Boolean} expanded
+ * @param {boolean} expanded
* @param {Object} args
- * @param {Boolean} args.unchanged
+ * @param {boolean} args.unchanged
* @param {Function} args.completeCallback
- * @returns {void}
+ * @return {void}
*/
onChangeExpanded: function ( expanded, args ) {
- // Immediately call the complete callback if there were no changes
+ // Immediately call the complete callback if there were no changes.
if ( args.unchanged ) {
if ( args.completeCallback ) {
args.completeCallback();
@@ -2916,7 +2921,7 @@
return;
}
- // Note: there is a second argument 'args' passed
+ // Note: there is a second argument 'args' passed.
var panel = this,
accordionSection = panel.contentContainer,
overlay = accordionSection.closest( '.wp-full-overlay' ),
@@ -2927,7 +2932,7 @@
skipTransition;
if ( expanded && ! accordionSection.hasClass( 'current-panel' ) ) {
- // Collapse any sibling sections/panels
+ // Collapse any sibling sections/panels.
api.section.each( function ( section ) {
if ( panel.id !== section.panel() ) {
section.collapse( { duration: 0 } );
@@ -3031,8 +3036,8 @@
* @since 4.9.0
*
* @param {string} id - The ID for the panel.
- * @param {object} options - Options.
- * @returns {void}
+ * @param {Object} options - Options.
+ * @return {void}
*/
initialize: function( id, options ) {
var panel = this;
@@ -3046,7 +3051,7 @@
* @since 4.9.0
*
* @param {string} [slug] - Theme slug.
- * @returns {boolean} Whether the theme can be switched to.
+ * @return {boolean} Whether the theme can be switched to.
*/
canSwitchTheme: function canSwitchTheme( slug ) {
if ( slug && slug === api.settings.theme.stylesheet ) {
@@ -3059,7 +3064,7 @@
* Attach events.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
attachEvents: function() {
var panel = this;
@@ -3067,7 +3072,7 @@
// Attach regular panel events.
api.Panel.prototype.attachEvents.apply( panel );
- // Temporary since supplying SFTP credentials does not work yet. See #42184
+ // Temporary since supplying SFTP credentials does not work yet. See #42184.
if ( api.settings.theme._canInstall && api.settings.theme._filesystemCredentialsNeeded ) {
panel.notifications.add( new api.Notification( 'theme_install_unavailable', {
message: api.l10n.themeInstallUnavailable,
@@ -3128,11 +3133,11 @@
*
* @since 4.9.0
*
- * @param {Boolean} expanded - Expanded state.
+ * @param {boolean} expanded - Expanded state.
* @param {Object} args - Args.
- * @param {Boolean} args.unchanged - Whether or not the state changed.
+ * @param {boolean} args.unchanged - Whether or not the state changed.
* @param {Function} args.completeCallback - Callback to execute when the animation completes.
- * @returns {void}
+ * @return {void}
*/
onChangeExpanded: function( expanded, args ) {
var panel = this, overlay, sections, hasExpandedSection = false;
@@ -3140,7 +3145,7 @@
// Expand/collapse the panel normally.
api.Panel.prototype.onChangeExpanded.apply( this, [ expanded, args ] );
- // Immediately call the complete callback if there were no changes
+ // Immediately call the complete callback if there were no changes.
if ( args.unchanged ) {
if ( args.completeCallback ) {
args.completeCallback();
@@ -3184,7 +3189,7 @@
* @since 4.9.0
*
* @param {jQuery.Event} event - Event.
- * @returns {jQuery.promise} Promise.
+ * @return {jQuery.promise} Promise.
*/
installTheme: function( event ) {
var panel = this, preview, onInstallSuccess, slug = $( event.target ).data( 'slug' ), deferred = $.Deferred(), request;
@@ -3289,7 +3294,7 @@
* @since 4.9.0
*
* @param {string} themeId Theme ID.
- * @returns {jQuery.promise} Promise.
+ * @return {jQuery.promise} Promise.
*/
loadThemePreview: function( themeId ) {
var panel = this, deferred = $.Deferred(), onceProcessingComplete, urlParser, queryParams;
@@ -3365,7 +3370,7 @@
* @since 4.9.0
*
* @param {jQuery.Event} event - Event.
- * @returns {void}
+ * @return {void}
*/
updateTheme: function( event ) {
wp.updates.maybeRequestFilesystemCredentials( event );
@@ -3395,7 +3400,7 @@
* @since 4.9.0
*
* @param {jQuery.Event} event - Event.
- * @returns {void}
+ * @return {void}
*/
deleteTheme: function( event ) {
var theme, section;
@@ -3477,8 +3482,8 @@
* @borrows wp.customize~Container#_toggleActive as this#_toggleActive
*
* @param {string} id - Unique identifier for the control instance.
- * @param {object} options - Options hash for the control instance.
- * @param {object} options.type - Type of control (e.g. text, radio, dropdown-pages, etc.)
+ * @param {Object} options - Options hash for the control instance.
+ * @param {Object} options.type - Type of control (e.g. text, radio, dropdown-pages, etc.)
* @param {string} [options.content] - The HTML content for the control or at least its container. This should normally be left blank and instead supplying a templateId.
* @param {string} [options.templateId] - Template ID for control's content.
* @param {string} [options.priority=10] - Order of priority to show the control within the section.
@@ -3491,8 +3496,8 @@
* @param {string} options.label - Label.
* @param {string} options.description - Description.
* @param {number} [options.instanceNumber] - Order in which this instance was created in relation to other instances.
- * @param {object} [options.params] - Deprecated wrapper for the above properties.
- * @returns {void}
+ * @param {Object} [options.params] - Deprecated wrapper for the above properties.
+ * @return {void}
*/
initialize: function( id, options ) {
var control = this, deferredSettingIds = [], settings, gatherSettings;
@@ -3500,7 +3505,7 @@
control.params = _.extend(
{},
control.defaults,
- control.params || {}, // In case sub-class already defines.
+ control.params || {}, // In case subclass already defines.
options.params || options || {} // The options.params property is deprecated, but it is checked first for back-compat.
);
@@ -3633,7 +3638,7 @@
* @since 4.7.0
* @access public
*
- * @returns {void}
+ * @return {void}
*/
linkElements: function () {
var control = this, nodes, radios, element;
@@ -3682,15 +3687,15 @@
var control = this,
inject;
- // Watch for changes to the section state
+ // Watch for changes to the section state.
inject = function ( sectionId ) {
var parentContainer;
- if ( ! sectionId ) { // @todo allow a control to be embedded without a section, for instance a control embedded in the front end.
+ if ( ! sectionId ) { // @todo Allow a control to be embedded without a section, for instance a control embedded in the front end.
return;
}
- // Wait for the section to be registered
+ // Wait for the section to be registered.
api.section( sectionId, function ( section ) {
- // Wait for the section to be ready/initialized
+ // Wait for the section to be ready/initialized.
section.deferred.embedded.done( function () {
parentContainer = ( section.contentContainer.is( 'ul' ) ) ? section.contentContainer : section.contentContainer.find( 'ul:first' );
if ( ! control.container.parent().is( parentContainer ) ) {
@@ -3708,7 +3713,7 @@
/**
* Triggered when the control's markup has been injected into the DOM.
*
- * @returns {void}
+ * @return {void}
*/
ready: function() {
var control = this, newItem;
@@ -3724,7 +3729,7 @@
control.addNewPage();
});
control.container.on( 'keydown', '.create-item-input', function( e ) {
- if ( 13 === e.which ) { // Enter
+ if ( 13 === e.which ) { // Enter.
control.addNewPage();
}
});
@@ -3739,7 +3744,7 @@
* including special handling for nav menu items and widgets.
*
* @since 4.6.0
- * @returns {jQuery} Setting validation message element.
+ * @return {jQuery} Setting validation message element.
*/
getNotificationsContainerElement: function() {
var control = this, controlTitle, notificationsContainer;
@@ -3770,7 +3775,7 @@
* Set up notifications.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
setupNotifications: function() {
var control = this, renderNotificationsIfVisible, onSectionAssigned;
@@ -3895,9 +3900,9 @@
*
* @since 4.1.0
*
- * @param {Boolean} active
+ * @param {boolean} active
* @param {Object} args
- * @param {Number} args.duration
+ * @param {number} args.duration
* @param {Function} args.completeCallback
*/
onChangeActive: function ( active, args ) {
@@ -3909,7 +3914,7 @@
}
if ( ! $.contains( document, this.container[0] ) ) {
- // jQuery.fn.slideUp is not hiding an element if it is not in the DOM
+ // jQuery.fn.slideUp is not hiding an element if it is not in the DOM.
this.container.toggle( active );
if ( args.completeCallback ) {
args.completeCallback();
@@ -3957,7 +3962,7 @@
}
};
- // Support the .dropdown class to open/close complex elements
+ // Support the .dropdown class to open/close complex elements.
this.container.on( 'click keydown', '.dropdown', function( event ) {
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
return;
@@ -3973,7 +3978,7 @@
control.container.parent().parent().find( 'li.library-selected' ).focus();
}
- // Don't want to fire focus and click at same time
+ // Don't want to fire focus and click at same time.
toggleFreeze = true;
setTimeout(function () {
toggleFreeze = false;
@@ -4017,7 +4022,8 @@
templateId = control.templateSelector;
- // Use default content template when a standard HTML type is used, there isn't a more specific template existing, and the control container is empty.
+ // Use default content template when a standard HTML type is used,
+ // there isn't a more specific template existing, and the control container is empty.
if ( templateId === 'customize-control-' + control.params.type + '-content' &&
_.contains( standardTypes, control.params.type ) &&
! document.getElementById( 'tmpl-' + templateId ) &&
@@ -4047,7 +4053,8 @@
*
* @since 4.7.0
* @access private
- * @returns {void}
+ *
+ * @return {void}
*/
addNewPage: function () {
var control = this, promise, toggle, container, input, title, select;
@@ -4070,7 +4077,8 @@
input.removeClass( 'invalid' );
input.attr( 'disabled', 'disabled' );
- // The menus functions add the page, publish when appropriate, and also add the new page to the dropdown-pages controls.
+ // The menus functions add the page, publish when appropriate,
+ // and also add the new page to the dropdown-pages controls.
promise = api.Menus.insertAutoDraftPost( {
post_title: title,
post_type: 'page'
@@ -4199,7 +4207,7 @@
control.container.on( 'click keydown', '.remove-button', control.removeFile );
control.container.on( 'click keydown', '.remove-button', control.cleanupPlayer );
- // Resize the player controls when it becomes visible (ie when section is expanded)
+ // Resize the player controls when it becomes visible (ie when section is expanded).
api.section( control.section() ).container
.on( 'expanded', function() {
if ( control.player ) {
@@ -4347,7 +4355,7 @@
/**
* Called when the "Remove" link is clicked. Empties the setting.
*
- * @param {object} event jQuery Event object
+ * @param {Object} event jQuery Event object
*/
removeFile: function( event ) {
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
@@ -4432,7 +4440,7 @@
/**
* Callback handler for when an attachment is selected in the media modal.
- * Does an additional AJAX request for setting the background context.
+ * Does an additional Ajax request for setting the background context.
*/
select: function() {
api.UploadControl.prototype.select.apply( this, arguments );
@@ -4557,7 +4565,7 @@
/**
* After the image has been cropped, apply the cropped image data to the setting.
*
- * @param {object} croppedImage Cropped attachment data.
+ * @param {Object} croppedImage Cropped attachment data.
*/
onCropped: function( croppedImage ) {
this.setImageFromAttachment( croppedImage );
@@ -4570,7 +4578,7 @@
*
* @param {wp.media.model.Attachment} attachment
* @param {wp.media.controller.Cropper} controller
- * @returns {Object} Options
+ * @return {Object} Options
*/
calculateImageSelectOptions: function( attachment, controller ) {
var control = controller.get( 'control' ),
@@ -4633,13 +4641,13 @@
/**
* Return whether the image must be cropped, based on required dimensions.
*
- * @param {bool} flexW
- * @param {bool} flexH
- * @param {int} dstW
- * @param {int} dstH
- * @param {int} imgW
- * @param {int} imgH
- * @return {bool}
+ * @param {boolean} flexW
+ * @param {boolean} flexH
+ * @param {number} dstW
+ * @param {number} dstH
+ * @param {number} imgW
+ * @param {number} imgH
+ * @return {boolean}
*/
mustBeCropped: function( flexW, flexH, dstW, dstH, imgW, imgH ) {
if ( true === flexW && true === flexH ) {
@@ -4676,7 +4684,7 @@
/**
* Updates the setting and re-renders the control UI.
*
- * @param {object} attachment
+ * @param {Object} attachment
*/
setImageFromAttachment: function( attachment ) {
this.params.attachment = attachment;
@@ -4762,7 +4770,7 @@
/**
* Updates the setting and re-renders the control UI.
*
- * @param {object} attachment
+ * @param {Object} attachment
*/
setImageFromAttachment: function( attachment ) {
var sizes = [ 'site_icon-32', 'thumbnail', 'full' ], link,
@@ -4791,7 +4799,7 @@
/**
* Called when the "Remove" link is clicked. Empties the setting.
*
- * @param {object} event jQuery Event object
+ * @param {Object} event jQuery Event object
*/
removeFile: function( event ) {
if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
@@ -4853,7 +4861,7 @@
*
* @since 4.2.0
*
- * @returns {Object} Options
+ * @return {Object} Options
*/
getInitialHeaderImage: function() {
if ( ! api.get().header_image || ! api.get().header_image_data || _.contains( [ 'remove-header', 'random-default-image', 'random-uploaded-image' ], api.get().header_image ) ) {
@@ -4886,7 +4894,7 @@
*
* @param {wp.media.model.Attachment} attachment
* @param {wp.media.controller.Cropper} controller
- * @returns {Object} Options
+ * @return {Object} Options
*/
calculateImageSelectOptions: function(attachment, controller) {
var xInit = parseInt(_wpCustomizeHeader.data.width, 10),
@@ -5001,7 +5009,7 @@
/**
* After the image has been cropped, apply the cropped image data to the setting.
*
- * @param {object} croppedImage Cropped attachment data.
+ * @param {Object} croppedImage Cropped attachment data.
*/
onCropped: function(croppedImage) {
var url = croppedImage.url,
@@ -5014,7 +5022,7 @@
/**
* If cropping was skipped, apply the image data directly to the setting.
*
- * @param {object} selection
+ * @param {Object} selection
*/
onSkippedCrop: function(selection) {
var url = selection.get('url'),
@@ -5028,10 +5036,10 @@
* header image data and inserts it into the user-uploaded headers
* collection.
*
- * @param {String} url
- * @param {Number} attachmentId
- * @param {Number} width
- * @param {Number} height
+ * @param {string} url
+ * @param {number} attachmentId
+ * @param {number} width
+ * @param {number} height
*/
setImageFromURL: function(url, attachmentId, width, height) {
var choice, data = {};
@@ -5128,7 +5136,7 @@
return;
}
- event.preventDefault(); // Keep this AFTER the key filter above
+ event.preventDefault(); // Keep this AFTER the key filter above.
section = api.section( control.section() );
section.showDetails( control.params.theme, function() {
@@ -5155,7 +5163,7 @@
*
* @since 4.2.0
* @param {Array} terms - An array of terms to search for.
- * @returns {boolean} Whether a theme control was activated or not.
+ * @return {boolean} Whether a theme control was activated or not.
*/
filter: function( terms ) {
var control = this,
@@ -5196,7 +5204,7 @@
control.params.priority = 101 - matchCount; // Sort results by match count.
return true;
} else {
- control.deactivate(); // Hide control
+ control.deactivate(); // Hide control.
control.params.priority = 101;
return false;
}
@@ -5207,7 +5215,7 @@
*
* @since 4.9.0
*
- * @returns {void}
+ * @return {void}
*/
rerenderAsInstalled: function( installed ) {
var control = this, section;
@@ -5237,8 +5245,8 @@
*
* @since 4.9.0
* @param {string} id - Unique identifier for the control instance.
- * @param {object} options - Options hash for the control instance.
- * @returns {void}
+ * @param {Object} options - Options hash for the control instance.
+ * @return {void}
*/
initialize: function( id, options ) {
var control = this;
@@ -5273,7 +5281,7 @@
* Initialize the editor when the containing section is ready and expanded.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
ready: function() {
var control = this;
@@ -5305,7 +5313,7 @@
* Initialize editor.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
initEditor: function() {
var control = this, element, editorSettings = false;
@@ -5356,7 +5364,7 @@
* @since 4.9.0
* @param {Object} [params] - Focus params.
* @param {Function} [params.completeCallback] - Function to call when expansion is complete.
- * @returns {void}
+ * @return {void}
*/
focus: function( params ) {
var control = this, extendedParams = _.extend( {}, params ), originalCompleteCallback;
@@ -5376,8 +5384,8 @@
* Initialize syntax-highlighting editor.
*
* @since 4.9.0
- * @param {object} codeEditorSettings - Code editor settings.
- * @returns {void}
+ * @param {Object} codeEditorSettings - Code editor settings.
+ * @return {void}
*/
initSyntaxHighlightingEditor: function( codeEditorSettings ) {
var control = this, $textarea = control.container.find( 'textarea' ), settings, suspendEditorUpdate = false;
@@ -5436,7 +5444,7 @@
* Handle tabbing to the field after the editor.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
onTabNext: function onTabNext() {
var control = this, controls, controlIndex, section;
@@ -5454,7 +5462,7 @@
* Handle tabbing to the field before the editor.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
onTabPrevious: function onTabPrevious() {
var control = this, controls, controlIndex, section;
@@ -5473,7 +5481,7 @@
*
* @since 4.9.0
* @param {Array} errorAnnotations - Error annotations.
- * @returns {void}
+ * @return {void}
*/
onUpdateErrorNotice: function onUpdateErrorNotice( errorAnnotations ) {
var control = this, message;
@@ -5496,7 +5504,7 @@
* Initialize plain-textarea editor when syntax highlighting is disabled.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
initPlainTextareaEditor: function() {
var control = this, $textarea = control.container.find( 'textarea' ), textarea = $textarea[0];
@@ -5556,7 +5564,7 @@
* Initialize behaviors.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
ready: function ready() {
var control = this;
@@ -5618,7 +5626,7 @@
* @since 4.9.0
*
* @param {string} datetime - Date/Time string. Accepts Y-m-d[ H:i[:s]] format.
- * @returns {object|null} Returns object containing date components or null if parse error.
+ * @return {Object|null} Returns object containing date components or null if parse error.
*/
parseDateTime: function parseDateTime( datetime ) {
var control = this, matches, date, midDayHour = 12;
@@ -5733,7 +5741,7 @@
* Populate setting value from the inputs.
*
* @since 4.9.0
- * @returns {boolean} If setting updated.
+ * @return {boolean} If setting updated.
*/
populateSetting: function populateSetting() {
var control = this, date;
@@ -5794,7 +5802,7 @@
* Check if the date is in the future.
*
* @since 4.9.0
- * @returns {boolean} True if future date.
+ * @return {boolean} True if future date.
*/
isFutureDate: function isFutureDate() {
var control = this;
@@ -5807,7 +5815,7 @@
* @since 4.9.0
* @param {string} hourInTwelveHourFormat - Hour in twelve hour format.
* @param {string} meridian - Either 'am' or 'pm'.
- * @returns {string} Hour in twenty four hour format.
+ * @return {string} Hour in twenty four hour format.
*/
convertHourToTwentyFourHourFormat: function convertHour( hourInTwelveHourFormat, meridian ) {
var hourInTwentyFourHourFormat, hour, midDayHour = 12;
@@ -5832,7 +5840,7 @@
* Populates date inputs in date fields.
*
* @since 4.9.0
- * @returns {boolean} Whether the inputs were populated.
+ * @return {boolean} Whether the inputs were populated.
*/
populateDateInputs: function populateDateInputs() {
var control = this, parsed;
@@ -5914,7 +5922,7 @@
* Initialize behaviors.
*
* @since 4.9.0
- * @returns {void}
+ * @return {void}
*/
ready: function ready() {
var control = this, element, component, node, url, input, button;
@@ -6042,7 +6050,8 @@
* @type {Function}
* @param {...string} ids - One or more ids for controls to obtain.
* @param {deferredControlsCallback} [callback] - Function called when all supplied controls exist.
- * @returns {wp.customize.Control|undefined|jQuery.promise} Control instance or undefined (if function called with one id param), or promise resolving to requested controls.
+ * @return {wp.customize.Control|undefined|jQuery.promise} Control instance or undefined (if function called with one id param),
+ * or promise resolving to requested controls.
*
* @example <caption>Loop over all registered controls.</caption>
* wp.customize.control.each( function( control ) { ... } );
@@ -6103,7 +6112,8 @@
* @type {Function}
* @param {...string} ids - One or more ids for sections to obtain.
* @param {deferredSectionsCallback} [callback] - Function called when all supplied sections exist.
- * @returns {wp.customize.Section|undefined|jQuery.promise} Section instance or undefined (if function called with one id param), or promise resolving to requested sections.
+ * @return {wp.customize.Section|undefined|jQuery.promise} Section instance or undefined (if function called with one id param),
+ * or promise resolving to requested sections.
*
* @example <caption>Loop over all registered sections.</caption>
* wp.customize.section.each( function( section ) { ... } )
@@ -6137,7 +6147,8 @@
* @type {Function}
* @param {...string} ids - One or more ids for panels to obtain.
* @param {deferredPanelsCallback} [callback] - Function called when all supplied panels exist.
- * @returns {wp.customize.Panel|undefined|jQuery.promise} Panel instance or undefined (if function called with one id param), or promise resolving to requested panels.
+ * @return {wp.customize.Panel|undefined|jQuery.promise} Panel instance or undefined (if function called with one id param),
+ * or promise resolving to requested panels.
*
* @example <caption>Loop over all registered panels.</caption>
* wp.customize.panel.each( function( panel ) { ... } )
@@ -6171,7 +6182,8 @@
* @type {Function}
* @param {...string} codes - One or more codes for notifications to obtain.
* @param {deferredNotificationsCallback} [callback] - Function called when all supplied notifications exist.
- * @returns {wp.customize.Notification|undefined|jQuery.promise} notification instance or undefined (if function called with one code param), or promise resolving to requested notifications.
+ * @return {wp.customize.Notification|undefined|jQuery.promise} Notification instance or undefined (if function called with one code param),
+ * or promise resolving to requested notifications.
*
* @example <caption>Check if existing notification</caption>
* exists = wp.customize.notifications.has( 'a_new_day_arrived' );
@@ -6206,10 +6218,10 @@
* @constructs wp.customize.PreviewFrame
* @augments wp.customize.Messenger
*
- * @param {object} params.container
- * @param {object} params.previewUrl
- * @param {object} params.query
- * @param {object} options
+ * @param {Object} params.container
+ * @param {Object} params.previewUrl
+ * @param {Object} params.query
+ * @param {Object} options
*/
initialize: function( params, options ) {
var deferred = $.Deferred();
@@ -6236,7 +6248,7 @@
/**
* Run the preview request.
*
- * @param {object} deferred jQuery Deferred object to be resolved with
+ * @param {Object} deferred jQuery Deferred object to be resolved with
* the request.
*/
run: function( deferred ) {
@@ -6444,12 +6456,12 @@
* @constructs wp.customize.Previewer
* @augments wp.customize.Messenger
*
- * @param {array} params.allowedUrls
+ * @param {Array} params.allowedUrls
* @param {string} params.container A selector or jQuery element for the preview
* frame to be placed.
* @param {string} params.form
* @param {string} params.previewUrl The URL to preview.
- * @param {object} options
+ * @param {Object} options
*/
initialize: function( params, options ) {
var previewer = this,
@@ -6494,13 +6506,15 @@
urlParser.href = previewer.origin();
previewer.add( 'scheme', urlParser.protocol.replace( /:$/, '' ) );
- // Limit the URL to internal, front-end links.
- //
- // If the front end and the admin are served from the same domain, load the
- // preview over ssl if the Customizer is being loaded over ssl. This avoids
- // insecure content warnings. This is not attempted if the admin and front end
- // are on different domains to avoid the case where the front end doesn't have
- // ssl certs.
+ /*
+ * Limit the URL to internal, front-end links.
+ *
+ * If the front end and the admin are served from the same domain, load the
+ * preview over ssl if the Customizer is being loaded over ssl. This avoids
+ * insecure content warnings. This is not attempted if the admin and front end
+ * are on different domains to avoid the case where the front end doesn't have
+ * ssl certs.
+ */
previewer.add( 'previewUrl', params.previewUrl ).setter( function( to ) {
var result = null, urlParser, queryParams, parsedAllowedUrl, parsedCandidateUrls = [];
@@ -6595,12 +6609,12 @@
* @since 4.7.0
* @access public
*
- * @param {object} data - Data from preview.
+ * @param {Object} data - Data from preview.
* @param {string} data.currentUrl - Current URL.
- * @param {object} data.activePanels - Active panels.
- * @param {object} data.activeSections Active sections.
- * @param {object} data.activeControls Active controls.
- * @returns {void}
+ * @param {Object} data.activePanels - Active panels.
+ * @param {Object} data.activeSections Active sections.
+ * @param {Object} data.activeControls Active controls.
+ * @return {void}
*/
ready: function( data ) {
var previewer = this, synced = {}, constructs;
@@ -6670,7 +6684,7 @@
* @since 4.7.0
* @access public
*
- * @returns {void}
+ * @return {void}
*/
keepPreviewAlive: function keepPreviewAlive() {
var previewer = this, keepAliveTick, timeoutId, handleMissingKeepAlive, scheduleKeepAliveCheck;
@@ -6731,12 +6745,13 @@
*
* @since 3.4.0
* @access public
- * @returns {void}
+ *
+ * @return {void}
*/
refresh: function() {
var previewer = this, onSettingChange;
- // Display loading indicator
+ // Display loading indicator.
previewer.send( 'loading-initiated' );
previewer.abort();
@@ -6902,10 +6917,10 @@
* @since 4.6.0
* @private
*
- * @param {object} args
- * @param {object} args.settingValidities
+ * @param {Object} args
+ * @param {Object} args.settingValidities
* @param {boolean} [args.focusInvalidControl=false]
- * @returns {void}
+ * @return {void}
*/
api._handleSettingValidities = function handleSettingValidities( args ) {
var invalidSettingControls, invalidSettings = [], wasFocused = false;
@@ -6978,7 +6993,7 @@
*
* @since 4.6.0
* @param {string[]} settingIds Setting IDs.
- * @returns {object<string, wp.customize.Control>} Mapping setting ids to arrays of controls.
+ * @return {Object<string, wp.customize.Control>} Mapping setting ids to arrays of controls.
*/
api.findControlsForSettings = function findControlsForSettings( settingIds ) {
var controls = {}, settingControls;
@@ -7009,7 +7024,7 @@
activeElement = $( document.activeElement );
}
- // Sort the sections within each panel
+ // Sort the sections within each panel.
api.panel.each( function ( panel ) {
if ( 'themes' === panel.id ) {
return; // Don't reflow theme sections, as doing so moves them after the themes container.
@@ -7027,7 +7042,7 @@
}
} );
- // Sort the controls within each section
+ // Sort the controls within each section.
api.section.each( function ( section ) {
var controls = section.controls(),
controlContainers = _.pluck( controls, 'container' );
@@ -7043,10 +7058,10 @@
}
} );
- // Sort the root panels and sections
+ // Sort the root panels and sections.
rootNodes.sort( api.utils.prioritySort );
rootHeadContainers = _.pluck( rootNodes, 'headContainer' );
- appendContainer = $( '#customize-theme-controls .customize-pane-parent' ); // @todo This should be defined elsewhere, and to be configurable
+ appendContainer = $( '#customize-theme-controls .customize-pane-parent' ); // @todo This should be defined elsewhere, and to be configurable.
if ( ! api.utils.areElementListsEqual( rootHeadContainers, appendContainer.children() ) ) {
_( rootNodes ).each( function ( rootNode ) {
appendContainer.append( rootNode.headContainer );
@@ -7054,7 +7069,7 @@
wasReflowed = true;
}
- // Now re-trigger the active Value callbacks to that the panels and sections can decide whether they can be rendered
+ // Now re-trigger the active Value callbacks so that the panels and sections can decide whether they can be rendered.
api.panel.each( function ( panel ) {
var value = panel.active();
panel.active.callbacks.fireWith( panel.active, [ value, value ] );
@@ -7064,7 +7079,7 @@
section.active.callbacks.fireWith( section.active, [ value, value ] );
} );
- // Restore focus if there was a reflow and there was an active (focused) element
+ // Restore focus if there was a reflow and there was an active (focused) element.
if ( wasReflowed && activeElement ) {
activeElement.focus();
}
@@ -7204,9 +7219,11 @@
cancelScheduleButtonReminder = api.utils.highlightButton( btnWrapper, {
delay: 1000,
- // Only abort the reminder when the save button is focused.
- // If the user clicks the settings button to toggle the
- // settings closed, we'll still remind them.
+ /*
+ * Only abort the reminder when the save button is focused.
+ * If the user clicks the settings button to toggle the
+ * settings closed, we'll still remind them.
+ */
focusTarget: saveBtn
} );
}
@@ -7384,9 +7401,9 @@
* @since 4.7.0 Added options param.
* @access public
*
- * @param {object} [options] Options.
+ * @param {Object} [options] Options.
* @param {boolean} [options.excludeCustomizedSaved=false] Exclude saved settings in customized response (values pending writing to changeset).
- * @return {object} Query vars.
+ * @return {Object} Query vars.
*/
query: function( options ) {
var queryVars = {
@@ -7422,11 +7439,11 @@
* @since 3.4.0
* @since 4.7.0 Added args param and return value.
*
- * @param {object} [args] Args.
+ * @param {Object} [args] Args.
* @param {string} [args.status=publish] Status.
* @param {string} [args.date] Date, in local time in MySQL format.
* @param {string} [args.title] Title
- * @returns {jQuery.promise} Promise.
+ * @return {jQuery.promise} Promise.
*/
save: function( args ) {
var previewer = this,
@@ -7575,7 +7592,7 @@
if ( '0' === response ) {
response = 'not_logged_in';
} else if ( '-1' === response ) {
- // Back-compat in case any other check_ajax_referer() call is dying
+ // Back-compat in case any other check_ajax_referer() call is dying.
response = 'invalid_nonce';
}
@@ -7699,7 +7716,7 @@
*
* @since 4.9.0
*
- * @returns {jQuery.promise} Promise.
+ * @return {jQuery.promise} Promise.
*/
trash: function trash() {
var request, success, fail;
@@ -7808,7 +7825,7 @@
api.previewer.send( 'nonce-refresh', nonce );
});
- // Create Settings
+ // Create Settings.
$.each( api.settings.settings, function( id, data ) {
var Constructor = api.settingConstructor[ data.type ] || api.Setting;
api.add( new Constructor( id, data.value, {
@@ -7818,28 +7835,31 @@
} ) );
});
- // Create Panels
+ // Create Panels.
$.each( api.settings.panels, function ( id, data ) {
var Constructor = api.panelConstructor[ data.type ] || api.Panel, options;
- options = _.extend( { params: data }, data ); // Inclusion of params alias is for back-compat for custom panels that expect to augment this property.
+ // Inclusion of params alias is for back-compat for custom panels that expect to augment this property.
+ options = _.extend( { params: data }, data );
api.panel.add( new Constructor( id, options ) );
});
- // Create Sections
+ // Create Sections.
$.each( api.settings.sections, function ( id, data ) {
var Constructor = api.sectionConstructor[ data.type ] || api.Section, options;
- options = _.extend( { params: data }, data ); // Inclusion of params alias is for back-compat for custom sections that expect to augment this property.
+ // Inclusion of params alias is for back-compat for custom sections that expect to augment this property.
+ options = _.extend( { params: data }, data );
api.section.add( new Constructor( id, options ) );
});
- // Create Controls
+ // Create Controls.
$.each( api.settings.controls, function( id, data ) {
var Constructor = api.controlConstructor[ data.type ] || api.Control, options;
- options = _.extend( { params: data }, data ); // Inclusion of params alias is for back-compat for custom controls that expect to augment this property.
+ // Inclusion of params alias is for back-compat for custom controls that expect to augment this property.
+ options = _.extend( { params: data }, data );
api.control.add( new Constructor( id, options ) );
});
- // Focus the autofocused element
+ // Focus the autofocused element.
_.each( [ 'panel', 'section', 'control' ], function( type ) {
var id = api.settings.autofocus[ type ];
if ( ! id ) {
@@ -7892,7 +7912,7 @@
api.notifications.render();
});
- // Save and activated states
+ // Save and activated states.
(function( state ) {
var saved = state.instance( 'saved' ),
saving = state.instance( 'saving' ),
@@ -8033,7 +8053,7 @@
* @access private
*
* @param {boolean} isIncluded Is UUID included.
- * @returns {void}
+ * @return {void}
*/
populateChangesetUuidParam = function( isIncluded ) {
var urlParser, queryParams;
@@ -8101,13 +8121,14 @@
* @since 4.9.0
*
* @param {string} [code] - Code.
- * @param {object} [params] - Params.
+ * @param {Object} [params] - Params.
*/
initialize: function( code, params ) {
var notification = this, _code, _params;
_code = code || 'changeset_locked';
_params = _.extend(
{
+ message: '',
type: 'warning',
containerClasses: '',
lockUser: {}
@@ -8189,10 +8210,10 @@
*
* @since 4.9.0
*
- * @param {object} [args] - Args.
- * @param {object} [args.lockUser] - Lock user data.
+ * @param {Object} [args] - Args.
+ * @param {Object} [args.lockUser] - Lock user data.
* @param {boolean} [args.allowOverride=false] - Whether override is allowed.
- * @returns {void}
+ * @return {void}
*/
function startLock( args ) {
if ( args && args.lockUser ) {
@@ -8251,7 +8272,7 @@
/**
* Obtain the URL to restore the autosave.
*
- * @returns {string} Customizer URL.
+ * @return {string} Customizer URL.
*/
function getAutosaveRestorationUrl() {
var urlParser, queryParams;
@@ -8272,7 +8293,7 @@
* Remove parameter from the URL.
*
* @param {Array} params - Parameter names to remove.
- * @returns {void}
+ * @return {void}
*/
function stripParamsFromLocation( params ) {
var urlParser = document.createElement( 'a' ), queryParams, strippedParams = 0;
@@ -8295,7 +8316,7 @@
/**
* Dismiss autosave.
*
- * @returns {void}
+ * @return {void}
*/
function dismissAutosave() {
if ( autosaveDismissed ) {
@@ -8314,7 +8335,7 @@
/**
* Add notification regarding the availability of an autosave to restore.
*
- * @returns {void}
+ * @return {void}
*/
function addAutosaveRestoreNotification() {
var code = 'autosave_available', onStateChange;
@@ -8492,7 +8513,7 @@
* @access private
*
* @param {wp.customize.Panel|wp.customize.Section} container Construct.
- * @returns {void}
+ * @return {void}
*/
changeContainer = function( container ) {
var newInstance = container,
@@ -8604,7 +8625,7 @@
* @since 4.7.0
* @access private
*
- * @returns {void}
+ * @return {void}
*/
updateHeaderHeight = function() {
activeHeader.height = activeHeader.element.outerHeight();
@@ -8616,10 +8637,10 @@
* @since 4.7.0
* @access private
*
- * @param {object} header - Header.
+ * @param {Object} header - Header.
* @param {number} scrollTop - Scroll top.
* @param {number} scrollDirection - Scroll direction, negative number being up and positive being down.
- * @returns {void}
+ * @return {void}
*/
positionStickyHeader = function( header, scrollTop, scrollDirection ) {
var headerElement = header.element,
@@ -8686,7 +8707,8 @@
};
}());
- // Previewed device bindings. (The api.previewedDevice property is how this Value was first introduced, but since it has moved to api.state.)
+ // Previewed device bindings. (The api.previewedDevice property
+ // is how this Value was first introduced, but since it has moved to api.state.)
api.previewedDevice = api.state( 'previewedDevice' );
// Set the default device.
@@ -8793,7 +8815,7 @@
api.state( 'selectedChangesetStatus' ).unbind( startPromptingBeforeUnload );
api.state( 'selectedChangesetDate' ).unbind( startPromptingBeforeUnload );
- // Prompt user with AYS dialog if leaving the Customizer with unsaved changes
+ // Prompt user with AYS dialog if leaving the Customizer with unsaved changes.
$( window ).on( 'beforeunload.customize-confirm', function() {
if ( ! isCleanState() && ! api.state( 'changesetLocked' ).get() ) {
setTimeout( function() {
@@ -8878,7 +8900,7 @@
});
} );
- // Pass titles to the parent
+ // Pass titles to the parent.
api.bind( 'title', function( newTitle ) {
parent.send( 'title', newTitle );
});
@@ -8890,7 +8912,7 @@
// Initialize the connection with the parent frame.
parent.send( 'ready' );
- // Control visibility for default controls
+ // Control visibility for default controls.
$.each({
'background_image': {
controls: [ 'background_preset', 'background_position', 'background_size', 'background_repeat', 'background_attachment' ],
@@ -8922,7 +8944,7 @@
api.control( 'background_preset', function( control ) {
var visibility, defaultValues, values, toggleVisibility, updateSettings, preset;
- visibility = { // position, size, repeat, attachment
+ visibility = { // position, size, repeat, attachment.
'default': [ false, false, false, false ],
'fill': [ true, false, false, false ],
'fit': [ true, false, true, false ],
@@ -8938,14 +8960,15 @@
_wpCustomizeBackground.defaults['default-attachment']
];
- values = { // position_x, position_y, size, repeat, attachment
+ values = { // position_x, position_y, size, repeat, attachment.
'default': defaultValues,
'fill': [ 'left', 'top', 'cover', 'no-repeat', 'fixed' ],
'fit': [ 'left', 'top', 'contain', 'no-repeat', 'fixed' ],
'repeat': [ 'left', 'top', 'auto', 'repeat', 'scroll' ]
};
- // @todo These should actually toggle the active state, but without the preview overriding the state in data.activeControls.
+ // @todo These should actually toggle the active state,
+ // but without the preview overriding the state in data.activeControls.
toggleVisibility = function( preset ) {
_.each( [ 'background_position', 'background_size', 'background_repeat', 'background_attachment' ], function( controlId, i ) {
var control = api.control( controlId );
@@ -9005,7 +9028,7 @@
} );
} );
- // Juggle the two controls that use header_textcolor
+ // Juggle the two controls that use header_textcolor.
api.control( 'display_header_text', function( control ) {
var last = '';