sergiotarxz/Wordpress
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Docs: Improve JSDoc for customize-preview-widgets.js.

Browse Source 
Props ireneyoast, andizer, robinvandervliet, boblinthorst.
Fixes #42954.


git-svn-id: https://develop.svn.wordpress.org/trunk@42416 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Anton Timmermans 2017-12-21 15:11:25 +00:00
parent 2c66a7db75
commit 9c8d49456e
1 changed files with 119 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

182
src/wp-includes/js/customize-preview-widgets.js
View File

@ -1,6 +1,19 @@
/* global _wpWidgetCustomizerPreviewSettings */ /* 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 ) { wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function( $, _, wp, api ) {
var self; var self;
@ -19,9 +32,13 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* Init widgets preview. * Initializes the widgets preview.
* *
* @since 4.5.0 * @since 4.5.0
*
* @memberOf wp.customize.widgetsPreview
*
* @returns {void}
*/ */
self.init = function() { self.init = function() {
var self = this; var self = this;
@ -59,25 +76,23 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
} ); } );
}; };
/**
* 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 */{ self.WidgetPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.WidgetPartial.prototype */{
/** /**
* Constructor. * Represents a partial widget instance.
* *
* @since 4.5.0 * @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 ) { initialize: function( id, options ) {
var partial = this, matches; var partial = this, matches;
@ -101,9 +116,11 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* 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() { refresh: function() {
var partial = this, refreshDeferred; var partial = this, refreshDeferred;
@ -118,10 +135,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* 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 * @inheritDoc
* @param {wp.customize.selectiveRefresh.Placement} placement * @param {wp.customize.selectiveRefresh.Placement} placement The placement
* function.
*
* @returns {void}
*/ */
renderContent: function( placement ) { renderContent: function( placement ) {
var partial = this; var partial = this;
@ -132,25 +153,22 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
} }
}); });
self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
/** /**
* Partial representing a widget area. * Represents a partial widget area.
*
* @since 4.5.0
*
* @class
* @augments wp.customize.selectiveRefresh.Partial
* *
* @memberOf wp.customize.widgetsPreview * @memberOf wp.customize.widgetsPreview
* @alias wp.customize.widgetsPreview.SidebarPartial * @alias wp.customize.widgetsPreview.SidebarPartial
* *
* @class * @param {string} id The partial's ID.
* @augments wp.customize.selectiveRefresh.Partial * @param {Object} options Options used to initialize the partial's instance.
* @since 4.5.0 * @param {Object} options.params The options parameters.
*/
self.SidebarPartial = api.selectiveRefresh.Partial.extend(/** @lends wp.customize.widgetsPreview.SidebarPartial.prototype */{
/**
* Constructor.
*
* @since 4.5.0
* @param {string} id - Partial ID.
* @param {Object} options
* @param {Object} options.params
*/ */
initialize: function( id, options ) { initialize: function( id, options ) {
var partial = this, matches; var partial = this, matches;
@ -179,9 +197,11 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* Set up the partial. * Sets up the partial.
* *
* @since 4.5.0 * @since 4.5.0
*
* @returns {void}
*/ */
ready: function() { ready: function() {
var sidebarPartial = this; var sidebarPartial = this;
@ -220,12 +240,16 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* 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. * Note that TreeWalker is not implemented in IE8.
* *
* @since 4.5.0 * @since 4.5.0
*
* @returns {Array.<{before: Comment, after: Comment, instanceNumber: number}>} * @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() { findDynamicSidebarBoundaryNodes: function() {
var partial = this, regExp, boundaryNodes = {}, recursiveCommentTraversal; var partial = this, regExp, boundaryNodes = {}, recursiveCommentTraversal;
@ -261,10 +285,12 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* Get the placements for this partial. * Gets the placements for this partial.
* *
* @since 4.5.0 * @since 4.5.0
* @returns {Array} *
* @returns {Array} An array containing placement objects for each of the
* dynamic sidebar boundary nodes.
*/ */
placements: function() { placements: function() {
var partial = this; var partial = this;
@ -286,7 +312,11 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
* *
* @since 4.5.0 * @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() { getWidgetIds: function() {
var sidebarPartial = this, settingId, widgetIds; var sidebarPartial = this, settingId, widgetIds;
@ -305,11 +335,13 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* 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() { reflowWidgets: function() {
var sidebarPartial = this, sidebarPlacements, widgetIds, widgetPartials, sortedSidebarContainers = []; var sidebarPartial = this, sidebarPlacements, widgetIds, widgetPartials, sortedSidebarContainers = [];
@ -369,12 +401,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* 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 * @param {string} widgetId The widget ID.
* @returns {wp.customize.selectiveRefresh.Partial} Widget instance partial. *
* @returns {wp.customize.selectiveRefresh.Partial} The widget instance partial.
*/ */
ensureWidgetPlacementContainers: function( widgetId ) { ensureWidgetPlacementContainers: function( widgetId ) {
var sidebarPartial = this, widgetPartial, wasInserted = false, partialId = 'widget[' + widgetId + ']'; var sidebarPartial = this, widgetPartial, wasInserted = false, partialId = 'widget[' + widgetId + ']';
@ -435,12 +469,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* Handle change to the sidebars_widgets[] setting. * Handles changes to the sidebars_widgets[] setting.
* *
* @since 4.5.0 * @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 ) { handleSettingChange: function( newWidgetIds, oldWidgetIds ) {
var sidebarPartial = this, needsRefresh, widgetsRemoved, widgetsAdded, addedWidgetPartials = []; var sidebarPartial = this, needsRefresh, widgetsRemoved, widgetsAdded, addedWidgetPartials = [];
@ -488,9 +524,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}, },
/** /**
* 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 * @since 4.5.0
*
* @returns {Promise} A promise postponing the refresh.
*/ */
refresh: function() { refresh: function() {
var partial = this, deferred = $.Deferred(); var partial = this, deferred = $.Deferred();
@ -516,9 +557,11 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
api.selectiveRefresh.partialConstructor.widget = self.WidgetPartial; 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 * @since 4.5.0
*
* @returns {void}
*/ */
self.addPartials = function() { self.addPartials = function() {
_.each( self.registeredSidebars, function( registeredSidebar ) { _.each( self.registeredSidebars, function( registeredSidebar ) {
@ -536,11 +579,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* 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 * @memberOf wp.customize.widgetsPreview
* *
* @since 3.9.0 * @since 3.9.0
*
* @returns {void}
*/ */
self.buildWidgetSelectors = function() { self.buildWidgetSelectors = function() {
var self = this; var self = this;
@ -576,12 +622,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* 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 * @memberOf wp.customize.widgetsPreview
* *
* @since 3.9.0 * @since 3.9.0
* @param {string} widgetId ID of the widget. * @param {string} widgetId ID of the widget.
*
* @returns {void}
*/ */
self.highlightWidget = function( widgetId ) { self.highlightWidget = function( widgetId ) {
var $body = $( document.body ), var $body = $( document.body ),
@ -596,12 +644,14 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* 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 * @memberOf wp.customize.widgetsPreview
* *
* @since 3.9.0 * @since 3.9.0
*
* @returns {void}
*/ */
self.highlightControls = function() { self.highlightControls = function() {
var self = this, var self = this,
@ -613,7 +663,7 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
} }
$( selector ).attr( 'title', this.l10n.widgetTooltip ); $( selector ).attr( 'title', this.l10n.widgetTooltip );
// Highlights widget when entering the widget editor.
$( document ).on( 'mouseenter', selector, function() { $( document ).on( 'mouseenter', selector, function() {
self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) ); self.preview.send( 'highlight-widget-control', $( this ).prop( 'id' ) );
}); });
@ -630,14 +680,16 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* Parse a widget ID. * Parses a widget ID.
* *
* @memberOf wp.customize.widgetsPreview * @memberOf wp.customize.widgetsPreview
* *
* @since 4.5.0 * @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 ) { self.parseWidgetId = function( widgetId ) {
var matches, parsed = { var matches, parsed = {
@ -657,14 +709,17 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* Parse a widget setting ID. * Parses a widget setting ID.
* *
* @memberOf wp.customize.widgetsPreview * @memberOf wp.customize.widgetsPreview
* *
* @since 4.5.0 * @since 4.5.0
* *
* @param {string} settingId Widget setting ID. * @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 ) { self.parseWidgetSettingId = function( settingId ) {
var matches, parsed = { var matches, parsed = {
@ -684,14 +739,15 @@ wp.customize.widgetsPreview = wp.customize.WidgetCustomizerPreview = (function(
}; };
/** /**
* Convert a widget ID into a Customizer setting ID. * Converts a widget ID into a Customizer setting ID.
* *
* @memberOf wp.customize.widgetsPreview * @memberOf wp.customize.widgetsPreview
* *
* @since 4.5.0 * @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 ) { self.getWidgetSettingId = function( widgetId ) {
var parsed = this.parseWidgetId( widgetId ), settingId; var parsed = this.parseWidgetId( widgetId ), settingId;