enmi-conf.org: comparison wp/wp-includes/js/customize-preview-widgets.js

Mercurial Mercurial > enmi-conf.org / comparison

summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help

wp/wp-includes/js/customize-preview-widgets.js

changeset 9	177826044cd9
parent 7	cf61fcea0001
child 16	a86126ab1dd4

equal deleted inserted replaced

-:c7c34916027a
+:177826044cd9
+/**
+* @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;
 	self = {
 		},
 		selectiveRefreshableWidgets: {}
 	};
 	/**
-	 * Init widgets preview.
+	 * Initializes the widgets preview.
 	 *
 	 * @since 4.5.0
+	 *
+	 * @memberOf wp.customize.widgetsPreview
+	 *
+	 * @returns {void}
 	 */
 	self.init = function() {
 		var self = this;
 		self.preview = api.preview;
 				api.preview.send( 'refresh' ); // Fallback in case theme does not support 'customize-selective-refresh-widgets'.
 			}
 		} );
 	};
-	/**
-	 * 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
+		 * @constructs
-		 * @param {Object} options.params
+		 * @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;
 			matches = id.match( /^widget\[(.+)]$/ );
 			if ( ! matches ) {
 			api.selectiveRefresh.Partial.prototype.initialize.call( partial, id, options );
 		},
 		/**
-		 * 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;
 			if ( ! self.selectiveRefreshableWidgets[ partial.widgetIdParts.idBase ] ) {
 				refreshDeferred = $.Deferred();
 				return api.selectiveRefresh.Partial.prototype.refresh.call( partial );
 			}
 		},
 		/**
-		 * 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;
 			if ( api.selectiveRefresh.Partial.prototype.renderContent.call( partial, placement ) ) {
 				api.preview.send( 'widget-updated', partial.widgetId );
 				api.selectiveRefresh.trigger( 'widget-updated', partial );
 			}
 		}
 	});
-	/**
-	 * 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
+		 * @class
-		 * @param {Object} options.params
+		 * @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;
 			matches = id.match( /^sidebar\[(.+)]$/ );
 			if ( ! matches ) {
 				throw new Error( 'Expected SidebarPartial to only have one associated setting' );
 			}
 		},
 		/**
-		 * Set up the partial.
+		 * Sets up the partial.
 		 *
 		 * @since 4.5.0
+		 *
+		 * @returns {void}
 		 */
 		ready: function() {
 			var sidebarPartial = this;
 			// Watch for changes to the sidebar_widgets setting.
 				}
 			} );
 		},
 		/**
-		 * 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;
 			regExp = /^(dynamic_sidebar_before|dynamic_sidebar_after):(.+):(\d+)$/;
 			recursiveCommentTraversal = function( childNodes ) {
 			recursiveCommentTraversal( document.body.childNodes );
 			return _.values( boundaryNodes );
 		},
 		/**
-		 * 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;
 			return _.map( partial.findDynamicSidebarBoundaryNodes(), function( boundaryNodes ) {
 				return new api.selectiveRefresh.Placement( {
 		/**
 		 * Get the list of widget IDs associated with this widget area.
 		 *
 		 * @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;
 			settingId = sidebarPartial.settings()[0];
 			if ( ! settingId ) {
 			}
 			return widgetIds.slice( 0 );
 		},
 		/**
-		 * 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
+		 *
-		 *
+		 * @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 = [];
 			widgetIds = sidebarPartial.getWidgetIds();
 			sidebarPlacements = sidebarPartial.placements();
 			return sortedSidebarContainers;
 		},
 		/**
-		 * 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
+		 *
-		 *
+		 * @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 + ']';
 			widgetPartial = api.selectiveRefresh.partial( partialId );
 			if ( ! widgetPartial ) {
 			return widgetPartial;
 		},
 		/**
-		 * 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} newWidgetIds New widget IDs.
-		 * @param {Array} oldWidgetIds Old widget ids.
+		 * @param {Array} oldWidgetIds Old widget IDs.
+		 *
+		 * @returns {void}
 		 */
 		handleSettingChange: function( newWidgetIds, oldWidgetIds ) {
 			var sidebarPartial = this, needsRefresh, widgetsRemoved, widgetsAdded, addedWidgetPartials = [];
 			needsRefresh = (
 			api.selectiveRefresh.trigger( 'sidebar-updated', sidebarPartial );
 		},
 		/**
-		 * Note that the meat is handled in handleSettingChange because it has the context of which widgets were removed.
+		 * Refreshes the sidebar partial.
 		 *
-		 * @since 4.5.0
+		 * 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();
 			deferred.fail( function() {
 	api.selectiveRefresh.partialConstructor.sidebar = self.SidebarPartial;
 	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 ) {
 			var partial, partialId = 'sidebar[' + registeredSidebar.id + ']';
 			partial = api.selectiveRefresh.partial( partialId );
 			}
 		} );
 	};
 	/**
-	 * 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;
 		$.each( self.registeredSidebars, function( i, sidebar ) {
 			self.widgetSelectors.push( widgetSelector );
 		});
 	};
 	/**
-	 * 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 ),
 			$widget = $( '#' + widgetId );
 			$widget.removeClass( 'widget-customizer-highlighted-widget' );
 		}, 500 );
 	};
 	/**
-	 * Show a title and highlight widgets on hover. On shift+clicking
+	 * Shows a title and highlights widgets on hover. On shift+clicking focuses the
-	 * focus the widget control.
+	 * widget control.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
 	 *
 	 * @since 3.9.0
+	 *
+	 * @returns {void}
 	 */
 	self.highlightControls = function() {
 		var self = this,
 			selector = this.widgetSelectors.join( ',' );
 		if ( ! api.settings.channel ) {
 			return;
 		}
 		$( 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' ) );
 		});
 		// Open expand the widget control when shift+clicking the widget element
 			self.preview.send( 'focus-widget-control', $( this ).prop( 'id' ) );
 		});
 	};
 	/**
-	 * Parse a widget ID.
+	 * Parses a widget ID.
 	 *
 	 * @memberOf wp.customize.widgetsPreview
 	 *
 	 * @since 4.5.0
 	 *
-	 * @param {string} widgetId Widget ID.
+	 * @param {string} widgetId The widget ID.
-	 * @returns {{idBase: string, number: number|null}}
+	 *
+	 * @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 = {
 			idBase: '',
 			number: null
 		return parsed;
 	};
 	/**
-	 * 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 = {
 			idBase: '',
 			number: null
 		}
 		return parsed;
 	};
 	/**
-	 * 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.
+	 * @param {string} widgetId The widget ID.
-	 * @returns {string} settingId Setting ID.
+	 *
+	 * @returns {string} The setting ID.
 	 */
 	self.getWidgetSettingId = function( widgetId ) {
 		var parsed = this.parseWidgetId( widgetId ), settingId;
 		settingId = 'widget_' + parsed.idBase;

enmi-conf.org