marionette.sliding-view

A sliding Collection View in Marionette.

Motivation

Some Collections contain many, many items, and rendering them all at once with a CollectionView can take a very long time. A 'sliding' CollectionView only displays some of the models at once (typically, only those visible), giving you fast load times even as the number of items goes into the tens of thousands.

Getting Started

This is a more complex view class. Accordingly, it may take some time to fully understand the API it provides. Once you've got it down, though, you should find that it's a really powerful tool.

Concepts

Understanding a few core concepts will help you to use the SlidingView.

Reference Collection

A SlidingView has two collections: collection and referenceCollection. The collection represents only the models that are currently being displayed. The referenceCollection is the full list of models that the SlidingView represents.

Update Event

The SlidingView determines if it needs to change the models that are displayed whenever the "update event" occurs. By default, the "update event" is the scroll event on the SlidingView's element.

Although in most cases the update event is typically a scroll event, it could be anything.

Lower and Upper Boundaries

The SlidingView has two internal properties, called the lowerBound and upperBound. These are two properties that can be used to determine which models from the reference collection should be displayed at any given time.

There are two hooks that are used to set the boundaries, and they are called everytime that the update event occurs.

In the simplest case, the boundaries will be indices that represent which indices to slice the referenceCollection at.

API

constructor( [options] )

A CollectionView typically receives a collection as an option. SlidingView is different in that you do not pass in a collection. Instead, pass it in as the option referenceCollection. While the referenceCollection represents the full list of models, the collection attribute will be created for you, and will be kept up-to-date with the current models that are displayed in the View.

You can either pass the referenceCollection as an option, or specify it on the prototype.

collectionClass

The Class of Collection that the SlidingView will instantiate to serve as its Collection. The default value is just Backbone.Collection, and, generally, you won't need to override this. Keep in mind that the models in this collection instance are the same models that exist in the referenceCollection.

registerUpdateEvent()

A hook that lets you register when to call the onUpdateEvent method. By default, the SlidingView listens to scroll events on its own element. By overriding this, you could make it update its collection when another element (like a parent) is scrolled, or any time any event occurs.

When overriding this method, use the onUpdateEvent method as your callback for the event.

var MySlidingView = Mn.SlidingView.extend({

  // Update whenever a model changes
  registerUpdateEvent: function() {
    var self = this;
    this.listenTo(someModel, 'change', function() {
      self.onUpdateEvent();
    });
  }
});

onUpdateEvent()

A callback that is executed every time the registered update event happens. The purpose of this callback is to throttle the true callback to the event, which is throttledUpdateHandler.

The default behavior is to throttle the throttledUpdateHandler method using the throttle method on the SlidingView.

For a big performance boost, you are highly encouraged to override this method to use requestAnimationFrame.

var MySlidingView = Mn.SlidingView.extend({

  // Use requestAnimationFrame for a big performance boost!
  onUpdateEvent: function() {
    requestAnimationFrame(this.throttledUpdateHandler);
  }
});

throttledUpdateHandler()

This is the method that contains all of the logic for the intelligent SlidingView updates. It is not recommended that you override this method. You only need to do anything with it when defining a custom onUpdateEvent method.

throttle( fn )

If you're not using requestAnimationFrame (you should be!), then you can specify how to throttle fn here. The default implementation is to use _.throttle at 60 fps.

Note that if you are using requestAnimationFrame, then you can ignore this method entirely.

pruneCollection(lowerBound, upperBound)

Use the values of lowerBound and upperBound to calculate a list of models to be set on the SlidingView's collection. By default, all of the models from referenceCollection are returned.

If your upper and lower boundaries reference indices, then you could slice your collection to return just the models within those indices.

var MySlidingView = Mn.SlidingView.extend({
  pruneCollection: function(lowerBound, upperBound) {
    return this.referenceCollection.slice(lowerBound, upperBound)
  }
});

initialLowerBound

The initial lower boundary for the SlidingView. It can be a flat value or a function.

var MySlidingView = Mn.SlidingView.extend({
  initialLowerBound: 3
});

initialUpperBound

The initial upper boundary for the SlidingView. It can be a flat value or a function.

var MySlidingView = Mn.SlidingView.extend({
  initialLowerBound: function() {
    return 5;
  }
});

getLowerBound()

A function that is called each time the update event occurs. Within this method you should calculate the new value of the lowerBound and return it.

getUpperBound( lowerBound )

Similar to the above, but for the upper boundary. It is passed the lowerBound that was just computed, if you need to use that as a reference.