Changeset 22681

Timestamp:

11/19/2012 10:40:49 AM (12 years ago)

Author:

koopersmith

Message:

Media: Add documentation to media.Views. see #21390.

File:

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

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

@@ -575 +575 @@
 
     _.extend( media.Views.prototype, {
+        // ### Fetch all of the subviews
+        //
+        // Returns an array of all subviews.
         all: function() {
             return _.flatten( this._views );
         },
 
+        // ### Get a selector's subviews
+        //
+        // Fetches all subviews that match a given `selector`.
+        //
+        // If no `selector` is provided, it will grab all subviews attached
+        // to the view's root.
         get: function( selector ) {
             selector = selector || '';
@@ -584 +593 @@
         },
 
+        // ### Register subview(s)
+        //
+        // Registers any number of `views` to a `selector`.
+        //
+        // When no `selector` is provided, the root selector (the empty string)
+        // is used. `views` accepts a `Backbone.View` instance or an array of
+        // `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
+        // 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`.
         set: function( selector, views, options ) {
             var $selector, els, existing, add, method;
@@ -639 +664 @@
         },
 
+        // ### Add subview(s) to existing subviews
+        //
+        // An alias to `Views.set()`, which defaults `options.add` to true.
+        //
+        // Adds any number of `views` to a `selector`.
+        //
+        // When no `selector` is provided, the root selector (the empty string)
+        // is used. `views` accepts a `Backbone.View` instance or an array of
+        // `Backbone.View` instances.
+        //
+        // Use `Views.set()` when setting `options.add` to `false`.
+        //
+        // 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()`.
         add: function( selector, views, options ) {
             return this.set( selector, views, _.extend({ add: true }, options ) );
         },
 
+        // ### Stop tracking subviews
+        //
+        // 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 ) {
             var existing;
@@ -659 +704 @@
         },
 
+        // ### Detach all subviews
+        //
+        // Detaches all subviews from the DOM.
+        //
+        // Helps to preserve all subview events when re-rendering the master
+        // view. Used in conjunction with `Views.render()`.
         detach: function() {
             $( _.pluck( this.all(), 'el' ) ).detach();
@@ -664 +715 @@
         },
 
+        // ### Render all subviews
+        //
+        // Renders all subviews. Used in conjunction with `Views.detach()`.
         render: function() {
             var root = this._views[''];
@@ -678 +732 @@
         },
 
+        // ### Dispose all subviews
+        //
+        // Triggers the `dispose()` method on all subviews. Resets the
+        // internals of the views manager.
         dispose: function() {
             delete this.parent;
@@ -687 +745 @@
         },
 
+        // ### Replace a selector's subviews
+        //
+        // By default, sets the `$target` selector's html to the subview `els`.
+        //
+        // Can be overridden in subclasses.
         replace: function( $target, els ) {
             $target.html( els );
@@ -692 +755 @@
         },
 
+        // ### Insert subviews into a selector
+        //
+        // By default, appends the subview `els` to the end of the `$target`
+        // selector. If `options.at` is set, inserts the subview `els` at the
+        // provided index.
+        //
+        // Can be overridden in subclasses.
         insert: function( $target, els, options ) {
             var at = options && options.at,