Minionette.View is the base View class, providing an easy way to
listen for events on an associated model or collection, an actually
useful generic rendering function, and easy subviews (AKA Regions).
In addition to the default options that Backbone pulls from the
initialization options, Minionette will also pull a #template
function, a Region class, and a regions object.
var v = new Minionette.View({
Region: Minionette.Region.extend(/* ... */),
regions: {
'one': '#one'
},
template: _.template('<p id="one"></p>')
});#modelEvents is an object, in the same form as Backbone's #events,
that specifies an event to listen for on the associated model and the
function to call when that event is triggered. The function can either
be directly assigned, or specified with a string of the function name on
the view. This property must be specified before an object is
instantiated, because the event listening happens in the constructor.
var V = Minionette.View.extend({
modelEvents: {
'change': function() {/* ... */}
}
});
var m = new Backbone.Model();
var v = new V({model: m});
m.set('test', 'er'); //=> change listener will fire.#collectionEvents is an object, in the same form as Backbone's
#events, that specifies an event to listen for on the associated
collection and the function to call when that event is triggered. The
function can either be directly assigned, or specified with a string of
the function name on the view. This property must be specified before an
object is instantiated, because the event listening happens in the
constructor.
var V = Minionette.View.extend({
collectionEvents: {
'add': function() {/* ... */}
}
});
var c = new Backbone.Collection();
var v = new V({collection: c});
c.add({}); //=> add listener will fire.The #serialize() method is meant to provide any data needed by the
#template method and should be overridden in a subclass. There is no
need to clone the output before returning, as it's data will be copied
over into a new object before being fed into #template().
var V = Minionette.View.extend({
template: _.template('<%= data %>'),
serialize: function() {
return {data: 'test'};
}
});
var v = new V();
v.render();
console.log(v.el); //=> <div>test</div>The #template() method should take any data needed to render the
view and its output will be used as the html for the view's $el. It is
fed all the data from the #serialize() method, along with a special
template helper function view().
view() is a special helper function that injects a region's subview
directly into the template. It looks for the attached region on the view,
and places the subviews entire $el (including the top level tag) into
that exact spot in the template. It does not render the region,
leaving that up to the developer, so that regions that don't need to be
re-rendered won't be. See an example of it's usage below:
Note: attaching an event listener on the view's 'render' event is any easy way to re-render any regions that need it.
var View = Minionette.View.extend({
template: _.template('The following is rendered by a subview: <%= view("text") %>')
});
var SubView = Minionette.View.extend({
tagName: 'span',
template: _.template('Hello from a subview!')
});
var view = new View({el: $('body')});
var subView = new SubView();
view.addRegion('text', subView);
view.render();
subView.render();
console.log(view.el); //=> <div>The following is rendered by a subview:<span>Hello from a subview!</span></div>The #remove() method does exactly what you would expect it to: it
removes the view and any associated regions.
The "remove" event is fired before calling #remove() on the view,
and is passed view as it's arguments.
The "removed" event is fired after calling #remove() on the view,
and is passed view as it's arguments.
Note that if you used view.listenTo(view, 'removed', ...), the
listener will never be fired because view.remove() calls
view.stopListening(). To properly listen for this event, use
view.on('removed', ...).
#render() detaches all associated regions (so they don't have their
DOM events unbound), then resets the view's $el with the output of
#template(). It will then reattach all regions into their proper
place.
The "render" event is fired at the beginning of the #render() method,
before any regions are detached and before the view's $el is reset.
Listen for this event to augment the #render() method without
overriding it. The view is passed as its argument.
The "rendered" event is fired at the end of the #render() method,
after all DOM changes. Listen for this event to augment the #render()
method without overriding it. The view is passed as its only argument.
The #addRegion() method creates a region in the view named name and
uses subView as it's view. This region is accessible as view[name].
If a false-y value is provided as subView, a default "place holder"
view will be used instead.
Alternatively, a selector can be passed as the subView argument. In this form, the region will take over the element matched by the selector, and attaching a view to the region will cause the matched element to be replaced with the view.
In any case, never worry about whether this view (the parent view) has been rendered. Region's will always be where they should be.
var View = Minionette.View.extend({
template: _.template('<div id="subView">This is a place holder view</div>' +
'<%= view("subView2") %>'),
regions: {
subView: '#subView',
subView2: new Minionette.View()
}
});
var v = new View();
v.render();
console.log(v.el); //=> <div><div id="subView">This is a place holder view</div><span data-cid="123"></span></div>
v.subView2.attach(new Minionette.View()).render();
console.log(v.el); //=> <div><div id="subView">This is a place holder view</div><div></div></div>
v.subView.attach(new Minionette.View().render());
console.log(v.el); //=> <div><div></div><div></div></div>The #addRegions() method adds several regions at a time. The regions
parameter must be an object, with keys specifying the region name and
values having the view (or selector string). Refer to
#addRegion() for more information.
var v = new Minionette.View);
v.addRegions({
subView: '#subView',
subView2: new Minionette.View(),
subView3: null
});