WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add some inline JS docs for Customizer. 

See #30469.

Built from https://develop.svn.wordpress.org/trunk@30738


git-svn-id: http://core.svn.wordpress.org/trunk@30728 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Scott Taylor 2014-12-04 02:04:22 +00:00
parent 82188f74aa
commit 097e4ede58
4 changed files with 127 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
wp-admin/js/common.js
View File

@ -247,6 +247,13 @@ $(document).ready( function() {
$( document ).trigger( 'wp-collapse-menu', { state: state } ); $( 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 ) { function adjustSubmenu( $menuItem ) {
var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop, var bottomOffset, pageHeight, adjustment, theFold, menutop, wintop, maxtop,
$submenu = $menuItem.find( '.wp-submenu' ); $submenu = $menuItem.find( '.wp-submenu' );

122
wp-admin/js/customize-controls.js
View File

@ -38,8 +38,10 @@
/** /**
* Watch all changes to Value properties, and bubble changes to parent Values instance * Watch all changes to Value properties, and bubble changes to parent Values instance
* *
* @since 4.1.0
*
* @param {wp.customize.Class} instance * @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.
*/ */
api.utils.bubbleChildValueChanges = function ( instance, properties ) { api.utils.bubbleChildValueChanges = function ( instance, properties ) {
$.each( properties, function ( i, key ) { $.each( properties, function ( i, key ) {
@ -54,7 +56,10 @@
/** /**
* Expand a panel, section, or control and focus on the first focusable element. * 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 ) { focus = function ( params ) {
var construct, completeCallback, focus; var construct, completeCallback, focus;
@ -85,6 +90,8 @@
* *
* If a.priority() === b.priority(), then sort by their respective params.instanceNumber. * 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)} a
* @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} b * @param {(wp.customize.Panel|wp.customize.Section|wp.customize.Control)} b
* @returns {Number} * @returns {Number}
@ -100,6 +107,8 @@
/** /**
* Return whether the supplied Event object is for a keydown event but not the Enter key. * Return whether the supplied Event object is for a keydown event but not the Enter key.
* *
* @since 4.1.0
*
* @param {jQuery.Event} event * @param {jQuery.Event} event
* @returns {boolean} * @returns {boolean}
*/ */
@ -110,6 +119,8 @@
/** /**
* Return whether the two lists of elements are the same and are in the same order. * 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} listA
* @param {Array|jQuery} listB * @param {Array|jQuery} listB
* @returns {boolean} * @returns {boolean}
@ -128,7 +139,9 @@
}; };
/** /**
* Base class for Panel and Section * Base class for Panel and Section.
*
* @since 4.1.0
* *
* @class * @class
* @augments wp.customize.Class * @augments wp.customize.Class
@ -137,6 +150,12 @@
defaultActiveArguments: { duration: 'fast', completeCallback: $.noop }, defaultActiveArguments: { duration: 'fast', completeCallback: $.noop },
defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop }, defaultExpandedArguments: { duration: 'fast', completeCallback: $.noop },
/**
* @since 4.1.0
*
* @param {String} id
* @param {Object} options
*/
initialize: function ( id, options ) { initialize: function ( id, options ) {
var container = this; var container = this;
container.id = id; container.id = id;
@ -175,6 +194,8 @@
}, },
/** /**
* @since 4.1.0
*
* @abstract * @abstract
*/ */
ready: function() {}, ready: function() {},
@ -182,6 +203,8 @@
/** /**
* Get the child models associated with this parent, sorting them by their priority Value. * Get the child models associated with this parent, sorting them by their priority Value.
* *
* @since 4.1.0
*
* @param {String} parentType * @param {String} parentType
* @param {String} childType * @param {String} childType
* @returns {Array} * @returns {Array}
@ -200,6 +223,9 @@
/** /**
* To override by subclass, to return whether the container has active children. * To override by subclass, to return whether the container has active children.
*
* @since 4.1.0
*
* @abstract * @abstract
*/ */
isContextuallyActive: function () { isContextuallyActive: function () {
@ -208,13 +234,18 @@
/** /**
* Handle changes to the active state. * Handle changes to the active state.
*
* This does not change the active state, it merely handles the behavior * This does not change the active state, it merely handles the behavior
* for when it does change. * for when it does change.
* *
* To override by subclass, update the container's UI to reflect the provided active state. * To override by subclass, update the container's UI to reflect the provided active state.
* *
* @since 4.1.0
*
* @param {Boolean} active * @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 ) { onChangeActive: function ( active, args ) {
var duration = ( 'resolved' === api.previewer.deferred.active.state() ? args.duration : 0 ); var duration = ( 'resolved' === api.previewer.deferred.active.state() ? args.duration : 0 );
@ -230,8 +261,10 @@
}, },
/** /**
* @since 4.1.0
*
* @params {Boolean} active * @params {Boolean} active
* @param {Object} [params] * @param {Object} [params]
* @returns {Boolean} false if state already applied * @returns {Boolean} false if state already applied
*/ */
_toggleActive: function ( active, params ) { _toggleActive: function ( active, params ) {
@ -317,14 +350,18 @@
}); });
/** /**
* @since 4.1.0
*
* @class * @class
* @augments wp.customize.Class * @augments wp.customize.Class
*/ */
api.Section = Container.extend({ api.Section = Container.extend({
/** /**
* @since 4.1.0
*
* @param {String} id * @param {String} id
* @param {Array} options * @param {Array} options
*/ */
initialize: function ( id, options ) { initialize: function ( id, options ) {
var section = this; var section = this;
@ -346,6 +383,8 @@
/** /**
* Embed the container in the DOM when any parent panel is ready. * Embed the container in the DOM when any parent panel is ready.
*
* @since 4.1.0
*/ */
embed: function () { embed: function () {
var section = this, inject; var section = this, inject;
@ -379,7 +418,9 @@
}, },
/** /**
* Add behaviors for the accordion section * Add behaviors for the accordion section.
*
* @since 4.1.0
*/ */
attachEvents: function () { attachEvents: function () {
var section = this; var section = this;
@ -402,7 +443,9 @@
/** /**
* Return whether this section has any active controls. * Return whether this section has any active controls.
* *
* @returns {boolean} * @since 4.1.0
*
* @returns {Boolean}
*/ */
isContextuallyActive: function () { isContextuallyActive: function () {
var section = this, var section = this,
@ -419,6 +462,8 @@
/** /**
* Get the controls that are associated with this section, sorted by their priority Value. * Get the controls that are associated with this section, sorted by their priority Value.
* *
* @since 4.1.0
*
* @returns {Array} * @returns {Array}
*/ */
controls: function () { controls: function () {
@ -426,10 +471,12 @@
}, },
/** /**
* Update UI to reflect expanded state * Update UI to reflect expanded state.
*
* @since 4.1.0
* *
* @param {Boolean} expanded * @param {Boolean} expanded
* @param {Object} args * @param {Object} args
*/ */
onChangeExpanded: function ( expanded, args ) { onChangeExpanded: function ( expanded, args ) {
var section = this, var section = this,
@ -472,10 +519,18 @@
}); });
/** /**
* @since 4.1.0
*
* @class * @class
* @augments wp.customize.Class * @augments wp.customize.Class
*/ */
api.Panel = Container.extend({ api.Panel = Container.extend({
/**
* @since 4.1.0
*
* @param {String} id
* @param {Object} options
*/
initialize: function ( id, options ) { initialize: function ( id, options ) {
var panel = this; var panel = this;
Container.prototype.initialize.call( panel, id, options ); Container.prototype.initialize.call( panel, id, options );
@ -487,6 +542,8 @@
/** /**
* Embed the container in the DOM when any parent panel is ready. * Embed the container in the DOM when any parent panel is ready.
*
* @since 4.1.0
*/ */
embed: function () { embed: function () {
var panel = this, var panel = this,
@ -499,7 +556,7 @@
}, },
/** /**
* * @since 4.1.0
*/ */
attachEvents: function () { attachEvents: function () {
var meta, panel = this; var meta, panel = this;
@ -543,6 +600,8 @@
/** /**
* Get the sections that are associated with this panel, sorted by their priority Value. * Get the sections that are associated with this panel, sorted by their priority Value.
* *
* @since 4.1.0
*
* @returns {Array} * @returns {Array}
*/ */
sections: function () { sections: function () {
@ -552,6 +611,8 @@
/** /**
* Return whether this panel has any active sections. * Return whether this panel has any active sections.
* *
* @since 4.1.0
*
* @returns {boolean} * @returns {boolean}
*/ */
isContextuallyActive: function () { isContextuallyActive: function () {
@ -569,8 +630,12 @@
/** /**
* Update UI to reflect expanded state * Update UI to reflect expanded state
* *
* @param {Boolean} expanded * @since 4.1.0
* @param {Object} args merged with this.defaultExpandedArguments *
* @param {Boolean} expanded
* @param {Object} args
* @param {Boolean} args.unchanged
* @param {Callback} args.completeCallback
*/ */
onChangeExpanded: function ( expanded, args ) { onChangeExpanded: function ( expanded, args ) {
@ -792,7 +857,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, focus: focus,
@ -801,8 +867,12 @@
* This does not change the active state, it merely handles the behavior * This does not change the active state, it merely handles the behavior
* for when it does change. * for when it does change.
* *
* @param {Boolean} active * @since 4.1.0
* @param {Object} args merged on top of this.defaultActiveArguments *
* @param {Boolean} active
* @param {Object} args
* @param {Number} args.duration
* @param {Callback} args.completeCallback
*/ */
onChangeActive: function ( active, args ) { onChangeActive: function ( active, args ) {
if ( ! $.contains( document, this.container ) ) { if ( ! $.contains( document, this.container ) ) {
@ -817,7 +887,7 @@
}, },
/** /**
* @deprecated alias of onChangeActive * @deprecated 4.1.0 Use this.onChangeActive() instead.
*/ */
toggle: function ( active ) { toggle: function ( active ) {
return this.onChangeActive( active, this.defaultActiveArguments ); return this.onChangeActive( active, this.defaultActiveArguments );
@ -826,6 +896,8 @@
/** /**
* Shorthand way to enable the active state. * Shorthand way to enable the active state.
* *
* @since 4.1.0
*
* @param {Object} [params] * @param {Object} [params]
* @returns {Boolean} false if already active * @returns {Boolean} false if already active
*/ */
@ -834,6 +906,8 @@
/** /**
* Shorthand way to disable the active state. * Shorthand way to disable the active state.
* *
* @since 4.1.0
*
* @param {Object} [params] * @param {Object} [params]
* @returns {Boolean} false if already inactive * @returns {Boolean} false if already inactive
*/ */
@ -880,6 +954,8 @@
* Render the control from its JS template, if it exists. * Render the control from its JS template, if it exists.
* *
* The control's container must already exist in the DOM. * The control's container must already exist in the DOM.
*
* @since 4.1.0
*/ */
renderContent: function () { renderContent: function () {
var template, var template,
@ -1291,7 +1367,7 @@
// Change objects contained within the main customize object to Settings. // Change objects contained within the main customize object to Settings.
api.defaultConstructor = api.Setting; 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.control = new api.Values({ defaultConstructor: api.Control });
api.section = new api.Values({ defaultConstructor: api.Section }); api.section = new api.Values({ defaultConstructor: api.Section });
api.panel = new api.Values({ defaultConstructor: api.Panel }); api.panel = new api.Values({ defaultConstructor: api.Panel });
@ -1495,7 +1571,9 @@
}()); }());
/** /**
* Set the document title of the customizer * Set the document title of the customizer.
*
* @since 4.1.0
* *
* @param {string} documentTitle * @param {string} documentTitle
*/ */
@ -1628,7 +1706,7 @@
// Update the URL when the iframe sends a URL message. // Update the URL when the iframe sends a URL message.
this.bind( 'url', this.previewUrl ); 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 ) { this.bind( 'documentTitle', function ( title ) {
api.setDocumentTitle( title ); api.setDocumentTitle( title );
} ); } );
@ -1768,7 +1846,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 ) { $( '#customize-info' ).find( '> .accordion-section-title' ).on( 'click keydown', function( event ) {
if ( api.utils.isKeydownButNotEnterEvent( event ) ) { if ( api.utils.isKeydownButNotEnterEvent( event ) ) {
return; return;
@ -1943,6 +2021,8 @@
/** /**
* Sort panels, sections, controls by priorities. Hide empty sections and panels. * Sort panels, sections, controls by priorities. Hide empty sections and panels.
*
* @since 4.1.0
*/ */
api.reflowPaneContents = _.bind( function () { api.reflowPaneContents = _.bind( function () {

22
wp-admin/js/customize-widgets.js
View File

@ -409,6 +409,9 @@
completeCallback: $.noop completeCallback: $.noop
}, },
/**
* @since 4.1.0
*/
initialize: function ( id, options ) { initialize: function ( id, options ) {
var control = this; var control = this;
api.Control.prototype.initialize.call( control, id, options ); api.Control.prototype.initialize.call( control, id, options );
@ -800,8 +803,11 @@
* *
* Overrides api.Control.toggle() * Overrides api.Control.toggle()
* *
* @param {Boolean} active * @since 4.1.0
* @param {Object} args *
* @param {Boolean} active
* @param {Object} args
* @param {Callback} args.completeCallback
*/ */
onChangeActive: function ( active, args ) { 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
@ -1134,6 +1140,8 @@
}, },
/** /**
* @since 4.1.0
*
* @param {Boolean} expanded * @param {Boolean} expanded
* @param {Object} [params] * @param {Object} [params]
* @returns {Boolean} false if state already applied * @returns {Boolean} false if state already applied
@ -1141,6 +1149,8 @@
_toggleExpanded: api.Section.prototype._toggleExpanded, _toggleExpanded: api.Section.prototype._toggleExpanded,
/** /**
* @since 4.1.0
*
* @param {Object} [params] * @param {Object} [params]
* @returns {Boolean} false if already expanded * @returns {Boolean} false if already expanded
*/ */
@ -1149,13 +1159,15 @@
/** /**
* Expand the widget form control * Expand the widget form control
* *
* @deprecated alias of expand() * @deprecated 4.1.0 Use this.expand() instead.
*/ */
expandForm: function() { expandForm: function() {
this.expand(); this.expand();
}, },
/** /**
* @since 4.1.0
*
* @param {Object} [params] * @param {Object} [params]
* @returns {Boolean} false if already collapsed * @returns {Boolean} false if already collapsed
*/ */
@ -1164,7 +1176,7 @@
/** /**
* Collapse the widget form control * Collapse the widget form control
* *
* @deprecated alias of expand() * @deprecated 4.1.0 Use this.collapse() instead.
*/ */
collapseForm: function() { collapseForm: function() {
this.collapse(); this.collapse();
@ -1378,6 +1390,8 @@
/** /**
* Sync the section's active state back to the Backbone model's is_rendered attribute * Sync the section's active state back to the Backbone model's is_rendered attribute
*
* @since 4.1.0
*/ */
ready: function () { ready: function () {
var section = this, registeredSidebar; var section = this, registeredSidebar;

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '4.1-beta2-30737'; $wp_version = '4.1-beta2-30738';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.