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

  • a subclass of Chaplin.View (default null)

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

autoRender

  • boolean (default true)

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

  • boolean (default true)

Should the view automatically render all items on instantiation?

Can be passed during instantiation via the options hash.

animationDuration

  • int, duration in ms (default 500)

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

listSelector

  • string (default null)

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

itemSelector

  • string (default null)

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

loadingSelector

  • string (default null)

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

fallbackSelector

  • string (default null)

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

useCssAnimation

  • boolean (default false)

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

  • string (default "animated-item-view")

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

animationEndClass

  • string (default "animated-item-view-end")

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]])

  • function filterer (see below)
  • function filterCallback (see below)

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)

  • Model item
  • int index of item in collection
  • returns boolean: is item included?

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)

  • View view
  • boolean 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)

  • Model item

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

initItemView(model)

  • Model 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])

  • Model item
  • View view
  • int index (if unset will search through collection)
  • boolean enableAnimation (default true)

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

removeViewForItem(model)

  • Model item

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

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

  • Model item
  • boolean includedInFilter
  • triggerEvent (default true)

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