WordPress.org

Make WordPress Core

Changeset 22684


Ignore:
Timestamp:
11/19/2012 12:11:16 PM (8 years ago)
Author:
koopersmith
Message:

Media: Add silent options to the views; improve documentation. see #21390.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/js/media-views.js

    r22682 r22684  
    614614        // `Backbone.View` instances.
    615615        //
    616         // Use `Views.add()` as a shortcut for setting `options.add` to `true`.
     616        // ---
    617617        //
    618618        // Accepts an `options` object, which has a significant effect on the
    619         // resulting behavior. By default, the provided `views` will replace
     619        // resulting behavior.
     620        //
     621        // `options.silent` – *boolean, `false`*
     622        // > If `options.silent` is true, no DOM modifications will be made.
     623        //
     624        // `options.add` – *boolean, `false`*
     625        // > Use `Views.add()` as a shortcut for setting `options.add` to true.
     626        //
     627        // > By default, the provided `views` will replace
    620628        // any existing views associated with the selector. If `options.add`
    621         // is set to `true`, the provided `views` will be added to the existing
    622         // views. When adding, the `views` will added to the end of the array
    623         // by default. To insert `views` at a specific index, use `options.at`.
     629        // is true, the provided `views` will be added to the existing views.
     630        //
     631        // `options.at` – *integer, `undefined`*
     632        // > When adding, to insert `views` at a specific index, use
     633        // `options.at`. By default, `views` are added to the end of the array.
    624634        set: function( selector, views, options ) {
    625             var $selector, els, existing, add, method;
     635            var $selector, els, existing, method;
    626636
    627637            if ( ! _.isString( selector ) ) {
     
    631641            }
    632642
     643            options  = options || {};
    633644            views    = _.isArray( views ) ? views : [ views ];
    634             add      = options && options.add;
    635645            existing = this.get( selector );
    636646            next     = views;
    637             method   = add ? 'insert' : 'replace';
     647            method   = options.add ? 'insert' : 'replace';
    638648
    639649            if ( existing ) {
    640                 if ( add ) {
     650                if ( options.add ) {
    641651                    if ( _.isUndefined( options.at ) )
    642652                        next = existing.concat( views );
     
    673683            }, this );
    674684
    675             this[ method ]( $selector, els, options );
     685            if ( ! options.silent )
     686                this[ method ]( $selector, els, options );
     687
    676688            return this;
    677689        },
     
    691703        // Accepts an `options` object. By default, provided `views` will be
    692704        // inserted at the end of the array of existing views. To insert
    693         // `views` at a specific index, use `options.at`. For more information
    694         // on the `options` object, see `Views.set()`.
     705        // `views` at a specific index, use `options.at`. If `options.silent`
     706        // is true, no DOM modifications will be made.
     707        //
     708        // For more information on the `options` object, see `Views.set()`.
    695709        add: function( selector, views, options ) {
    696710            return this.set( selector, views, _.extend({ add: true }, options ) );
     
    700714        //
    701715        // Stops tracking `views` registered to a `selector`. If no `views` are
    702         // set, then all of the `selector`'s subviews will be unregistered.
    703         unset: function( selector, views ) {
     716        // set, then all of the `selector`'s subviews will be unregistered and
     717        // disposed.
     718        //
     719        // Accepts an `options` object. If `options.silent` is set, `dispose`
     720        // will *not* be triggered on the unregistered views.
     721        unset: function( selector, views, options ) {
    704722            var existing;
    705723
    706724            if ( ! _.isString( selector ) ) {
     725                options = views;
    707726                views = selector;
    708727                selector = '';
     
    713732                this._views[ selector ] = views.length ? _.difference( existing, views ) : [];
    714733            }
     734
     735            if ( ! options || ! options.silent )
     736                _.invoke( views, 'dispose', { silent: true });
    715737
    716738            return this;
     
    747769        // ### Dispose all subviews
    748770        //
    749         // Triggers the `dispose()` method on all subviews. Resets the
    750         // internals of the views manager.
    751         dispose: function() {
    752             delete this.parent;
    753             delete this.selector;
     771        // Triggers the `dispose()` method on all subviews. Detaches the master
     772        // view from its parent. Resets the internals of the views manager.
     773        //
     774        // Accepts an `options` object. If `options.silent` is set, `unset`
     775        // will *not* be triggered on the master view's parent.
     776        dispose: function( options ) {
     777            if ( ! options || ! options.silent ) {
     778                if ( this.parent && this.parent.views )
     779                    this.parent.views.unset( this.selector, this.view, { silent: true });
     780                delete this.parent;
     781                delete this.selector;
     782            }
    754783
    755784            _.invoke( this.all(), 'dispose' );
Note: See TracChangeset for help on using the changeset viewer.