enmi-conf.org: comparison wp/wp-admin/js/customize-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-admin/js/customize-widgets.js

changeset 16	a86126ab1dd4
parent 9	177826044cd9
child 18	be944660c56a

equal deleted inserted replaced

-:3d4e9c994f10
+:a86126ab1dd4
 	 * @namespace wp.customize.Widgets
 	 */
 	api.Widgets = api.Widgets || {};
 	api.Widgets.savedWidgetIds = {};
-	// Link settings
+	// Link settings.
 	api.Widgets.data = _wpCustomizeWidgetsSettings || {};
 	l10n = api.Widgets.data.l10n;
 	/**
 	 * wp.customize.Widgets.WidgetModel
 	 */
 	api.Widgets.WidgetCollection = Backbone.Collection.extend(/** @lends wp.customize.Widgets.WidgetCollection.prototype */{
 		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
+			// Don't do anything if we've already done this search.
-			// Useful because the search handler fires multiple times per keystroke
+			// 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...
 			if ( this.terms.length > 0 ) {
 				this.search( this.terms );
 					widget.set( 'search_matched', true );
 				} );
 			}
 		},
-		// 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' );
 			this.each( function ( data ) {
 				haystack = [ data.get( 'name' ), data.get( 'id' ), data.get( 'description' ) ].join( ' ' );
 			'click .widget-tpl' : '_submit',
 			'keypress .widget-tpl' : '_submit',
 			'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,
 		searchMatchesCount: null,
 			this.updateList();
 			// 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
+			 * If the available widgets panel is open and the customize controls
-			// available widgets panel. Also close on back button click.
+			 * 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 ) {
 					self.close();
 				}
 			} );
-			// 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 );
 		},
 		/**
 		 * Performs a search and handles selected widget.
 			// Update the search matches count.
 			this.updateSearchMatchesCount();
 			// 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 ) {
 					this.select( firstVisible );
 				}
 		/**
 		 * 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;
 			}
 			this.submit( $( event.currentTarget ) );
 		 * Opens the panel.
 		 */
 		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();
 				}
 			} );
 			$( 'body' ).addClass( 'adding-widget' );
 			this.$el.find( '.selected' ).removeClass( 'selected' );
-			// Reset search
+			// Reset search.
 			this.collection.doSearch( '' );
 			if ( ! api.settings.browser.mobile ) {
 				this.$search.focus();
 			}
 			this.currentSidebarControl = null;
 			this.selected = null;
 			$( 'body' ).removeClass( 'adding-widget' );
-			this.$search.val( '' );
+			this.$search.val( '' ).trigger( 'input' );
 		},
 		/**
 		 * Adds keyboard accessiblity to the panel.
 		 */
 				}
 				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;
 			}
 			if ( isEnter ) {
 	api.Widgets.formSyncHandlers = {
 		/**
 		 * @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' ),
 				newWidgetError = $( '<div>' + newForm + '</div>' ).find( '.widget-error:first' );
 		 * Handle changes to the setting
 		 */
 		_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;
 			};
 			api.bind( 'ready', rememberSavedWidgetId );
 			api.bind( 'saved', rememberSavedWidgetId );
 			this._updateCount = 0;
 			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 } );
 				}
 			} );
 					windowHeight = $( window ).height(),
 					formHeight = $widgetForm.outerHeight(),
 					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
