--- a/wp/wp-admin/js/customize-widgets.js Tue Oct 22 16:11:46 2019 +0200
+++ b/wp/wp-admin/js/customize-widgets.js Tue Dec 15 13:49:49 2020 +0100
@@ -17,7 +17,7 @@
api.Widgets = api.Widgets || {};
api.Widgets.savedWidgetIds = {};
- // Link settings
+ // Link settings.
api.Widgets.data = _wpCustomizeWidgetsSettings || {};
l10n = api.Widgets.data.l10n;
@@ -59,16 +59,16 @@
model: api.Widgets.WidgetModel,
// Controls searching on the current widget collection
- // and triggers an update event
+ // and triggers an update event.
doSearch: function( value ) {
- // Don't do anything if we've already done this search
- // Useful because the search handler fires multiple times per keystroke
+ // Don't do anything if we've already done this search.
+ // Useful because the search handler fires multiple times per keystroke.
if ( this.terms === value ) {
return;
}
- // Updates terms with the value passed
+ // Updates terms with the value passed.
this.terms = value;
// If we have terms, run a search...
@@ -84,16 +84,16 @@
}
},
- // Performs a search within the collection
+ // Performs a search within the collection.
// @uses RegExp
search: function( term ) {
var match, haystack;
- // Escape the term string for RegExp meta characters
+ // Escape the term string for RegExp meta characters.
term = term.replace( /[-\/\\^$*+?.()|[\]{}]/g, '\\$&' );
// Consider spaces as word delimiters and match the whole string
- // so matching terms can be combined
+ // so matching terms can be combined.
term = term.replace( / /g, ')(?=.*' );
match = new RegExp( '^(?=.*' + term + ').+', 'i' );
@@ -150,10 +150,10 @@
'keydown' : 'keyboardAccessible'
},
- // Cache current selected widget
+ // Cache current selected widget.
selected: null,
- // Cache sidebar control which has opened panel
+ // Cache sidebar control which has opened panel.
currentSidebarControl: null,
$search: null,
$clearResults: null,
@@ -181,9 +181,11 @@
// Set the initial search count to the number of available widgets.
this.searchMatchesCount = this.collection.length;
- // If the available widgets panel is open and the customize controls are
- // interacted with (i.e. available widgets panel is blurred) then close the
- // available widgets panel. Also close on back button click.
+ /*
+ * If the available widgets panel is open and the customize controls
+ * are interacted with (i.e. available widgets panel is blurred) then
+ * close the available widgets panel. Also close on back button click.
+ */
$( '#customize-controls, #available-widgets .customize-section-title' ).on( 'click keydown', function( e ) {
var isAddNewBtn = $( e.target ).is( '.add-new-widget, .add-new-widget *' );
if ( $( 'body' ).hasClass( 'adding-widget' ) && ! isAddNewBtn ) {
@@ -191,12 +193,12 @@
}
} );
- // Clear the search results and trigger a `keyup` event to fire a new search.
+ // Clear the search results and trigger an `input` event to fire a new search.
this.$clearResults.on( 'click', function() {
- self.$search.val( '' ).focus().trigger( 'keyup' );
+ self.$search.val( '' ).focus().trigger( 'input' );
} );
- // Close the panel if the URL in the preview changes
+ // Close the panel if the URL in the preview changes.
api.previewer.bind( 'url', this.close );
},
@@ -212,19 +214,19 @@
// Announce how many search results.
this.announceSearchMatches();
- // Remove a widget from being selected if it is no longer visible
+ // Remove a widget from being selected if it is no longer visible.
if ( this.selected && ! this.selected.is( ':visible' ) ) {
this.selected.removeClass( 'selected' );
this.selected = null;
}
- // If a widget was selected but the filter value has been cleared out, clear selection
+ // If a widget was selected but the filter value has been cleared out, clear selection.
if ( this.selected && ! event.target.value ) {
this.selected.removeClass( 'selected' );
this.selected = null;
}
- // If a filter has been entered and a widget hasn't been selected, select the first one shown
+ // If a filter has been entered and a widget hasn't been selected, select the first one shown.
if ( ! this.selected && event.target.value ) {
firstVisible = this.$el.find( '> .widget-tpl:visible:first' );
if ( firstVisible.length ) {
@@ -300,7 +302,7 @@
* Handles submit for keypress and click on widget.
*/
_submit: function( event ) {
- // Only proceed with keypress if it is Enter or Spacebar
+ // Only proceed with keypress if it is Enter or Spacebar.
if ( event.type === 'keypress' && ( event.which !== 13 && event.which !== 32 ) ) {
return;
}
@@ -344,7 +346,7 @@
open: function( sidebarControl ) {
this.currentSidebarControl = sidebarControl;
- // Wide widget controls appear over the preview, and so they need to be collapsed when the panel opens
+ // Wide widget controls appear over the preview, and so they need to be collapsed when the panel opens.
_( this.currentSidebarControl.getWidgetFormControls() ).each( function( control ) {
if ( control.params.is_wide ) {
control.collapseForm();
@@ -359,7 +361,7 @@
this.$el.find( '.selected' ).removeClass( 'selected' );
- // Reset search
+ // Reset search.
this.collection.doSearch( '' );
if ( ! api.settings.browser.mobile ) {
@@ -382,7 +384,7 @@
$( 'body' ).removeClass( 'adding-widget' );
- this.$search.val( '' );
+ this.$search.val( '' ).trigger( 'input' );
},
/**
@@ -427,7 +429,7 @@
return;
}
- // If enter pressed but nothing entered, don't do anything
+ // If enter pressed but nothing entered, don't do anything.
if ( isEnter && ! this.$search.val() ) {
return;
}
@@ -457,7 +459,7 @@
/**
* @param {jQuery.Event} e
* @param {jQuery} widget
- * @param {String} newForm
+ * @param {string} newForm
*/
rss: function( e, widget, newForm ) {
var oldWidgetError = widget.find( '.widget-error:first' ),
@@ -601,7 +603,7 @@
_setupModel: function() {
var self = this, rememberSavedWidgetId;
- // Remember saved widgets so we know which to trash (move to inactive widgets sidebar)
+ // Remember saved widgets so we know which to trash (move to inactive widgets sidebar).
rememberSavedWidgetId = function() {
api.Widgets.savedWidgetIds[self.params.widget_id] = true;
};
@@ -612,7 +614,7 @@
this.isWidgetUpdating = false;
this.liveUpdateMode = true;
- // Update widget whenever model changes
+ // Update widget whenever model changes.
this.setting.bind( function( to, from ) {
if ( ! _( from ).isEqual( to ) && ! self.isWidgetUpdating ) {
self.updateWidget( { instance: to } );
@@ -657,10 +659,10 @@
top;
$widgetInside.css( 'max-height', windowHeight );
top = Math.max(
- 0, // prevent top from going off screen
+ 0, // Prevent top from going off screen.
Math.min(
- Math.max( offsetTop, 0 ), // distance widget in panel is from top of screen
- windowHeight - formHeight // flush up against bottom of screen
+ Math.max( offsetTop, 0 ), // Distance widget in panel is from top of screen.
+ windowHeight - formHeight // Flush up against bottom of screen.
)
);
$widgetInside.css( 'top', top );
@@ -679,7 +681,7 @@
$themeControlsContainer.off( 'expanded collapsed', positionWidget );
} );
- // Reposition whenever a sidebar's widgets are changed
+ // Reposition whenever a sidebar's widgets are changed.
api.each( function( setting ) {
if ( 0 === setting.id.indexOf( 'sidebars_widgets[' ) ) {
setting.bind( function() {
@@ -710,7 +712,7 @@
$closeBtn = this.container.find( '.widget-control-close' );
$closeBtn.on( 'click', function() {
self.collapse();
- self.container.find( '.widget-top .widget-action:first' ).focus(); // keyboard accessibility
+ self.container.find( '.widget-top .widget-action:first' ).focus(); // Keyboard accessibility.
} );
},
@@ -837,7 +839,7 @@
wp.a11y.speak( l10n.widgetMovedDown );
}
- $( this ).focus(); // re-focus after the container was moved
+ $( this ).focus(); // Re-focus after the container was moved.
}
} );
@@ -885,12 +887,12 @@
_setupHighlightEffects: function() {
var self = this;
- // Highlight whenever hovering or clicking over the form
+ // Highlight whenever hovering or clicking over the form.
this.container.on( 'mouseenter click', function() {
self.setting.previewer.send( 'highlight-widget', self.params.widget_id );
} );
- // Highlight when the setting is updated
+ // Highlight when the setting is updated.
this.setting.bind( function() {
self.setting.previewer.send( 'highlight-widget', self.params.widget_id );
} );
@@ -906,7 +908,7 @@
$widgetRoot = this.container.find( '.widget:first' );
$widgetContent = $widgetRoot.find( '.widget-content:first' );
- // Configure update button
+ // Configure update button.
$saveBtn = this.container.find( '.widget-control-save' );
$saveBtn.val( l10n.saveBtnLabel );
$saveBtn.attr( 'title', l10n.saveBtnTooltip );
@@ -920,15 +922,15 @@
self.updateWidget();
}, 250 );
- // Trigger widget form update when hitting Enter within an input
+ // Trigger widget form update when hitting Enter within an input.
$widgetContent.on( 'keydown', 'input', function( e ) {
- if ( 13 === e.which ) { // Enter
+ if ( 13 === e.which ) { // Enter.
e.preventDefault();
self.updateWidget( { ignoreActiveElement: true } );
}
} );
- // Handle widgets that support live previews
+ // Handle widgets that support live previews.
$widgetContent.on( 'change input propertychange', ':input', function( e ) {
if ( ! self.liveUpdateMode ) {
return;
@@ -938,7 +940,7 @@
}
} );
- // Remove loading indicators when the setting is saved and the preview updates
+ // Remove loading indicators when the setting is saved and the preview updates.
this.setting.previewer.channel.bind( 'synced', function() {
self.container.removeClass( 'previewer-loading' );
} );
@@ -966,12 +968,12 @@
*
* @since 4.1.0
*
- * @param {Boolean} active
+ * @param {boolean} active
* @param {Object} args
* @param {function} args.completeCallback
*/
onChangeActive: function ( active, args ) {
- // Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments
+ // Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments.
this.container.toggleClass( 'widget-rendered', active );
if ( args.completeCallback ) {
args.completeCallback();
@@ -984,10 +986,10 @@
_setupRemoveUI: function() {
var self = this, $removeBtn, replaceDeleteWithRemove;
- // Configure remove button
+ // Configure remove button.
$removeBtn = this.container.find( '.widget-control-remove' );
$removeBtn.on( 'click', function() {
- // Find an adjacent element to add focus to when this widget goes away
+ // Find an adjacent element to add focus to when this widget goes away.
var $adjacentFocusTarget;
if ( self.container.next().is( '.customize-control-widget_form' ) ) {
$adjacentFocusTarget = self.container.next().find( '.widget-action:first' );
@@ -1014,12 +1016,12 @@
sidebarWidgetIds.splice( i, 1 );
sidebarsWidgetsControl.setting( sidebarWidgetIds );
- $adjacentFocusTarget.focus(); // keyboard accessibility
+ $adjacentFocusTarget.focus(); // Keyboard accessibility.
} );
} );
replaceDeleteWithRemove = function() {
- $removeBtn.text( l10n.removeBtnLabel ); // wp_widget_control() outputs the button as "Delete"
+ $removeBtn.text( l10n.removeBtnLabel ); // wp_widget_control() outputs the button as "Delete".
$removeBtn.attr( 'title', l10n.removeBtnTooltip );
};
@@ -1038,7 +1040,7 @@
* over when copying sanitized values over to the form loaded.
*
* @param {jQuery} container element in which to look for inputs
- * @returns {jQuery} inputs
+ * @return {jQuery} inputs
* @private
*/
_getInputs: function( container ) {
@@ -1050,7 +1052,7 @@
* This string can be used to compare whether or not the form has all of the same fields.
*
* @param {jQuery} inputs
- * @returns {string}
+ * @return {string}
* @private
*/
_getInputsSignature: function( inputs ) {
@@ -1073,7 +1075,7 @@
* Get the state for an input depending on its type.
*
* @param {jQuery|Element} input
- * @returns {string|boolean|array|*}
+ * @return {string|boolean|Array|*}
* @private
*/
_getInputState: function( input ) {
@@ -1093,7 +1095,7 @@
* Update an input's state based on its type.
*
* @param {jQuery|Element} input
- * @param {string|boolean|array|*} state
+ * @param {string|boolean|Array|*} state
* @private
*/
_setInputState: function ( input, state ) {
@@ -1104,7 +1106,7 @@
if ( ! $.isArray( state ) ) {
state = [];
} else {
- // Make sure all state items are strings since the DOM value is a string
+ // Make sure all state items are strings since the DOM value is a string.
state = _.map( state, function ( value ) {
return String( value );
} );
@@ -1141,10 +1143,10 @@
* Submit the widget form via Ajax and get back the updated instance,
* along with the new widget control form to render.
*
- * @param {object} [args]
+ * @param {Object} [args]
* @param {Object|null} [args.instance=null] When the model changes, the instance is sent here; otherwise, the inputs from the form are used
* @param {Function|null} [args.complete=null] Function which is called when the request finishes. Context is bound to the control. First argument is any error. Following arguments are for success.
- * @param {Boolean} [args.ignoreActiveElement=false] Whether or not updating a field will be deferred if focus is still on the element.
+ * @param {boolean} [args.ignoreActiveElement=false] Whether or not updating a field will be deferred if focus is still on the element.
*/
updateWidget: function( args ) {
var self = this, instanceOverride, completeCallback, $widgetRoot, $widgetContent,
@@ -1168,7 +1170,7 @@
$widgetRoot = this.container.find( '.widget:first' );
$widgetContent = $widgetRoot.find( '.widget-content:first' );
- // Remove a previous error message
+ // Remove a previous error message.
$widgetContent.find( '.widget-error' ).remove();
this.container.addClass( 'widget-form-loading' );
@@ -1190,9 +1192,11 @@
data = $.param( params );
$inputs = this._getInputs( $widgetContent );
- // Store the value we're submitting in data so that when the response comes back,
- // we know if it got sanitized; if there is no difference in the sanitized value,
- // then we do not need to touch the UI and mess up the user's ongoing editing.
+ /*
+ * Store the value we're submitting in data so that when the response comes back,
+ * we know if it got sanitized; if there is no difference in the sanitized value,
+ * then we do not need to touch the UI and mess up the user's ongoing editing.
+ */
$inputs.each( function() {
$( this ).data( 'state' + updateNumber, self._getInputState( this ) );
} );
@@ -1235,14 +1239,14 @@
$sanitizedInputs = self._getInputs( sanitizedForm );
hasSameInputsInResponse = self._getInputsSignature( $inputs ) === self._getInputsSignature( $sanitizedInputs );
- // Restore live update mode if sanitized fields are now aligned with the existing fields
+ // Restore live update mode if sanitized fields are now aligned with the existing fields.
if ( hasSameInputsInResponse && ! self.liveUpdateMode ) {
self.liveUpdateMode = true;
self.container.removeClass( 'widget-form-disabled' );
self.container.find( 'input[name="savewidget"]' ).hide();
}
- // Sync sanitized field states to existing fields if they are aligned
+ // Sync sanitized field states to existing fields if they are aligned.
if ( hasSameInputsInResponse && self.liveUpdateMode ) {
$inputs.each( function( i ) {
var $input = $( this ),
@@ -1261,13 +1265,13 @@
$( document ).trigger( 'widget-synced', [ $widgetRoot, r.data.form ] );
- // Otherwise, if sanitized fields are not aligned with existing fields, disable live update mode if enabled
+ // Otherwise, if sanitized fields are not aligned with existing fields, disable live update mode if enabled.
} else if ( self.liveUpdateMode ) {
self.liveUpdateMode = false;
self.container.find( 'input[name="savewidget"]' ).show();
isLiveUpdateAborted = true;
- // Otherwise, replace existing form with the sanitized form
+ // Otherwise, replace existing form with the sanitized form.
} else {
$widgetContent.html( r.data.form );
@@ -1283,11 +1287,11 @@
*/
isChanged = ! isLiveUpdateAborted && ! _( self.setting() ).isEqual( r.data.instance );
if ( isChanged ) {
- self.isWidgetUpdating = true; // suppress triggering another updateWidget
+ self.isWidgetUpdating = true; // Suppress triggering another updateWidget.
self.setting( r.data.instance );
self.isWidgetUpdating = false;
} else {
- // no change was made, so stop the spinner now instead of when the preview would updates
+ // No change was made, so stop the spinner now instead of when the preview would updates.
self.container.removeClass( 'previewer-loading' );
}
@@ -1295,7 +1299,7 @@
completeCallback.call( self, null, { noChange: ! isChanged, ajaxFinished: true } );
}
} else {
- // General error message
+ // General error message.
message = l10n.error;
if ( r.data && r.data.message ) {
@@ -1339,7 +1343,7 @@
*
* @param {Boolean} expanded
* @param {Object} [params]
- * @returns {Boolean} false if state already applied
+ * @return {Boolean} False if state already applied.
*/
_toggleExpanded: api.Section.prototype._toggleExpanded,
@@ -1347,7 +1351,7 @@
* @since 4.1.0
*
* @param {Object} [params]
- * @returns {Boolean} false if already expanded
+ * @return {Boolean} False if already expanded.
*/
expand: api.Section.prototype.expand,
@@ -1364,7 +1368,7 @@
* @since 4.1.0
*
* @param {Object} [params]
- * @returns {Boolean} false if already collapsed
+ * @return {Boolean} False if already collapsed.
*/
collapse: api.Section.prototype.collapse,
@@ -1394,7 +1398,7 @@
/**
* Respond to change in the expanded state.
*
- * @param {Boolean} expanded
+ * @param {boolean} expanded
* @param {Object} args merged on top of this.defaultActiveArguments
*/
onChangeExpanded: function ( expanded, args ) {
@@ -1405,7 +1409,7 @@
self.embedWidgetContent();
}
- // If the expanded state is unchanged only manipulate container expanded states
+ // If the expanded state is unchanged only manipulate container expanded states.
if ( args.unchanged ) {
if ( expanded ) {
api.Control.prototype.expand.call( self, {
@@ -1421,7 +1425,7 @@
expandControl = function() {
- // Close all other widget controls before expanding this one
+ // Close all other widget controls before expanding this one.
api.control.each( function( otherControl ) {
if ( self.params.type === otherControl.params.type && self !== otherControl ) {
otherControl.collapse();
@@ -1494,7 +1498,7 @@
/**
* Get the position (index) of the widget in the containing sidebar
*
- * @returns {Number}
+ * @return {number}
*/
getWidgetSidebarPosition: function() {
var sidebarWidgetIds, position;
@@ -1526,7 +1530,7 @@
/**
* @private
*
- * @param {Number} offset 1|-1
+ * @param {number} offset 1|-1
*/
_moveWidgetByOne: function( offset ) {
var i, sidebarWidgetsSetting, sidebarWidgetIds, adjacentWidgetId;
@@ -1534,7 +1538,7 @@
i = this.getWidgetSidebarPosition();
sidebarWidgetsSetting = this.getSidebarWidgetsControl().setting;
- sidebarWidgetIds = Array.prototype.slice.call( sidebarWidgetsSetting() ); // clone
+ sidebarWidgetIds = Array.prototype.slice.call( sidebarWidgetsSetting() ); // Clone.
adjacentWidgetId = sidebarWidgetIds[i + offset];
sidebarWidgetIds[i + offset] = this.params.widget_id;
sidebarWidgetIds[i] = adjacentWidgetId;
@@ -1545,7 +1549,7 @@
/**
* Toggle visibility of the widget move area
*
- * @param {Boolean} [showOrHide]
+ * @param {boolean} [showOrHide]
*/
toggleWidgetMoveArea: function( showOrHide ) {
var self = this, $moveWidgetArea;
@@ -1557,7 +1561,7 @@
}
if ( showOrHide ) {
- // reset the selected sidebar
+ // Reset the selected sidebar.
$moveWidgetArea.find( '.selected' ).removeClass( 'selected' );
$moveWidgetArea.find( 'li' ).filter( function() {
@@ -1651,7 +1655,7 @@
/**
* Update the notice.
*
- * @returns {void}
+ * @return {void}
*/
updateNotice = function() {
var activeSectionCount = getActiveSectionCount(), someRenderedMessage, nonRenderedAreaCount, registeredAreaCount;
@@ -1707,7 +1711,7 @@
*
* @since 4.4.0
*
- * @returns {boolean}
+ * @return {boolean}
*/
isContextuallyActive: function() {
var panel = this;
@@ -1780,7 +1784,7 @@
removedWidgetIds = _( oldWidgetIds ).difference( newWidgetIds );
- // Filter out any persistent widget IDs for widgets which have been deactivated
+ // Filter out any persistent widget IDs for widgets which have been deactivated.
newWidgetIds = _( newWidgetIds ).filter( function( newWidgetId ) {
var parsedWidgetId = parseWidgetId( newWidgetId );
@@ -1797,7 +1801,7 @@
return widgetFormControl;
} );
- // Sort widget controls to their new positions
+ // Sort widget controls to their new positions.
widgetFormControls.sort( function( a, b ) {
var aIndex = _.indexOf( newWidgetIds, a.params.widget_id ),
bIndex = _.indexOf( newWidgetIds, b.params.widget_id );
@@ -1810,25 +1814,26 @@
control.section( self.section() );
priority += 1;
});
- self.priority( priority ); // Make sure sidebar control remains at end
+ self.priority( priority ); // Make sure sidebar control remains at end.
- // Re-sort widget form controls (including widgets form other sidebars newly moved here)
+ // Re-sort widget form controls (including widgets form other sidebars newly moved here).
self._applyCardinalOrderClassNames();
- // If the widget was dragged into the sidebar, make sure the sidebar_id param is updated
+ // If the widget was dragged into the sidebar, make sure the sidebar_id param is updated.
_( widgetFormControls ).each( function( widgetFormControl ) {
widgetFormControl.params.sidebar_id = self.params.sidebar_id;
} );
- // Cleanup after widget removal
+ // Cleanup after widget removal.
_( removedWidgetIds ).each( function( removedWidgetId ) {
- // Using setTimeout so that when moving a widget to another sidebar, the other sidebars_widgets settings get a chance to update
+ // Using setTimeout so that when moving a widget to another sidebar,
+ // the other sidebars_widgets settings get a chance to update.
setTimeout( function() {
var removedControl, wasDraggedToAnotherSidebar, inactiveWidgets, removedIdBase,
widget, isPresentInAnotherSidebar = false;
- // Check if the widget is in another sidebar
+ // Check if the widget is in another sidebar.
api.each( function( otherSetting ) {
if ( otherSetting.id === self.setting.id || 0 !== otherSetting.id.indexOf( 'sidebars_widgets[' ) || otherSetting.id === 'sidebars_widgets[wp_inactive_widgets]' ) {
return;
@@ -1849,24 +1854,24 @@
removedControl = api.Widgets.getWidgetFormControlForWidget( removedWidgetId );
- // Detect if widget control was dragged to another sidebar
+ // Detect if widget control was dragged to another sidebar.
wasDraggedToAnotherSidebar = removedControl && $.contains( document, removedControl.container[0] ) && ! $.contains( self.$sectionContent[0], removedControl.container[0] );
- // Delete any widget form controls for removed widgets
+ // Delete any widget form controls for removed widgets.
if ( removedControl && ! wasDraggedToAnotherSidebar ) {
api.control.remove( removedControl.id );
removedControl.container.remove();
}
- // Move widget to inactive widgets sidebar (move it to trash) if has been previously saved
- // This prevents the inactive widgets sidebar from overflowing with throwaway widgets
+ // Move widget to inactive widgets sidebar (move it to Trash) if has been previously saved.
+ // This prevents the inactive widgets sidebar from overflowing with throwaway widgets.
if ( api.Widgets.savedWidgetIds[removedWidgetId] ) {
inactiveWidgets = api.value( 'sidebars_widgets[wp_inactive_widgets]' )().slice();
inactiveWidgets.push( removedWidgetId );
api.value( 'sidebars_widgets[wp_inactive_widgets]' )( _( inactiveWidgets ).unique() );
}
- // Make old single widget available for adding again
+ // Make old single widget available for adding again.
removedIdBase = parseWidgetId( removedWidgetId ).id_base;
widget = api.Widgets.availableWidgets.findWhere( { id_base: removedIdBase } );
if ( widget && ! widget.get( 'is_multi' ) ) {
@@ -1915,9 +1920,9 @@
over: function() {
var section = api.section( self.section.get() );
section.expand({
- allowMultiple: true, // Prevent the section being dragged from to be collapsed
+ allowMultiple: true, // Prevent the section being dragged from to be collapsed.
completeCallback: function () {
- // @todo It is not clear when refreshPositions should be called on which sections, or if it is even needed
+ // @todo It is not clear when refreshPositions should be called on which sections, or if it is even needed.
api.section.each( function ( otherSection ) {
if ( otherSection.container.find( '.customize-control-sidebar_widgets' ).length ) {
otherSection.container.find( '.accordion-section-content:first' ).sortable( 'refreshPositions' );
@@ -2002,7 +2007,7 @@
/**
* Enable/disable the reordering UI
*
- * @param {Boolean} showOrHide to enable/disable reordering
+ * @param {boolean} showOrHide to enable/disable reordering
*
* @todo We should have a reordering state instead and rename this to onChangeReordering
*/
@@ -2059,8 +2064,8 @@
},
/**
- * @param {string} widgetId or an id_base for adding a previously non-existing widget
- * @returns {object|false} widget_form control instance, or false on error
+ * @param {string} widgetId or an id_base for adding a previously non-existing widget.
+ * @return {Object|false} widget_form control instance, or false on error.
*/
addWidget: function( widgetId ) {
var self = this, controlHtml, $widget, controlType = 'widget_form', controlContainer, controlConstructor,
@@ -2078,7 +2083,7 @@
return false;
}
- // Set up new multi widget
+ // Set up new multi widget.
if ( widget.get( 'is_multi' ) && ! widgetNumber ) {
widget.set( 'multi_number', widget.get( 'multi_number' ) + 1 );
widgetNumber = widget.get( 'multi_number' );
@@ -2090,7 +2095,7 @@
return m.replace( /__i__|%i%/g, widgetNumber );
} );
} else {
- widget.set( 'is_disabled', true ); // Prevent single widget from being added again now
+ widget.set( 'is_disabled', true ); // Prevent single widget from being added again now.
}
$widget = $( controlHtml );
@@ -2100,7 +2105,7 @@
.addClass( 'customize-control-' + controlType )
.append( $widget );
- // Remove icon which is visible inside the panel
+ // Remove icon which is visible inside the panel.
controlContainer.find( '> .widget-icon' ).remove();
if ( widget.get( 'is_multi' ) ) {
@@ -2110,7 +2115,7 @@
widgetId = controlContainer.find( '[name="widget-id"]' ).val();
- controlContainer.hide(); // to be slid-down below
+ controlContainer.hide(); // To be slid-down below.
settingId = 'widget_' + widget.get( 'id_base' );
if ( widget.get( 'is_multi' ) ) {
@@ -2118,7 +2123,7 @@
}
controlContainer.attr( 'id', 'customize-control-' + settingId.replace( /\]/g, '' ).replace( /\[/g, '-' ) );
- // Only create setting if it doesn't already exist (if we're adding a pre-existing inactive widget)
+ // Only create setting if it doesn't already exist (if we're adding a pre-existing inactive widget).
isExistingWidget = api.has( settingId );
if ( ! isExistingWidget ) {
settingArgs = {
@@ -2126,7 +2131,7 @@
previewer: this.setting.previewer
};
setting = api.create( settingId, settingId, '', settingArgs );
- setting.set( {} ); // mark dirty, changing from '' to {}
+ setting.set( {} ); // Mark dirty, changing from '' to {}.
}
controlConstructor = api.controlConstructor[controlType];
@@ -2146,7 +2151,7 @@
} );
api.control.add( widgetFormControl );
- // Make sure widget is removed from the other sidebars
+ // Make sure widget is removed from the other sidebars.
api.each( function( otherSetting ) {
if ( otherSetting.id === self.setting.id ) {
return;
@@ -2165,7 +2170,7 @@
}
} );
- // Add widget to this sidebar
+ // Add widget to this sidebar.
sidebarWidgets = this.setting().slice();
if ( -1 === _.indexOf( sidebarWidgets, widgetId ) ) {
sidebarWidgets.push( widgetId );
@@ -2184,7 +2189,7 @@
}
} );
- // Register models for custom panel, section, and control types
+ // Register models for custom panel, section, and control types.
$.extend( api.panelConstructor, {
widgets: api.Widgets.WidgetsPanel
});
@@ -2200,15 +2205,15 @@
* Init Customizer for widgets.
*/
api.bind( 'ready', function() {
- // Set up the widgets panel
+ // Set up the widgets panel.
api.Widgets.availableWidgetsPanel = new api.Widgets.AvailableWidgetsPanelView({
collection: api.Widgets.availableWidgets
});
- // Highlight widget control
+ // Highlight widget control.
api.previewer.bind( 'highlight-widget-control', api.Widgets.highlightWidgetFormControl );
- // Open and focus widget control
+ // Open and focus widget control.
api.previewer.bind( 'focus-widget-control', api.Widgets.focusWidgetFormControl );
} );
@@ -2241,12 +2246,12 @@
/**
* Given a widget control, find the sidebar widgets control that contains it.
* @param {string} widgetId
- * @return {object|null}
+ * @return {Object|null}
*/
api.Widgets.getSidebarWidgetControlContainingWidget = function( widgetId ) {
var foundControl = null;
- // @todo this can use widgetIdToSettingId(), then pass into wp.customize.control( x ).getSidebarWidgetsControl()
+ // @todo This can use widgetIdToSettingId(), then pass into wp.customize.control( x ).getSidebarWidgetsControl().
api.control.each( function( control ) {
if ( control.params.type === 'sidebar_widgets' && -1 !== _.indexOf( control.setting(), widgetId ) ) {
foundControl = control;
@@ -2260,12 +2265,12 @@
* Given a widget ID for a widget appearing in the preview, get the widget form control associated with it.
*
* @param {string} widgetId
- * @return {object|null}
+ * @return {Object|null}
*/
api.Widgets.getWidgetFormControlForWidget = function( widgetId ) {
var foundControl = null;
- // @todo We can just use widgetIdToSettingId() here
+ // @todo We can just use widgetIdToSettingId() here.
api.control.each( function( control ) {
if ( control.params.type === 'widget_form' && control.params.widget_id === widgetId ) {
foundControl = control;
@@ -2328,8 +2333,8 @@
}
/**
- * @param {String} widgetId
- * @returns {Object}
+ * @param {string} widgetId
+ * @return {Object}
*/
function parseWidgetId( widgetId ) {
var matches, parsed = {
@@ -2342,7 +2347,7 @@
parsed.id_base = matches[1];
parsed.number = parseInt( matches[2], 10 );
} else {
- // likely an old single widget
+ // Likely an old single widget.
parsed.id_base = widgetId;
}
@@ -2350,8 +2355,8 @@
}
/**
- * @param {String} widgetId
- * @returns {String} settingId
+ * @param {string} widgetId
+ * @return {string} settingId
*/
function widgetIdToSettingId( widgetId ) {
var parsed = parseWidgetId( widgetId ), settingId;