WordPress.org

Make WordPress Core

Ticket #33639: 33639.diff

File 33639.diff, 4.1 KB (added by ericlewis, 5 years ago)
  • src/wp-includes/js/customize-base.js

    diff --git a/src/wp-includes/js/customize-base.js b/src/wp-includes/js/customize-base.js
    index 2e0ab19..720a312 100644
    a b window.wp = window.wp || {}; 
    7474                }
    7575
    7676                magic = this;
     77
     78                /*
     79                 * If the class has a method called "instance",
     80                 * the return value from the class' constructor will be a function that
     81                 * calls invoked, along with all the object properties of the class.
     82                 */
    7783                if ( this.instance ) {
    7884                        magic = function() {
    7985                                return magic.instance.apply( magic, arguments );
    window.wp = window.wp || {}; 
    101107
    102108        api.Class.applicator = {};
    103109
     110        /**
     111         * Initialize a class instance.
     112         *
     113         * Override this function in a subclass as needed.
     114         */
    104115        api.Class.prototype.initialize = function() {};
    105116
    106117        /*
    window.wp = window.wp || {}; 
    281292                        this._deferreds = {};
    282293                },
    283294
     295                /**
     296                 * Get the instance of an item from the collection if only ID is specified.
     297                 *
     298                 * If more than one argument is supplied, all are expected to be IDs and
     299                 * the last to be a function callback that will be invoked when the requested
     300                 * items are available.
     301                 *
     302                 * @see {api.Values.when}
     303                 *
     304                 * @param  {string}   id ID of the item.
     305                 * @param  {...}         Zero or more IDs of items to wait for and a callback
     306                 *                       function to invoke when they're available. Optional.
     307                 * @return {mixed}    The item instance if only one ID was supplied.
     308                 *                    A Deferred Promise object if a callback function is supplied.
     309                 */
    284310                instance: function( id ) {
    285311                        if ( arguments.length === 1 )
    286312                                return this.value( id );
    window.wp = window.wp || {}; 
    288314                        return this.when.apply( this, arguments );
    289315                },
    290316
     317                /**
     318                 * Get the instance of an item.
     319                 *
     320                 * @param  {string} id The ID of the item.
     321                 * @return {[type]}    [description]
     322                 */
    291323                value: function( id ) {
    292324                        return this._value[ id ];
    293325                },
    294326
     327                /**
     328                 * Whether the collection has an item with the given ID.
     329                 *
     330                 * @param  {string}  id The ID of the item to look for.
     331                 * @return {Boolean}
     332                 */
    295333                has: function( id ) {
    296334                        return typeof this._value[ id ] !== 'undefined';
    297335                },
    298336
     337                /**
     338                 * Add an item to the collection.
     339                 *
     340                 * @param {string} id    The ID of the item.
     341                 * @param {mixed}  value The item instance.
     342                 * @return {mixed} The new item's instance.
     343                 */
    299344                add: function( id, value ) {
    300345                        if ( this.has( id ) )
    301346                                return this.value( id );
    window.wp = window.wp || {}; 
    307352
    308353                        this.trigger( 'add', value );
    309354
     355                        // If a deferred object exists for this item,
     356                        // resolve it.
    310357                        if ( this._deferreds[ id ] )
    311358                                this._deferreds[ id ].resolve();
    312359
    313360                        return this._value[ id ];
    314361                },
    315362
     363                /**
     364                 * Create a new item of the collection using the collection's default constructor
     365                 * and store it in the collection.
     366                 *
     367                 * @param  {string} id    The ID of the item.
     368                 * @param  {mixed}  value Any extra arguments are passed into the item's initialize method.
     369                 * @return {mixed}  The new item's instance.
     370                 */
    316371                create: function( id ) {
    317372                        return this.add( id, new this.defaultConstructor( api.Class.applicator, slice.call( arguments, 1 ) ) );
    318373                },
    window.wp = window.wp || {}; 
    325380                        });
    326381                },
    327382
     383                /**
     384                 * Remove an item from the collection.
     385                 *
     386                 * @param  {string} id The ID of the item to remove.
     387                 */
    328388                remove: function( id ) {
    329389                        var value;
    330390
    window.wp = window.wp || {}; 
    359419                        if ( $.isFunction( ids[ ids.length - 1 ] ) )
    360420                                dfd.done( ids.pop() );
    361421
     422                        /*
     423                         * Create a stack of deferred objects for each item that is not
     424                         * yet available, and invoke the supplied callback when they are.
     425                         */
    362426                        $.when.apply( $, $.map( ids, function( id ) {
    363427                                if ( self.has( id ) )
    364428                                        return;
    365429
     430                                /*
     431                                 * The requested item is not available yet, create a deferred
     432                                 * object to resolve when it becomes available.
     433                                 */
    366434                                return self._deferreds[ id ] = self._deferreds[ id ] || $.Deferred();
    367435                        })).done( function() {
    368436                                var values = $.map( ids, function( id ) {