2.1   Model

Backbone represents data as Models, which can be created, validated, destroyed, and saved to the server. For example, a simple model look like this:

app.Todo = Backbone.Model.extend({
    defaults: {
        title: '',
        completed: false
    },
});

Whenever a UI action causes an attribute of a model to change, the model triggers a "change" event; all the Views that display the model's state can be notified of the change so that they are able to respond accordingly.

Properties:

defaults

Used to specify the default attributes for your model. When creating an instance of the model, any unspecified attributes will be set to their default value.

get(attribute)

To access attributes, use get:

var todo = new app.Todo({title: "Get the milk"});
todo.get('title'); // "Get the milk"
todo.get("created_at"); // undefined
todo.set("created_at", Date());
todo.get("created_at"); // "Wed Sep 12 2012 12:51:17 GMT-0400 (EDT)"

parse(response, options)

Called whenever a model's data is returned by the server, in fetch, and save. The function is passed the raw response object, and should return the attributes hash to be set on the model. The default implementation is a no-op, simply passing through the JSON response. Override this if you need to work with a preexisting API, or better namespace your responses.

url()

The relative URL where the model's resource would be located on the server. [*] If your models are located somewhere else, override this method with the correct logic. Generates URLs of the form: "[collection.url]/[id]" by default, but you may override by specifying an explicit urlRoot if the model's collection shouldn't be taken into account.

urlRoot

Enables the default url() function to generate URLs based on the model id if you're using a model outside of a collection.

2.2   Collection

A collection is an ordered set of models.

A simple collection looks like this:

var Cars = Backbone.Collection.extend({
    model: app.Car,
});

2.3   View

A view is a subclass of Backbone.View that overrides the render() method:

var AppView = Backbone.View.extend({
    template: _.template($('#my-template').html()),

    render: function() {
        this.$el.html(this.template(this.model.toJSON()));
        return this;
    }
});

To construct a view, use the constructor as expected:

var appView = new AppView({
    el: el,
    model: model,
    foo: foo
});

Options passed to the view will be available on the this.options object. However, there are several special options that will be attached directly to the view if passed: model, collection, el, id, className, tagName, attributes, and events. If the view defines an initialize() function, it will be called when the view is first created. If you'd like to create a view that references an element already in the DOM, pass in the element as an option: new View({el: existingElement}).

Backbone will attach event listeners at instantiation time, right before invoking initialize.

Properties:

delegateEvents([events])

This function is called within the View's constructor for you, so you usually do not need to call this function yourself. However, if a parent view calls $this.$el.empty and re-renders the child view, you will need to invoke this since this.$el.empty removes event handlers.

$el

A cached jQuery object of the view's element.

el

All views have a DOM_ element at all time. If no element is passed to the constructor, Backbone will create a root element for the view automatically.

events

A hash or method which returns a hash from CSS selectors to either names of method on the view or standalone functions:

var MyView = Backbone.View.extend({
    events: {
        "dblclick": "open",
        "click .icon.doc": "select",
    },

    open: function() {
        window.open(this.model.get("viewer_url")),
    },

    select: function(e) {
        this.model.set({selected: true});
    }
})

Omitting the selector causes the events to be bound to the view's root element.

render

Render the view template from model data, and updates this.el with the new HTML. A good convention is to return this at the end of render to enable chained calls.

template

Backbone is agnostic with respect to your preferred method of HTML templating.

render: function () {
    this.$el.html(this.template(options));
    return this;
}

?

render : function () {
    this.$el.html(this.template());

    this.subview1 = new Subview1();
    this.subview2 = new Subview2();

    this.$el.append(this.subview1.render().$el);
    this.$el.append(this.subview2.render().$el);

    return this;
}

render : function () {
    this.$el.html(this.template());

    this.subview1.setElement(this.$('.subview1')).render();
    this.subview2.setElement(this.$('.subview2')).render();
}

