Chaplin Documentation

Chaplin.CollectionView → Source

The CollectionView is responsible for displaying collections. For every item in a collection, it instantiates a corresponding item view and inserts it into the DOM. It reacts to collection change events (add, remove and reset) and provides basic filtering, caching of views, fallback content and loading indicators.

Properties

itemView

Your item view class, which will be instantiated for each individual item in the collection.

autoRender

Render the view automatically on instantiation. Other than in Chaplin.View, this is active by default. Your inheriting classes (and instantiated objects via the options hash) can set their own value.

renderItems

Should the view automatically render all items on instantiation?

Can be passed during instantiation via the options hash.

animationDuration

When new items are added, their views are faded in over a period of animationDuration milliseconds. Set to 0 to disable fade in.

listSelector

Specifies a selector for the container into which item views will be injected. If empty, the collection view’s $el is used.

itemSelector

Selector identifying child elements considered part of this collection. If empty, all children of listSelector are considered.

loadingSelector

Selector for a loading indicator element which is shown while the collection is syncing.

fallbackSelector

Selector for a fallback element which is shown if the collection is empty.

useCssAnimation

By default, fading in is done by a JavaScript function which can be slow on mobile devices. CSS animations are faster, but require manual definition.

animationStartClass

CSS classes that will be used when the hiding/showing of child views starts.

animationEndClass

CSS classes that will be used when the hiding/showing of child views ends.

Methods

Most of CollectionView’s methods should not need to be called externally. Modifying the underlying collection will automatically update the items on screen (for instance, fetching more models from the server), as the view listens for add, remove, and reset events by default.

initialize([options={}])

filter([filterer, [filterCallback]])

Calling filter directly with a filterer and filterCallback overrides the CollectionView’s properties of the same name.

When called with no arguments it is a no-op.

filterer(item, index)

An iterator function that determines which items are shown. Can be passed in during instantiation via options. The function is optional; if not set all items will be included.

Example

filterer: (item, index) ->
  item.get 'color' is 'red'

...

filterer: (item, index) ->
  index < 20 if @limit? else true

filterer: function(item, index) {
  return item.get('color') === 'red';
}
...

filterer: function(item, index) {
  return (this.limit != null) ? index < 20 : true;
}

filterCallback(view, included)

Called on each item in the collection during filtering. The default implementation hides excluded views.

Example

filterCallback: (view, included) ->
  view.$el.toggleClass('active', included)

...

filterCallback: (view, included) ->
  opts = if included then 'long-title, large-thumbnail' else 'short-title, small-thumbnail'
  view.showExtendedOptions(opts)

filterCallback: function(view, included) {
  view.$el.toggleClass('active', included);
}

...

filterCallback: function(view, included) {
  var opts = (included) ? 'long-title, large-thumbnail' : 'short-title, small-thumbnail';
  view.showExtendedOptions(opts);
}

addCollectionListeners()

By default adds event listeners for add, remove, and reset events. Can be extended to track more events.

getItemViews()

Returns a hash of views, with their cid properties as keys.

renderAllItems()

Renders and inserts all items in the collection, triggering a visibilityChange event.

renderItem(model)

Instantiates and renders the view for an item using the viewsByCid hash as a cache to prevent multiple instantiations.

initItemView(model)

Returns an instance of the view class (as determined by the itemView property). Override this method to use several item view constructors depending on the model type or data.

insertView(item, view, [index], [enableAnimation])

Inserts a view into the list at the proper position and runs the this.filterer function.

removeViewForItem(model)

Removes the view for an item, triggering a visibilityChange event.

updateVisibleItems(item, [includedInFilter], [triggerEvent])

Updates the list of visible items and triggers a visibilityChanged event if an item changed its visibility.

Usage

Most inheriting classes of CollectionView should be very small, with the majority of implementations only needing to overwrite the itemView property. Standard View conventions like adding this.listenTo handlers should still take place in initialize, but the majority of collection-specific logic is handled by this class.

Example

class LikesView extends CollectionView
  autoRender: true
  className: 'likes-list'
  itemView: LikeView
  tagName: 'ul'

var LikesView = CollectionView.extend({
  autoRender: true,
  className: 'likes-list',
  itemView: LikeView,
  tagName: 'ul'
});

Real World Examples