For demos see the Backbone.CollectionView home page.
Depends on jQuery and jQueryUI for event handling and sorting, respectively.
- Renders a collection of models, updating automatically when models are added or removed.
- Keeps track of selected model(s) and fires events when the selection is changed.
- Adds "selected" css class to selected model views for easy stying.
- Supports single and multiple selection through meta-key and shift clicks.
- Allows a user to reorder the collection by dragging and dropping.
- Supports changing the currently selected model(s) through up and down arrow key presses.
- Allows you to filter which models are visible, selectable, and sortable.
- Integrates with Backbone.Courier out of the box.
var myCollectionView =el : // must be a 'ul' (i.e. unordered list) or 'table' elementmodelView : EmployeeView // a View class to be used for rendering each model in the collectioncollection : employeeCollection;myCollectionView;myCollectionView;
<table>element into which your collection will be rendered. If you supply a
<table>element, your modelView must have an element of type of
collection: The collection of models to be rendered.
modelView: A view constructor that will be used to create the views for each individual model.
selectable: (default: true) Determines whether models in the CollectionView are selectable.
reuseModelViews: (default: true) When
true, modelViews are reused instead of being re-created from scratch when the CollectionView is re-rendered.
detachedRendering: (default: false) When
true, all the modelViews are rendered before being added to the DOM to improve performance. If your modelView rendering relies on its location in the DOM (for sizing or other reasons), use the default value of
sortable: (default: false) Determines if models can be rearranged by dragging and dropping.
sortableOptions: Options passed through to the created jQueryUI sortable. Only applies if
emptyListCaption: A string (or a function returning a string) to be shown when the list is empty.
The following options apply when
selectable option is set:
clickToSelect: (default: true) Determines whether mouse clicks should automatically select models as would be appropriate in a standard HTML mutli-SELECT element.
processKeyEvents: (default: true) Determines if the collection view should respond to arrow key events as would be appropriate in a standard HTML multi-SELECT element.
selectMultiple: (default: false) Determines if multiple models can be selected at once.
clickToToggle: (default: false) Determines if clicking a model view should toggle its selected / unselected state. Only applies if
The following options expect a filter function that takes a single parameter, the model in question, and returns
false. They are all optional, defaulting to passing all models.
visibleModelsFilter: Determines which models are visible.
selectableModelsFilter: In a selectable CollectionView, determines which models are selectable.
sortableModelsFilter: In a sortable CollectionView, determines which models are sortable.
- setSelectedModel( modelReference, [options] ) Sets which model(s) are selected. (See below.)
- getSelectedModel( [options] ) Returns references to the selected model(s). (See below.)
- setOption( optionName, optionValue ) Updates the value of a configuration option. All constructor options above are valid except
el. The CollectionView is automatically re-rendered if necessary.
- collection The Backbone collection instance that this CollectionView represents.
- viewManager A Backbone.BabySitter instance that contains the views corresponding to the individual models in the collection. Backbone.Babysitter implements a "view collection" that enables you to, for example, iterate through all the model views, or easily trigger an event on all model views at once. See the Backbone.BabySitter documentation for more information.
setSelectedModel(s) methods are used to get or set the currently selected models. The methods are able to reference models in a variety of ways using the
// Returns an array of the selected modelsmyCollectionView;// Returns an array of the ids of the selected modelsmyCollectionView;// Select model id 2 and model id 4myCollectionView;// Select the model with cid equal to "c21"myCollectionView;// Returns the view object that represents the selected modelmyCollectionView;
As shown in the examples, the plural versions of the methods expect / return an array of "model references", whereas the singular versions expect / return just a single "model reference".
There are four valid values for
by option which determine the type of "model reference" used.
idof the model.
cidof the model.
"offset": The zero-based index of the model in the collection, only counting visible models.
"view": The view that was created to represent the model when the CollectionView was rendered.
by option is provided the model object itself is expected / returned.
setSelectedModel(s) function accepts one additional option,
silent, which, when true, will prevent the
selectionChanged event from being fired.
trigger the following events on themselves. If Backbone.Courier
is available, these events are also "spawned".
- "selectionChanged" ( newSelectedModels, oldSelectedModels ) Fired whenever the selection is changed, either by the user or by a programmatic call to
- "updateDependentControls" ( selectedModels ) Fired whenever controls that are dependent on the selection should be updated (e.g. buttons that should be disabled on no selection). This event is always fired just after
selectionChangedis fired. In addition, it is fired after rendering and sorting.
- "click" ( clickedModel ) Fired when a model view is clicked.
- "doubleClick" ( clickedModel ) Fired when a model view is double clicked.
In addition, sortable CollectionViews fire these events:
- "sortStart" Fired just as a model view is starting to be dragged.
- "sortStop" Fired after a drag is finished and after the collection is reordered.
- "reorder" Fired when a drag is finished, but before the collection is reordered.
How you style the collection view is up to you.
table element that is used as the collection view's element will be given the
collection-list class. Generally you will want to eliminate bullets, etc., from your collection view list elements, which you can do with these "base" styles:
When a model is selected, its view's
tr element will be given the
You can style the caption created by the
emptyListCaption option with the
var.empty-list-caption selector. These styles will center the empty list caption text near the top of the collection view.
See the the Backbone.CollectionView home page for styling examples.
See the the Backbone.CollectionView home page for styling examples.
- Backbone.js (tested with v1.0, v0.9.10)
- jQuery (tested with v1.9.1)
- jQueryUI - for sorting (tested with v1.10.1)
- (optional) Backbone.Courier