Changeset 41799

Timestamp:

10/09/2017 06:55:44 PM (7 years ago)

Author:

westonruter

Message:

Customize: Add jsdoc for api.panel, api.section, api.control, and api.notifications collections.

Props shramee, westonruter.
Fixes #39930.

File:

• trunk/src/wp-admin/js/customize-controls.js (modified) (1 diff)

trunk/src/wp-admin/js/customize-controls.js

@@ -5585 +5585 @@
     api.defaultConstructor = api.Setting;
 
-    // Create the collections for Controls, Sections and Panels.
+    /**
+     * Callback for resolved controls.
+     *
+     * @callback deferredControlsCallback
+     * @param {wp.customize.Control[]} Resolved controls.
+     */
+
+    /**
+     * Collection of all registered controls.
+     *
+     * @since 3.4.0
+     *
+     * @type {Function}
+     * @param {...string} ids - One or more ids for controls to obtain.
+     * @param {deferredControlsCallback} [callback] - Function called when all supplied controls exist.
+     * @returns {wp.customize.Control|undefined|jQuery.promise} Control instance or undefined (if function called with one id param), or promise resolving to requested controls.
+     *
+     * @example <caption>Loop over all registered controls.</caption>
+     * wp.customize.control.each( function( control ) { ... } );
+     *
+     * @example <caption>Getting `background_color` control instance.</caption>
+     * control = wp.customize.control( 'background_color' );
+     *
+     * @example <caption>Check if control exists.</caption>
+     * hasControl = wp.customize.control.has( 'background_color' );
+     *
+     * @example <caption>Deferred getting of `background_color` control until it exists, using callback.</caption>
+     * wp.customize.control( 'background_color', function( control ) { ... } );
+     *
+     * @example <caption>Get title and tagline controls when they both exist, using promise (only available when multiple IDs are present).</caption>
+     * promise = wp.customize.control( 'blogname', 'blogdescription' );
+     * promise.done( function( titleControl, taglineControl ) { ... } );
+     *
+     * @example <caption>Get title and tagline controls when they both exist, using callback.</caption>
+     * wp.customize.control( 'blogname', 'blogdescription', function( titleControl, taglineControl ) { ... } );
+     *
+     * @example <caption>Getting setting value for `background_color` control.</caption>
+     * value = wp.customize.control( 'background_color ').setting.get();
+     * value = wp.customize( 'background_color' ).get(); // Same as above, since setting ID and control ID are the same.
+     *
+     * @example <caption>Add new control for site title.</caption>
+     * wp.customize.control.add( new wp.customize.Control( 'other_blogname', {
+     *     setting: 'blogname',
+     *     type: 'text',
+     *     label: 'Site title',
+     *     section: 'other_site_identify'
+     * } ) );
+     *
+     * @example <caption>Remove control.</caption>
+     * wp.customize.control.remove( 'other_blogname' );
+     *
+     * @example <caption>Listen for control being added.</caption>
+     * wp.customize.control.bind( 'add', function( addedControl ) { ... } )
+     *
+     * @example <caption>Listen for control being removed.</caption>
+     * wp.customize.control.bind( 'removed', function( removedControl ) { ... } )
+     */
     api.control = new api.Values({ defaultConstructor: api.Control });
+
+    /**
+     * Callback for resolved sections.
+     *
+     * @callback deferredSectionsCallback
+     * @param {wp.customize.Section[]} Resolved sections.
+     */
+
+    /**
+     * Collection of all registered sections.
+     *
+     * @since 3.4.0
+     *
+     * @type {Function}
+     * @param {...string} ids - One or more ids for sections to obtain.
+     * @param {deferredSectionsCallback} [callback] - Function called when all supplied sections exist.
+     * @returns {wp.customize.Section|undefined|jQuery.promise} Section instance or undefined (if function called with one id param), or promise resolving to requested sections.
+     *
+     * @example <caption>Loop over all registered sections.</caption>
+     * wp.customize.section.each( function( section ) { ... } )
+     *
+     * @example <caption>Getting `title_tagline` section instance.</caption>
+     * section = wp.customize.section( 'title_tagline' )
+     *
+     * @example <caption>Expand dynamically-created section when it exists.</caption>
+     * wp.customize.section( 'dynamically_created', function( section ) {
+     *     section.expand();
+     * } );
+     *
+     * @see {@link wp.customize.control} for further examples of how to interact with {@link wp.customize.Values} instances.
+     */
     api.section = new api.Values({ defaultConstructor: api.Section });
+
+    /**
+     * Callback for resolved panels.
+     *
+     * @callback deferredPanelsCallback
+     * @param {wp.customize.Panel[]} Resolved panels.
+     */
+
+    /**
+     * Collection of all registered panels.
+     *
+     * @since 4.0.0
+     *
+     * @type {Function}
+     * @param {...string} ids - One or more ids for panels to obtain.
+     * @param {deferredPanelsCallback} [callback] - Function called when all supplied panels exist.
+     * @returns {wp.customize.Panel|undefined|jQuery.promise} Panel instance or undefined (if function called with one id param), or promise resolving to requested panels.
+     *
+     * @example <caption>Loop over all registered panels.</caption>
+     * wp.customize.panel.each( function( panel ) { ... } )
+     *
+     * @example <caption>Getting nav_menus panel instance.</caption>
+     * panel = wp.customize.panel( 'nav_menus' );
+     *
+     * @example <caption>Expand dynamically-created panel when it exists.</caption>
+     * wp.customize.panel( 'dynamically_created', function( panel ) {
+     *     panel.expand();
+     * } );
+     *
+     * @see {@link wp.customize.control} for further examples of how to interact with {@link wp.customize.Values} instances.
+     */
     api.panel = new api.Values({ defaultConstructor: api.Panel });
 
-    // Create the collection for global Notifications.
+    /**
+     * Callback for resolved notifications.
+     *
+     * @callback deferredNotificationsCallback
+     * @param {wp.customize.Notification[]} Resolved notifications.
+     */
+
+    /**
+     * Collection of all global notifications.
+     *
+     * @since 4.9.0
+     *
+     * @type {Function}
+     * @param {...string} codes - One or more codes for notifications to obtain.
+     * @param {deferredNotificationsCallback} [callback] - Function called when all supplied notifications exist.
+     * @returns {wp.customize.Notification|undefined|jQuery.promise} notification instance or undefined (if function called with one code param), or promise resolving to requested notifications.
+     *
+     * @example <caption>Check if existing notification</caption>
+     * exists = wp.customize.notifications.has( 'a_new_day_arrived' );
+     *
+     * @example <caption>Obtain existing notification</caption>
+     * notification = wp.customize.notifications( 'a_new_day_arrived' );
+     *
+     * @example <caption>Obtain notification that may not exist yet.</caption>
+     * wp.customize.notifications( 'a_new_day_arrived', function( notification ) { ... } );
+     *
+     * @example <caption>Add a warning notification.</caption>
+     * wp.customize.notifications.add( new wp.customize.Notification( 'midnight_almost_here', {
+     *     type: 'warning',
+     *     message: 'Midnight has almost arrived!',
+     *     dismissible: true
+     * } ) );
+     *
+     * @example <caption>Remove a notification.</caption>
+     * wp.customize.notifications.remove( 'a_new_day_arrived' );
+     *
+     * @see {@link wp.customize.control} for further examples of how to interact with {@link wp.customize.Values} instances.
+     */
     api.notifications = new api.Notifications();