WordPress.org

Make WordPress Core

Changeset 41799


Ignore:
Timestamp:
10/09/2017 06:55:44 PM (9 months ago)
Author:
westonruter
Message:

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

Props shramee, westonruter.
Fixes #39930.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/customize-controls.js

    r41797 r41799  
    55855585    api.defaultConstructor = api.Setting;
    55865586
    5587     // Create the collections for Controls, Sections and Panels.
     5587    /**
     5588     * Callback for resolved controls.
     5589     *
     5590     * @callback deferredControlsCallback
     5591     * @param {wp.customize.Control[]} Resolved controls.
     5592     */
     5593
     5594    /**
     5595     * Collection of all registered controls.
     5596     *
     5597     * @since 3.4.0
     5598     *
     5599     * @type {Function}
     5600     * @param {...string} ids - One or more ids for controls to obtain.
     5601     * @param {deferredControlsCallback} [callback] - Function called when all supplied controls exist.
     5602     * @returns {wp.customize.Control|undefined|jQuery.promise} Control instance or undefined (if function called with one id param), or promise resolving to requested controls.
     5603     *
     5604     * @example <caption>Loop over all registered controls.</caption>
     5605     * wp.customize.control.each( function( control ) { ... } );
     5606     *
     5607     * @example <caption>Getting `background_color` control instance.</caption>
     5608     * control = wp.customize.control( 'background_color' );
     5609     *
     5610     * @example <caption>Check if control exists.</caption>
     5611     * hasControl = wp.customize.control.has( 'background_color' );
     5612     *
     5613     * @example <caption>Deferred getting of `background_color` control until it exists, using callback.</caption>
     5614     * wp.customize.control( 'background_color', function( control ) { ... } );
     5615     *
     5616     * @example <caption>Get title and tagline controls when they both exist, using promise (only available when multiple IDs are present).</caption>
     5617     * promise = wp.customize.control( 'blogname', 'blogdescription' );
     5618     * promise.done( function( titleControl, taglineControl ) { ... } );
     5619     *
     5620     * @example <caption>Get title and tagline controls when they both exist, using callback.</caption>
     5621     * wp.customize.control( 'blogname', 'blogdescription', function( titleControl, taglineControl ) { ... } );
     5622     *
     5623     * @example <caption>Getting setting value for `background_color` control.</caption>
     5624     * value = wp.customize.control( 'background_color ').setting.get();
     5625     * value = wp.customize( 'background_color' ).get(); // Same as above, since setting ID and control ID are the same.
     5626     *
     5627     * @example <caption>Add new control for site title.</caption>
     5628     * wp.customize.control.add( new wp.customize.Control( 'other_blogname', {
     5629     *     setting: 'blogname',
     5630     *     type: 'text',
     5631     *     label: 'Site title',
     5632     *     section: 'other_site_identify'
     5633     * } ) );
     5634     *
     5635     * @example <caption>Remove control.</caption>
     5636     * wp.customize.control.remove( 'other_blogname' );
     5637     *
     5638     * @example <caption>Listen for control being added.</caption>
     5639     * wp.customize.control.bind( 'add', function( addedControl ) { ... } )
     5640     *
     5641     * @example <caption>Listen for control being removed.</caption>
     5642     * wp.customize.control.bind( 'removed', function( removedControl ) { ... } )
     5643     */
    55885644    api.control = new api.Values({ defaultConstructor: api.Control });
     5645
     5646    /**
     5647     * Callback for resolved sections.
     5648     *
     5649     * @callback deferredSectionsCallback
     5650     * @param {wp.customize.Section[]} Resolved sections.
     5651     */
     5652
     5653    /**
     5654     * Collection of all registered sections.
     5655     *
     5656     * @since 3.4.0
     5657     *
     5658     * @type {Function}
     5659     * @param {...string} ids - One or more ids for sections to obtain.
     5660     * @param {deferredSectionsCallback} [callback] - Function called when all supplied sections exist.
     5661     * @returns {wp.customize.Section|undefined|jQuery.promise} Section instance or undefined (if function called with one id param), or promise resolving to requested sections.
     5662     *
     5663     * @example <caption>Loop over all registered sections.</caption>
     5664     * wp.customize.section.each( function( section ) { ... } )
     5665     *
     5666     * @example <caption>Getting `title_tagline` section instance.</caption>
     5667     * section = wp.customize.section( 'title_tagline' )
     5668     *
     5669     * @example <caption>Expand dynamically-created section when it exists.</caption>
     5670     * wp.customize.section( 'dynamically_created', function( section ) {
     5671     *     section.expand();
     5672     * } );
     5673     *
     5674     * @see {@link wp.customize.control} for further examples of how to interact with {@link wp.customize.Values} instances.
     5675     */
    55895676    api.section = new api.Values({ defaultConstructor: api.Section });
     5677
     5678    /**
     5679     * Callback for resolved panels.
     5680     *
     5681     * @callback deferredPanelsCallback
     5682     * @param {wp.customize.Panel[]} Resolved panels.
     5683     */
     5684
     5685    /**
     5686     * Collection of all registered panels.
     5687     *
     5688     * @since 4.0.0
     5689     *
     5690     * @type {Function}
     5691     * @param {...string} ids - One or more ids for panels to obtain.
     5692     * @param {deferredPanelsCallback} [callback] - Function called when all supplied panels exist.
     5693     * @returns {wp.customize.Panel|undefined|jQuery.promise} Panel instance or undefined (if function called with one id param), or promise resolving to requested panels.
     5694     *
     5695     * @example <caption>Loop over all registered panels.</caption>
     5696     * wp.customize.panel.each( function( panel ) { ... } )
     5697     *
     5698     * @example <caption>Getting nav_menus panel instance.</caption>
     5699     * panel = wp.customize.panel( 'nav_menus' );
     5700     *
     5701     * @example <caption>Expand dynamically-created panel when it exists.</caption>
     5702     * wp.customize.panel( 'dynamically_created', function( panel ) {
     5703     *     panel.expand();
     5704     * } );
     5705     *
     5706     * @see {@link wp.customize.control} for further examples of how to interact with {@link wp.customize.Values} instances.
     5707     */
    55905708    api.panel = new api.Values({ defaultConstructor: api.Panel });
    55915709
    5592     // Create the collection for global Notifications.
     5710    /**
     5711     * Callback for resolved notifications.
     5712     *
     5713     * @callback deferredNotificationsCallback
     5714     * @param {wp.customize.Notification[]} Resolved notifications.
     5715     */
     5716
     5717    /**
     5718     * Collection of all global notifications.
     5719     *
     5720     * @since 4.9.0
     5721     *
     5722     * @type {Function}
     5723     * @param {...string} codes - One or more codes for notifications to obtain.
     5724     * @param {deferredNotificationsCallback} [callback] - Function called when all supplied notifications exist.
     5725     * @returns {wp.customize.Notification|undefined|jQuery.promise} notification instance or undefined (if function called with one code param), or promise resolving to requested notifications.
     5726     *
     5727     * @example <caption>Check if existing notification</caption>
     5728     * exists = wp.customize.notifications.has( 'a_new_day_arrived' );
     5729     *
     5730     * @example <caption>Obtain existing notification</caption>
     5731     * notification = wp.customize.notifications( 'a_new_day_arrived' );
     5732     *
     5733     * @example <caption>Obtain notification that may not exist yet.</caption>
     5734     * wp.customize.notifications( 'a_new_day_arrived', function( notification ) { ... } );
     5735     *
     5736     * @example <caption>Add a warning notification.</caption>
     5737     * wp.customize.notifications.add( new wp.customize.Notification( 'midnight_almost_here', {
     5738     *     type: 'warning',
     5739     *     message: 'Midnight has almost arrived!',
     5740     *     dismissible: true
     5741     * } ) );
     5742     *
     5743     * @example <caption>Remove a notification.</caption>
     5744     * wp.customize.notifications.remove( 'a_new_day_arrived' );
     5745     *
     5746     * @see {@link wp.customize.control} for further examples of how to interact with {@link wp.customize.Values} instances.
     5747     */
    55935748    api.notifications = new api.Notifications();
    55945749
Note: See TracChangeset for help on using the changeset viewer.