marionette.sliding-view

A sliding Collection View in Marionette.

View example.

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( initialLowerBound )

The initial upper boundary for the SlidingView. It can be a flat value or a function. When a function is provided, it will be passed the initial lower boundary.

var MySlidingView = Mn.SlidingView.extend({
  initialLowerBound: function(initialLowerBound) {
    return initialLowerBound + 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.

compareBoundaries( a, b )

This method is used to determine whether or not two boundaries are equal. The default implementation is simply a === b, which works if you're using simple boundaries, like numbers or strings. Sometimes, though, more complex charts or grids require returning JavaScript Objects as boundaries. This hook allows you to define how those Objects should be compared.

isSmallChange( boundaries )

isSmallChange determines whether the render will occur instantly or if it will be delayed. The delay prevents too many items from being rendered at a single time, which greatly improves performance.

isSmallChange can be provided as a flat value or as a function. When a function is provided, it is passed an object with four properties:

• oldLowerBound - The previous lower boundary
• oldUpperBound - The previous upper boundary
• lowerBound - The new lower boundary
• upperBound - The new upper boundary

If your boundaries are indices, you might implement an isSmallChange method like so:

isSmallChange: function(bounds) {
  var lowerBoundDiff = Math.abs(bounds.oldLowerBound - bounds.lowerBound);
  var upperBoundDiff = Math.abs(bounds.oldUpperBound - bounds.upperBound);

  // This means that anytime less than 6 items are added/removed we will render
  // immediately rather than waiting 50ms
  return lowerBoundDiff + upperBoundDiff < 6;
}