WordPress.org

Make WordPress Core

Changeset 41799


Ignore:
Timestamp:
10/09/17 18:55:44 (10 days 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.