+						Math.max( offsetTop, 0 ), // Distance widget in panel is from top of screen.
-						windowHeight - formHeight // flush up against bottom of screen
+						windowHeight - formHeight // Flush up against bottom of screen.
 					)
 				);
 				$widgetInside.css( 'top', top );
 			};
 				$customizeSidebar.off( 'scroll', positionWidget );
 				$( window ).off( 'resize', positionWidget );
 				$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() {
 						if ( self.container.hasClass( 'expanded' ) ) {
 							positionWidget();
 			} );
 			$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.
 			} );
 		},
 		/**
 		 * Update the title of the form if a title field is entered
 					} else {
 						self.moveDown();
 						wp.a11y.speak( l10n.widgetMovedDown );
 					}
-					$( this ).focus(); // re-focus after the container was moved
+					$( this ).focus(); // Re-focus after the container was moved.
 				}
 			} );
 			/**
 			 * Handle selecting a sidebar to move to
 		 * Highlight widgets in preview when interacted with in the Customizer
 		 */
 		_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 );
 			} );
 		},
 				$saveBtn, updateWidgetDebounced, formSyncHandler;
 			$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 );
 			$saveBtn.removeClass( 'button-primary' );
 			$saveBtn.on( 'click', function( e ) {
 			updateWidgetDebounced = _.debounce( function() {
 				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;
 				}
 				if ( e.type === 'change' || ( this.checkValidity && this.checkValidity() ) ) {
 					updateWidgetDebounced();
 				}
 			} );
-			// 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' );
 			} );
 			api.previewer.bind( 'widget-updated', function( updatedWidgetId ) {
 		 *
 		 * Overrides api.Control.toggle()
 		 *
 		 * @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();
 			}
 		},
 		 * Set up event handlers for widget removal
 		 */
 		_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' );
 				} else if ( self.container.prev().is( '.customize-control-widget_form' ) ) {
 					$adjacentFocusTarget = self.container.prev().find( '.widget-action:first' );
 					}
 					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 );
 			};
 			if ( this.params.is_new ) {
 				api.bind( 'saved', replaceDeleteWithRemove );
 		 * be aligned to copy the sanitized over. The elements returned by this
 		 * are passed into this._getInputsSignature(), and they are iterated
 		 * 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 ) {
 			return $( container ).find( ':input[name]' );
 		},
 		/**
 		 * Iterate over supplied inputs and create a signature string for all of them together.
 		 * 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 ) {
 			var inputsSignatures = _( inputs ).map( function( input ) {
 				var $input = $( input ), signatureParts;
 		/**
 		 * 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 ) {
 			input = $( input );
 			if ( input.is( ':radio, :checkbox' ) ) {
 		/**
 		 * 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 ) {
 			input = $( input );
 			if ( input.is( ':radio, :checkbox' ) ) {
 				input.prop( 'checked', state );
 			} else if ( input.is( 'select[multiple]' ) ) {
 				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 );
 					} );
 				}
 				input.find( 'option' ).each( function () {
 		/**
 		 * 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,
 				updateNumber, params, data, $inputs, processing, jqxhr, isChanged;
 			updateNumber = this._updateCount;
 			$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' );
 			this.container.addClass( 'previewer-loading' );
 			processing = api.state( 'processing' );
 			params.customized = wp.customize.previewer.query().customized;
 			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,
+			 * Store the value we're submitting in data so that when the response comes back,
-			// then we do not need to touch the UI and mess up the user's ongoing editing.
+			 * 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 ) );
 			} );
 			if ( instanceOverride ) {
 				if ( r.success ) {
 					sanitizedForm = $( '<div>' + r.data.form + '</div>' );
 					$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 ),
 								$sanitizedInput = $( $sanitizedInputs[i] ),
 								submittedState, sanitizedState,	canUpdateState;
 							}
 						} );
 						$( 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 );
 						self.container.removeClass( 'widget-form-disabled' );
 					 * needing to be rendered, and so we can preempt the event for the
 					 * preview finishing loading.
 					 */
 					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' );
 					}
 					if ( completeCallback ) {
 						completeCallback.call( self, null, { noChange: ! isChanged, ajaxFinished: true } );
 					}
 				} else {
-					// General error message
+					// General error message.
 					message = l10n.error;
 					if ( r.data && r.data.message ) {
 						message = r.data.message;
 					}
 		/**
 		 * @since 4.1.0
 		 *
 		 * @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,
 		/**
 		 * @since 4.1.0
 		 *
 		 * @param {Object} [params]
-		 * @returns {Boolean} false if already expanded
+		 * @return {Boolean} False if already expanded.
 		 */
 		expand: api.Section.prototype.expand,
 		/**
 		 * Expand the widget form control
 		/**
 		 * @since 4.1.0
 		 *
 		 * @param {Object} [params]
-		 * @returns {Boolean} false if already collapsed
+		 * @return {Boolean} False if already collapsed.
 		 */
 		collapse: api.Section.prototype.collapse,
 		/**
 		 * Collapse the widget form control
 		},
 		/**
 		 * 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 ) {
 			var self = this, $widget, $inside, complete, prevComplete, expandControl, $toggleBtn;
 			self.embedWidgetControl(); // Make sure the outer form is embedded so that the expanded state can be set in the UI.
 			if ( expanded ) {
 				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, {
 						completeCallback:  args.completeCallback
 					});
 			$inside = $widget.find( '.widget-inside:first' );
 			$toggleBtn = this.container.find( '.widget-top button.widget-action' );
 			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();
 					}
 				} );
 		},
 		/**
 		 * Get the position (index) of the widget in the containing sidebar
 		 *
-		 * @returns {Number}
+		 * @return {number}
 		 */
 		getWidgetSidebarPosition: function() {
 			var sidebarWidgetIds, position;
 			sidebarWidgetIds = this.getSidebarWidgetsControl().setting();
 		},
 		/**
 		 * @private
 		 *
-		 * @param {Number} offset 1|-1
+		 * @param {number} offset 1|-1
 		 */
 		_moveWidgetByOne: function( offset ) {
 			var i, sidebarWidgetsSetting, sidebarWidgetIds,	adjacentWidgetId;
 			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;
 			sidebarWidgetsSetting( sidebarWidgetIds );
 		},
 		/**
 		 * Toggle visibility of the widget move area
 		 *
-		 * @param {Boolean} [showOrHide]
+		 * @param {boolean} [showOrHide]
 		 */
 		toggleWidgetMoveArea: function( showOrHide ) {
 			var self = this, $moveWidgetArea;
 			$moveWidgetArea = this.container.find( '.move-widget-area' );
 			if ( typeof showOrHide === 'undefined' ) {
 				showOrHide = ! $moveWidgetArea.hasClass( 'active' );
 			}
 			if ( showOrHide ) {
-				// reset the selected sidebar
+				// Reset the selected sidebar.
 				$moveWidgetArea.find( '.selected' ).removeClass( 'selected' );
 				$moveWidgetArea.find( 'li' ).filter( function() {
 					return $( this ).data( 'id' ) === self.params.sidebar_id;
 				} ).addClass( 'selected' );
 				};
 				/**
 				 * Update the notice.
 				 *
-				 * @returns {void}
+				 * @return {void}
 				 */
 				updateNotice = function() {
 					var activeSectionCount = getActiveSectionCount(), someRenderedMessage, nonRenderedAreaCount, registeredAreaCount;
 					noticeContainer.empty();
 		 * This ensures that the widgets panel appears even when there are no
 		 * sidebars displayed on the URL currently being previewed.
 		 *
 		 * @since 4.4.0
 		 *
-		 * @returns {boolean}
+		 * @return {boolean}
 		 */
 		isContextuallyActive: function() {
 			var panel = this;
 			return panel.active();
 		}
 			this.setting.bind( function( newWidgetIds, oldWidgetIds ) {
 				var widgetFormControls, removedWidgetIds, priority;
 				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 );
 					return !! api.Widgets.availableWidgets.findWhere( { id_base: parsedWidgetId.id_base } );
 				} );
 					}
 					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 );
 					return aIndex - bIndex;
 				});
 				_( widgetFormControls ).each( function ( control ) {
 					control.priority( priority );
 					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;
 							}
 							return;
 						}
 						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
