wp-includes/js/wp-backbone.js

   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` &ndash; *boolean, `false`*
  65                 // > If `options.silent` is true, no DOM modifications will be made.
  66                 //
  67                 // `options.add` &ndash; *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` &ndash; *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));