--- a/wp/wp-includes/js/customize-preview-widgets.js Mon Oct 14 18:06:33 2019 +0200
+++ b/wp/wp-includes/js/customize-preview-widgets.js Mon Oct 14 18:28:13 2019 +0200
@@ -1,6 +1,23 @@
+/**
+ * @output wp-includes/js/customize-preview-widgets.js
+ */
+
/* global _wpWidgetCustomizerPreviewSettings */
-/** @namespace wp.customize.widgetsPreview */
+/**
+ * Handles the initialization, refreshing and rendering of widget partials and sidebar widgets.
+ *
+ * @since 4.5.0
+ *
+ * @namespace wp.customize.widgetsPreview
+ *
+ * @param {jQuery} $ The jQuery object.
+ * @param {Object} _ The utilities library.
+ * @param {Object} wp Current WordPress environment instance.
+ * @param {Object} api Information from the API.
+ *
+ * @returns {Object} Widget-related variables.
+ */
wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) {
var self;
@@ -19,9 +36,13 @@
};
/**
- * Init widgets preview.
+ * Initializes the widgets preview.
*
* @since 4.5.0
+ *
+ * @memberOf wp.customize.widgetsPreview
+ *
+ * @returns {void}
*/
self.init = function() {
var self = this;
@@ -59,25 +80,23 @@
} );
};
- /**
- * Partial representing a widget instance.
- *
- * @memberOf wp.customize.widgetsPreview
- * @alias wp.customize.widgetsPreview.WidgetPartial
- *
- * @class
- * @augments wp.customize.selectiveRefresh.Partial
- * @since 4.5.0
- */
self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{
/**
- * Constructor.
+ * Represents a partial widget instance.
*
* @since 4.5.0
- * @param {string} id - Partial ID.
- * @param {Object} options
- * @param {Object} options.params
+ *
+ * @constructs
+ * @augments wp.customize.selectiveRefresh.Partial
+ *
+ * @alias wp.customize.widgetsPreview.WidgetPartial
+ * @memberOf wp.customize.widgetsPreview
+ *
+ * @param {string} id The partial's ID.
+ * @param {Object} options Options used to initialize the partial's
+ * instance.
+ * @param {Object} options.params The options parameters.
*/
initialize: function( id, options ) {
var partial = this, matches;
@@ -101,9 +120,11 @@
},
/**
- * Refresh widget partial.
+ * Refreshes the widget partial.
*
- * @returns {Promise}
+ * @since 4.5.0
+ *
+ * @returns {Promise|void} Either a promise postponing the refresh, or void.
*/
refresh: function() {
var partial = this, refreshDeferred;
@@ -118,10 +139,14 @@
},
/**
- * Send widget-updated message to parent so spinner will get removed from widget control.
+ * Sends the widget-updated message to the parent so the spinner will get
+ * removed from the widget control.
*
- * @inheritdoc
- * @param {wp.customize.selectiveRefresh.Placement} placement
+ * @inheritDoc
+ * @param {wp.customize.selectiveRefresh.Placement} placement The placement
+ * function.
+ *
+ * @returns {void}
*/
renderContent: function( placement ) {
var partial = this;
@@ -132,25 +157,22 @@
}
});
- /**
- * Partial representing a widget area.
- *
- * @memberOf wp.customize.widgetsPreview
- * @alias wp.customize.widgetsPreview.SidebarPartial
- *
- * @class
- * @augments wp.customize.selectiveRefresh.Partial
- * @since 4.5.0
- */
self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
/**
- * Constructor.
+ * Represents a partial widget area.
*
* @since 4.5.0
- * @param {string} id - Partial ID.
- * @param {Object} options
- * @param {Object} options.params
+ *
+ * @class
+ * @augments wp.customize.selectiveRefresh.Partial
+ *
+ * @memberOf wp.customize.widgetsPreview
+ * @alias wp.customize.widgetsPreview.SidebarPartial
+ *
+ * @param {string} id The partial's ID.
+ * @param {Object} options Options used to initialize the partial's instance.
+ * @param {Object} options.params The options parameters.
*/
initialize: function( id, options ) {
var partial = this, matches;
@@ -179,9 +201,11 @@
},
/**
- * Set up the partial.
+ * Sets up the partial.
*
* @since 4.5.0
+ *
+ * @returns {void}
*/
ready: function() {
var sidebarPartial = this;
@@ -220,12 +244,16 @@
},
/**
- * Get the before/after boundary nodes for all instances of this sidebar (usually one).
+ * Gets the before/after boundary nodes for all instances of this sidebar
+ * (usually one).
*
* Note that TreeWalker is not implemented in IE8.
*
* @since 4.5.0
+ *
* @returns {Array.<{before: Comment, after: Comment, instanceNumber: number}>}
+ * An array with an object for each sidebar instance, containing the
+ * node before and after the sidebar instance and its instance number.
*/
findDynamicSidebarBoundaryNodes: function() {
var partial = this, regExp, boundaryNodes = {}, recursiveCommentTraversal;
@@ -261,10 +289,12 @@
},
/**
- * Get the placements for this partial.
+ * Gets the placements for this partial.
*
* @since 4.5.0
- * @returns {Array}
+ *
+ * @returns {Array} An array containing placement objects for each of the
+ * dynamic sidebar boundary nodes.
*/
placements: function() {
var partial = this;
@@ -286,7 +316,11 @@
*
* @since 4.5.0
*
- * @returns {Array}
+ * @throws {Error} If there's no settingId.
+ * @throws {Error} If the setting doesn't exist in the API.
+ * @throws {Error} If the API doesn't pass an array of widget ids.
+ *
+ * @returns {Array} A shallow copy of the array containing widget IDs.
*/
getWidgetIds: function() {
var sidebarPartial = this, settingId, widgetIds;
@@ -305,11 +339,13 @@
},
/**
- * Reflow widgets in the sidebar, ensuring they have the proper position in the DOM.
+ * Reflows widgets in the sidebar, ensuring they have the proper position in the
+ * DOM.
*
* @since 4.5.0
*
- * @return {Array.<wp.customize.selectiveRefresh.Placement>} List of placements that were reflowed.
+ * @returns {Array.<wp.customize.selectiveRefresh.Placement>} List of placements
+ * that were reflowed.
*/
reflowWidgets: function() {
var sidebarPartial = this, sidebarPlacements, widgetIds, widgetPartials, sortedSidebarContainers = [];
@@ -369,12 +405,14 @@
},
/**
- * Make sure there is a widget instance container in this sidebar for the given widget ID.
+ * Makes sure there is a widget instance container in this sidebar for the given
+ * widget ID.
*
* @since 4.5.0
*
- * @param {string} widgetId
- * @returns {wp.customize.selectiveRefresh.Partial} Widget instance partial.
+ * @param {string} widgetId The widget ID.
+ *
+ * @returns {wp.customize.selectiveRefresh.Partial} The widget instance partial.
*/
ensureWidgetPlacementContainers: function( widgetId ) {
var sidebarPartial = this, widgetPartial, wasInserted = false, partialId = 'widget[' + widgetId + ']';
@@ -435,12 +473,14 @@
},
/**
- * Handle change to the sidebars_widgets[] setting.
+ * Handles changes to the sidebars_widgets[] setting.
*
* @since 4.5.0
*
- * @param {Array} newWidgetIds New widget ids.
- * @param {Array} oldWidgetIds Old widget ids.
+ * @param {Array} newWidgetIds New widget IDs.
+ * @param {Array} oldWidgetIds Old widget IDs.
+ *
+ * @returns {void}
*/
handleSettingChange: function( newWidgetIds, oldWidgetIds ) {
var sidebarPartial = this, needsRefresh, widgetsRemoved, widgetsAdded, addedWidgetPartials = [];
@@ -488,9 +528,14 @@
},
/**
- * Note that the meat is handled in handleSettingChange because it has the context of which widgets were removed.
+ * Refreshes the sidebar partial.
+ *
+ * Note that the meat is handled in handleSettingChange because it has the
+ * context of which widgets were removed.
*
* @since 4.5.0
+ *
+ * @returns {Promise} A promise postponing the refresh.
*/
refresh: function() {
var partial = this, deferred = $.Deferred();
@@ -516,9 +561,11 @@
api.selectiveRefresh.partialConstructor.widget = self.WidgetPartial;
/**
- * Add partials for the registered widget areas (sidebars).
+ * Adds partials for the registered widget areas (sidebars).
*
* @since 4.5.0
+ *
+ * @returns {void}
*/
self.addPartials = function() {
_.each( self.registeredSidebars, function( registeredSidebar ) {
@@ -536,11 +583,14 @@
};
/**
- * Calculate the selector for the sidebar's widgets based on the registered sidebar's info.
+ * Calculates the selector for the sidebar's widgets based on the registered
+ * sidebar's info.
*
* @memberOf wp.customize.widgetsPreview
*
* @since 3.9.0
+ *
+ * @returns {void}
*/
self.buildWidgetSelectors = function() {
var self = this;
@@ -576,12 +626,14 @@
};
/**
- * Highlight the widget on widget updates or widget control mouse overs.
+ * Highlights the widget on widget updates or widget control mouse overs.
*
* @memberOf wp.customize.widgetsPreview
*
* @since 3.9.0
* @param {string} widgetId ID of the widget.
+ *
+ * @returns {void}
*/
self.highlightWidget = function( widgetId ) {
var $body = $( document.body ),
@@ -596,12 +648,14 @@
};
/**
- * Show a title and highlight widgets on hover. On shift+clicking
- * focus the widget control.
+ * Shows a title and highlights widgets on hover. On shift+clicking focuses the
+ * widget control.
*
* @memberOf wp.customize.widgetsPreview
*
* @since 3.9.0
+ *
+ * @returns {void}
*/
self.highlightControls = function() {
var self = this,
@@ -613,7 +667,7 @@
}
$( selector ).attr( 'title', this.l10n.widgetTooltip );
-
+ // Highlights widget when entering the widget editor.
$( document ).on( 'mouseenter', selector, function() {
self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) );
});
@@ -630,14 +684,16 @@
};
/**
- * Parse a widget ID.
+ * Parses a widget ID.
*
* @memberOf wp.customize.widgetsPreview
*
* @since 4.5.0
*
- * @param {string} widgetId Widget ID.
- * @returns {{idBase: string, number: number|null}}
+ * @param {string} widgetId The widget ID.
+ *
+ * @returns {{idBase: string, number: number|null}} An object containing the
+ * idBase and number of the parsed widget ID.
*/
self.parseWidgetId = function( widgetId ) {
var matches, parsed = {
@@ -657,14 +713,17 @@
};
/**
- * Parse a widget setting ID.
+ * Parses a widget setting ID.
*
* @memberOf wp.customize.widgetsPreview
*
* @since 4.5.0
*
* @param {string} settingId Widget setting ID.
- * @returns {{idBase: string, number: number|null}|null}
+ *
+ * @returns {{idBase: string, number: number|null}|null} Either an object
+ * containing the idBase and number of the parsed widget setting ID, or
+ * null.
*/
self.parseWidgetSettingId = function( settingId ) {
var matches, parsed = {
@@ -684,14 +743,15 @@
};
/**
- * Convert a widget ID into a Customizer setting ID.
+ * Converts a widget ID into a Customizer setting ID.
*
* @memberOf wp.customize.widgetsPreview
*
* @since 4.5.0
*
- * @param {string} widgetId Widget ID.
- * @returns {string} settingId Setting ID.
+ * @param {string} widgetId The widget ID.
+ *
+ * @returns {string} The setting ID.
*/
self.getWidgetSettingId = function( widgetId ) {
var parsed = this.parseWidgetId( widgetId ), settingId;