+						// 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
+						// 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' ) ) {
 							widget.set( 'is_disabled', false );
 						}
 			this.$controlSection.find( '.accordion-section-title' ).droppable({
 				accept: '.customize-control-widget_form',
 				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' );
 								}
 							} );
 		 **********************************************************************/
 		/**
 		 * 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
 		 */
 		toggleReordering: function( showOrHide ) {
 			var addNewWidgetBtn = this.$sectionContent.find( '.add-new-widget' ),
 			return formControls;
 		},
 		/**
-		 * @param {string} widgetId or an id_base for adding a previously non-existing widget
+		 * @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
+		 * @return {Object|false} widget_form control instance, or false on error.
 		 */
 		addWidget: function( widgetId ) {
 			var self = this, controlHtml, $widget, controlType = 'widget_form', controlContainer, controlConstructor,
 				parsedWidgetId = parseWidgetId( widgetId ),
 				widgetNumber = parsedWidgetId.number,
 			if ( widgetNumber && ! widget.get( 'is_multi' ) ) {
 				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' );
 			}
 			if ( widget.get( 'is_multi' ) ) {
 				controlHtml = controlHtml.replace( /<[^<>]+>/g, function( m ) {
 					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 );
 			controlContainer = $( '<li/>' )
 				.addClass( 'customize-control' )
 				.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' ) ) {
 				controlContainer.find( 'input[name="widget_number"]' ).val( widgetNumber );
 				controlContainer.find( 'input[name="multi_number"]' ).val( widgetNumber );
 			}
 			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' ) ) {
 				settingId += '[' + widgetNumber + ']';
 			}
 			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 = {
 					transport: api.Widgets.data.selectiveRefreshableWidgets[ widget.get( 'id_base' ) ] ? 'postMessage' : 'refresh',
 					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];
 			widgetFormControl = new controlConstructor( settingId, {
 				settings: {
 				height: widget.get( 'height' ),
 				is_wide: widget.get( 'is_wide' )
 			} );
 			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;
 				}
 					otherSidebarWidgets.splice( i );
 					otherSetting( otherSidebarWidgets );
 				}
 			} );
-			// Add widget to this sidebar
+			// Add widget to this sidebar.
 			sidebarWidgets = this.setting().slice();
 			if ( -1 === _.indexOf( sidebarWidgets, widgetId ) ) {
 				sidebarWidgets.push( widgetId );
 				this.setting( sidebarWidgets );
 			}
 			return widgetFormControl;
 		}
 	} );
-	// 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
 	});
 	$.extend( api.sectionConstructor, {
 		sidebar: api.Widgets.SidebarSection
 	/**
 	 * 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 );
 	} );
 	/**
 	 * Highlight a widget control.
 	},
 	/**
 	 * 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;
 			}
 		} );
 	/**
 	 * 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;
 			}
 		} );
 		}
 		focusConstruct.expanded.bind( onceCollapsed );
 	}
 	/**
-	 * @param {String} widgetId
+	 * @param {string} widgetId
-	 * @returns {Object}
+	 * @return {Object}
 	 */
 	function parseWidgetId( widgetId ) {
 		var matches, parsed = {
 			number: null,
 			id_base: null
 		matches = widgetId.match( /^(.+)-(\d+)$/ );
 		if ( matches ) {
 			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;
 		}
 		return parsed;
 	}
 	/**
-	 * @param {String} widgetId
+	 * @param {string} widgetId
-	 * @returns {String} settingId
+	 * @return {string} settingId
 	 */
 	function widgetIdToSettingId( widgetId ) {
 		var parsed = parseWidgetId( widgetId ), settingId;
 		settingId = 'widget_' + parsed.id_base;

enmi-conf.org