diff --git src/wp-admin/js/common.js src/wp-admin/js/common.js index 9d8af9b..9c49be8 100644 --- src/wp-admin/js/common.js +++ src/wp-admin/js/common.js @@ -247,6 +247,13 @@ $(document).ready( function() { $( document ).trigger( 'wp-collapse-menu', { state: state } ); }); + /** + * Ensure an admin submenu is within the visual viewport. + * + * @since 4.1.0 + * + * @param {jQuery} $menuItem The parent menu item containing the submenu. + */ function adjustSubmenu( $menuItem ) { var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop, $submenu = $menuItem.find( '.wp-submenu' ); diff --git src/wp-admin/js/customize-controls.js src/wp-admin/js/customize-controls.js index 7b9f7b1..23fa4f5 100644 --- src/wp-admin/js/customize-controls.js +++ src/wp-admin/js/customize-controls.js @@ -35,8 +35,10 @@ /** * Watch all changes to Value properties, and bubble changes to parent Values instance * + * @since 4.1.0 + * * @param {wp.customize.Class} instance - * @param {Array} properties The names of the Value instances to watch. + * @param {Array} properties The names of the Value instances to watch. */ bubbleChildValueChanges = function ( instance, properties ) { $.each( properties, function ( i, key ) { @@ -51,7 +53,10 @@ /** * Expand a panel, section, or control and focus on the first focusable element. * - * @param {Object} [params] + * @since 4.1.0 + * + * @param {Object} [params] + * @param {Callback} [params.completeCallback] */ focus = function ( params ) { var construct, completeCallback, focus; @@ -82,6 +87,8 @@ * * If a.priority() === b.priority(), then sort by their respective params.instanceNumber. * + * @since 4.1.0 + * * @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} a * @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} b * @returns {Number} @@ -97,6 +104,8 @@ /** * Return whether the supplied Event object is for a keydown event but not the Enter key. * + * @since 4.1.0 + * * @param {jQuery.Event} event * @returns {boolean} */ @@ -107,6 +116,8 @@ /** * Return whether the two lists of elements are the same and are in the same order. * + * @since 4.1.0 + * * @param {Array|jQuery} listA * @param {Array|jQuery} listB * @returns {boolean} @@ -125,7 +136,9 @@ }; /** - * Base class for Panel and Section + * Base class for Panel and Section. + * + * @since 4.1.0 * * @class * @augments wp.customize.Class @@ -134,6 +147,12 @@ defaultActiveArguments: { duration: 'fast', completeCallback: $.noop }, defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop }, + /** + * @since 4.1.0 + * + * @param {String} id + * @param {Object} options + */ initialize: function ( id, options ) { var container = this; container.id = id; @@ -174,6 +193,8 @@ }, /** + * @since 4.1.0 + * * @abstract */ ready: function() {}, @@ -181,6 +202,8 @@ /** * Get the child models associated with this parent, sorting them by their priority Value. * + * @since 4.1.0 + * * @param {String} parentType * @param {String} childType * @returns {Array} @@ -199,6 +222,9 @@ /** * To override by subclass, to return whether the container has active children. + * + * @since 4.1.0 + * * @abstract */ isContextuallyActive: function () { @@ -207,13 +233,18 @@ /** * Handle changes to the active state. + * * This does not change the active state, it merely handles the behavior * for when it does change. * * To override by subclass, update the container's UI to reflect the provided active state. * + * @since 4.1.0 + * * @param {Boolean} active - * @param {Object} args merged on top of this.defaultActiveArguments + * @param {Object} args + * @param {Object} args.duration + * @param {Object} args.completeCallback */ onChangeActive: function ( active, args ) { var duration = ( 'resolved' === api.previewer.deferred.active.state() ? args.duration : 0 ); @@ -229,8 +260,10 @@ }, /** + * @since 4.1.0 + * * @params {Boolean} active - * @param {Object} [params] + * @param {Object} [params] * @returns {Boolean} false if state already applied */ _toggleActive: function ( active, params ) { @@ -316,14 +349,18 @@ }); /** + * @since 4.1.0 + * * @class * @augments wp.customize.Class */ api.Section = Container.extend({ /** + * @since 4.1.0 + * * @param {String} id - * @param {Array} options + * @param {Array} options */ initialize: function ( id, options ) { var section = this; @@ -345,6 +382,8 @@ /** * Embed the container in the DOM when any parent panel is ready. + * + * @since 4.1.0 */ embed: function () { var section = this, inject; @@ -378,7 +417,9 @@ }, /** - * Add behaviors for the accordion section + * Add behaviors for the accordion section. + * + * @since 4.1.0 */ attachEvents: function () { var section = this; @@ -401,7 +442,9 @@ /** * Return whether this section has any active controls. * - * @returns {boolean} + * @since 4.1.0 + * + * @returns {Boolean} */ isContextuallyActive: function () { var section = this, @@ -418,6 +461,8 @@ /** * Get the controls that are associated with this section, sorted by their priority Value. * + * @since 4.1.0 + * * @returns {Array} */ controls: function () { @@ -425,10 +470,12 @@ }, /** - * Update UI to reflect expanded state + * Update UI to reflect expanded state. + * + * @since 4.1.0 * * @param {Boolean} expanded - * @param {Object} args + * @param {Object} args */ onChangeExpanded: function ( expanded, args ) { var section = this, @@ -471,10 +518,18 @@ }); /** + * @since 4.1.0 + * * @class * @augments wp.customize.Class */ api.Panel = Container.extend({ + /** + * @since 4.1.0 + * + * @param {String} id + * @param {Object} options + */ initialize: function ( id, options ) { var panel = this; Container.prototype.initialize.call( panel, id, options ); @@ -486,6 +541,8 @@ /** * Embed the container in the DOM when any parent panel is ready. + * + * @since 4.1.0 */ embed: function () { var panel = this, @@ -498,7 +555,7 @@ }, /** - * + * @since 4.1.0 */ attachEvents: function () { var meta, panel = this; @@ -542,6 +599,8 @@ /** * Get the sections that are associated with this panel, sorted by their priority Value. * + * @since 4.1.0 + * * @returns {Array} */ sections: function () { @@ -551,6 +610,8 @@ /** * Return whether this panel has any active sections. * + * @since 4.1.0 + * * @returns {boolean} */ isContextuallyActive: function () { @@ -568,8 +629,12 @@ /** * Update UI to reflect expanded state * - * @param {Boolean} expanded - * @param {Object} args merged with this.defaultExpandedArguments + * @since 4.1.0 + * + * @param {Boolean} expanded + * @param {Object} args + * @param {Boolean} args.unchanged + * @param {Callback} args.completeCallback */ onChangeExpanded: function ( expanded, args ) { @@ -791,7 +856,8 @@ }, /** - * Bring the containing section and panel into view and then this control into view, focusing on the first input + * Bring the containing section and panel into view and then + * this control into view, focusing on the first input. */ focus: focus, @@ -800,8 +866,12 @@ * This does not change the active state, it merely handles the behavior * for when it does change. * - * @param {Boolean} active - * @param {Object} args merged on top of this.defaultActiveArguments + * @since 4.1.0 + * + * @param {Boolean} active + * @param {Object} args + * @param {Number} args.duration + * @param {Callback} args.completeCallback */ onChangeActive: function ( active, args ) { if ( ! $.contains( document, this.container ) ) { @@ -816,7 +886,7 @@ }, /** - * @deprecated alias of onChangeActive + * @deprecated 4.1.0 Use this.onChangeActive() instead. */ toggle: function ( active ) { return this.onChangeActive( active, this.defaultActiveArguments ); @@ -825,6 +895,8 @@ /** * Shorthand way to enable the active state. * + * @since 4.1.0 + * * @param {Object} [params] * @returns {Boolean} false if already active */ @@ -833,6 +905,8 @@ /** * Shorthand way to disable the active state. * + * @since 4.1.0 + * * @param {Object} [params] * @returns {Boolean} false if already inactive */ @@ -879,6 +953,8 @@ * Render the control from its JS template, if it exists. * * The control's container must already exist in the DOM. + * + * @since 4.1.0 */ renderContent: function () { var template, @@ -1290,7 +1366,7 @@ // Change objects contained within the main customize object to Settings. api.defaultConstructor = api.Setting; - // Create the collection of Control objects. + // Create the collections for Controls, Sections and Panels. api.control = new api.Values({ defaultConstructor: api.Control }); api.section = new api.Values({ defaultConstructor: api.Section }); api.panel = new api.Values({ defaultConstructor: api.Panel }); @@ -1494,7 +1570,9 @@ }()); /** - * Set the document title of the customizer + * Set the document title of the customizer. + * + * @since 4.1.0 * * @param {string} documentTitle */ @@ -1627,7 +1705,7 @@ // Update the URL when the iframe sends a URL message. this.bind( 'url', this.previewUrl ); - // Update the document title when the preview changes + // Update the document title when the preview changes. this.bind( 'documentTitle', function ( title ) { api.setDocumentTitle( title ); } ); @@ -1766,7 +1844,7 @@ } }); - // Expand/Collapse the main customizer customize info + // Expand/Collapse the main customizer customize info. $( '#customize-info' ).find( '> .accordion-section-title' ).on( 'click keydown', function( event ) { if ( isKeydownButNotEnterEvent( event ) ) { return; @@ -1941,6 +2019,8 @@ /** * Sort panels, sections, controls by priorities. Hide empty sections and panels. + * + * @since 4.1.0 */ api.reflowPaneContents = _.bind( function () { diff --git src/wp-admin/js/customize-widgets.js src/wp-admin/js/customize-widgets.js index d649b6b..93585ab 100644 --- src/wp-admin/js/customize-widgets.js +++ src/wp-admin/js/customize-widgets.js @@ -409,6 +409,9 @@ completeCallback: $.noop }, + /** + * @since 4.1.0 + */ initialize: function ( id, options ) { var control = this; api.Control.prototype.initialize.call( control, id, options ); @@ -800,8 +803,11 @@ * * Overrides api.Control.toggle() * - * @param {Boolean} active - * @param {Object} args + * @since 4.1.0 + * + * @param {Boolean} active + * @param {Object} args + * @param {Callback} args.completeCallback */ onChangeActive: function ( active, args ) { // Note: there is a second 'args' parameter being passed, merged on top of this.defaultActiveArguments @@ -1134,6 +1140,8 @@ }, /** + * @since 4.1.0 + * * @param {Boolean} expanded * @param {Object} [params] * @returns {Boolean} false if state already applied @@ -1141,6 +1149,8 @@ _toggleExpanded: api.Section.prototype._toggleExpanded, /** + * @since 4.1.0 + * * @param {Object} [params] * @returns {Boolean} false if already expanded */ @@ -1149,13 +1159,15 @@ /** * Expand the widget form control * - * @deprecated alias of expand() + * @deprecated 4.1.0 Use this.expand() instead. */ expandForm: function() { this.expand(); }, /** + * @since 4.1.0 + * * @param {Object} [params] * @returns {Boolean} false if already collapsed */ @@ -1164,7 +1176,7 @@ /** * Collapse the widget form control * - * @deprecated alias of expand() + * @deprecated 4.1.0 Use this.collapse() instead. */ collapseForm: function() { this.collapse(); @@ -1378,6 +1390,8 @@ /** * Sync the section's active state back to the Backbone model's is_rendered attribute + * + * @since 4.1.0 */ ready: function () { var section = this, registeredSidebar;