Backbone Support

Summary

Backbone Support provides a collection of utility classes for use with
Backbone.js. There's no built-in garbage collection for Backbone’s event
bindings, and forgetting to unbind can cause bugs and memory leaks. Backbone
Support has you covered.

Backbone Support provides two utility classes, SwappingRouter and
CompositeView, which are extensions of Backbone's standard View and Router
objects. They provide methods that simplify creating and managing nested views
and automate the cleanup of events when switching between views.

The book contains complete instructions and in-depth coverage of the internals
of CompositeView and SwappingRouter, and an example application that shows
their usage.

SwappingRouter

A Router subclass the provides a standard way to swap one view for another.

This introduces a convention that all views have a leave() function,
responsible for unbinding and cleaning up the view. And the convention that
all actions underneath the same Router share the same root element, and
define it as el on the router. Additionally, the render method for every
view must return that view (a fairly standard backbone convention).

Now, a SwappingRouter can take advantage of the leave() function, and
clean up any existing views before swapping to a new one. It swaps into a new
view by rendering that view into its own el:

CompositeView

CompositeView provides a convention for a parent view that has one or more
child views.

This introduces a convention that all views have a leave() function,
responsible for unbinding and cleaning up the view.

CompositeView provides methods for adding and removing children from the
parent view.

CompositeView maintains an array of its immediate children as
this.children. Using this reference, a parent view's leave()
method will invoke leave() on all its children, ensuring that an entire
tree of composed views is cleaned up properly.

For child views that can dismiss themselves, such as dialog boxes, children
maintain a back-reference at this.parent. This is used to reach up and call
this.parent.removeChild(this) for these self-dismissing views.

Compatibility

Backbone Support is compatible with Backbone v0.5.3 and higher, including
Backbone v1.0 (as of Backbone Support v0.4.0).

Dependencies

Backbone Support requires the following libraries:

jQuery or Zepto

Underscore

Backbone

Included Versions

For convenience, Backbone Support comes with a vendored copy of Backbone and
Underscore to get you up and running as quickly as possible. If you want to
use these included files, simply follow the instructions below in the
Installation section. The current vendored versions are:

Backbone v1.0.0

Underscore v1.4.4

Alternate Versions

If you require a different version of Backbone or Underscore than those
provided by this gem, simply put the script files in
vendor/assets/javascripts which has higher precedence than the versions
provided by the gem thanks to the ordering of the search paths in the asset
pipeline.

Installation

We recommend you use Backbone-Support with Rails 3.1 or higher in order to take
advantage of the asset pipeline.

With Rails 3.1 or higher

Add the gem to your Gemfile:

gem"backbone-support"

And then bundle install.

Before including any part of Backbone Support, you must include its
dependencies. In your application.js (or any other manifest file), add the
following to load in the needed dependencies:

// jQuery is provided by the 'jquery-rails' gem, included with Rails
//= require jquery
//
// Backbone Support includes Backbone and Underscore, or you can provides
// alternate versions by placing them in vendor/assets/javascripts/
//= require backbone
//= require underscore

To require all of Backbone Support, add the following:

//= require backbone-support

This should be above any usage of SwappingController or SwappingRouter, but
below the inclusion of Backbone.js, Underscore, and jQuery.

If you do not wish to include all of backbone-support, you can include
individual pieces. Require the support file and the individual assets you
wish to use: