[Summary view] [Print] [Text view]

   1  window.wp = window.wp || {};
   2  
   3  (function ($) {
   4      // Create the WordPress Backbone namespace.
   5      wp.Backbone = {};
   6  
   7  
   8      // wp.Backbone.Subviews
   9      // --------------------
  10      //
  11      // A subview manager.
  12      wp.Backbone.Subviews = function( view, views ) {
  13          this.view = view;
  14          this._views = _.isArray( views ) ? { '': views } : views || {};
  15      };
  16  
  17      wp.Backbone.Subviews.extend = Backbone.Model.extend;
  18  
  19      _.extend( wp.Backbone.Subviews.prototype, {
  20          // ### Fetch all of the subviews
  21          //
  22          // Returns an array of all subviews.
  23          all: function() {
  24              return _.flatten( this._views );
  25          },
  26  
  27          // ### Get a selector's subviews
  28          //
  29          // Fetches all subviews that match a given `selector`.
  30          //
  31          // If no `selector` is provided, it will grab all subviews attached
  32          // to the view's root.
  33          get: function( selector ) {
  34              selector = selector || '';
  35              return this._views[ selector ];
  36          },
  37  
  38          // ### Get a selector's first subview
  39          //
  40          // Fetches the first subview that matches a given `selector`.
  41          //
  42          // If no `selector` is provided, it will grab the first subview
  43          // attached to the view's root.
  44          //
  45          // Useful when a selector only has one subview at a time.
  46          first: function( selector ) {
  47              var views = this.get( selector );
  48              return views && views.length ? views[0] : null;
  49          },
  50  
  51          // ### Register subview(s)
  52          //
  53          // Registers any number of `views` to a `selector`.
  54          //
  55          // When no `selector` is provided, the root selector (the empty string)
  56          // is used. `views` accepts a `Backbone.View` instance or an array of
  57          // `Backbone.View` instances.
  58          //
  59          // ---
  60          //
  61          // Accepts an `options` object, which has a significant effect on the
  62          // resulting behavior.
  63          //
  64          // `options.silent` – *boolean, `false`*
  65          // > If `options.silent` is true, no DOM modifications will be made.
  66          //
  67          // `options.add` – *boolean, `false`*
  68          // > Use `Views.add()` as a shortcut for setting `options.add` to true.
  69          //
  70          // > By default, the provided `views` will replace
  71          // any existing views associated with the selector. If `options.add`
  72          // is true, the provided `views` will be added to the existing views.
  73          //
  74          // `options.at` – *integer, `undefined`*
  75          // > When adding, to insert `views` at a specific index, use
  76          // `options.at`. By default, `views` are added to the end of the array.
  77          set: function( selector, views, options ) {
  78              var existing, next;
  79  
  80              if ( ! _.isString( selector ) ) {
  81                  options  = views;
  82                  views    = selector;
  83                  selector = '';
  84              }
  85  
  86              options  = options || {};
  87              views    = _.isArray( views ) ? views : [ views ];
  88              existing = this.get( selector );
  89              next     = views;
  90  
  91              if ( existing ) {
  92                  if ( options.add ) {
  93                      if ( _.isUndefined( options.at ) ) {
  94                          next = existing.concat( views );
  95                      } else {
  96                          next = existing;
  97                          next.splice.apply( next, [ options.at, 0 ].concat( views ) );
  98                      }
  99                  } else {
 100                      _.each( next, function( view ) {
 101                          view.__detach = true;
 102                      });
 103  
 104                      _.each( existing, function( view ) {
 105                          if ( view.__detach )
 106                              view.$el.detach();
 107                          else
 108                              view.remove();
 109                      });
 110  
 111                      _.each( next, function( view ) {
 112                          delete view.__detach;
 113                      });
 114                  }
 115              }
 116  
 117              this._views[ selector ] = next;
 118  
 119              _.each( views, function( subview ) {
 120                  var constructor = subview.Views || wp.Backbone.Subviews,
 121                      subviews = subview.views = subview.views || new constructor( subview );
 122                  subviews.parent   = this.view;
 123                  subviews.selector = selector;
 124              }, this );
 125  
 126              if ( ! options.silent )
 127                  this._attach( selector, views, _.extend({ ready: this._isReady() }, options ) );
 128  
 129              return this;
 130          },
 131  
 132          // ### Add subview(s) to existing subviews
 133          //
 134          // An alias to `Views.set()`, which defaults `options.add` to true.
 135          //
 136          // Adds any number of `views` to a `selector`.
 137          //
 138          // When no `selector` is provided, the root selector (the empty string)
 139          // is used. `views` accepts a `Backbone.View` instance or an array of
 140          // `Backbone.View` instances.
 141          //
 142          // Use `Views.set()` when setting `options.add` to `false`.
 143          //
 144          // Accepts an `options` object. By default, provided `views` will be
 145          // inserted at the end of the array of existing views. To insert
 146          // `views` at a specific index, use `options.at`. If `options.silent`
 147          // is true, no DOM modifications will be made.
 148          //
 149          // For more information on the `options` object, see `Views.set()`.
 150          add: function( selector, views, options ) {
 151              if ( ! _.isString( selector ) ) {
 152                  options  = views;
 153                  views    = selector;
 154                  selector = '';
 155              }
 156  
 157              return this.set( selector, views, _.extend({ add: true }, options ) );
 158          },
 159  
 160          // ### Stop tracking subviews
 161          //
 162          // Stops tracking `views` registered to a `selector`. If no `views` are
 163          // set, then all of the `selector`'s subviews will be unregistered and
 164          // removed.
 165          //
 166          // Accepts an `options` object. If `options.silent` is set, `remove`
 167          // will *not* be triggered on the unregistered views.
 168          unset: function( selector, views, options ) {
 169              var existing;
 170  
 171              if ( ! _.isString( selector ) ) {
 172                  options = views;
 173                  views = selector;
 174                  selector = '';
 175              }
 176  
 177              views = views || [];
 178  
 179              if ( existing = this.get( selector ) ) {
 180                  views = _.isArray( views ) ? views : [ views ];
 181                  this._views[ selector ] = views.length ? _.difference( existing, views ) : [];
 182              }
 183  
 184              if ( ! options || ! options.silent )
 185                  _.invoke( views, 'remove' );
 186  
 187              return this;
 188          },
 189  
 190          // ### Detach all subviews
 191          //
 192          // Detaches all subviews from the DOM.
 193          //
 194          // Helps to preserve all subview events when re-rendering the master
 195          // view. Used in conjunction with `Views.render()`.
 196          detach: function() {
 197              $( _.pluck( this.all(), 'el' ) ).detach();
 198              return this;
 199          },
 200  
 201          // ### Render all subviews
 202          //
 203          // Renders all subviews. Used in conjunction with `Views.detach()`.
 204          render: function() {
 205              var options = {
 206                      ready: this._isReady()
 207                  };
 208  
 209              _.each( this._views, function( views, selector ) {
 210                  this._attach( selector, views, options );
 211              }, this );
 212  
 213              this.rendered = true;
 214              return this;
 215          },
 216  
 217          // ### Remove all subviews
 218          //
 219          // Triggers the `remove()` method on all subviews. Detaches the master
 220          // view from its parent. Resets the internals of the views manager.
 221          //
 222          // Accepts an `options` object. If `options.silent` is set, `unset`
 223          // will *not* be triggered on the master view's parent.
 224          remove: function( options ) {
 225              if ( ! options || ! options.silent ) {
 226                  if ( this.parent && this.parent.views )
 227                      this.parent.views.unset( this.selector, this.view, { silent: true });
 228                  delete this.parent;
 229                  delete this.selector;
 230              }
 231  
 232              _.invoke( this.all(), 'remove' );
 233              this._views = [];
 234              return this;
 235          },
 236  
 237          // ### Replace a selector's subviews
 238          //
 239          // By default, sets the `$target` selector's html to the subview `els`.
 240          //
 241          // Can be overridden in subclasses.
 242          replace: function( $target, els ) {
 243              $target.html( els );
 244              return this;
 245          },
 246  
 247          // ### Insert subviews into a selector
 248          //
 249          // By default, appends the subview `els` to the end of the `$target`
 250          // selector. If `options.at` is set, inserts the subview `els` at the
 251          // provided index.
 252          //
 253          // Can be overridden in subclasses.
 254          insert: function( $target, els, options ) {
 255              var at = options && options.at,
 256                  $children;
 257  
 258              if ( _.isNumber( at ) && ($children = $target.children()).length > at )
 259                  $children.eq( at ).before( els );
 260              else
 261                  $target.append( els );
 262  
 263              return this;
 264          },
 265  
 266          // ### Trigger the ready event
 267          //
 268          // **Only use this method if you know what you're doing.**
 269          // For performance reasons, this method does not check if the view is
 270          // actually attached to the DOM. It's taking your word for it.
 271          //
 272          // Fires the ready event on the current view and all attached subviews.
 273          ready: function() {
 274              this.view.trigger('ready');
 275  
 276              // Find all attached subviews, and call ready on them.
 277              _.chain( this.all() ).map( function( view ) {
 278                  return view.views;
 279              }).flatten().where({ attached: true }).invoke('ready');
 280          },
 281  
 282          // #### Internal. Attaches a series of views to a selector.
 283          //
 284          // Checks to see if a matching selector exists, renders the views,
 285          // performs the proper DOM operation, and then checks if the view is
 286          // attached to the document.
 287          _attach: function( selector, views, options ) {
 288              var $selector = selector ? this.view.$( selector ) : this.view.$el,
 289                  managers;
 290  
 291              // Check if we found a location to attach the views.
 292              if ( ! $selector.length )
 293                  return this;
 294  
 295              managers = _.chain( views ).pluck('views').flatten().value();
 296  
 297              // Render the views if necessary.
 298              _.each( managers, function( manager ) {
 299                  if ( manager.rendered )
 300                      return;
 301  
 302                  manager.view.render();
 303                  manager.rendered = true;
 304              }, this );
 305  
 306              // Insert or replace the views.
 307              this[ options.add ? 'insert' : 'replace' ]( $selector, _.pluck( views, 'el' ), options );
 308  
 309              // Set attached and trigger ready if the current view is already
 310              // attached to the DOM.
 311              _.each( managers, function( manager ) {
 312                  manager.attached = true;
 313  
 314                  if ( options.ready )
 315                      manager.ready();
 316              }, this );
 317  
 318              return this;
 319          },
 320  
 321          // #### Internal. Checks if the current view is in the DOM.
 322          _isReady: function() {
 323              var node = this.view.el;
 324              while ( node ) {
 325                  if ( node === document.body )
 326                      return true;
 327                  node = node.parentNode;
 328              }
 329  
 330              return false;
 331          }
 332      });
 333  
 334  
 335      // wp.Backbone.View
 336      // ----------------
 337      //
 338      // The base view class.
 339      wp.Backbone.View = Backbone.View.extend({
 340          // The constructor for the `Views` manager.
 341          Subviews: wp.Backbone.Subviews,
 342  
 343          constructor: function() {
 344              this.views = new this.Subviews( this, this.views );
 345              this.on( 'ready', this.ready, this );
 346  
 347              Backbone.View.apply( this, arguments );
 348          },
 349  
 350          remove: function() {
 351              var result = Backbone.View.prototype.remove.apply( this, arguments );
 352  
 353              // Recursively remove child views.
 354              if ( this.views )
 355                  this.views.remove();
 356  
 357              return result;
 358          },
 359  
 360          render: function() {
 361              var options;
 362  
 363              if ( this.prepare )
 364                  options = this.prepare();
 365  
 366              this.views.detach();
 367  
 368              if ( this.template ) {
 369                  options = options || {};
 370                  this.trigger( 'prepare', options );
 371                  this.$el.html( this.template( options ) );
 372              }
 373  
 374              this.views.render();
 375              return this;
 376          },
 377  
 378          prepare: function() {
 379              return this.options;
 380          },
 381  
 382          ready: function() {}
 383      });
 384  }(jQuery));