docs/minionette.collectionview.md
Minionette.CollectionView
=========================
`Minionette.CollectionView` is an optimized
[Minionette.View](/docs/minionette.view.md) for your Backbone
collections. It quickly handles rendering using a DocumentFragment,
ensuring at most three content reflows. The most important feature of
`CollectionView` is the `#ModelView` property, from which all models
will have a view instantiated from. Additionally, it will forward a
modelView's events, prefixed by `#modelViewEventPrefix`, for easy event
listening directly on the collectionView.
## #ModelView
The `#ModelView` property should be the View class that you wish for all
your modelViews to be rendered as.
Alternatively, you may specify a properties object, which will be passed
into the `#extend()` method of `Minionette.ModelView`. This allows you
to easily define a #ModelView without declaring a class.
```javascript
var CV = Minionette.CollectionView.extend({
template: function() { /* the collectionView template */ },
tagName: 'ul', // The collectionView tagName,
// ...
ModelView: { // Specify a properties object to extend ModelView with
template: function() { /* the modelView template */ },
tagName: 'li', // The modelView tagName,
}
});
```
## #collectionEvents
```javascript
collectionEvents = {
add: 'addOne',
remove: 'removeOne',
reset: 'render',
sort: 'render'
};
```
`CollectionView` will listen for the default collection events,
rendering the appropriate function to keep things speedy.
## #modelViewEventPrefix = 'modelView'
`CollectionView` listens to all events triggered by instantiated
modelView's and will forward them. By default, `#modelViewEventPrefix`
is the string "modelView", meaning an event "test" triggered by a
modelView will be forwarded as "modelView:test" by the collectionView.
Setting `#modelViewEventPrefix` to a false-y value will cause events to
be forwarded without a prefix, so that "test" will be forwarded as
"test" by the collectionView.
Additionally, the collectionView will append itself as the final
argument passed to the event listeners.
```javascript
var CV = Minionette.CollectionView.extend({
modelViewEventPrefix: 'prefix'
});
var cv = new CV({collection: new Backbone.Collection()});
cv.on('prefix:render', function(modelView, collectionView) {
// do stuff...
});
cv.collection.add({}); // above event listener will be fired,
// adding a model creates a modelView and renders it.
```
## #render()
The `#render()` method augments `Minionette.View`'s
[#render()](/docs/minionette.view.md#render) with the collection
specific rendering. It will remove all previously associated modelViews,
and render the new ones inside a DocumentFragment, which will be
appended to the collectionView's $el.
## #addOne(model)
`#addOne()` creates a new modelView by calling
[#buildModelView()](#buildmodelviewmodel). It then renders that
modelView, and passes it to [#appendModelView()](#appendmodelviewview).
### #buildModelView(model)
`#buildModelView()` creates a new instance of #ModelView, and returns
it. It's helpful to override this method if you need to pass custom data
during the construction of the instance.
```javascript
var CV = Minionette.CollectionView.extend({
buildModelView: function(model) {
return new this.ModelView({model: model, custom: 'options'});
}
});
```
### #appendModelView(view)
`#appendModelView()`, by default, takes the passed in view and appends
its $el to the collectionView's $el. Override this method to append
modelViews to to specific elements in the collectionView's $el.
```javascript
var CV = Minionette.CollectionView.extend({
tagName: 'div',
template: _.template('<ul><li>last</li></ul>'),
appendModelView: function(view) {
this.$('ul :last-child').before(view.$el);
}
});
```
### "addOne" Event
The "addOne" event is fired after instantiating the modelView, and is
passed that modelView and the collectionView as argumentss.
### "addedOne" Event
The "addedOne" event is fired after rendering the modelView and adding
it to the collectionView's $el, and is passed that modelView and the
collectionView as it's arguments.
## #removeOne(model)
`#removeOne()` attempts to find the view associated with the removed
`model`, and calls `#remove()` on it.
### "removeOne" Event
The "removeOne" event is fired before calling `#remove()` on the view,
and is passed that modelView and the collectionView as it's arguments.
### "removedOne" Event
The "removedOne" event is fired after calling `#remove()` on the view,
and is passed that modelView and the collectionView as it's arguments.
## #remove()
`CollectionView` augments `Minionette.View`'s [#remove()](/docs/minionette.view.md#remove) method to make
sure all associated modelViews are `#remove()`ed.