diff -r c7c34916027a -r 177826044cd9 wp/wp-admin/js/customize-widgets.js --- a/wp/wp-admin/js/customize-widgets.js Mon Oct 14 18:06:33 2019 +0200 +++ b/wp/wp-admin/js/customize-widgets.js Mon Oct 14 18:28:13 2019 +0200 @@ -1,3 +1,7 @@ +/** + * @output wp-admin/js/customize-widgets.js + */ + /* global _wpCustomizeWidgetsSettings */ (function( wp, $ ){ @@ -7,6 +11,9 @@ var api = wp.customize, l10n; + /** + * @namespace wp.customize.Widgets + */ api.Widgets = api.Widgets || {}; api.Widgets.savedWidgetIds = {}; @@ -19,10 +26,10 @@ * * A single widget model. * - * @constructor + * @class wp.customize.Widgets.WidgetModel * @augments Backbone.Model */ - api.Widgets.WidgetModel = Backbone.Model.extend({ + api.Widgets.WidgetModel = Backbone.Model.extend(/** @lends wp.customize.Widgets.WidgetModel.prototype */{ id: null, temp_id: null, classname: null, @@ -45,10 +52,10 @@ * * Collection for widget models. * - * @constructor - * @augments Backbone.Model + * @class wp.customize.Widgets.WidgetCollection + * @augments Backbone.Collection */ - api.Widgets.WidgetCollection = Backbone.Collection.extend({ + api.Widgets.WidgetCollection = Backbone.Collection.extend(/** @lends wp.customize.Widgets.WidgetCollection.prototype */{ model: api.Widgets.WidgetModel, // Controls searching on the current widget collection @@ -103,10 +110,10 @@ * * A single sidebar model. * - * @constructor + * @class wp.customize.Widgets.SidebarModel * @augments Backbone.Model */ - api.Widgets.SidebarModel = Backbone.Model.extend({ + api.Widgets.SidebarModel = Backbone.Model.extend(/** @lends wp.customize.Widgets.SidebarModel.prototype */{ after_title: null, after_widget: null, before_title: null, @@ -123,30 +130,20 @@ * * Collection for sidebar models. * - * @constructor + * @class wp.customize.Widgets.SidebarCollection * @augments Backbone.Collection */ - api.Widgets.SidebarCollection = Backbone.Collection.extend({ + api.Widgets.SidebarCollection = Backbone.Collection.extend(/** @lends wp.customize.Widgets.SidebarCollection.prototype */{ model: api.Widgets.SidebarModel }); api.Widgets.registeredSidebars = new api.Widgets.SidebarCollection( api.Widgets.data.registeredSidebars ); - /** - * wp.customize.Widgets.AvailableWidgetsPanelView - * - * View class for the available widgets panel. - * - * @constructor - * @augments wp.Backbone.View - * @augments Backbone.View - */ - api.Widgets.AvailableWidgetsPanelView = wp.Backbone.View.extend({ + api.Widgets.AvailableWidgetsPanelView = wp.Backbone.View.extend(/** @lends wp.customize.Widgets.AvailableWidgetsPanelView.prototype */{ el: '#available-widgets', events: { 'input #widgets-search': 'search', - 'keyup #widgets-search': 'search', 'focus .widget-tpl' : 'focus', 'click .widget-tpl' : '_submit', 'keypress .widget-tpl' : '_submit', @@ -162,6 +159,12 @@ $clearResults: null, searchMatchesCount: null, + /** + * View class for the available widgets panel. + * + * @constructs wp.customize.Widgets.AvailableWidgetsPanelView + * @augments wp.Backbone.View + */ initialize: function() { var self = this; @@ -197,8 +200,10 @@ api.previewer.bind( 'url', this.close ); }, - // Performs a search and handles selected widget - search: function( event ) { + /** + * Performs a search and handles selected widget. + */ + search: _.debounce( function( event ) { var firstVisible; this.collection.doSearch( event.target.value ); @@ -240,15 +245,19 @@ } else { this.$el.removeClass( 'no-widgets-found' ); } - }, + }, 500 ), - // Update the count of the available widgets that have the `search_matched` attribute. + /** + * Updates the count of the available widgets that have the `search_matched` attribute. + */ updateSearchMatchesCount: function() { this.searchMatchesCount = this.collection.where({ search_matched: true }).length; }, - // Send a message to the aria-live region to announce how many search results. - announceSearchMatches: _.debounce( function() { + /** + * Sends a message to the aria-live region to announce how many search results. + */ + announceSearchMatches: function() { var message = l10n.widgetsFound.replace( '%d', this.searchMatchesCount ) ; if ( ! this.searchMatchesCount ) { @@ -256,9 +265,11 @@ } wp.a11y.speak( message ); - }, 500 ), + }, - // Changes visibility of available widgets + /** + * Changes visibility of available widgets. + */ updateList: function() { this.collection.each( function( widget ) { var widgetTpl = $( '#widget-tpl-' + widget.id ); @@ -269,19 +280,25 @@ } ); }, - // Highlights a widget + /** + * Highlights a widget. + */ select: function( widgetTpl ) { this.selected = $( widgetTpl ); this.selected.siblings( '.widget-tpl' ).removeClass( 'selected' ); this.selected.addClass( 'selected' ); }, - // Highlights a widget on focus + /** + * Highlights a widget on focus. + */ focus: function( event ) { this.select( $( event.currentTarget ) ); }, - // Submit handler for keypress and click on widget + /** + * Handles submit for keypress and click on widget. + */ _submit: function( event ) { // Only proceed with keypress if it is Enter or Spacebar if ( event.type === 'keypress' && ( event.which !== 13 && event.which !== 32 ) ) { @@ -291,7 +308,9 @@ this.submit( $( event.currentTarget ) ); }, - // Adds a selected widget to the sidebar + /** + * Adds a selected widget to the sidebar. + */ submit: function( widgetTpl ) { var widgetId, widget, widgetFormControl; @@ -319,7 +338,9 @@ this.close(); }, - // Opens the panel + /** + * Opens the panel. + */ open: function( sidebarControl ) { this.currentSidebarControl = sidebarControl; @@ -346,7 +367,9 @@ } }, - // Closes the panel + /** + * Closes the panel. + */ close: function( options ) { options = options || {}; @@ -362,7 +385,9 @@ this.$search.val( '' ); }, - // Add keyboard accessiblity to the panel + /** + * Adds keyboard accessiblity to the panel. + */ keyboardAccessible: function( event ) { var isEnter = ( event.which === 13 ), isEsc = ( event.which === 27 ), @@ -424,6 +449,8 @@ * Handlers for the widget-synced event, organized by widget ID base. * Other widgets may provide their own update handlers by adding * listeners for the widget-synced event. + * + * @alias wp.customize.Widgets.formSyncHandlers */ api.Widgets.formSyncHandlers = { @@ -446,23 +473,22 @@ } }; - /** - * wp.customize.Widgets.WidgetControl - * - * Customizer control for widgets. - * Note that 'widget_form' must match the WP_Widget_Form_Customize_Control::$type - * - * @constructor - * @augments wp.customize.Control - */ - api.Widgets.WidgetControl = api.Control.extend({ + api.Widgets.WidgetControl = api.Control.extend(/** @lends wp.customize.Widgets.WidgetControl.prototype */{ defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop }, /** + * wp.customize.Widgets.WidgetControl + * + * Customizer control for widgets. + * Note that 'widget_form' must match the WP_Widget_Form_Customize_Control::$type + * * @since 4.1.0 + * + * @constructs wp.customize.Widgets.WidgetControl + * @augments wp.customize.Control */ initialize: function( id, options ) { var control = this; @@ -682,8 +708,7 @@ } ); $closeBtn = this.container.find( '.widget-control-close' ); - $closeBtn.on( 'click', function( e ) { - e.preventDefault(); + $closeBtn.on( 'click', function() { self.collapse(); self.container.find( '.widget-top .widget-action:first' ).focus(); // keyboard accessibility } ); @@ -943,7 +968,7 @@ * * @param {Boolean} active * @param {Object} args - * @param {Callback} args.completeCallback + * @param {function} args.completeCallback */ onChangeActive: function ( active, args ) { // Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments @@ -961,9 +986,7 @@ // Configure remove button $removeBtn = this.container.find( '.widget-control-remove' ); - $removeBtn.on( 'click', function( e ) { - e.preventDefault(); - + $removeBtn.on( 'click', function() { // Find an adjacent element to add focus to when this widget goes away var $adjacentFocusTarget; if ( self.container.next().is( '.customize-control-widget_form' ) ) { @@ -1574,8 +1597,11 @@ * Customizer panel containing the widget area sections. * * @since 4.4.0 + * + * @class wp.customize.Widgets.WidgetsPanel + * @augments wp.customize.Panel */ - api.Widgets.WidgetsPanel = api.Panel.extend({ + api.Widgets.WidgetsPanel = api.Panel.extend(/** @lends wp.customize.Widgets.WigetsPanel.prototype */{ /** * Add and manage the display of the no-rendered-areas notice. @@ -1604,7 +1630,7 @@ */ getActiveSectionCount = function() { return _.filter( panel.sections(), function( section ) { - return section.active(); + return 'sidebar' === section.params.type && section.active(); } ).length; }; @@ -1695,8 +1721,11 @@ * Customizer section representing a widget area widget * * @since 4.1.0 + * + * @class wp.customize.Widgets.SidebarSection + * @augments wp.customize.Section */ - api.Widgets.SidebarSection = api.Section.extend({ + api.Widgets.SidebarSection = api.Section.extend(/** @lends wp.customize.Widgets.SidebarSection.prototype */{ /** * Sync the section's active state back to the Backbone model's is_rendered attribute @@ -1722,10 +1751,10 @@ * * @since 3.9.0 * - * @constructor + * @class wp.customize.Widgets.SidebarControl * @augments wp.customize.Control */ - api.Widgets.SidebarControl = api.Control.extend({ + api.Widgets.SidebarControl = api.Control.extend(/** @lends wp.customize.Widgets.SidebarControl.prototype */{ /** * Set up the control