Changeset 22684

Timestamp:

11/19/2012 12:11:16 PM (12 years ago)

Author:

koopersmith

Message:

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

File:

• trunk/wp-includes/js/media-views.js (modified) (7 diffs)

trunk/wp-includes/js/media-views.js

@@ -614 +614 @@
         // `Backbone.View` instances.
         //
-        // Use `Views.add()` as a shortcut for setting `options.add` to `true`.
+        // ---
         //
         // Accepts an `options` object, which has a significant effect on the
-        // resulting behavior. By default, the provided `views` will replace
+        // resulting behavior.
+        //
+        // `options.silent` – *boolean, `false`*
+        // > If `options.silent` is true, no DOM modifications will be made.
+        //
+        // `options.add` – *boolean, `false`*
+        // > Use `Views.add()` as a shortcut for setting `options.add` to true.
+        //
+        // > By default, the provided `views` will replace
         // any existing views associated with the selector. If `options.add`
-        // is set to `true`, the provided `views` will be added to the existing
-        // views. When adding, the `views` will added to the end of the array
-        // by default. To insert `views` at a specific index, use `options.at`.
+        // is true, the provided `views` will be added to the existing views.
+        //
+        // `options.at` – *integer, `undefined`*
+        // > When adding, to insert `views` at a specific index, use
+        // `options.at`. By default, `views` are added to the end of the array.
         set: function( selector, views, options ) {
-            var $selector, els, existing, add, method;
+            var $selector, els, existing, method;
 
             if ( ! _.isString( selector ) ) {
@@ -631 +641 @@
             }
 
+            options  = options || {};
             views    = _.isArray( views ) ? views : [ views ];
-            add      = options && options.add;
             existing = this.get( selector );
             next     = views;
-            method   = add ? 'insert' : 'replace';
+            method   = options.add ? 'insert' : 'replace';
 
             if ( existing ) {
-                if ( add ) {
+                if ( options.add ) {
                     if ( _.isUndefined( options.at ) )
                         next = existing.concat( views );
@@ -673 +683 @@
             }, this );
 
-            this[ method ]( $selector, els, options );
+            if ( ! options.silent )
+                this[ method ]( $selector, els, options );
+
             return this;
         },
@@ -691 +703 @@
         // Accepts an `options` object. By default, provided `views` will be
         // inserted at the end of the array of existing views. To insert
-        // `views` at a specific index, use `options.at`. For more information
-        // on the `options` object, see `Views.set()`.
+        // `views` at a specific index, use `options.at`. If `options.silent`
+        // is true, no DOM modifications will be made.
+        //
+        // For more information on the `options` object, see `Views.set()`.
         add: function( selector, views, options ) {
             return this.set( selector, views, _.extend({ add: true }, options ) );
@@ -700 +714 @@
         //
         // Stops tracking `views` registered to a `selector`. If no `views` are
-        // set, then all of the `selector`'s subviews will be unregistered.
-        unset: function( selector, views ) {
+        // set, then all of the `selector`'s subviews will be unregistered and
+        // disposed.
+        //
+        // Accepts an `options` object. If `options.silent` is set, `dispose`
+        // will *not* be triggered on the unregistered views.
+        unset: function( selector, views, options ) {
             var existing;
 
             if ( ! _.isString( selector ) ) {
+                options = views;
                 views = selector;
                 selector = '';
@@ -713 +732 @@
                 this._views[ selector ] = views.length ? _.difference( existing, views ) : [];
             }
+
+            if ( ! options || ! options.silent )
+                _.invoke( views, 'dispose', { silent: true });
 
             return this;
@@ -747 +769 @@
         // ### Dispose all subviews
         //
-        // Triggers the `dispose()` method on all subviews. Resets the
-        // internals of the views manager.
-        dispose: function() {
-            delete this.parent;
-            delete this.selector;
+        // Triggers the `dispose()` method on all subviews. Detaches the master
+        // view from its parent. Resets the internals of the views manager.
+        //
+        // Accepts an `options` object. If `options.silent` is set, `unset`
+        // will *not* be triggered on the master view's parent.
+        dispose: function( options ) {
+            if ( ! options || ! options.silent ) {
+                if ( this.parent && this.parent.views )
+                    this.parent.views.unset( this.selector, this.view, { silent: true });
+                delete this.parent;
+                delete this.selector;
+            }
 
             _.invoke( this.all(), 'dispose' );