--- a/wp/wp-admin/js/customize-nav-menus.js Mon Oct 14 18:06:33 2019 +0200
+++ b/wp/wp-admin/js/customize-nav-menus.js Mon Oct 14 18:28:13 2019 +0200
@@ -1,3 +1,7 @@
+/**
+ * @output wp-admin/js/customize-nav-menus.js
+ */
+
/* global _wpCustomizeNavMenusSettings, wpNavMenu, console */
( function( api, wp, $ ) {
'use strict';
@@ -13,6 +17,9 @@
this.jQueryExtensions();
};
+ /**
+ * @namespace wp.customize.Menus
+ */
api.Menus = api.Menus || {};
// Link settings.
@@ -35,6 +42,8 @@
* Newly-created Nav Menus and Nav Menu Items have negative integer IDs which
* serve as placeholders until Save & Publish happens.
*
+ * @alias wp.customize.Menus.generatePlaceholderAutoIncrementId
+ *
* @return {number}
*/
api.Menus.generatePlaceholderAutoIncrementId = function() {
@@ -46,7 +55,7 @@
*
* A single available menu item model. See PHP's WP_Customize_Nav_Menu_Item_Setting class.
*
- * @constructor
+ * @class wp.customize.Menus.AvailableItemModel
* @augments Backbone.Model
*/
api.Menus.AvailableItemModel = Backbone.Model.extend( $.extend(
@@ -61,10 +70,10 @@
*
* Collection for available menu item models.
*
- * @constructor
- * @augments Backbone.Model
+ * @class wp.customize.Menus.AvailableItemCollection
+ * @augments Backbone.Collection
*/
- api.Menus.AvailableItemCollection = Backbone.Collection.extend({
+ api.Menus.AvailableItemCollection = Backbone.Collection.extend(/** @lends wp.customize.Menus.AvailableItemCollection.prototype */{
model: api.Menus.AvailableItemModel,
sort_key: 'order',
@@ -84,7 +93,7 @@
* Insert a new `auto-draft` post.
*
* @since 4.7.0
- * @access public
+ * @alias wp.customize.Menus.insertAutoDraftPost
*
* @param {object} params - Parameters for the draft post to create.
* @param {string} params.post_type - Post type to add.
@@ -141,22 +150,12 @@
return deferred.promise();
};
- /**
- * wp.customize.Menus.AvailableMenuItemsPanelView
- *
- * View class for the available menu items panel.
- *
- * @constructor
- * @augments wp.Backbone.View
- * @augments Backbone.View
- */
- api.Menus.AvailableMenuItemsPanelView = wp.Backbone.View.extend({
+ api.Menus.AvailableMenuItemsPanelView = wp.Backbone.View.extend(/** @lends wp.customize.Menus.AvailableMenuItemsPanelView.prototype */{
el: '#available-menu-items',
events: {
'input #menu-items-search': 'debounceSearch',
- 'keyup #menu-items-search': 'debounceSearch',
'focus .menu-item-tpl': 'focus',
'click .menu-item-tpl': '_submit',
'click #custom-menu-item-submit': '_submitLink',
@@ -181,6 +180,14 @@
loading: false,
addingNew: false,
+ /**
+ * wp.customize.Menus.AvailableMenuItemsPanelView
+ *
+ * View class for the available menu items panel.
+ *
+ * @constructs wp.customize.Menus.AvailableMenuItemsPanelView
+ * @augments wp.Backbone.View
+ */
initialize: function() {
var self = this;
@@ -537,6 +544,7 @@
var menuItem,
itemName = $( '#custom-menu-item-name' ),
itemUrl = $( '#custom-menu-item-url' ),
+ url = itemUrl.val().trim(),
urlRegex;
if ( ! this.currentMenuControl ) {
@@ -560,14 +568,14 @@
if ( '' === itemName.val() ) {
itemName.addClass( 'invalid' );
return;
- } else if ( ! urlRegex.test( itemUrl.val() ) ) {
+ } else if ( ! urlRegex.test( url ) ) {
itemUrl.addClass( 'invalid' );
return;
}
menuItem = {
'title': itemName.val(),
- 'url': itemUrl.val(),
+ 'url': url,
'type': 'custom',
'type_label': api.Menus.data.l10n.custom_label,
'object': 'custom'
@@ -753,10 +761,10 @@
* Customizer panel for menus. This is used only for screen options management.
* Note that 'menus' must match the WP_Customize_Menu_Panel::$type.
*
- * @constructor
+ * @class wp.customize.Menus.MenusPanel
* @augments wp.customize.Panel
*/
- api.Menus.MenusPanel = api.Panel.extend({
+ api.Menus.MenusPanel = api.Panel.extend(/** @lends wp.customize.Menus.MenusPanel.prototype */{
attachEvents: function() {
api.Panel.prototype.attachEvents.call( this );
@@ -885,10 +893,10 @@
* Customizer section for menus. This is used only for lazy-loading child controls.
* Note that 'nav_menu' must match the WP_Customize_Menu_Section::$type.
*
- * @constructor
+ * @class wp.customize.Menus.MenuSection
* @augments wp.customize.Section
*/
- api.Menus.MenuSection = api.Section.extend({
+ api.Menus.MenuSection = api.Section.extend(/** @lends wp.customize.Menus.MenuSection.prototype */{
/**
* Initialize.
@@ -1212,10 +1220,10 @@
*
* Customizer section for new menus.
*
- * @constructor
+ * @class wp.customize.Menus.NewMenuSection
* @augments wp.customize.Section
*/
- api.Menus.NewMenuSection = api.Section.extend({
+ api.Menus.NewMenuSection = api.Section.extend(/** @lends wp.customize.Menus.NewMenuSection.prototype */{
/**
* Add behaviors for the accordion section.
@@ -1451,10 +1459,10 @@
* Customizer control for menu locations (rendered as a <select>).
* Note that 'nav_menu_location' must match the WP_Customize_Nav_Menu_Location_Control::$type.
*
- * @constructor
+ * @class wp.customize.Menus.MenuLocationControl
* @augments wp.customize.Control
*/
- api.Menus.MenuLocationControl = api.Control.extend({
+ api.Menus.MenuLocationControl = api.Control.extend(/** @lends wp.customize.Menus.MenuLocationControl.prototype */{
initialize: function( id, options ) {
var control = this,
matches = id.match( /^nav_menu_locations\[(.+?)]/ );
@@ -1529,19 +1537,18 @@
}
});
- /**
- * wp.customize.Menus.MenuItemControl
- *
- * Customizer control for menu items.
- * Note that 'menu_item' must match the WP_Customize_Menu_Item_Control::$type.
- *
- * @constructor
- * @augments wp.customize.Control
- */
- api.Menus.MenuItemControl = api.Control.extend({
+ api.Menus.MenuItemControl = api.Control.extend(/** @lends wp.customize.Menus.MenuItemControl.prototype */{
/**
- * @inheritdoc
+ * wp.customize.Menus.MenuItemControl
+ *
+ * Customizer control for menu items.
+ * Note that 'menu_item' must match the WP_Customize_Menu_Item_Control::$type.
+ *
+ * @constructs wp.customize.Menus.MenuItemControl
+ * @augments wp.customize.Control
+ *
+ * @inheritDoc
*/
initialize: function( id, options ) {
var control = this;
@@ -2324,10 +2331,10 @@
*
* Customizer control for a nav menu's name.
*
- * @constructor
+ * @class wp.customize.Menus.MenuNameControl
* @augments wp.customize.Control
*/
- api.Menus.MenuNameControl = api.Control.extend({
+ api.Menus.MenuNameControl = api.Control.extend(/** @lends wp.customize.Menus.MenuNameControl.prototype */{
ready: function() {
var control = this;
@@ -2364,10 +2371,10 @@
* Customizer control for a nav menu's locations.
*
* @since 4.9.0
- * @constructor
+ * @class wp.customize.Menus.MenuLocationsControl
* @augments wp.customize.Control
*/
- api.Menus.MenuLocationsControl = api.Control.extend({
+ api.Menus.MenuLocationsControl = api.Control.extend(/** @lends wp.customize.Menus.MenuLocationsControl.prototype */{
/**
* Set up the control.
@@ -2437,10 +2444,10 @@
*
* Customizer control for a nav menu's auto add.
*
- * @constructor
+ * @class wp.customize.Menus.MenuAutoAddControl
* @augments wp.customize.Control
*/
- api.Menus.MenuAutoAddControl = api.Control.extend({
+ api.Menus.MenuAutoAddControl = api.Control.extend(/** @lends wp.customize.Menus.MenuAutoAddControl.prototype */{
ready: function() {
var control = this,
@@ -2490,10 +2497,10 @@
* Customizer control for menus.
* Note that 'nav_menu' must match the WP_Menu_Customize_Control::$type
*
- * @constructor
+ * @class wp.customize.Menus.MenuControl
* @augments wp.customize.Control
*/
- api.Menus.MenuControl = api.Control.extend({
+ api.Menus.MenuControl = api.Control.extend(/** @lends wp.customize.Menus.MenuControl.prototype */{
/**
* Set up the control.
*/
@@ -3021,22 +3028,18 @@
}
} );
- /**
- * wp.customize.Menus.NewMenuControl
- *
- * Customizer control for creating new menus and handling deletion of existing menus.
- * Note that 'new_menu' must match the WP_Customize_New_Menu_Control::$type.
- *
- * @constructor
- * @augments wp.customize.Control
- * @deprecated 4.9.0 This class is no longer used due to new menu creation UX.
- */
- api.Menus.NewMenuControl = api.Control.extend({
+ api.Menus.NewMenuControl = api.Control.extend(/** @lends wp.customize.Menus.NewMenuControl.prototype */{
/**
- * Initialize.
+ * wp.customize.Menus.NewMenuControl
+ *
+ * Customizer control for creating new menus and handling deletion of existing menus.
+ * Note that 'new_menu' must match the WP_Customize_New_Menu_Control::$type.
*
- * @deprecated 4.9.0
+ * @constructs wp.customize.Menus.NewMenuControl
+ * @augments wp.customize.Control
+ *
+ * @deprecated 4.9.0 This class is no longer used due to new menu creation UX.
*/
initialize: function() {
if ( 'undefined' !== typeof console && console.warn ) {
@@ -3111,7 +3114,7 @@
nav_menu_item: api.Menus.MenuItemControl,
nav_menu: api.Menus.MenuControl,
nav_menu_name: api.Menus.MenuNameControl,
- new_menu: api.Menus.NewMenuControl, // @todo Remove in 5.0. See #42364.
+ new_menu: api.Menus.NewMenuControl, // @todo Remove in a future release. See #42364.
nav_menu_locations: api.Menus.MenuLocationsControl,
nav_menu_auto_add: api.Menus.MenuAutoAddControl
});
@@ -3166,6 +3169,8 @@
* When customize_save comes back with a success, make sure any inserted
* nav menus and items are properly re-added with their newly-assigned IDs.
*
+ * @alias wp.customize.Menus.applySavedData
+ *
* @param {object} data
* @param {array} data.nav_menu_updates
* @param {array} data.nav_menu_item_updates
@@ -3396,6 +3401,8 @@
/**
* Focus a menu item control.
*
+ * @alias wp.customize.Menus.focusMenuItemControl
+ *
* @param {string} menuItemId
*/
api.Menus.focusMenuItemControl = function( menuItemId ) {
@@ -3408,6 +3415,8 @@
/**
* Get the control for a given menu.
*
+ * @alias wp.customize.Menus.getMenuControl
+ *
* @param menuId
* @return {wp.customize.controlConstructor.menus[]}
*/
@@ -3418,6 +3427,8 @@
/**
* Given a menu item ID, get the control associated with it.
*
+ * @alias wp.customize.Menus.getMenuItemControl
+ *
* @param {string} menuItemId
* @return {object|null}
*/
@@ -3426,6 +3437,8 @@
};
/**
+ * @alias wp.customize.Menus~menuItemIdToSettingId
+ *
* @param {String} menuItemId
*/
function menuItemIdToSettingId( menuItemId ) {
@@ -3436,12 +3449,14 @@
* Apply sanitize_text_field()-like logic to the supplied name, returning a
* "unnammed" fallback string if the name is then empty.
*
+ * @alias wp.customize.Menus~displayNavMenuName
+ *
* @param {string} name
* @returns {string}
*/
function displayNavMenuName( name ) {
name = name || '';
- name = $( '<div>' ).text( name ).html(); // Emulate esc_html() which is used in wp-admin/nav-menus.php.
+ name = wp.sanitize.stripTagsAndEncodeText( name ); // Remove any potential tags from name.
name = $.trim( name );
return name || api.Menus.data.l10n.unnamed;
}