render : function () {
    this.$el.html(this.template());

    this.assign(this.subview1, '.subview1');
    this.assign(this.subview2, '.subview2');
}

assign : function (view, selector) {
    view.setElement(this.$(selector)).render();
}

var ParentView = Backbone.View.extend({
    initialize: function() {
        this.children = _.map(this.model.children, function(model) {
            return new ChildView({model: model});
        }, this);
    },
    render: function() {
        this.$el.html(this.template(this.model.toJSON()));
        _.each(this.children, function(child) {
            // This needs to call setElement
            child.render();
            this.$("#children").append(child.el);
        });
    },
    template: _.template($('#parent-template').html()),
});

var ListView = Backbone.View.extend({
    addOne: function(model) {
        var view = new this.options.viewClass({model: model});
        view.render();
        this.$el.append(view.el);
        this.views.push(view);
    },

    clear: function() {
        _.invoke(this.views, 'remove');
        this.views = [];
    },

    initialize: function() {
        this.views = [];
        this.listenTo(this.collection, 'add remove', this.render, this);
    },

    render: function() {
        this.clear();
        this.collection.each(this.addOne, this);
    }
});

2.4   Event

2.5   Router

2.6   History

2.7   Sync

2.8   Utility

3.1   Event aggregator

An event aggregator is a central object that manages the raising of events and the subscribers for those events. In terms of messaging patterns, the event aggregator is an in-memory, object based publish-subscribe model. It allows you have to have disparate parts of your system react to the events of other parts of the system, without having them directly coupled. [3]

A simple event aggregator might work like this [3]:

AddEditView = Backbone.View.extend({
  initialize: function(options){
    _.bindAll(this, "editMedication");
    options.vent.bind("editMedication", this.editMedication);
  },

  editMedication: function(medication){
    this.model = medication;
    this.render();
  }
});

MedicationView = Backbone.View.extend({
  events: {
    "click #edit": "editMedication"
  },

  initialize: function(options){
    this.vent = options.vent;
  },

  editMedication: function(){
    this.vent.trigger("editMedication", this.model);
  }
});

// Event aggregator object
var vent = _.extend({}, Backbone.Events);

var addEditView = new AddEditView({vent: vent});

medicationList.each(function(med){
  new MedicationView({model: med, vent: vent});
});

To make the event dispatcher global, add the event aggregator to the prototype of every core object:

var dispatcher = _.extend({}, Backbone.Events, {
  cid: "dispatcher"
});
_.each([
      Backbone.Collection.prototype,
      Backbone.Model.prototype,
      Backbone.View.prototype,
      Backbone.Router.prototype
  ], function(proto) {
  return _.extend(proto, {
    global_dispatcher: dispatcher
  });
});

3.2   Forms

It can be difficult to sync forms with models. A natural pattern might look this:

var Form = Backbone.View.extend({
    events: {
        'change input': 'set',
        'change select': 'set'
    },
    initialize: function() {
        this.listenTo(this.model, 'change', this.render);
    },
    render: function() {
        this.$el.html(this.template(this.model.attributes));
    },
    set: function(e) {
        self.model.set(e.target.name, e.target.value);
    },
    template: _.template($('template-form')).html()
});

However, this make it impossible for a user to tab through a form, since the form re-renders every time the user change an input.

A simple solution here would be to provide some option to interpolate the form without re-rendering the entire template:

var Form = Backbone.View.extend({
    events: {
        'change input': 'set',
        'change select': 'set'
    },
    interpolate: function(model) {
        _.each(model.changed, function(value, key) {
            this.$('input[name="' + key + '"]').val(value);
            this.$('select[name="' + key + '"]').val(value);
        }, this);
    },
    initialize: function() {
        this.listenTo(this.model, 'change', this.interpolate);
    },
    render: function() {
        this.$el.html(this.template(this.model.attributes));
        this.interpolate(this.model);
    },
    set: function(e) {
        self.model.set(e.target.name, e.target.value);
    },
    template: _.template($('template-form')).html()
});

