minionette.collectionview.md

Minionette.CollectionView

Minionette.CollectionView is an optimized Minionette.View 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.

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

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.

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() 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(). It then renders that modelView, and passes it to #appendModelView().

#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.

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.

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() method to make sure all associated modelViews are #remove()ed.