--- 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