3.3   View decomposition

The following example demonstrates that we sometime must decompose views in order to get the functionality we need. I haven't figured out the general principle yet though.

Consider a form element which has a submit button that should only be enabled if the form is valid:

<script type="text/template" id="form-template">
    <form>
        <input name="name" type="text" value="{{model.name}}">
        <button type="submit" {{ isValid ? "" : "disabled" }}>
    </form>
</script>

var Form = Backbone.View.extend({
    events: {
        'input input: set'
    },

    isValid: function() {
        return !_.some(this.$("[required]:visible"), function(field) {
            return $(field).val() === "";
        });
    },

    render: function() {
        this.$el.html(this.template(_.extend({
            isValid: this.isValid()
        }, this.model.attributes)));
    },

    set: function(e) {
        this.model.set(e.target.id, e.target.value, {silent: true});
    },

    template: _.template($('#form-template').html())
})

The above will not work very well. The trouble is that set() updates the model silently, which means the submit button will not become valid when the user fills in the name. However, if we disable silent, then every time the user inputs a character into the input, the view will be rendered and the user will not be able to type.

To fix this, we can decompose the view into two parts and reassign isValid to the model:

<script type="text/template" id="form-template">
    <form>
        <input name="name" type="text" value="{{model.name}}">
        <div class="controls"></div>
    </form>
</script>

<script type="text/template" id="button-submit-template">
    <button type="submit" {{ isValid ? "" : "disabled" }}>
</script>

var ButtonSubmit = Backbone.View.extend({
    initialize: function() {
        this.listenTo(this.model, 'change', this.render);
    }

    render: function() {
        this.$el.html(this.template({isValid: this.model.isValid()}));
    },

    template: _.template($('#button-submit-template').html())
});

var Form = Backbone.View.extend({
    events: {
        'input input: set'
    },

    initialize: function() {
        this.buttonSubmit = new ButtonSubmit({model: model});
    },

    render: function() {
        this.$el.html(this.template(_.extend(this.model.attributes)));
        this.buttonSubmit.setElement(this.$('.controls')).render();
    },

    set: function(e) {
        this.model.set(e.target.id, e.target.value, {silent: true});
    },

    template: _.template($('#form-template').html())
})

5.1   0.3

• 0.3.1: https://github.com/jashkenas/backbone/commit/78cf0706943e1d1e99c4be6357bdf64f7f1c1671
• 0.3.2: https://github.com/jashkenas/backbone/commit/356664a7357ddb9b4cfcda40e37918d21c0b0dd3

5.2   0.2

5.3   0.1

• 0.1.2 https://github.com/jashkenas/backbone/commit/d2ba3311843e6ac33160b31305c57b68ed162992
• 0.1.1 https://github.com/jashkenas/backbone/commit/184687b28fb9c5a11333b32da3b485f926da6636

6.1   How can I use Mustache template syntax?

To make Backbone use Mustache template syntax you can override the templateSetting variable of Underscore.js:

_.templateSettings = {
    evaluate: /\[\[(.+?)\]\]/g,
    interpolate: /\{\{(.+?)\}\}/g
};

Then you can use {{  }} instead of <%=  %> and [[ ]] instead of <% %>.

6.2   How do I fetch relationships of a model?

Consider the following:

var Parent = Backbone.Model.extend({
    parse: function(response) {
        response.children = _.map(response.children, function(id) {
            var child = Child({id: id});
            child.fetch(); // This is asynchronous, so it fails
            return child.attributes;
        });
        return response;
    },
    url: "/parents"
});

Possible solutions....

• Extend Backbone.Model to have a synchronous fetch
• Delay parsing children until Parent.initialize(), but this suffer the same problem since initialize() is synchronous. This is also bad, because the Parent is in a sort of inconsistent state.
• Delay parsing until render(), but that mixes up initialization logic with render().