1 window.wp = window.wp || {};
4 // Create the WordPress Backbone namespace.
8 // wp.Backbone.Subviews
9 // --------------------
12 wp.Backbone.Subviews = function( view, views ) {
14 this._views = _.isArray( views ) ? { '': views } : views || {};
17 wp.Backbone.Subviews.extend = Backbone.Model.extend;
19 _.extend( wp.Backbone.Subviews.prototype, {
20 // ### Fetch all of the subviews
22 // Returns an array of all subviews.
24 return _.flatten( this._views );
27 // ### Get a selector's subviews
29 // Fetches all subviews that match a given `selector`.
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 ];
38 // ### Get a selector's first subview
40 // Fetches the first subview that matches a given `selector`.
42 // If no `selector` is provided, it will grab the first subview
43 // attached to the view's root.
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;
51 // ### Register subview(s)
53 // Registers any number of `views` to a `selector`.
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.
61 // Accepts an `options` object, which has a significant effect on the
62 // resulting behavior.
64 // `options.silent` – *boolean, `false`*
65 // > If `options.silent` is true, no DOM modifications will be made.
67 // `options.add` – *boolean, `false`*
68 // > Use `Views.add()` as a shortcut for setting `options.add` to true.
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.
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 ) {
80 if ( ! _.isString( selector ) ) {
86 options = options || {};
87 views = _.isArray( views ) ? views : [ views ];
88 existing = this.get( selector );
93 if ( _.isUndefined( options.at ) ) {
94 next = existing.concat( views );
97 next.splice.apply( next, [ options.at, 0 ].concat( views ) );
100 _.each( next, function( view ) {
101 view.__detach = true;
104 _.each( existing, function( view ) {
111 _.each( next, function( view ) {
112 delete view.__detach;
117 this._views[ selector ] = next;
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;
126 if ( ! options.silent )
127 this._attach( selector, views, _.extend({ ready: this._isReady() }, options ) );
132 // ### Add subview(s) to existing subviews
134 // An alias to `Views.set()`, which defaults `options.add` to true.
136 // Adds any number of `views` to a `selector`.
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.
142 // Use `Views.set()` when setting `options.add` to `false`.
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.
149 // For more information on the `options` object, see `Views.set()`.
150 add: function( selector, views, options ) {
151 if ( ! _.isString( selector ) ) {
157 return this.set( selector, views, _.extend({ add: true }, options ) );
160 // ### Stop tracking subviews
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
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 ) {
171 if ( ! _.isString( selector ) ) {
179 if ( existing = this.get( selector ) ) {
180 views = _.isArray( views ) ? views : [ views ];
181 this._views[ selector ] = views.length ? _.difference( existing, views ) : [];
184 if ( ! options || ! options.silent )
185 _.invoke( views, 'remove' );
190 // ### Detach all subviews
192 // Detaches all subviews from the DOM.
194 // Helps to preserve all subview events when re-rendering the master
195 // view. Used in conjunction with `Views.render()`.
197 $( _.pluck( this.all(), 'el' ) ).detach();
201 // ### Render all subviews
203 // Renders all subviews. Used in conjunction with `Views.detach()`.
206 ready: this._isReady()
209 _.each( this._views, function( views, selector ) {
210 this._attach( selector, views, options );
213 this.rendered = true;
217 // ### Remove all subviews
219 // Triggers the `remove()` method on all subviews. Detaches the master
220 // view from its parent. Resets the internals of the views manager.
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 });
229 delete this.selector;
232 _.invoke( this.all(), 'remove' );
237 // ### Replace a selector's subviews
239 // By default, sets the `$target` selector's html to the subview `els`.
241 // Can be overridden in subclasses.
242 replace: function( $target, els ) {
247 // ### Insert subviews into a selector
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
253 // Can be overridden in subclasses.
254 insert: function( $target, els, options ) {
255 var at = options && options.at,
258 if ( _.isNumber( at ) && ($children = $target.children()).length > at )
259 $children.eq( at ).before( els );
261 $target.append( els );
266 // ### Trigger the ready event
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.
272 // Fires the ready event on the current view and all attached subviews.
274 this.view.trigger('ready');
276 // Find all attached subviews, and call ready on them.
277 _.chain( this.all() ).map( function( view ) {
279 }).flatten().where({ attached: true }).invoke('ready');
282 // #### Internal. Attaches a series of views to a selector.
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,
291 // Check if we found a location to attach the views.
292 if ( ! $selector.length )
295 managers = _.chain( views ).pluck('views').flatten().value();
297 // Render the views if necessary.
298 _.each( managers, function( manager ) {
299 if ( manager.rendered )
302 manager.view.render();
303 manager.rendered = true;
306 // Insert or replace the views.
307 this[ options.add ? 'insert' : 'replace' ]( $selector, _.pluck( views, 'el' ), options );
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;
321 // #### Internal. Checks if the current view is in the DOM.
322 _isReady: function() {
323 var node = this.view.el;
325 if ( node === document.body )
327 node = node.parentNode;
338 // The base view class.
339 wp.Backbone.View = Backbone.View.extend({
340 // The constructor for the `Views` manager.
341 Subviews: wp.Backbone.Subviews,
343 constructor: function( options ) {
344 this.views = new this.Subviews( this, this.views );
345 this.on( 'ready', this.ready, this );
347 this.options = options || {};
349 Backbone.View.apply( this, arguments );
353 var result = Backbone.View.prototype.remove.apply( this, arguments );
355 // Recursively remove child views.
366 options = this.prepare();
370 if ( this.template ) {
371 options = options || {};
372 this.trigger( 'prepare', options );
373 this.$el.html( this.template( options ) );
380 prepare: function() {