1/**
2 * @output wp-includes/js/wp-backbone.js
3 */
4
5/** @namespace wp */
6window.wp = window.wp || {};
7
8(function ($) {
9 /**
10 * Create the WordPress Backbone namespace.
11 *
12 * @namespace wp.Backbone
13 */
14 wp.Backbone = {};
15
16 /**
17 * A backbone subview manager.
18 *
19 * @since 3.5.0
20 * @since 3.6.0 Moved wp.media.Views to wp.Backbone.Subviews.
21 *
22 * @memberOf wp.Backbone
23 *
24 * @class
25 *
26 * @param {wp.Backbone.View} view The main view.
27 * @param {Array|Object} views The subviews for the main view.
28 */
29 wp.Backbone.Subviews = function( view, views ) {
30 this.view = view;
31 this._views = _.isArray( views ) ? { '': views } : views || {};
32 };
33
34 wp.Backbone.Subviews.extend = Backbone.Model.extend;
35
36 _.extend( wp.Backbone.Subviews.prototype, {
37 /**
38 * Fetches all of the subviews.
39 *
40 * @since 3.5.0
41 *
42 * @return {Array} All the subviews.
43 */
44 all: function() {
45 return _.flatten( _.values( this._views ) );
46 },
47
48 /**
49 * Fetches all subviews that match a given `selector`.
50 *
51 * If no `selector` is provided, it will grab all subviews attached
52 * to the view's root.
53 *
54 * @since 3.5.0
55 *
56 * @param {string} selector A jQuery selector.
57 *
58 * @return {Array} All the subviews that match the selector.
59 */
60 get: function( selector ) {
61 selector = selector || '';
62 return this._views[ selector ];
63 },
64
65 /**
66 * Fetches the first subview that matches a given `selector`.
67 *
68 * If no `selector` is provided, it will grab the first subview attached to the
69 * view's root.
70 *
71 * Useful when a selector only has one subview at a time.
72 *
73 * @since 3.5.0
74 *
75 * @param {string} selector A jQuery selector.
76 *
77 * @return {Backbone.View} The view.
78 */
79 first: function( selector ) {
80 var views = this.get( selector );
81 return views && views.length ? views[0] : null;
82 },
83
84 /**
85 * Registers subview(s).
86 *
87 * Registers any number of `views` to a `selector`.
88 *
89 * When no `selector` is provided, the root selector (the empty string)
90 * is used. `views` accepts a `Backbone.View` instance or an array of
91 * `Backbone.View` instances.
92 *
93 * ---
94 *
95 * Accepts an `options` object, which has a significant effect on the
96 * resulting behavior.
97 *
98 * `options.silent` - *boolean, `false`*
99 * If `options.silent` is true, no DOM modifications will be made.
100 *
101 * `options.add` - *boolean, `false`*
102 * Use `Views.add()` as a shortcut for setting `options.add` to true.
103 *
104 * By default, the provided `views` will replace any existing views
105 * associated with the selector. If `options.add` is true, the provided
106 * `views` will be added to the existing views.
107 *
108 * `options.at` - *integer, `undefined`*
109 * When adding, to insert `views` at a specific index, use `options.at`.
110 * By default, `views` are added to the end of the array.
111 *
112 * @since 3.5.0
113 *
114 * @param {string} selector A jQuery selector.
115 * @param {Array|Object} views The subviews for the main view.
116 * @param {Object} options Options for call. If `options.silent` is true,
117 * no DOM modifications will be made. Use
118 * `Views.add()` as a shortcut for setting
119 * `options.add` to true. If `options.add` is
120 * true, the provided `views` will be added to
121 * the existing views. When adding, to insert
122 * `views` at a specific index, use `options.at`.
123 *
124 * @return {wp.Backbone.Subviews} The current Subviews instance.
125 */
126 set: function( selector, views, options ) {
127 var existing, next;
128
129 if ( ! _.isString( selector ) ) {
130 options = views;
131 views = selector;
132 selector = '';
133 }
134
135 options = options || {};
136 views = _.isArray( views ) ? views : [ views ];
137 existing = this.get( selector );
138 next = views;
139
140 if ( existing ) {
141 if ( options.add ) {
142 if ( _.isUndefined( options.at ) ) {
143 next = existing.concat( views );
144 } else {
145 next = existing;
146 next.splice.apply( next, [ options.at, 0 ].concat( views ) );
147 }
148 } else {
149 _.each( next, function( view ) {
150 view.__detach = true;
151 });
152
153 _.each( existing, function( view ) {
154 if ( view.__detach )
155 view.$el.detach();
156 else
157 view.remove();
158 });
159
160 _.each( next, function( view ) {
161 delete view.__detach;
162 });
163 }
164 }
165
166 this._views[ selector ] = next;
167
168 _.each( views, function( subview ) {
169 var constructor = subview.Views || wp.Backbone.Subviews,
170 subviews = subview.views = subview.views || new constructor( subview );
171 subviews.parent = this.view;
172 subviews.selector = selector;
173 }, this );
174
175 if ( ! options.silent )
176 this._attach( selector, views, _.extend({ ready: this._isReady() }, options ) );
177
178 return this;
179 },
180
181 /**
182 * Add subview(s) to existing subviews.
183 *
184 * An alias to `Views.set()`, which defaults `options.add` to true.
185 *
186 * Adds any number of `views` to a `selector`.
187 *
188 * When no `selector` is provided, the root selector (the empty string)
189 * is used. `views` accepts a `Backbone.View` instance or an array of
190 * `Backbone.View` instances.
191 *
192 * Uses `Views.set()` when setting `options.add` to `false`.
193 *
194 * Accepts an `options` object. By default, provided `views` will be
195 * inserted at the end of the array of existing views. To insert
196 * `views` at a specific index, use `options.at`. If `options.silent`
197 * is true, no DOM modifications will be made.
198 *
199 * For more information on the `options` object, see `Views.set()`.
200 *
201 * @since 3.5.0
202 *
203 * @param {string} selector A jQuery selector.
204 * @param {Array|Object} views The subviews for the main view.
205 * @param {Object} options Options for call. To insert `views` at a
206 * specific index, use `options.at`. If
207 * `options.silent` is true, no DOM modifications
208 * will be made.
209 *
210 * @return {wp.Backbone.Subviews} The current subviews instance.
211 */
212 add: function( selector, views, options ) {
213 if ( ! _.isString( selector ) ) {
214 options = views;
215 views = selector;
216 selector = '';
217 }
218
219 return this.set( selector, views, _.extend({ add: true }, options ) );
220 },
221
222 /**
223 * Removes an added subview.
224 *
225 * Stops tracking `views` registered to a `selector`. If no `views` are
226 * set, then all of the `selector`'s subviews will be unregistered and
227 * removed.
228 *
229 * Accepts an `options` object. If `options.silent` is set, `remove`
230 * will *not* be triggered on the unregistered views.
231 *
232 * @since 3.5.0
233 *
234 * @param {string} selector A jQuery selector.
235 * @param {Array|Object} views The subviews for the main view.
236 * @param {Object} options Options for call. If `options.silent` is set,
237 * `remove` will *not* be triggered on the
238 * unregistered views.
239 *
240 * @return {wp.Backbone.Subviews} The current Subviews instance.
241 */
242 unset: function( selector, views, options ) {
243 var existing;
244
245 if ( ! _.isString( selector ) ) {
246 options = views;
247 views = selector;
248 selector = '';
249 }
250
251 views = views || [];
252
253 if ( existing = this.get( selector ) ) {
254 views = _.isArray( views ) ? views : [ views ];
255 this._views[ selector ] = views.length ? _.difference( existing, views ) : [];
256 }
257
258 if ( ! options || ! options.silent )
259 _.invoke( views, 'remove' );
260
261 return this;
262 },
263
264 /**
265 * Detaches all subviews.
266 *
267 * Helps to preserve all subview events when re-rendering the master
268 * view. Used in conjunction with `Views.render()`.
269 *
270 * @since 3.5.0
271 *
272 * @return {wp.Backbone.Subviews} The current Subviews instance.
273 */
274 detach: function() {
275 $( _.pluck( this.all(), 'el' ) ).detach();
276 return this;
277 },
278
279 /**
280 * Renders all subviews.
281 *
282 * Used in conjunction with `Views.detach()`.
283 *
284 * @since 3.5.0
285 *
286 * @return {wp.Backbone.Subviews} The current Subviews instance.
287 */
288 render: function() {
289 var options = {
290 ready: this._isReady()
291 };
292
293 _.each( this._views, function( views, selector ) {
294 this._attach( selector, views, options );
295 }, this );
296
297 this.rendered = true;
298 return this;
299 },
300
301 /**
302 * Removes all subviews.
303 *
304 * Triggers the `remove()` method on all subviews. Detaches the master
305 * view from its parent. Resets the internals of the views manager.
306 *
307 * Accepts an `options` object. If `options.silent` is set, `unset`
308 * will *not* be triggered on the master view's parent.
309 *
310 * @since 3.6.0
311 *
312 * @param {Object} options Options for call.
313 * @param {boolean} options.silent If true, `unset` will *not* be triggered on
314 * the master views' parent.
315 *
316 * @return {wp.Backbone.Subviews} The current Subviews instance.
317 */
318 remove: function( options ) {
319 if ( ! options || ! options.silent ) {
320 if ( this.parent && this.parent.views )
321 this.parent.views.unset( this.selector, this.view, { silent: true });
322 delete this.parent;
323 delete this.selector;
324 }
325
326 _.invoke( this.all(), 'remove' );
327 this._views = [];
328 return this;
329 },
330
331 /**
332 * Replaces a selector's subviews
333 *
334 * By default, sets the `$target` selector's html to the subview `els`.
335 *
336 * Can be overridden in subclasses.
337 *
338 * @since 3.5.0
339 *
340 * @param {string} $target Selector where to put the elements.
341 * @param {*} els HTML or elements to put into the selector's HTML.
342 *
343 * @return {wp.Backbone.Subviews} The current Subviews instance.
344 */
345 replace: function( $target, els ) {
346 $target.html( els );
347 return this;
348 },
349
350 /**
351 * Insert subviews into a selector.
352 *
353 * By default, appends the subview `els` to the end of the `$target`
354 * selector. If `options.at` is set, inserts the subview `els` at the
355 * provided index.
356 *
357 * Can be overridden in subclasses.
358 *
359 * @since 3.5.0
360 *
361 * @param {string} $target Selector where to put the elements.
362 * @param {*} els HTML or elements to put at the end of the
363 * $target.
364 * @param {?Object} options Options for call.
365 * @param {?number} options.at At which index to put the elements.
366 *
367 * @return {wp.Backbone.Subviews} The current Subviews instance.
368 */
369 insert: function( $target, els, options ) {
370 var at = options && options.at,
371 $children;
372
373 if ( _.isNumber( at ) && ($children = $target.children()).length > at )
374 $children.eq( at ).before( els );
375 else
376 $target.append( els );
377
378 return this;
379 },
380
381 /**
382 * Triggers the ready event.
383 *
384 * Only use this method if you know what you're doing. For performance reasons,
385 * this method does not check if the view is actually attached to the DOM. It's
386 * taking your word for it.
387 *
388 * Fires the ready event on the current view and all attached subviews.
389 *
390 * @since 3.5.0
391 */
392 ready: function() {
393 this.view.trigger('ready');
394
395 // Find all attached subviews, and call ready on them.
396 _.chain( this.all() ).map( function( view ) {
397 return view.views;
398 }).flatten().where({ attached: true }).invoke('ready');
399 },
400 /**
401 * Attaches a series of views to a selector. Internal.
402 *
403 * Checks to see if a matching selector exists, renders the views,
404 * performs the proper DOM operation, and then checks if the view is
405 * attached to the document.
406 *
407 * @since 3.5.0
408 *
409 * @private
410 *
411 * @param {string} selector A jQuery selector.
412 * @param {Array|Object} views The subviews for the main view.
413 * @param {Object} options Options for call.
414 * @param {boolean} options.add If true the provided views will be added.
415 *
416 * @return {wp.Backbone.Subviews} The current Subviews instance.
417 */
418 _attach: function( selector, views, options ) {
419 var $selector = selector ? this.view.$( selector ) : this.view.$el,
420 managers;
421
422 // Check if we found a location to attach the views.
423 if ( ! $selector.length )
424 return this;
425
426 managers = _.chain( views ).pluck('views').flatten().value();
427
428 // Render the views if necessary.
429 _.each( managers, function( manager ) {
430 if ( manager.rendered )
431 return;
432
433 manager.view.render();
434 manager.rendered = true;
435 }, this );
436
437 // Insert or replace the views.
438 this[ options.add ? 'insert' : 'replace' ]( $selector, _.pluck( views, 'el' ), options );
439
440 /*
441 * Set attached and trigger ready if the current view is already
442 * attached to the DOM.
443 */
444 _.each( managers, function( manager ) {
445 manager.attached = true;
446
447 if ( options.ready )
448 manager.ready();
449 }, this );
450
451 return this;
452 },
453
454 /**
455 * Determines whether or not the current view is in the DOM.
456 *
457 * @since 3.5.0
458 *
459 * @private
460 *
461 * @return {boolean} Whether or not the current view is in the DOM.
462 */
463 _isReady: function() {
464 var node = this.view.el;
465 while ( node ) {
466 if ( node === document.body )
467 return true;
468 node = node.parentNode;
469 }
470
471 return false;
472 }
473 });
474
475 wp.Backbone.View = Backbone.View.extend({
476
477 // The constructor for the `Views` manager.
478 Subviews: wp.Backbone.Subviews,
479
480 /**
481 * The base view class.
482 *
483 * This extends the backbone view to have a build-in way to use subviews. This
484 * makes it easier to have nested views.
485 *
486 * @since 3.5.0
487 * @since 3.6.0 Moved wp.media.View to wp.Backbone.View
488 *
489 * @constructs
490 * @augments Backbone.View
491 *
492 * @memberOf wp.Backbone
493 *
494 *
495 * @param {Object} options The options for this view.
496 */
497 constructor: function( options ) {
498 this.views = new this.Subviews( this, this.views );
499 this.on( 'ready', this.ready, this );
500
501 this.options = options || {};
502
503 Backbone.View.apply( this, arguments );
504 },
505
506 /**
507 * Removes this view and all subviews.
508 *
509 * @since 3.5.0
510 *
511 * @return {wp.Backbone.Subviews} The current Subviews instance.
512 */
513 remove: function() {
514 var result = Backbone.View.prototype.remove.apply( this, arguments );
515
516 // Recursively remove child views.
517 if ( this.views )
518 this.views.remove();
519
520 return result;
521 },
522
523 /**
524 * Renders this view and all subviews.
525 *
526 * @since 3.5.0
527 *
528 * @return {wp.Backbone.View} The current instance of the view.
529 */
530 render: function() {
531 var options;
532
533 if ( this.prepare )
534 options = this.prepare();
535
536 this.views.detach();
537
538 if ( this.template ) {
539 options = options || {};
540 this.trigger( 'prepare', options );
541 this.$el.html( this.template( options ) );
542 }
543
544 this.views.render();
545 return this;
546 },
547
548 /**
549 * Returns the options for this view.
550 *
551 * @since 3.5.0
552 *
553 * @return {Object} The options for this view.
554 */
555 prepare: function() {
556 return this.options;
557 },
558
559 /**
560 * Method that is called when the ready event is triggered.
561 *
562 * @since 3.5.0
563 */
564 ready: function() {}
565 });
566}(jQuery));
567