Developing Backbone.js Applications

Available free for open-source reading below or for purchase via the O'Reilly store.
Pull requests and comments always welcome.

Prelude

Not so long ago, “data-rich web application” was an oxymoron. Today, these applications are everywhere and you need to know how to build them.

Traditionally, web applications left the heavy-lifting of data to servers that pushed HTML to the browser in complete page loads. The use of client-side JavaScript was limited to improving the user experience. Now this relationship has been inverted - client applications pull raw data from the server and render it into the browser when and where it is needed.

Think of the Ajax shopping cart which doesn’t require a refresh on the page when adding an item to your basket. Initially, jQuery became the go-to library for this paradigm. Its nature was to make Ajax requests then update text on the page and so on. However, this pattern with jQuery revealed that we have implicit model data on the client side. With the server no longer being the only place that knows about our item count, it was a hint that there was a natural tension and pull of this evolution.

The rise of arbitrary code on the client-side which can talk to the server however it sees fit has meant an increase in client-side complexity. Good architecture on the client has gone from an afterthought to essential - you can’t just hack together some jQuery code and expect it to scale as your application grows. Most likely, you would end up with a nightmarish tangle of UI callbacks entwined with business logic, destined to be discarded by the poor soul who inherits your code.

Thankfully, there are a growing number of JavaScript libraries that can help improve the structure and maintainability of your code, making it easier to build ambitious interfaces without a great deal of effort. Backbone.js has quickly become one of the most popular open-source solutions to these issues and in this book we will take you through an in-depth walkthrough of it.

Begin with the fundamentals, work your way through the exercises, and learn how to build an application that is both cleanly organized and maintainable. If you are a developer looking to write code that can be more easily read, structured, and extended - this guide can help.

Improving developer education is important to me, which is why this book is released under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported license. This means you can purchase or grab a copy of the book for free or help to further improve it. Corrections to existing material are always welcome and I hope that together we can provide the community with an up-to-date resource that is of help.

My extended thanks go out to Jeremy Ashkenas and DocumentCloud for creating Backbone.js and these members of the community for their assistance making this project far better than I could have imagined.

Target Audience

This book is targeted at novice to intermediate developers wishing to learn how to better structure their client-side code. An understanding of JavaScript fundamentals is required to get the most out of it, however we have tried to provide a basic description of these concepts where possible.

Acknowledgements

I am indebted to the fantastic work done by the technical reviewers who helped review and improve this book. Their knowledge, energy, and passion have helped shape it into a better learning resource and they continue to serve as a source of inspiration. Thanks go out to:

I would also like to thank my loving family for their patience and support while I worked on this book, as well as my brilliant editor Mary Treseler.

Credits

None of this work would have been possible without the time and effort invested by the other developers and authors in the community who helped contribute to it. I would like to extend my thanks to:

Target Version

Developing Backbone.js Applications targets Backbone.js 1.1.x (and Underscore 1.6.x) and will actively attempt to stay up to date with more recent versions of these libraries. Where possible, if you find using a newer version of Backbone breaks an example, please consult the official guide to upgrading as it contains instructions for how to work around breaking changes. StackOverflow also contains many excellent examples of how other users are handling updating their code.

Reading

I assume your level of knowledge about JavaScript goes beyond the basics and as such certain topics such as object literals are skipped. If you need to learn more about the language, I am happy to suggest:

Introduction

Frank Lloyd Wright once said “You can’t make an architect. You can however open the doors and windows toward the light as you see it.” In this book, I hope to shed some light on how to improve the structure of your web applications, opening doors to what will hopefully be more maintainable, readable applications in your future.

The goal of all architecture is to build something well; in our case, to craft code that is enduring and delights both ourselves and the developers who will maintain our code long after we are gone. We all want our architecture to be simple, yet beautiful.

While modern web development has evolved significantly with frameworks like React, Vue, and Angular becoming popular choices for new projects, understanding Backbone.js remains valuable as it teaches fundamental concepts about application architecture and state management that are still relevant today.

What Is MVC in Modern Web Development?

The Model-View-Controller (MVC) pattern, while evolved in modern frameworks, remains an important architectural concept. Today’s frameworks often implement variations of this pattern:

Modern frameworks have evolved these concepts: - React uses a component-based architecture with state management - Vue combines template-based views with reactive data models - Angular implements a more traditional MVC-like pattern with additional features

Backbone.js implements its own interpretation of MVC, which we’ll explore in detail.

What is Backbone.js?

Backbone.js (current version 1.5.0) is a lightweight JavaScript library that adds structure to client-side code. While newer frameworks may be more popular for new projects, Backbone.js offers several advantages:

Backbone.js is particularly valuable for: * Understanding fundamental concepts of structured JavaScript applications * Maintaining or upgrading legacy applications * Building lightweight applications where minimal framework overhead is desired * Learning about event-driven architecture and data binding

Modern JavaScript Application Architecture

Backbone.js influenced many of these modern practices, particularly in areas of: - Event-driven architecture - Model-View separation - RESTful API integration - Client-side routing

When to Use Backbone.js Today

While new projects might benefit from modern frameworks, Backbone.js remains relevant in several scenarios:

Setting Expectations

This book will: 1. Teach fundamental concepts of structured JavaScript applications 2. Show how to build applications using Backbone.js 3. Demonstrate modern JavaScript practices within Backbone.js 4. Explain how concepts from Backbone.js influence modern frameworks

Chapter 2, Fundamentals, explores MVC pattern history and modern implementations.

Chapter 3, Backbone Basics, covers core Backbone.js features with modern JavaScript syntax.

Chapter 4, Exercise 1: Todos, builds a Todo application using current best practices.

Chapter 5, Exercise 2: Book Library, creates a RESTful application with modern API integration.

Chapter 6, Backbone Extensions, explores useful extensions and modern alternatives.

Chapter 7, Common Problems and Solutions, addresses current development challenges.

Chapter 9, Exercise 3: Modular Todo App, rebuilds the Todo app using modern tooling.

Chapter 12, Mobile Applications, covers responsive design and mobile considerations.

Chapter 13-15, Testing, covers modern testing practices with Jasmine, QUnit, and SinonJS.

Chapter 18, Appendix, includes additional patterns and architectural considerations.

Fundamentals

Design patterns remain fundamental to modern web development, helping us create maintainable and scalable applications. While the JavaScript ecosystem has evolved significantly, understanding these patterns is crucial as they form the foundation of many modern frameworks and libraries.

MVC and Modern Architecture

The Model-View-Controller (MVC) pattern, originally designed by Trygve Reenskaug in 1979, has evolved significantly in the web development context. Today, we see various interpretations and adaptations of MVC across different frameworks:

Classical MVC vs Modern Implementations

Classical MVC was designed for desktop applications with a clear separation between: * Models (data and business logic) * Views (user interface) * Controllers (user input handling)

Modern web frameworks have adapted these concepts to better suit web applications:

// Classical MVC-style code
const UserModel = {
    data: { name: '', email: '' },
    validate() { /* ... */ }
};

const UserView = {
    render() { /* ... */ },
    update() { /* ... */ }
};

const UserController = {
    handleInput() { /* ... */ },
    updateModel() { /* ... */ }
};

// Modern Backbone.js approach
const User = Backbone.Model.extend({
    defaults: {
        name: '',
        email: ''
    },
    validate(attrs) {
        if (!attrs.email) {
            return "Email is required";
        }
    }
});

const UserView = Backbone.View.extend({
    template: _.template($('#user-template').html()),
    
    events: {
        'input .email': 'updateEmail'
    },
    
    render() {
        this.$el.html(this.template(this.model.toJSON()));
        return this;
    },
    
    updateEmail(e) {
        this.model.set('email', e.target.value);
    }
});

Modern Web Context

// Backbone's event-driven state management
const TodoApp = Backbone.Model.extend({
    defaults: {
        todos: [],
        filter: 'all'
    }
});

const app = new TodoApp();
app.on('change:filter', (model, value) => {
    // Update UI based on filter
});

// Modern async with Backbone
const Tasks = Backbone.Collection.extend({
    url: '/api/tasks',
    
    async fetchActive() {
        try {
            await this.fetch({
                data: { status: 'active' }
            });
        } catch (error) {
            console.error('Failed to fetch tasks:', error);
        }
    }
});

const LiveFeed = Backbone.View.extend({
    initialize() {
        this.websocket = new WebSocket('ws://api.example.com/feed');
        this.websocket.onmessage = this.handleUpdate.bind(this);
    },
    
    handleUpdate(event) {
        const data = JSON.parse(event.data);
        this.model.set(data);
    }
});

Client-Side Architecture

const AppRouter = Backbone.Router.extend({
    routes: {
        '': 'home',
        'users/:id': 'showUser',
        '*notFound': 'handle404'
    },
    
    async showUser(id) {
        try {
            const user = await new User({ id }).fetch();
            new UserView({ model: user }).render();
        } catch (error) {
            this.handle404();
        }
    }
});

const AppState = Backbone.Model.extend({
    localStorage: new Backbone.LocalStorage('app-state'),
    
    defaults: {
        theme: 'light',
        language: 'en',
        lastVisited: null
    }
});

const SyncedModel = Backbone.Model.extend({
    sync: async function(method, model, options) {
        // Custom sync logic
        const result = await Backbone.sync.call(this, method, model, options);
        // Post-sync operations
        return result;
    }
});

Modern Best Practices

// Use classes instead of Backbone.Model.extend
class User extends Backbone.Model {
    get fullName() {
        return `${this.get('firstName')} ${this.get('lastName')}`;
    }
    
    async save() {
        try {
            await super.save();
            this.trigger('savedSuccessfully');
        } catch (error) {
            this.trigger('saveError', error);
        }
    }
}

// Using JSDoc for better IDE support
/**
 * @typedef {Object} UserAttributes
 * @property {string} firstName
 * @property {string} lastName
 * @property {string} email
 */

/**
 * @extends {Backbone.Model<UserAttributes>}
 */
class TypedUser extends Backbone.Model {
    defaults() {
        return {
            firstName: '',
            lastName: '',
            email: ''
        };
    }
}

// webpack.config.js
module.exports = {
    entry: './src/app.js',
    output: {
        filename: 'bundle.js'
    },
    module: {
        rules: [
            {
                test: /\.js$/,
                use: 'babel-loader'
            }
        ]
    }
};

Summary

While modern frameworks may have different approaches to structuring applications, the fundamental principles of MVC remain relevant:

Backbone.js implements these principles in a lightweight, flexible way that can still be valuable in modern web development, especially when:

Understanding these fundamentals helps developers make better architectural decisions, regardless of the framework they choose to use.

Backbone Basics

In this section, you’ll learn the essentials of Backbone’s models, views, collections, events, and routers. This isn’t by any means a replacement for the official documentation, but it will help you understand many of the core concepts behind Backbone before you start building applications using it.

Getting set up

Before we dive into more code examples, let’s define some boilerplate markup you can use to specify the dependencies Backbone requires. This boilerplate can be reused in many ways with little to no alteration and will allow you to run code from examples with ease.

You can paste the following into your text editor of choice, replacing the commented line between the script tags with the JavaScript from any given example:

<!DOCTYPE HTML>
<html>
<head>
    <meta charset="UTF-8">
    <title>Title</title>
</head>
<body>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script src="http://underscorejs.org/underscore-min.js"></script>
<script src="http://backbonejs.org/backbone-min.js"></script>
<script>
  // Your code goes here
</script>
</body>
</html>

You can then save and run the file in your browser of choice, such as Chrome or Firefox. Alternatively, if you prefer working with an online code editor, jsFiddle and jsBin versions of this boilerplate are also available.

Most examples can also be run directly from within the console in your browser’s developer tools, assuming you’ve loaded the boilerplate HTML page so that Backbone and its dependencies are available for use.

For Chrome, you can open up the DevTools via the Chrome menu in the top right hand corner: select “Tools > Developer Tools” or alternatively use the Control + Shift + I shortcut on Windows/Linux or Command + Option + I on Mac.

Next, switch to the Console tab, from where you can enter in and run any piece of JavaScript code by hitting the return key. You can also use the Console as a multi-line editor using the Shift + Enter shortcut on Windows/Linux, or Ctrl + Enter shortcut on Mac to move from the end of one line to the start of another.

Models

Backbone models contain data for an application as well as the logic around this data. For example, we can use a model to represent the concept of a todo item including its attributes like title (todo content) and completed (current state of the todo).

var Todo = Backbone.Model.extend({});

// We can then create our own concrete instance of a (Todo) model
// with no values at all:
var todo1 = new Todo();
// Following logs: {}
console.log(JSON.stringify(todo1));

// or with some arbitrary data:
var todo2 = new Todo({
  title: 'Check the attributes of both model instances in the console.',
  completed: true
});

// Following logs: {"title":"Check the attributes of both model instances in the console.","completed":true}
console.log(JSON.stringify(todo2));

Initialization

The initialize() method is called when a new instance of a model is created. Its use is optional; however you’ll see why it’s good practice to use it below.

var Todo = Backbone.Model.extend({
  initialize: function(){
      console.log('This model has been initialized.');
  }
});

var myTodo = new Todo();
// Logs: This model has been initialized.

There are times when you want your model to have a set of default values (e.g., in a scenario where a complete set of data isn’t provided by the user). This can be set using a property called defaults in your model.

var Todo = Backbone.Model.extend({
  // Default todo attribute values
  defaults: {
    title: '',
    completed: false
  }
});

// Now we can create our concrete instance of the model
// with default values as follows:
var todo1 = new Todo();

// Following logs: {"title":"","completed":false}
console.log(JSON.stringify(todo1));

// Or we could instantiate it with some of the attributes (e.g., with custom title):
var todo2 = new Todo({
  title: 'Check attributes of the logged models in the console.'
});

// Following logs: {"title":"Check attributes of the logged models in the console.","completed":false}
console.log(JSON.stringify(todo2));

// Or override all of the default attributes:
var todo3 = new Todo({
  title: 'This todo is done, so take no action on this one.',
  completed: true
});

// Following logs: {"title":"This todo is done, so take no action on this one.","completed":true} 
console.log(JSON.stringify(todo3));

Getters & Setters

var Todo = Backbone.Model.extend({
  // Default todo attribute values
  defaults: {
    title: '',
    completed: false
  }
});

var todo1 = new Todo();
console.log(todo1.get('title')); // empty string
console.log(todo1.get('completed')); // false

var todo2 = new Todo({
  title: "Retrieved with model's get() method.",
  completed: true
});
console.log(todo2.get('title')); // Retrieved with model's get() method.
console.log(todo2.get('completed')); // true

If you need to read or clone all of a model’s data attributes, use its toJSON() method. This method returns a copy of the attributes as an object (not a JSON string despite its name). (When JSON.stringify() is passed an object with a toJSON() method, it stringifies the return value of toJSON() instead of the original object. The examples in the previous section took advantage of this feature when they called JSON.stringify() to log model instances.)

var Todo = Backbone.Model.extend({
  // Default todo attribute values
  defaults: {
    title: '',
    completed: false
  }
});

var todo1 = new Todo();
var todo1Attributes = todo1.toJSON();
// Following logs: {"title":"","completed":false} 
console.log(todo1Attributes);

var todo2 = new Todo({
  title: "Try these examples and check results in console.",
  completed: true
});

// logs: {"title":"Try these examples and check results in console.","completed":true}
console.log(todo2.toJSON());

Model.set() sets a hash containing one or more attributes on the model. When any of these attributes alter the state of the model, a “change” event is triggered on it. Change events for each attribute are also triggered and can be bound to (e.g. change:name, change:age).

var Todo = Backbone.Model.extend({
  // Default todo attribute values
  defaults: {
    title: '',
    completed: false
  }
});

// Setting the value of attributes via instantiation
var myTodo = new Todo({
  title: "Set through instantiation."
});
console.log('Todo title: ' + myTodo.get('title')); // Todo title: Set through instantiation.
console.log('Completed: ' + myTodo.get('completed')); // Completed: false

// Set single attribute value at a time through Model.set():
myTodo.set("title", "Title attribute set through Model.set().");
console.log('Todo title: ' + myTodo.get('title')); // Todo title: Title attribute set through Model.set().
console.log('Completed: ' + myTodo.get('completed')); // Completed: false

// Set map of attributes through Model.set():
myTodo.set({
  title: "Both attributes set through Model.set().",
  completed: true
});
console.log('Todo title: ' + myTodo.get('title')); // Todo title: Both attributes set through Model.set().
console.log('Completed: ' + myTodo.get('completed')); // Completed: true

Models expose an .attributes attribute which represents an internal hash containing the state of that model. This is generally in the form of a JSON object similar to the model data you might find on the server but can take other forms.

Setting values through the .attributes attribute on a model bypasses triggers bound to the model.

Passing {silent:true} on set doesn’t delay individual "change:attr" events. Instead they are silenced entirely:

var Person = new Backbone.Model();
Person.on("change:name", function() { console.log('Name changed'); });
Person.set({name: 'Andrew'});
// log entry: Name changed

Person.set({name: 'Jeremy'}, {silent: true});
// no log entry

console.log(Person.hasChanged("name"));
// true: change was recorded
console.log(Person.hasChanged(null));
// true: something (anything) has changed

Remember where possible it is best practice to use Model.set(), or direct instantiation as explained earlier.

Listening for changes to your model

If you want to receive a notification when a Backbone model changes you can bind a listener to the model for its change event. A convenient place to add listeners is in the initialize() function as shown below:

var Todo = Backbone.Model.extend({
  // Default todo attribute values
  defaults: {
    title: '',
    completed: false
  },
  initialize: function(){
    console.log('This model has been initialized.');
    this.on('change', function(){
        console.log('- Values for this model have changed.');
    });
  }
});

var myTodo = new Todo();

myTodo.set('title', 'The listener is triggered whenever an attribute value changes.');
console.log('Title has changed: ' + myTodo.get('title'));


myTodo.set('completed', true);
console.log('Completed has changed: ' + myTodo.get('completed'));

myTodo.set({
  title: 'Changing more than one attribute at the same time only triggers the listener once.',
  completed: true
});

// Above logs:
// This model has been initialized.
// - Values for this model have changed.
// Title has changed: The listener is triggered whenever an attribute value changes.
// - Values for this model have changed.
// Completed has changed: true
// - Values for this model have changed.

You can also listen for changes to individual attributes in a Backbone model. In the following example, we log a message whenever a specific attribute (the title of our Todo model) is altered.

var Todo = Backbone.Model.extend({
  // Default todo attribute values
  defaults: {
    title: '',
    completed: false
  },

  initialize: function(){
    console.log('This model has been initialized.');
    this.on('change:title', function(){
        console.log('Title value for this model has changed.');
    });
  },

  setTitle: function(newTitle){
    this.set({ title: newTitle });
  }
});

var myTodo = new Todo();

// Both of the following changes trigger the listener:
myTodo.set('title', 'Check what\'s logged.');
myTodo.setTitle('Go fishing on Sunday.');

// But, this change type is not observed, so no listener is triggered:
myTodo.set('completed', true);
console.log('Todo set as completed: ' + myTodo.get('completed'));

// Above logs:
// This model has been initialized.
// Title value for this model has changed.
// Title value for this model has changed.
// Todo set as completed: true

Validation

Backbone supports model validation through model.validate(), which allows checking the attribute values for a model prior to setting them. By default, validation occurs when the model is persisted using the save() method or when set() is called if {validate:true} is passed as an argument.

var Person = new Backbone.Model({name: 'Jeremy'});

// Validate the model name
Person.validate = function(attrs) {
  if (!attrs.name) {
    return 'I need your name';
  }
};

// Change the name
Person.set({name: 'Samuel'});
console.log(Person.get('name'));
// 'Samuel'

// Remove the name attribute, force validation
Person.unset('name', {validate: true});
// false

Above, we also use the unset() method, which removes an attribute by deleting it from the internal model attributes hash.

Validation functions can be as simple or complex as necessary. If the attributes provided are valid, nothing should be returned from .validate(). If they are invalid, an error value should be returned instead.

var Todo = Backbone.Model.extend({
  defaults: {
    completed: false
  },

  validate: function(attributes){
    if(attributes.title === undefined){
        return "Remember to set a title for your todo.";
    }
  },

  initialize: function(){
    console.log('This model has been initialized.');
    this.on("invalid", function(model, error){
        console.log(error);
    });
  }
});

var myTodo = new Todo();
myTodo.set('completed', true, {validate: true}); // logs: Remember to set a title for your todo.
console.log('completed: ' + myTodo.get('completed')); // completed: false

Note: the attributes object passed to the validate function represents what the attributes would be after completing the current set() or save(). This object is distinct from the current attributes of the model and from the parameters passed to the operation. Since it is created by shallow copy, it is not possible to change any Number, String, or Boolean attribute of the input within the function, but it is possible to change attributes in nested objects.

Note also, that validation on initialization is possible but of limited use, as the object being constructed is internally marked invalid but nevertheless passed back to the caller (continuing the above example):

var emptyTodo = new Todo(null, {validate: true});
console.log(emptyTodo.validationError);

Views

Views in Backbone don’t contain the HTML markup for your application; they contain the logic behind the presentation of the model’s data to the user. This is usually achieved using JavaScript templating (e.g., Underscore Microtemplates, Mustache, jQuery-tmpl, etc.). A view’s render() method can be bound to a model’s change() event, enabling the view to instantly reflect model changes without requiring a full page refresh.

Creating new views

Creating a new view is relatively straightforward and similar to creating new models. To create a new View, simply extend Backbone.View. We introduced the sample TodoView below in the previous chapter; now let’s take a closer look at how it works:

var TodoView = Backbone.View.extend({

  tagName:  'li',

  // Cache the template function for a single item.
  todoTpl: _.template( "An example template" ),

  events: {
    'dblclick label': 'edit',
    'keypress .edit': 'updateOnEnter',
    'blur .edit':   'close'
  },

  initialize: function (options) {
    // In Backbone 1.1.0, if you want to access passed options in
    // your view, you will need to save them as follows:
    this.options = options || {};
  },

  // Re-render the title of the todo item.
  render: function() {
    this.$el.html( this.todoTpl( this.model.attributes ) );
    this.input = this.$('.edit');
    return this;
  },

  edit: function() {
    // executed when todo label is double clicked
  },

  close: function() {
    // executed when todo loses focus
  },

  updateOnEnter: function( e ) {
    // executed on each keypress when in todo edit mode,
    // but we'll wait for enter to get in action
  }
});

var todoView = new TodoView();

// log reference to a DOM element that corresponds to the view instance
console.log(todoView.el); // logs <li></li>

What is el?

The central property of a view is el (the value logged in the last statement of the example). What is el and how is it defined?

el is basically a reference to a DOM element and all views must have one. Views can use el to compose their element’s content and then insert it into the DOM all at once, which makes for faster rendering because the browser performs the minimum required number of reflows and repaints.

There are two ways to associate a DOM element with a view: a new element can be created for the view and subsequently added to the DOM or a reference can be made to an element which already exists in the page.

If you want to create a new element for your view, set any combination of the following properties on the view: tagName, id, and className. A new element will be created for you by the library and a reference to it will be available at the el property. If nothing is specified tagName defaults to div.

In the example above, tagName is set to ‘li’, resulting in creation of an li element. The following example creates a ul element with id and class attributes:

var TodosView = Backbone.View.extend({
  tagName: 'ul', // required, but defaults to 'div' if not set
  className: 'container', // optional, you can assign multiple classes to 
                          // this property like so: 'container homepage'
  id: 'todos' // optional
});

var todosView = new TodosView();
console.log(todosView.el); // logs <ul id="todos" class="container"></ul>

The above code creates the DOM element below but doesn’t append it to the DOM.

<ul id="todos" class="container"></ul>

If the element already exists in the page, you can set el as a CSS selector that matches the element.

var todosView = new TodosView({el: $('#footer')});

Note: When declaring a View, options, el, tagName, id and className may be defined as functions, if you want their values to be determined at runtime.

View logic often needs to invoke jQuery or Zepto functions on the el element and elements nested within it. Backbone makes it easy to do so by defining the $el property and $() function. The view.$el property is equivalent to $(view.el) and view.$(selector) is equivalent to $(view.el).find(selector). In our TodoView example’s render method, we see this.$el used to set the HTML of the element and this.$() used to find subelements of class ‘edit’.

If you need to apply an existing Backbone view to a different DOM element setElement can be used for this purpose. Overriding this.el needs to both change the DOM reference and re-bind events to the new element (and unbind from the old).

setElement will create a cached $el reference for you, moving the delegated events for a view from the old element to the new one.


// We create two DOM elements representing buttons
// which could easily be containers or something else
var button1 = $('<button></button>');
var button2 = $('<button></button>');

// Define a new view
var View = Backbone.View.extend({
      events: {
        click: function(e) {
          console.log(view.el === e.target);
        }
      }
    });

// Create a new instance of the view, applying it
// to button1
var view = new View({el: button1});

// Apply the view to button2 using setElement
view.setElement(button2);

button1.trigger('click'); 
button2.trigger('click'); // returns true

The “el” property represents the markup portion of the view that will be rendered; to get the view to actually render to the page, you need to add it as a new element or append it to an existing element.


// We can also provide raw markup to setElement
// as follows (just to demonstrate it can be done):
var view = new Backbone.View;
view.setElement('<p><a><b>test</b></a></p>');
console.log(view.$('a b').html()); // outputs "test"

render() is an optional function that defines the logic for rendering a template. We’ll use Underscore’s micro-templating in these examples, but remember you can use other templating frameworks if you prefer. Our example will reference the following HTML markup:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title></title>
  <meta name="description" content="">
</head>
<body>
  <div id="todo">
  </div>
  <script type="text/template" id="item-template">
    <div>
      <input id="todo_complete" type="checkbox" <%= completed ? 'checked="checked"' : '' %>>
      <%= title %>
    </div>
  </script>
  <script src="jquery-min.js"></script>
  <script src="underscore-min.js"></script>
  <script src="backbone-min.js"></script>
  <script src="example.js"></script>
</body>
</html>

The _.template method in Underscore compiles JavaScript templates into functions which can be evaluated for rendering. In the TodoView, I’m passing the markup from the template with id item-template to _.template() to be compiled and stored in the todoTpl property when the view is created.

The render() method uses this template by passing it the toJSON() encoding of the attributes of the model associated with the view. The template returns its markup after using the model’s title and completed flag to evaluate the expressions containing them. I then set this markup as the HTML content of the el DOM element using the $el property.

Presto! This populates the template, giving you a data-complete set of markup in just a few short lines of code.

A common Backbone convention is to return this at the end of render(). This is useful for a number of reasons, including:

Let’s try to implement the latter of these. The render method of a simple ListView which doesn’t use an ItemView for each item could be written:


var ListView = Backbone.View.extend({

  // Compile a template for this view. In this case '...'
  // is a placeholder for a template such as 
  // $("#list_template").html() 
  template: _.template(…),
  
  render: function() {
    this.$el.html(this.template(this.model.attributes));
    return this;
  }
});

Simple enough. Let’s now assume a decision is made to construct the items using an ItemView to provide enhanced behaviour to our list. The ItemView could be written:


var ItemView = Backbone.View.extend({
  events: {},
  render: function(){
    this.$el.html(this.template(this.model.attributes));
    return this;
  }
});

Note the usage of return this; at the end of render. This common pattern enables us to reuse the view as a sub-view. We can also use it to pre-render the view prior to rendering. Using this requires that we make a change to our ListView’s render method as follows:


var ListView = Backbone.View.extend({
  render: function(){

    // Assume our model exposes the items we will
    // display in our list
    var items = this.model.get('items');

    // Loop through each of our items using the Underscore
    // _.each iterator
    _.each(items, function(item){

      // Create a new instance of the ItemView, passing 
      // it a specific model item
      var itemView = new ItemView({ model: item });
      // The itemView's DOM element is appended after it
      // has been rendered. Here, the 'return this' is helpful
      // as the itemView renders its model. Later, we ask for 
      // its output ("el")
      this.$el.append( itemView.render().el );
    }, this);
  }
});

The Backbone events hash allows us to attach event listeners to either el-relative custom selectors, or directly to el if no selector is provided. An event takes the form of a key-value pair 'eventName selector': 'callbackFunction' and a number of DOM event-types are supported, including click, submit, mouseover, dblclick and more.


// A sample view
var TodoView = Backbone.View.extend({
  tagName:  'li',

  // with an events hash containing DOM events
  // specific to an item:
  events: {
    'click .toggle': 'toggleCompleted',
    'dblclick label': 'edit',
    'keypress .edit': 'updateOnEnter',
    'click .destroy': 'clear',
    'blur .edit': 'close'
  },

What isn’t instantly obvious is that while Backbone uses jQuery’s .delegate() underneath, it goes further by extending it so that this always refers to the current view object within callback functions. The only thing to really keep in mind is that any string callback supplied to the events attribute must have a corresponding function with the same name within the scope of your view.

The declarative, delegated jQuery events means that you don’t have to worry about whether a particular element has been rendered to the DOM yet or not. Usually with jQuery you have to worry about “presence or absence in the DOM” all the time when binding events.

In our TodoView example, the edit callback is invoked when the user double-clicks a label element within the el element, updateOnEnter is called for each keypress in an element with class ‘edit’, and close executes when an element with class ‘edit’ loses focus. Each of these callback functions can use this to refer to the TodoView object.

Note that you can also bind methods yourself using _.bind(this.viewEvent, this), which is effectively what the value in each event’s key-value pair is doing. Below we use _.bind to re-render our view when a model changes.


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

_.bind only works on one method at a time, but effectively binds a function to an object so that anytime the function is called the value of this will be the object. _.bind also supports passing in arguments to the function in order to fill them in advance - a technique known as partial application.

Collections

Collections are sets of Models and are created by extending Backbone.Collection.

Normally, when creating a collection you’ll also want to define a property specifying the type of model that your collection will contain, along with any instance properties required.

In the following example, we create a TodoCollection that will contain our Todo models:

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

var TodosCollection = Backbone.Collection.extend({
  model: Todo
});

var myTodo = new Todo({title:'Read the whole book', id: 2});

// pass array of models on collection instantiation
var todos = new TodosCollection([myTodo]);
console.log("Collection size: " + todos.length); // Collection size: 1

Adding and Removing Models

The preceding example populated the collection using an array of models when it was instantiated. After a collection has been created, models can be added and removed using the add() and remove() methods:

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

var TodosCollection = Backbone.Collection.extend({
  model: Todo
});

var a = new Todo({ title: 'Go to Jamaica.'}),
    b = new Todo({ title: 'Go to China.'}),
    c = new Todo({ title: 'Go to Disneyland.'});

var todos = new TodosCollection([a,b]);
console.log("Collection size: " + todos.length);
// Logs: Collection size: 2

todos.add(c);
console.log("Collection size: " + todos.length);
// Logs: Collection size: 3

todos.remove([a,b]);
console.log("Collection size: " + todos.length);
// Logs: Collection size: 1

todos.remove(c);
console.log("Collection size: " + todos.length);
// Logs: Collection size: 0

Note that add() and remove() accept both individual models and lists of models.

Also note that when using add() on a collection, passing {merge: true} causes duplicate models to have their attributes merged in to the existing models, instead of being ignored.

var items = new Backbone.Collection;
items.add([{ id : 1, name: "Dog" , age: 3}, { id : 2, name: "cat" , age: 2}]);
items.add([{ id : 1, name: "Bear" }], {merge: true });
items.add([{ id : 2, name: "lion" }]); // merge: false
 
console.log(JSON.stringify(items.toJSON()));
// [{"id":1,"name":"Bear","age":3},{"id":2,"name":"cat","age":2}]

Retrieving Models

There are a few different ways to retrieve a model from a collection. The most straight-forward is to use Collection.get() which accepts a single id as follows:

var myTodo = new Todo({title:'Read the whole book', id: 2});

// pass array of models on collection instantiation
var todos = new TodosCollection([myTodo]);

var todo2 = todos.get(2);

// Models, as objects, are passed by reference
console.log(todo2 === myTodo); // true

In client-server applications, collections contain models obtained from the server. Anytime you’re exchanging data between the client and a server, you will need a way to uniquely identify models. In Backbone, this is done using the id, cid, and idAttribute properties.

Each model in Backbone has an id, which is a unique identifier that is either an integer or string (e.g., a UUID). Models also have a cid (client id) which is automatically generated by Backbone when the model is created. Either identifier can be used to retrieve a model from a collection.

The main difference between them is that the cid is generated by Backbone; it is helpful when you don’t have a true id - this may be the case if your model has yet to be saved to the server or you aren’t saving it to a database.

The idAttribute is the identifying attribute name of the model returned from the server (i.e. the id in your database). This tells Backbone which data field from the server should be used to populate the id property (think of it as a mapper). By default, it assumes id, but this can be customized as needed. For instance, if your server sets a unique attribute on your model named “userId” then you would set idAttribute to “userId” in your model definition.

The value of a model’s idAttribute should be set by the server when the model is saved. After this point you shouldn’t need to set it manually, unless further control is required.

Internally, Backbone.Collection contains an array of models enumerated by their id property, if the model instances happen to have one. When collection.get(id) is called, this array is checked for existence of the model instance with the corresponding id.

// extends the previous example

var todoCid = todos.get(todo2.cid);

// As mentioned in previous example, 
// models are passed by reference
console.log(todoCid === myTodo); // true

Listening for events

As collections represent a group of items, we can listen for add and remove events which occur when models are added to or removed from a collection. Here’s an example:

var TodosCollection = new Backbone.Collection();

TodosCollection.on("add", function(todo) {
  console.log("I should " + todo.get("title") + ". Have I done it before? "  + (todo.get("completed") ? 'Yeah!': 'No.' ));
});

TodosCollection.add([
  { title: 'go to Jamaica', completed: false },
  { title: 'go to China', completed: false },
  { title: 'go to Disneyland', completed: true }
]);

// The above logs:
// I should go to Jamaica. Have I done it before? No.
// I should go to China. Have I done it before? No.
// I should go to Disneyland. Have I done it before? Yeah!

In addition, we’re also able to bind to a change event to listen for changes to any of the models in the collection.

var TodosCollection = new Backbone.Collection();

// log a message if a model in the collection changes
TodosCollection.on("change:title", function(model) {
    console.log("Changed my mind! I should " + model.get('title'));
});

TodosCollection.add([
  { title: 'go to Jamaica.', completed: false, id: 3 },
]);

var myTodo = TodosCollection.get(3);

myTodo.set('title', 'go fishing');
// Logs: Changed my mind! I should go fishing

jQuery-style event maps of the form obj.on({click: action}) can also be used. These can be clearer than needing three separate calls to .on and should align better with the events hash used in Views:


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

var myTodo = new Todo();
myTodo.set({title: 'Buy some cookies', completed: true});

myTodo.on({
   'change:title' : titleChanged,
   'change:completed' : stateChanged
});

function titleChanged(){
  console.log('The title was changed!');
}

function stateChanged(){
  console.log('The state was changed!');
}

myTodo.set({title: 'Get the groceries'});
// The title was changed!

Backbone events also support a once() method, which ensures that a callback only fires one time when a notification arrives. It is similar to Node’s once, or jQuery’s one. This is particularly useful for when you want to say “the next time something happens, do this”.

// Define an object with two counters
var TodoCounter = { counterA: 0, counterB: 0 };
// Mix in Backbone Events
_.extend(TodoCounter, Backbone.Events);

// Increment counterA, triggering an event
var incrA = function(){ 
  TodoCounter.counterA += 1; 
  // This triggering will not 
  // produce any effect on the counters
  TodoCounter.trigger('event'); 
};

// Increment counterB
var incrB = function(){ 
  TodoCounter.counterB += 1; 
};

// Use once rather than having to explicitly unbind
// our event listener
TodoCounter.once('event', incrA);
TodoCounter.once('event', incrB);

// Trigger the event for the first time
TodoCounter.trigger('event');

// Check out output
console.log(TodoCounter.counterA === 1); // true
console.log(TodoCounter.counterB === 1); // true

Resetting/Refreshing Collections

Rather than adding or removing models individually, you might want to update an entire collection at once. Collection.set() takes an array of models and performs the necessary add, remove, and change operations required to update the collection.

var TodosCollection = new Backbone.Collection();

TodosCollection.add([
    { id: 1, title: 'go to Jamaica.', completed: false },
    { id: 2, title: 'go to China.', completed: false },
    { id: 3, title: 'go to Disneyland.', completed: true }
]);

// we can listen for add/change/remove events
TodosCollection.on("add", function(model) {
  console.log("Added " + model.get('title'));
});

TodosCollection.on("remove", function(model) {
  console.log("Removed " + model.get('title'));
});

TodosCollection.on("change:completed", function(model) {
  console.log("Completed " + model.get('title'));
});

TodosCollection.set([
    { id: 1, title: 'go to Jamaica.', completed: true },
    { id: 2, title: 'go to China.', completed: false },
    { id: 4, title: 'go to Disney World.', completed: false }
]);

// Above logs:
// Completed go to Jamaica.
// Removed go to Disneyland.
// Added go to Disney World.

If you need to simply replace the entire content of the collection then Collection.reset() can be used:

var TodosCollection = new Backbone.Collection();

// we can listen for reset events
TodosCollection.on("reset", function() {
  console.log("Collection reset.");
});

TodosCollection.add([
  { title: 'go to Jamaica.', completed: false },
  { title: 'go to China.', completed: false },
  { title: 'go to Disneyland.', completed: true }
]);

console.log('Collection size: ' + TodosCollection.length); // Collection size: 3

TodosCollection.reset([
  { title: 'go to Cuba.', completed: false }
]);
// Above logs 'Collection reset.'

console.log('Collection size: ' + TodosCollection.length); // Collection size: 1

Another useful tip is to use reset with no arguments to clear out a collection completely. This is handy when dynamically loading a new page of results where you want to blank out the current page of results.

myCollection.reset();

Note that using Collection.reset() doesn’t fire any add or remove events. A reset event is fired instead as shown in the previous example. The reason you might want to use this is to perform super-optimized rendering in extreme cases where individual events are too expensive.

Also note that listening to a reset event, the list of previous models is available in options.previousModels, for convenience.

var todo = new Backbone.Model();
var todos = new Backbone.Collection([todo])
.on('reset', function(todos, options) {
  console.log(options.previousModels);
  console.log([todo]);
  console.log(options.previousModels[0] === todo); // true
});
todos.reset([]);

The set() method available for Collections can also be used for “smart” updating of sets of models. This method attempts to perform smart updating of a collection using a specified list of models. When a model in this list isn’t present in the collection, it is added. If it’s present, its attributes will be merged. Models which are present in the collection but not in the list are removed.


// Define a model of type 'Beatle' with a 'job' attribute
var Beatle = Backbone.Model.extend({
  defaults: {
    job: 'musician'
  }
});

// Create models for each member of the Beatles
var john = new Beatle({ firstName: 'John', lastName: 'Lennon'});
var paul = new Beatle({ firstName: 'Paul', lastName: 'McCartney'});
var george = new Beatle({ firstName: 'George', lastName: 'Harrison'});
var ringo = new Beatle({ firstName: 'Ringo', lastName: 'Starr'});

// Create a collection using our models
var theBeatles = new Backbone.Collection([john, paul, george, ringo]);

// Create a separate model for Pete Best
var pete = new Beatle({ firstName: 'Pete', lastName: 'Best'});

// Update the collection
theBeatles.set([john, paul, george, pete]);

// Fires a `remove` event for 'Ringo', and an `add` event for 'Pete'.
// Updates any of John, Paul and Georges's attributes that may have
// changed over the years.

Underscore utility functions

Backbone takes full advantage of its hard dependency on Underscore by making many of its utilities directly available on collections:

var todos = new Backbone.Collection();

todos.add([
  { title: 'go to Belgium.', completed: false },
  { title: 'go to China.', completed: false },
  { title: 'go to Austria.', completed: true }
]);

// iterate over models in the collection
todos.forEach(function(model){
  console.log(model.get('title'));
});
// Above logs:
// go to Belgium.
// go to China.
// go to Austria.

// sort collection
var sortedByAlphabet = todos.sortBy(function (todo) {
    return todo.get("title").toLowerCase();
});

console.log("- Now sorted: ");

sortedByAlphabet.forEach(function(model){
  console.log(model.get('title'));
});
// Above logs:
// - Now sorted:
// go to Austria.
// go to Belgium.
// go to China.

map(): iterate through a collection, mapping each value through a transformation function

var count = 1;
console.log(todos.map(function(model){
  return count++ + ". " + model.get('title');
}));
// Above logs:
//1. go to Belgium.
//2. go to China.
//3. go to Austria.

todos.max(function(model){
  return model.id;
}).id;

todos.min(function(model){
  return model.id;
}).id;

var captions = todos.pluck('caption');
// returns list of captions

var Todos = Backbone.Collection.extend({
  model: Todo,
  filterById: function(ids){
    return this.filter(
      function(c) { 
        return _.contains(ids, c.id); 
      })
  }
});

var people = new Backbone.Collection;

people.comparator = function(a, b) {
  return a.get('name') < b.get('name') ? -1 : 1;
};

var tom = new Backbone.Model({name: 'Tom'});
var rob = new Backbone.Model({name: 'Rob'});
var tim = new Backbone.Model({name: 'Tim'});

people.add(tom);
people.add(rob);
people.add(tim);

console.log(people.indexOf(rob) === 0); // true
console.log(people.indexOf(tim) === 1); // true
console.log(people.indexOf(tom) === 2); // true

any(): confirm if any of the values in a collection pass an iterator truth test

todos.any(function(model){
  return model.id === 100;
});

// or
todos.some(function(model){
  return model.id === 100;
});

todos.size();

// equivalent to
todos.length;

var isEmpty = todos.isEmpty();

var todos = new Backbone.Collection();

todos.add([
  { title: 'go to Belgium.', completed: false },
  { title: 'go to China.', completed: false },
  { title: 'go to Austria.', completed: true }
]);

// create groups of completed and incomplete models
var byCompleted = todos.groupBy('completed');
var completed = new Backbone.Collection(byCompleted[true]);
console.log(completed.pluck('title'));
// logs: ["go to Austria."]

In addition, several of the Underscore operations on objects are available as methods on Models.

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

var todo = new Todo({title: 'go to Austria.'});
console.log(todo.pick('title'));
// logs {title: "go to Austria"}

var todo = new Todo({title: 'go to Austria.'});
console.log(todo.omit('title'));
// logs {completed: false}

var todo = new Todo({title: 'go to Austria.'});
console.log(todo.keys());
// logs: ["title", "completed"]

console.log(todo.values());
//logs: ["go to Austria.", false]

var todo = new Todo({title: 'go to Austria.'});
var pairs = todo.pairs();

console.log(pairs[0]);
// logs: ["title", "go to Austria."]
console.log(pairs[1]);
// logs: ["completed", false]

invert(): create object in which the values are keys and the attributes are values

var todo = new Todo({title: 'go to Austria.'});
console.log(todo.invert());

// logs: {'go to Austria.': 'title', 'false': 'completed'}

The complete list of what Underscore can do can be found in its official documentation.

Chainable API

Speaking of utility methods, another bit of sugar in Backbone is its support for Underscore’s chain() method. Chaining is a common idiom in object-oriented languages; a chain is a sequence of method calls on the same object that are performed in a single statement. While Backbone makes Underscore’s array manipulation operations available as methods of Collection objects, they cannot be directly chained since they return arrays rather than the original Collection.

Fortunately, the inclusion of Underscore’s chain() method enables you to chain calls to these methods on Collections.

The chain() method returns an object that has all of the Underscore array operations attached as methods which return that object. The chain ends with a call to the value() method which simply returns the resulting array value. In case you haven’t seen it before, the chainable API looks like this:

var collection = new Backbone.Collection([
  { name: 'Tim', age: 5 },
  { name: 'Ida', age: 26 },
  { name: 'Rob', age: 55 }
]);

var filteredNames = collection.chain() // start chain, returns wrapper around collection's models
  .filter(function(item) { return item.get('age') > 10; }) // returns wrapped array excluding Tim
  .map(function(item) { return item.get('name'); }) // returns wrapped array containing remaining names
  .value(); // terminates the chain and returns the resulting array

console.log(filteredNames); // logs: ['Ida', 'Rob']

Some of the Backbone-specific methods do return this, which means they can be chained as well:

var collection = new Backbone.Collection();

collection
    .add({ name: 'John', age: 23 })
    .add({ name: 'Harry', age: 33 })
    .add({ name: 'Steve', age: 41 });

var names = collection.pluck('name');

console.log(names); // logs: ['John', 'Harry', 'Steve']

RESTful Persistence

Thus far, all of our example data has been created in the browser. For most single page applications, the models are derived from a data store residing on a server. This is an area in which Backbone dramatically simplifies the code you need to write to perform RESTful synchronization with a server through a simple API on its models and collections.

Collections.fetch() retrieves a set of models from the server in the form of a JSON array by sending an HTTP GET request to the URL specified by the collection’s url property (which may be a function). When this data is received, a set() will be executed to update the collection.

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

var TodosCollection = Backbone.Collection.extend({
  model: Todo,
  url: '/todos'
});

var todos = new TodosCollection();
todos.fetch(); // sends HTTP GET to /todos

While Backbone can retrieve an entire collection of models from the server at once, updates to models are performed individually using the model’s save() method. When save() is called on a model that was fetched from the server, it constructs a URL by appending the model’s id to the collection’s URL and sends an HTTP PUT to the server. If the model is a new instance that was created in the browser (i.e. it doesn’t have an id) then an HTTP POST is sent to the collection’s URL. Collections.create() can be used to create a new model, add it to the collection, and send it to the server in a single method call.

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

var TodosCollection = Backbone.Collection.extend({
  model: Todo,
  url: '/todos'
});

var todos = new TodosCollection();
todos.fetch();

var todo2 = todos.get(2);
todo2.set('title', 'go fishing');
todo2.save(); // sends HTTP PUT to /todos/2

todos.create({title: 'Try out code samples'}); // sends HTTP POST to /todos and adds to collection

As mentioned earlier, a model’s validate() method is called automatically by save() and will trigger an invalid event on the model if validation fails.

A model can be removed from the containing collection and the server by calling its destroy() method. Unlike Collection.remove() which only removes a model from a collection, Model.destroy() will also send an HTTP DELETE to the collection’s URL.

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

var TodosCollection = Backbone.Collection.extend({
  model: Todo,
  url: '/todos'
});

var todos = new TodosCollection();
todos.fetch();

var todo2 = todos.get(2);
todo2.destroy(); // sends HTTP DELETE to /todos/2 and removes from collection

var todo = new Backbone.Model();
console.log(todo.destroy());
// false

Each RESTful API method accepts a variety of options. Most importantly, all methods accept success and error callbacks which can be used to customize the handling of server responses.

Specifying the {patch: true} option to Model.save() will cause it to use HTTP PATCH to send only the changed attributes (i.e. partial updates) to the server instead of the entire model; i.e. model.save(attrs, {patch: true}):

// Save partial using PATCH
model.clear().set({id: 1, a: 1, b: 2, c: 3, d: 4});
model.save();
model.save({b: 2, d: 4}, {patch: true});
console.log(this.syncArgs.method);
// 'patch'

Similarly, passing the {reset: true} option to Collection.fetch() will result in the collection being updated using reset() rather than set().

See the Backbone.js documentation for full descriptions of the supported options.

Events

Events are a basic inversion of control. Instead of having one function call another by name, the second function is registered as a handler to be called when a specific event occurs.

The part of your application that has to know how to call the other part of your app has been inverted. This is the core thing that makes it possible for your business logic to not have to know about how your user interface works and is the most powerful thing about the Backbone Events system.

Mastering events is one of the quickest ways to become more productive with Backbone, so let’s take a closer look at Backbone’s event model.

Note that Backbone.Events is mixed into the Backbone object. Since Backbone is globally visible, it can be used as a simple event bus:

Backbone.on('event', function() {console.log('Handled Backbone event');});
Backbone.trigger('event'); // logs: Handled Backbone event

on(), off(), and trigger()

Backbone.Events can give any object the ability to bind and trigger custom events. We can mix this module into any object easily and there isn’t a requirement for events to be declared before being bound to a callback handler.

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

// Add a custom event
ourObject.on('dance', function(msg){
  console.log('We triggered ' + msg);
});

// Trigger the custom event
ourObject.trigger('dance', 'our event');

If you’re familiar with jQuery custom events or the concept of Publish/Subscribe, Backbone.Events provides a system that is very similar with on being analogous to subscribe and trigger being similar to publish.

on binds a callback function to an object, as we’ve done with dance in the above example. The callback is invoked whenever the event is triggered.

The official Backbone.js documentation recommends namespacing event names using colons if you end up using quite a few of these on your page. e.g.:

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

function dancing (msg) { console.log("We started " + msg); }

// Add namespaced custom events
ourObject.on("dance:tap", dancing);
ourObject.on("dance:break", dancing);

// Trigger the custom events
ourObject.trigger("dance:tap", "tap dancing. Yeah!");
ourObject.trigger("dance:break", "break dancing. Yeah!");

// This one triggers nothing as no listener listens for it
ourObject.trigger("dance", "break dancing. Yeah!");

A special all event is made available in case you would like notifications for every event that occurs on the object (e.g., if you would like to screen events in a single location). The all event can be used as follows:

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

function dancing (msg) { console.log("We started " + msg); }

ourObject.on("all", function(eventName){
  console.log("The name of the event passed was " + eventName);
});

// This time each event will be caught with a catch 'all' event listener
ourObject.trigger("dance:tap", "tap dancing. Yeah!");
ourObject.trigger("dance:break", "break dancing. Yeah!");
ourObject.trigger("dance", "break dancing. Yeah!");

off removes callback functions that were previously bound to an object. Going back to our Publish/Subscribe comparison, think of it as an unsubscribe for custom events.

To remove the dance event we previously bound to ourObject, we would simply do:

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

function dancing (msg) { console.log("We " + msg); }

// Add namespaced custom events
ourObject.on("dance:tap", dancing);
ourObject.on("dance:break", dancing);

// Trigger the custom events. Each will be caught and acted upon.
ourObject.trigger("dance:tap", "started tap dancing. Yeah!");
ourObject.trigger("dance:break", "started break dancing. Yeah!");

// Removes event bound to the object
ourObject.off("dance:tap");

// Trigger the custom events again, but one is logged.
ourObject.trigger("dance:tap", "stopped tap dancing."); // won't be logged as it's not listened for
ourObject.trigger("dance:break", "break dancing. Yeah!");

To remove all callbacks for the event we pass an event name (e.g., move) to the off() method on the object the event is bound to. If we wish to remove a specific callback, we can pass that callback as the second parameter:

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

function dancing (msg) { console.log("We are dancing. " + msg); }
function jumping (msg) { console.log("We are jumping. " + msg); }

// Add two listeners to the same event
ourObject.on("move", dancing);
ourObject.on("move", jumping);

// Trigger the events. Both listeners are called.
ourObject.trigger("move", "Yeah!");

// Removes specified listener
ourObject.off("move", dancing);

// Trigger the events again. One listener left.
ourObject.trigger("move", "Yeah, jump, jump!");

Finally, as we have seen in our previous examples, trigger triggers a callback for a specified event (or a space-separated list of events). e.g.:

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

function doAction (msg) { console.log("We are " + msg); }

// Add event listeners
ourObject.on("dance", doAction);
ourObject.on("jump", doAction);
ourObject.on("skip", doAction);

// Single event
ourObject.trigger("dance", 'just dancing.');

// Multiple events
ourObject.trigger("dance jump skip", 'very tired from so much action.');

var ourObject = {};

// Mixin
_.extend(ourObject, Backbone.Events);

function doAction (action, duration) {
  console.log("We are " + action + ' for ' + duration ); 
}

// Add event listeners
ourObject.on("dance", doAction);
ourObject.on("jump", doAction);
ourObject.on("skip", doAction);

// Passing multiple arguments to single event
ourObject.trigger("dance", 'dancing', "5 minutes");

// Passing multiple arguments to multiple events
ourObject.trigger("dance jump skip", 'on fire', "15 minutes");

listenTo() and stopListening()

While on() and off() add callbacks directly to an observed object, listenTo() tells an object to listen for events on another object, allowing the listener to keep track of the events for which it is listening. stopListening() can subsequently be called on the listener to tell it to stop listening for events:

var a = _.extend({}, Backbone.Events);
var b = _.extend({}, Backbone.Events);
var c = _.extend({}, Backbone.Events);

// add listeners to A for events on B and C
a.listenTo(b, 'anything', function(event){ console.log("anything happened"); });
a.listenTo(c, 'everything', function(event){ console.log("everything happened"); });

// trigger an event
b.trigger('anything'); // logs: anything happened

// stop listening
a.stopListening();

// A does not receive these events
b.trigger('anything');
c.trigger('everything');

stopListening() can also be used to selectively stop listening based on the event, model, or callback handler.

If you use on and off and remove views and their corresponding models at the same time, there are generally no problems. But a problem arises when you remove a view that had registered to be notified about events on a model, but you don’t remove the model or call off to remove the view’s event handler. Since the model has a reference to the view’s callback function, the JavaScript garbage collector cannot remove the view from memory. This is called a “ghost view” and is a form of memory leak which is common since the models generally tend to outlive the corresponding views during an application’s lifecycle. For details on the topic and a solution, check this excellent article by Derick Bailey.

Practically, every on called on an object also requires an off to be called in order for the garbage collector to do its job. listenTo() changes that, allowing Views to bind to Model notifications and unbind from all of them with just one call - stopListening().

The default implementation of View.remove() makes a call to stopListening(), ensuring that any listeners bound using listenTo() are unbound before the view is destroyed.

var view = new Backbone.View();
var b = _.extend({}, Backbone.Events);

view.listenTo(b, 'all', function(){ console.log(true); });
b.trigger('anything');  // logs: true

view.listenTo(b, 'all', function(){ console.log(false); });
view.remove(); // stopListening() implicitly called
b.trigger('anything');  // does not log anything

Events and Views

Within a View, there are two types of events you can listen for: DOM events and events triggered using the Event API. It is important to understand the differences in how views bind to these events and the context in which their callbacks are invoked.

DOM events can be bound to using the View’s events property or using jQuery.on(). Within callbacks bound using the events property, this refers to the View object; whereas any callbacks bound directly using jQuery will have this set to the handling DOM element by jQuery. All DOM event callbacks are passed an event object by jQuery. See delegateEvents() in the Backbone documentation for additional details.

Event API events are bound as described in this section. If the event is bound using on() on the observed object, a context parameter can be passed as the third argument. If the event is bound using listenTo() then within the callback this refers to the listener. The arguments passed to Event API callbacks depends on the type of event. See the Catalog of Events in the Backbone documentation for details.

<div id="todo">
    <input type='checkbox' />
</div>

var View = Backbone.View.extend({

    el: '#todo',

    // bind to DOM event using events property
    events: {
        'click [type="checkbox"]': 'clicked',
    },

    initialize: function () {
        // bind to DOM event using jQuery
        this.$el.click(this.jqueryClicked);

        // bind to API event
        this.on('apiEvent', this.callback);
    },

    // 'this' is view
    clicked: function(event) {
        console.log("events handler for " + this.el.outerHTML);
        this.trigger('apiEvent', event.type);
    },

    // 'this' is handling DOM element
    jqueryClicked: function(event) {
        console.log("jQuery handler for " + this.outerHTML);
    },

    callback: function(eventType) {
        console.log("event type was " + eventType);
    }

});

var view = new View();

Routers

In Backbone, routers provide a way for you to connect URLs (either hash fragments, or real) to parts of your application. Any piece of your application that you want to be bookmarkable, shareable, and back-button-able, needs a URL.

http://example.com/#about
http://example.com/#search/seasonal-horns/page2

An application will usually have at least one route mapping a URL route to a function that determines what happens when a user reaches that route. This relationship is defined as follows:

'route' : 'mappedFunction'

Let’s define our first router by extending Backbone.Router. For the purposes of this guide, we’re going to continue pretending we’re creating a complex todo application (something like a personal organizer/planner) that requires a complex TodoRouter.

Note the inline comments in the code example below as they continue our lesson on routers.

var TodoRouter = Backbone.Router.extend({
    /* define the route and function maps for this router */
    routes: {
        "about" : "showAbout",
        /* Sample usage: http://example.com/#about */

        "todo/:id" : "getTodo",
        /* This is an example of using a ":param" variable which allows us to match
        any of the components between two URL slashes */
        /* Sample usage: http://example.com/#todo/5 */

        "search/:query" : "searchTodos",
        /* We can also define multiple routes that are bound to the same map function,
        in this case searchTodos(). Note below how we're optionally passing in a
        reference to a page number if one is supplied */
        /* Sample usage: http://example.com/#search/job */

        "search/:query/p:page" : "searchTodos",
        /* As we can see, URLs may contain as many ":param"s as we wish */
        /* Sample usage: http://example.com/#search/job/p1 */

        "todos/:id/download/*documentPath" : "downloadDocument",
        /* This is an example of using a *splat. Splats are able to match any number of
        URL components and can be combined with ":param"s*/
        /* Sample usage: http://example.com/#todos/5/download/files/Meeting_schedule.doc */

        /* If you wish to use splats for anything beyond default routing, it's probably a good
        idea to leave them at the end of a URL otherwise you may need to apply regular
        expression parsing on your fragment */

        "*other"    : "defaultRoute",
        /* This is a default route that also uses a *splat. Consider the
        default route a wildcard for URLs that are either not matched or where
        the user has incorrectly typed in a route path manually */
        /* Sample usage: http://example.com/# <anything> */

        "optional(/:item)": "optionalItem",
        "named/optional/(y:z)": "namedOptionalItem"
        /* Router URLs also support optional parts via parentheses, without having
           to use a regex.  */
    },

    showAbout: function(){
    },

    getTodo: function(id){
        /*
        Note that the id matched in the above route will be passed to this function
        */
        console.log("You are trying to reach todo " + id);
    },

    searchTodos: function(query, page){
        var page_number = page || 1;
        console.log("Page number: " + page_number + " of the results for todos containing the word: " + query);
    },

    downloadDocument: function(id, path){
    },

    defaultRoute: function(other){
        console.log('Invalid. You attempted to reach:' + other);
    }
});

/* Now that we have a router setup, we need to instantiate it */

var myTodoRouter = new TodoRouter();

Backbone offers an opt-in for HTML5 pushState support via window.history.pushState. This permits you to define routes such as http://backbonejs.org/just/an/example. This will be supported with automatic degradation when a user’s browser doesn’t support pushState. Note that it is vastly preferred if you’re capable of also supporting pushState on the server side, although it is a little more difficult to implement.

Andrew de Andrade has pointed out that DocumentCloud, the creators of Backbone, usually only use a single router in most of their applications. You’re very likely to not require more than one or two routers in your own projects; the majority of your application routing can be kept organized in a single router without it getting unwieldy.

Backbone.history

Next, we need to initialize Backbone.history as it handles hashchange events in our application. This will automatically handle routes that have been defined and trigger callbacks when they’ve been accessed.

The Backbone.history.start() method will simply tell Backbone that it’s okay to begin monitoring all hashchange events as follows:

var TodoRouter = Backbone.Router.extend({
  /* define the route and function maps for this router */
  routes: {
    "about" : "showAbout",
    "search/:query" : "searchTodos",
    "search/:query/p:page" : "searchTodos"
  },

  showAbout: function(){},

  searchTodos: function(query, page){
    var page_number = page || 1;
    console.log("Page number: " + page_number + " of the results for todos containing the word: " + query);
  }
});

var myTodoRouter = new TodoRouter();

Backbone.history.start();

// Go to and check console:
// http://localhost/#search/job/p3   logs: Page number: 3 of the results for todos containing the word: job
// http://localhost/#search/job      logs: Page number: 1 of the results for todos containing the word: job 
// etc.

Note: To run the last example, you’ll need to create a local development environment and test project, which we will cover later on in the book.

If you would like to update the URL to reflect the application state at a particular point, you can use the router’s .navigate() method. By default, it simply updates your URL fragment without triggering the hashchange event:

// Let's imagine we would like a specific fragment (edit) once a user opens a single todo
var TodoRouter = Backbone.Router.extend({
  routes: {
    "todo/:id": "viewTodo",
    "todo/:id/edit": "editTodo"
    // ... other routes
  },

  viewTodo: function(id){
    console.log("View todo requested.");
    this.navigate("todo/" + id + '/edit'); // updates the fragment for us, but doesn't trigger the route
  },

  editTodo: function(id) {
    console.log("Edit todo opened.");
  }
});

var myTodoRouter = new TodoRouter();

Backbone.history.start();

// Go to: http://localhost/#todo/4
//
// URL is updated to: http://localhost/#todo/4/edit
// but editTodo() function is not invoked even though location we end up is mapped to it.
//
// logs: View todo requested.

It is also possible for Router.navigate() to trigger the route along with updating the URL fragment by passing the trigger:true option.

Note: This usage is discouraged. The recommended usage is the one described above which creates a bookmarkable URL when your application transitions to a specific state.

var TodoRouter = Backbone.Router.extend({
  routes: {
    "todo/:id": "viewTodo",
    "todo/:id/edit": "editTodo"
    // ... other routes
  },

  viewTodo: function(id){
    console.log("View todo requested.");
    this.navigate("todo/" + id + '/edit', {trigger: true}); // updates the fragment and triggers the route as well
  },

  editTodo: function(id) {
    console.log("Edit todo opened.");
  }
});

var myTodoRouter = new TodoRouter();

Backbone.history.start();

// Go to: http://localhost/#todo/4
//
// URL is updated to: http://localhost/#todo/4/edit
// and this time editTodo() function is invoked.
//
// logs:
// View todo requested.
// Edit todo opened.

A “route” event is also triggered on the router in addition to being fired on Backbone.history.

Backbone.history.on('route', onRoute);

// Trigger 'route' event on router instance.
router.on('route', function(name, args) {
  console.log(name === 'routeEvent'); 
});

location.replace('http://example.com#route-event/x');
Backbone.history.checkUrl();

Backbone’s Sync API

We previously discussed how Backbone supports RESTful persistence via its fetch() and create() methods on Collections and save(), and destroy() methods on Models. Now we are going to take a closer look at Backbone’s sync method which underlies these operations.

The Backbone.sync method is an integral part of Backbone.js. It assumes a jQuery-like $.ajax() method, so HTTP parameters are organized based on jQuery’s API. Since some legacy servers may not support JSON-formatted requests and HTTP PUT and DELETE operations, Backbone can be configured to emulate these capabilities using the two configuration variables shown below with their default values:

Backbone.emulateHTTP = false; // set to true if server cannot handle HTTP PUT or HTTP DELETE
Backbone.emulateJSON = false; // set to true if server cannot handle application/json requests

The inline Backbone.emulateHTTP option should be set to true if extended HTTP methods are not supported by the server. The Backbone.emulateJSON option should be set to true if the server does not understand the MIME type for JSON.

// Overwriting jQuery ajax method - no actual request will be made
var ajaxSettings;
$.ajax = function (ajaxRequest) {
    ajaxSettings = ajaxRequest;
};

// Create a new library collection
var Library = Backbone.Collection.extend({
    url : function() { return '/library'; }
});

// Define attributes for our model
var attrs = {
    title  : "The Tempest",
    author : "Bill Shakespeare",
    length : 123
};

// Create a new Library instance
var library = new Library;

// Create a new instance of a model within our collection
library.create(attrs, {wait: false});

// Update with just emulateHTTP
library.first().save({id: '2-the-tempest', author: 'Tim Shakespeare'}, {
  emulateHTTP: true
});

// Check the ajaxSettings being used for our request
console.log(ajaxSettings.url === '/library/2-the-tempest'); // true
console.log(ajaxSettings.type === 'POST'); // true
console.log(ajaxSettings.contentType === 'application/json'); // true

// Parse the data for the request to confirm it is as expected
var data = JSON.parse(ajaxSettings.data);
console.log(data.id === '2-the-tempest');  // true
console.log(data.author === 'Tim Shakespeare'); // true
console.log(data.length === 123); // true

library.first().save({id: '2-the-tempest', author: 'Tim Shakespeare'}, {
  emulateJSON: true
});

console.log(ajaxSettings.url === '/library/2-the-tempest'); // true
console.log(ajaxSettings.type === 'PUT'); // true
console.log(ajaxSettings.contentType ==='application/x-www-form-urlencoded'); // true

var data = JSON.parse(ajaxSettings.data.model);
console.log(data.id === '2-the-tempest'); // true
console.log(data.author ==='Tim Shakespeare'); // true
console.log(data.length === 123); // true

Backbone.sync is called every time Backbone tries to read, save, or delete models. It uses jQuery or Zepto’s $.ajax() implementations to make these RESTful requests, however this can be overridden as per your needs.

The sync function may be overridden globally as Backbone.sync, or at a finer-grained level, by adding a sync function to a Backbone collection or to an individual model.

Since all persistence is handled by the Backbone.sync function, an alternative persistence layer can be used by simply overriding Backbone.sync with a function that has the same signature:

Backbone.sync = function(method, model, options) {
};

The methodMap below is used by the standard sync implementation to map the method parameter to an HTTP operation and illustrates the type of action required by each method argument:

var methodMap = {
  'create': 'POST',
  'update': 'PUT',
  'patch':  'PATCH',
  'delete': 'DELETE',
  'read':   'GET'
};

If we wanted to replace the standard sync implementation with one that simply logged the calls to sync, we could do this:

var id_counter = 1;
Backbone.sync = function(method, model) {
  console.log("I've been passed " + method + " with " + JSON.stringify(model));
  if(method === 'create'){ model.set('id', id_counter++); }
};

The Backbone.sync method is intended to be overridden to support other persistence backends. The built-in method is tailored to a certain breed of RESTful JSON APIs - Backbone was originally extracted from a Ruby on Rails application, which uses HTTP methods like PUT in the same way.

Backbone.sync = function(method, model, options) {

  function success(result) {
    // Handle successful results from MyAPI
    if (options.success) {
      options.success(result);
    }
  }

  function error(result) {
    // Handle error results from MyAPI
    if (options.error) {
      options.error(result);
    }
  }

  options || (options = {});

  switch (method) {
    case 'create':
      return MyAPI.create(model, success, error);

    case 'update':
      return MyAPI.update(model, success, error);

    case 'patch':
      return MyAPI.patch(model, success, error);

    case 'delete':
      return MyAPI.destroy(model, success, error);

    case 'read':
      if (model.cid) {
        return MyAPI.find(model, success, error);
      } else {
        return MyAPI.findAll(model, success, error);
      }
  }
};

This pattern delegates API calls to a new object (MyAPI), which could be a Backbone-style class that supports events. This can be safely tested separately, and potentially used with libraries other than Backbone.

There are quite a few sync implementations out there. The following examples are all available on GitHub:

Dependencies

What this translates to is that if you require working with anything beyond models, you will need to include a DOM manipulation library such as jQuery or Zepto. Underscore is primarily used for its utility methods (which Backbone relies upon heavily) and json2.js for legacy browser JSON support if Backbone.sync is used.

Summary

In this chapter we have introduced you to the components you will be using to build applications with Backbone: Models, Views, Collections, and Routers. We’ve also explored the Events mix-in that Backbone uses to enhance all components with publish-subscribe capabilities and seen how it can be used with arbitrary objects. Finally, we saw how Backbone leverages the Underscore.js and jQuery/Zepto APIs to add rich manipulation and persistence features to Backbone Collections and Models.

Backbone has many operations and options beyond those we have covered here and is always evolving, so be sure to visit the official documentation for more details and the latest features. In the next chapter you will start to get your hands dirty as we walk you through the implementation of your first Backbone application.

Exercise 1: Todos - Your First Backbone.js App

Now that we’ve covered fundamentals, let’s write our first Backbone.js application. We’ll build the Backbone Todo List application exhibited on TodoMVC.com. Building a Todo List is a great way to learn Backbone’s conventions. It’s a relatively simple application, yet technical challenges surrounding binding, persisting model data, routing, and template rendering provide opportunities to illustrate some core Backbone features.

Let’s consider the application’s architecture at a high level. We’ll need:

Static HTML

Header and Scripts

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <title>Backbone.js • TodoMVC</title>
  <link rel="stylesheet" href="assets/index.css">
</head>
<body>
  <script type="text/template" id="item-template"></script>
  <script type="text/template" id="stats-template"></script>
  <script src="js/lib/jquery.min.js"></script>
  <script src="js/lib/underscore-min.js"></script>
  <script src="js/lib/backbone-min.js"></script>
  <script src="js/lib/backbone.localStorage.js"></script>
  <script src="js/models/todo.js"></script>
  <script src="js/collections/todos.js"></script>
  <script src="js/views/todos.js"></script>
  <script src="js/views/app.js"></script>
  <script src="js/routers/router.js"></script>
  <script src="js/app.js"></script>
</body>
</html>

In addition to the aforementioned dependencies, note that a few other application-specific files are also loaded. These are organized into folders representing their application responsibilities: models, views, collections, and routers. An app.js file is present to house central initialization code.

Note: If you want to follow along, create a directory structure as demonstrated in index.html:

You will also need index.css, which should live in an assets directory. And remember that you can see a demo of the final application at TodoMVC.com.

We will be creating the application JavaScript files during the tutorial. Don’t worry about the two ‘text/template’ script elements - we will replace those soon!

Application HTML

Now let’s populate the body of index.html. We’ll need an <input> for creating new todos, a <ul id="todo-list" /> for listing the actual todos, and a footer where we can later insert statistics and links for performing operations such as clearing completed todos. We’ll add the following markup immediately inside our body tag before the script elements:

  <section class="todoapp">
    <header class="header">
      <h1>todos</h1>
      <input class="new-todo" placeholder="What needs to be done?" autofocus>
    </header>
    <section class="main">
      <input class="toggle-all" type="checkbox">
      <label for="toggle-all">Mark all as complete</label>
      <ul class="todo-list"></ul>
    </section>
    <footer class="footer"></footer>
  </section>
  <div class="info">
    <p>Double-click to edit a todo</p>
    <p>Written by <a href="https://github.com/addyosmani">Addy Osmani</a></p>
    <p>Part of <a href="http://todomvc.com">TodoMVC</a></p>
  </div>

Templates

To complete index.html, we need to add the templates which we will use to dynamically create HTML by injecting model data into their placeholders. One way of including templates in the page is by using custom script tags. These don’t get evaluated by the browser, which just interprets them as plain text. Underscore micro-templating can then access the templates, rendering fragments of HTML.

We’ll start by filling in the #item-template which will be used to display individual todo items.

  <!-- index.html -->

  <script type="text/template" id="item-template">
    <div class="view">
      <input class="toggle" type="checkbox" <%= completed ? 'checked' : '' %>>
      <label><%= title %></label>
      <button class="destroy"></button>
    </div>
    <input class="edit" value="<%= title %>">
  </script>

The template tags in the above markup, such as <%= and <%-, are specific to Underscore.js and are documented on the Underscore site. In your own applications, you have a choice of template libraries, such as Mustache or Handlebars. Use whichever you prefer, Backbone doesn’t mind.

We also need to define the #stats-template template which we will use to populate the footer.

  <!-- index.html -->

  <script type="text/template" id="stats-template">
    <span class="todo-count"><strong><%= remaining %></strong> <%= remaining === 1 ? 'item' : 'items' %> left</span>
    <ul class="filters">
      <li>
        <a class="selected" href="#/">All</a>
      </li>
      <li>
        <a href="#/active">Active</a>
      </li>
      <li>
        <a href="#/completed">Completed</a>
      </li>
    </ul>
    <% if (completed) { %>
    <button class="clear-completed">Clear completed (<%= completed %>)</button>
    <% } %>
  </script>

The #stats-template displays the number of remaining incomplete items and contains a list of hyperlinks which will be used to perform actions when we implement our router. It also contains a button which can be used to clear all of the completed items.

Now that we have all the HTML that we will need, we’ll start implementing our application by returning to the fundamentals: a Todo model.

Todo model

The Todo model is remarkably straightforward. First, a todo has two attributes: a title stores a todo item’s title and a completed status indicates if it’s complete. These attributes are passed as defaults, as shown below:


  // js/models/todo.js

  var app = app || {};

  // Todo Model
  // ----------
  // Our basic **Todo** model has `title` and `completed` attributes.

  app.Todo = Backbone.Model.extend({

    // Default attributes ensure that each todo created has `title` and `completed` keys.
    defaults: {
      title: '',
      completed: false
    },

    // Toggle the `completed` state of this todo item.
    toggle: function() {
      this.save({
        completed: !this.get('completed')
      });
    }

  });

Second, the Todo model has a toggle() method through which a Todo item’s completion status can be set and simultaneously persisted.

Todo collection

Next, a TodoList collection is used to group our models. The collection uses the LocalStorage adapter to override Backbone’s default sync() operation with one that will persist our Todo records to HTML5 Local Storage. Through local storage, they’re saved between page requests.


  // js/collections/todos.js

  var app = app || {};

  // Todo Collection
  // ---------------

  // The collection of todos is backed by *localStorage* instead of a remote
  // server.
  var TodoList = Backbone.Collection.extend({

    // Reference to this collection's model.
    model: app.Todo,

    // Save all of the todo items under the `"todos-backbone"` namespace.
    localStorage: new Backbone.LocalStorage('todos-backbone'),

    // Filter down the list of all todo items that are finished.
    completed: function() {
      return this.filter(function( todo ) {
        return todo.get('completed');
      });
    },

    // Filter down the list to only todo items that are still not finished.
    remaining: function() {
      return this.without.apply( this, this.completed() );
    },

    // We keep the Todos in sequential order, despite being saved by unordered
    // GUID in the database. This generates the next order number for new items.
    nextOrder: function() {
      if ( !this.length ) {
        return 1;
      }
      return this.last().get('order') + 1;
    },

    // Todos are sorted by their original insertion order.
    comparator: function( todo ) {
      return todo.get('order');
    }
  });

  // Create our global collection of **Todos**.
  app.Todos = new TodoList();

The collection’s completed() and remaining() methods return an array of finished and unfinished todos, respectively.

A nextOrder() method implements a sequence generator while a comparator() sorts items by their insertion order.

Note: this.filter, this.without and this.last are Underscore methods that are mixed in to Backbone.Collection so that the reader knows how to find out more about them.

Application View

Let’s examine the core application logic which resides in the views. Each view supports functionality such as edit-in-place, and therefore contains a fair amount of logic. To help organize this logic, we’ll use the element controller pattern. The element controller pattern consists of two views: one controls a collection of items while the other deals with each individual item.

In our case, an AppView will handle the creation of new todos and rendering of the initial todo list. Instances of TodoView will be associated with each individual Todo record. Todo instances can handle editing, updating, and destroying their associated todo.

To keep things short and simple, we won’t be implementing all of the application’s features in this tutorial, we’ll just cover enough to get you started. Even so, there is a lot for us to cover in AppView, so we’ll split our discussion into two sections.


  // js/views/app.js

  var app = app || {};

  // The Application
  // ---------------

  // Our overall **AppView** is the top-level piece of UI.
  app.AppView = Backbone.View.extend({

    // Instead of generating a new element, bind to the existing skeleton of
    // the App already present in the HTML.
    el: '.todoapp',

    // Our template for the line of statistics at the bottom of the app.
    statsTemplate: _.template( $('#stats-template').html() ),

    // At initialization we bind to the relevant events on the `Todos`
    // collection, when items are added or changed.
    initialize: function() {
      this.allCheckbox = this.$('.toggle-all')[0];
      this.$input = this.$('.new-todo');
      this.$footer = this.$('.footer');
      this.$main = this.$('.main');

      this.listenTo(app.Todos, 'add', this.addOne);
      this.listenTo(app.Todos, 'reset', this.addAll);
    },

    // Add a single todo item to the list by creating a view for it, and
    // appending its element to the `<ul>`.
    addOne: function( todo ) {
      var view = new app.TodoView({ model: todo });
      $('.todo-list').append( view.render().el );
    },

    // Add all items in the **Todos** collection at once.
    addAll: function() {
      this.$('.todo-list').html('');
      app.Todos.each(this.addOne, this);
    }

  });

A few notable features are present in our initial version of AppView, including a statsTemplate, an initialize method that’s implicitly called on instantiation, and several view-specific methods.

An el (element) property stores a selector targeting the DOM element with an ID of todoapp. In the case of our application, el refers to the matching <section id="todoapp" /> element in index.html.

The call to _.template uses Underscore’s micro-templating to construct a statsTemplate object from our #stats-template. We will use this template later when we render our view.

Now let’s take a look at the initialize function. First, it’s using jQuery to cache the elements it will be using into local properties (recall that this.$() finds elements relative to this.$el). Then it’s binding to two events on the Todos collection: add and reset. Since we’re delegating handling of updates and deletes to the TodoView view, we don’t need to worry about those here. The two pieces of logic are:

Note that we were able to use this within addAll() to refer to the view because listenTo() implicitly set the callback’s context to the view when it created the binding.


  // js/views/app.js

  var app = app || {};

  // The Application
  // ---------------

  // Our overall **AppView** is the top-level piece of UI.
  app.AppView = Backbone.View.extend({

    // Instead of generating a new element, bind to the existing skeleton of
    // the App already present in the HTML.
    el: '.todoapp',

    // Our template for the line of statistics at the bottom of the app.
    statsTemplate: _.template( $('#stats-template').html() ),

    // New
    // Delegated events for creating new items, and clearing completed ones.
    events: {
      'keypress .new-todo': 'createOnEnter',
      'click .clear-completed': 'clearCompleted',
      'click .toggle-all': 'toggleAllComplete'
    },

    // At initialization we bind to the relevant events on the `Todos`
    // collection, when items are added or changed. Kick things off by
    // loading any preexisting todos that might be saved in *localStorage*.
    initialize: function() {
      this.allCheckbox = this.$('.toggle-all')[0];
      this.$input = this.$('.new-todo');
      this.$footer = this.$('.footer');
      this.$main = this.$('.main');

      this.listenTo(app.Todos, 'add', this.addOne);
      this.listenTo(app.Todos, 'reset', this.addAll);

      // New
      this.listenTo(app.Todos, 'change:completed', this.filterOne);
      this.listenTo(app.Todos,'filter', this.filterAll);
      this.listenTo(app.Todos, 'all', this.render);

      app.Todos.fetch();
    },

    // New
    // Re-rendering the App just means refreshing the statistics -- the rest
    // of the app doesn't change.
    render: function() {
      var completed = app.Todos.completed().length;
      var remaining = app.Todos.remaining().length;

      if ( app.Todos.length ) {
        this.$main.show();
        this.$footer.show();

        this.$footer.html(this.statsTemplate({
          completed: completed,
          remaining: remaining
        }));

        this.$('.filters li a')
          .removeClass('selected')
          .filter('[href="#/' + ( app.TodoFilter || '' ) + '"]')
          .addClass('selected');
      } else {
        this.$main.hide();
        this.$footer.hide();
      }

      this.allCheckbox.checked = !remaining;
    },

    // Add a single todo item to the list by creating a view for it, and
    // appending its element to the `<ul>`.
    addOne: function( todo ) {
      var view = new app.TodoView({ model: todo });
      $('.todo-list').append( view.render().el );
    },

    // Add all items in the **Todos** collection at once.
    addAll: function() {
      this.$('.todo-list').html('');
      app.Todos.each(this.addOne, this);
    },

    // New
    filterOne : function (todo) {
      todo.trigger('visible');
    },

    // New
    filterAll : function () {
      app.Todos.each(this.filterOne, this);
    },


    // New
    // Generate the attributes for a new Todo item.
    newAttributes: function() {
      return {
        title: this.$input.val().trim(),
        order: app.Todos.nextOrder(),
        completed: false
      };
    },

    // New
    // If you hit return in the main input field, create new Todo model,
    // persisting it to localStorage.
    createOnEnter: function( event ) {
      if ( event.which !== ENTER_KEY || !this.$input.val().trim() ) {
        return;
      }

      app.Todos.create( this.newAttributes() );
      this.$input.val('');
    },

    // New
    // Clear all completed todo items, destroying their models.
    clearCompleted: function() {
      _.invoke(app.Todos.completed(), 'destroy');
      return false;
    },

    // New
    toggleAllComplete: function() {
      var completed = this.allCheckbox.checked;

      app.Todos.each(function( todo ) {
        todo.save({
          'completed': completed
        });
      });
    }
  });

We have added the logic for creating new todos, editing them, and filtering them based on their completed status.

The initialize() method completes by fetching the previously saved todos from localStorage.

Individual Todo View

Now let’s look at the TodoView view. This will be in charge of individual Todo records, making sure the view updates when the todo does. To enable this functionality, we will add event listeners to the view that listen for events on an individual todo’s HTML representation.


  // js/views/todos.js

  var app = app || {};

  // Todo Item View
  // --------------

  // The DOM element for a todo item...
  app.TodoView = Backbone.View.extend({

    //... is a list tag.
    tagName: 'li',

    // Cache the template function for a single item.
    template: _.template( $('#item-template').html() ),

    // The DOM events specific to an item.
    events: {
      'dblclick label': 'edit',
      'keypress .edit': 'updateOnEnter',
      'blur .edit': 'close'
    },

    // The TodoView listens for changes to its model, re-rendering. Since there's
    // a one-to-one correspondence between a **Todo** and a **TodoView** in this
    // app, we set a direct reference on the model for convenience.
    initialize: function() {
      this.listenTo(this.model, 'change', this.render);
    },

    // Re-renders the titles of the todo item.
    render: function() {
      this.$el.html( this.template( this.model.attributes ) );
      this.$input = this.$('.edit');
      return this;
    },

    // Switch this view into `"editing"` mode, displaying the input field.
    edit: function() {
      this.$el.addClass('editing');
      this.$input.focus();
    },

    // Close the `"editing"` mode, saving changes to the todo.
    close: function() {
      var value = this.$input.val().trim();

      if ( value ) {
        this.model.save({ title: value });
      }

      this.$el.removeClass('editing');
    },

    // If you hit `enter`, we're through editing the item.
    updateOnEnter: function( e ) {
      if ( e.which === ENTER_KEY ) {
        this.close();
      }
    }
  });

In the initialize() constructor, we set up a listener that monitors a todo model’s change event. As a result, when the todo gets updated, the application will re-render the view and visually reflect its changes. Note that the model passed in the arguments hash by our AppView is automatically available to us as this.model.

In the render() method, we render our Underscore.js #item-template, which was previously compiled into this.template using Underscore’s _.template() method. This returns an HTML fragment that replaces the content of the view’s element (an li element was implicitly created for us based on the tagName property). In other words, the rendered template is now present under this.el and can be appended to the todo list in the user interface. render() finishes by caching the input element within the instantiated template into this.$input.

Startup

So now we have two views: AppView and TodoView. The former needs to be instantiated on page load so its code gets executed. This can be accomplished through jQuery’s ready() utility, which will execute a function when the DOM is loaded.


  // js/app.js

  var app = app || {};
  var ENTER_KEY = 13;

  $(function() {

    // Kick things off by creating the **App**.
    new app.AppView();

  });

In action

Let’s pause and ensure that the work we’ve done so far functions as intended.

If you are following along, open file://*path*/index.html in your browser and monitor its console. If all is well, you shouldn’t see any JavaScript errors other than regarding the router.js file that we haven’t created yet. The todo list should be blank as we haven’t yet created any todos. Plus, there is some additional work we’ll need to do before the user interface fully functions.

In the console, add a new todo item: app.Todos.create({ title: 'My first Todo item'}); and hit return.

If all is functioning properly, this should log the new todo we’ve just added to the todos collection. The newly created todo is also saved to Local Storage and will be available on page refresh.

app.Todos.create() executes a collection method (Collection.create(attributes, [options])) which instantiates a new model item of the type passed into the collection definition, in our case app.Todo:


  // from our js/collections/todos.js

  var TodoList = Backbone.Collection.extend({

      model: app.Todo // the model type used by collection.create() to instantiate new model in the collection
      ...
  )};

var secondTodo = app.Todos.create({ title: 'My second Todo item'});
secondTodo instanceof app.Todo // returns true

The todos added through the console should still appear in the list since they are populated from the Local Storage. Also, we should be able to create a new todo by typing a title and pressing enter.

Excellent, we’re making great progress, but what about completing and deleting todos?

Completing & deleting todos

The next part of our tutorial is going to cover completing and deleting todos. These two actions are specific to each Todo item, so we need to add this functionality to the TodoView view. We will do so by adding togglecompleted() and clear() methods along with corresponding entries in the events hash.


  // js/views/todos.js

  var app = app || {};

  // Todo Item View
  // --------------

  // The DOM element for a todo item...
  app.TodoView = Backbone.View.extend({

    //... is a list tag.
    tagName: 'li',

    // Cache the template function for a single item.
    template: _.template( $('#item-template').html() ),

    // The DOM events specific to an item.
    events: {
      'click .toggle': 'toggleCompleted', // NEW
      'dblclick label': 'edit',
      'click .destroy': 'clear',           // NEW
      'keypress .edit': 'updateOnEnter',
      'blur .edit': 'close'
    },

    // The TodoView listens for changes to its model, re-rendering. Since there's
    // a one-to-one correspondence between a **Todo** and a **TodoView** in this
    // app, we set a direct reference on the model for convenience.
    initialize: function() {
      this.listenTo(this.model, 'change', this.render);
      this.listenTo(this.model, 'destroy', this.remove);        // NEW
      this.listenTo(this.model, 'visible', this.toggleVisible); // NEW
    },

    // Re-render the titles of the todo item.
    render: function() {
      this.$el.html( this.template( this.model.attributes ) );

      this.$el.toggleClass( 'completed', this.model.get('completed') ); // NEW
      this.toggleVisible();                                             // NEW

      this.$input = this.$('.edit');
      return this;
    },

    // NEW - Toggles visibility of item
    toggleVisible : function () {
      this.$el.toggleClass( 'hidden',  this.isHidden());
    },

    // NEW - Determines if item should be hidden
    isHidden : function () {
      var isCompleted = this.model.get('completed');
      return ( // hidden cases only
        (!isCompleted && app.TodoFilter === 'completed')
        || (isCompleted && app.TodoFilter === 'active')
      );
    },

    // NEW - Toggle the `"completed"` state of the model.
    togglecompleted: function() {
      this.model.toggle();
    },

    // Switch this view into `"editing"` mode, displaying the input field.
    edit: function() {
      this.$el.addClass('editing');
      this.$input.focus();
    },

    // Close the `"editing"` mode, saving changes to the todo.
    close: function() {
      var value = this.$input.val().trim();

      if ( value ) {
        this.model.save({ title: value });
      } else {
        this.clear(); // NEW
      }

      this.$el.removeClass('editing');
    },

    // If you hit `enter`, we're through editing the item.
    updateOnEnter: function( e ) {
      if ( e.which === ENTER_KEY ) {
        this.close();
      }
    },

    // NEW - Remove the item, destroy the model from *localStorage* and delete its view.
    clear: function() {
      this.model.destroy();
    }
  });

The key part of this is the two event handlers we’ve added, a togglecompleted event on the todo’s checkbox, and a click event on the todo’s <button class="destroy" /> button.

Let’s look at the events that occur when we click the checkbox for a todo item:

Todo routing

Finally, we move on to routing, which will allow us to easily filter the list of items that are active as well as those which have been completed. We’ll be supporting the following routes:

When the route changes, the todo list will be filtered on a model level and the selected class on the filter links in the footer will be toggled as described above. When an item is updated while a filter is active it will be updated accordingly (e.g., if the filter is active and the item is checked, it will be hidden). The active filter is persisted on reload.


  // js/routers/router.js

  // Todo Router
  // ----------

  var app = app || {};

  var Workspace = Backbone.Router.extend({
    routes:{
      '*filter': 'setFilter'
    },

    setFilter: function( param ) {
      // Set the current filter to be used
      if (param) {
        param = param.trim();
      }
      app.TodoFilter = param || '';

      // Trigger a collection filter event, causing hiding/unhiding
      // of Todo view items
      app.Todos.trigger('filter');
    }
  });

  app.TodoRouter = new Workspace();
  Backbone.history.start();

Our router uses a *splat to set up a default route which passes the string after ‘#/’ in the URL to setFilter() which sets app.TodoFilter to that string.

As we can see in the line app.Todos.trigger('filter'), once the filter has been set, we simply trigger ‘filter’ on our Todos collection to toggle which items are visible and which are hidden. Recall that our AppView’s filterAll() method is bound to the collection’s filter event and that any event on the collection will cause the AppView to re-render.

Finally, we create an instance of our router and call Backbone.history.start() to route the initial URL during page load.

Summary

We’ve now built our first complete Backbone.js application. The latest version of the full app can be viewed online at any time and the sources are readily available via TodoMVC.

Later on in the book, we’ll learn how to further modularize this application using RequireJS, swap out our persistence layer to a database back-end, and finally unit test the application with a few different testing frameworks.

Exercise 2: Book Library - Your First RESTful Backbone.js App

In this chapter, we’ll build a library application for managing digital books using Backbone.js. This differs from the previous Todo application by introducing more sophisticated relationships between models and how to handle them using a REST API.

The Library Application

Our library will allow users to: - Add new books with title, author, release date, and keywords - Display the list of books - Delete books - Search through the library

Setting Up

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <title>Backbone.js Library</title>
    <link rel="stylesheet" href="css/style.css">
</head>
<body>
    <div id="books">
        <form id="addBook" action="#">
            <div>
                <label for="title">Title:</label>
                <input id="title" type="text">
            </div>
            <div>
                <label for="author">Author:</label>
                <input id="author" type="text">
            </div>
            <div>
                <label for="releaseDate">Release date:</label>
                <input id="releaseDate" type="text">
            </div>
            <div>
                <label for="keywords">Keywords:</label>
                <input id="keywords" type="text">
            </div>
            <div>
                <button id="add">Add</button>
            </div>
        </form>
    </div>

    <script id="bookTemplate" type="text/template">
        <img src="<%= coverImage %>"/>
        <ul>
            <li><%= title %></li>
            <li><%= author %></li>
            <li><%= releaseDate %></li>
            <li>
                <%- keywords.map(keyword => `<span class="keyword">${keyword}</span>`).join(' ') %>
            </li>
        </ul>

        <button class="delete">Delete</button>
    </script>

    <script src="js/lib/jquery.min.js"></script>
    <script src="js/lib/underscore.min.js"></script>
    <script src="js/lib/backbone.min.js"></script>
    <script src="js/models/book.js"></script>
    <script src="js/collections/library.js"></script>
    <script src="js/views/book.js"></script>
    <script src="js/views/library.js"></script>
    <script src="js/app.js"></script>
</body>
</html>

The Book Model

// models/book.js
const Book = Backbone.Model.extend({
    defaults: {
        title: '',
        author: '',
        releaseDate: '',
        keywords: [],
        coverImage: 'img/placeholder.png'
    },

    parse(response) {
        // Handle MongoDB-style _id
        if (response._id) {
            response.id = response._id;
        }
        return response;
    }
});

The Library Collection

// collections/library.js
const Library = Backbone.Collection.extend({
    model: Book,
    url: '/api/books'
});

The Book View

// views/book.js
const BookView = Backbone.View.extend({
    tagName: 'div',
    className: 'bookContainer',
    template: _.template($('#bookTemplate').html()),

    events: {
        'click .delete': 'deleteBook'
    },

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

    deleteBook() {
        this.model.destroy({
            success: () => {
                this.remove();
            },
            error: (model, response) => {
                console.error('Error deleting book:', response);
            }
        });
    }
});

The Library View

// views/library.js
const LibraryView = Backbone.View.extend({
    el: '#books',

    events: {
        'click #add': 'addBook'
    },

    initialize() {
        this.collection = new Library();
        this.listenTo(this.collection, 'add', this.renderBook);
        this.listenTo(this.collection, 'reset', this.render);

        this.collection.fetch({reset: true});
    },

    render() {
        this.collection.each(book => {
            this.renderBook(book);
        });
    },

    renderBook(book) {
        const bookView = new BookView({model: book});
        this.$el.append(bookView.render().el);
    },

    addBook(e) {
        e.preventDefault();

        const formData = {
            title: $('#title').val(),
            author: $('#author').val(),
            releaseDate: $('#releaseDate').val(),
            keywords: $('#keywords').val().split(',').map(k => k.trim())
        };

        this.collection.create(formData, {
            wait: true,
            success: () => {
                $('#addBook')[0].reset();
            },
            error: (model, response) => {
                console.error('Error adding book:', response);
            }
        });
    }
});

Starting the Application

// app.js
$(() => {
    new LibraryView();
});

Styling

/* style.css */
.bookContainer {
    border: 1px solid #ccc;
    margin: 10px;
    padding: 15px;
    border-radius: 5px;
    display: inline-block;
}

.bookContainer img {
    max-width: 100px;
    margin-bottom: 10px;
}

.keyword {
    background: #eee;
    padding: 2px 5px;
    border-radius: 3px;
    margin-right: 5px;
    font-size: 0.9em;
}

#addBook {
    margin: 20px;
}

#addBook div {
    margin-bottom: 10px;
}

#addBook label {
    display: inline-block;
    width: 100px;
}

Important Notes

this.collection.create(formData, {
    wait: true,
    success: () => {
        // Handle success
    },
    error: (model, response) => {
        console.error('Error:', response);
    }
});

parse(response) {
    if (response._id) {
        response.id = response._id;
    }
    return response;
}

keywords.map(keyword => `<span class="keyword">${keyword}</span>`).join(' ')

this.listenTo(this.collection, 'add', this.renderBook);

Testing the Application

Server-Side Implementation

Backbone Extensions

Backbone is flexible, simple, and powerful. However, you may find that the complexity of the application you are working on requires more than what it provides out of the box. There are certain concerns which it just doesn’t address directly as one of its goals is to be minimalist.

Take for example Views, which provide a default render method which does nothing and produces no real results when called, despite most implementations using it to generate the HTML that the view manages. Also, Models and Collections have no built-in way of handling nested hierarchies - if you require this functionality, you need to write it yourself or use a plugin.

In these cases, there are many existing Backbone plugins which can provide advanced solutions for large-scale Backbone apps. A fairly complete list of plugins and frameworks available can be found on the Backbone wiki. Using these add-ons, there is enough for applications of most sizes to be completed successfully.

In this section of the book we will look at two popular Backbone add-ons: MarionetteJS and Thorax.

MarionetteJS (Backbone.Marionette)

As we’ve seen, Backbone provides a great set of building blocks for our JavaScript applications. It gives us the core constructs that are needed to build small to mid-sized apps, organize jQuery DOM events, or create single page apps that support mobile devices and large scale enterprise needs. But Backbone is not a complete framework, it’s a library - a set of building blocks that leaves much of the application design, architecture, and scalability to the developer, including memory management, view management, and more.

MarionetteJS (a.k.a. Backbone.Marionette) provides many of the features that the non-trivial application developer needs, above what Backbone itself provides. It is a composite application library that aims to simplify the construction of large scale applications. It does this by providing a collection of common design and implementation patterns found in the applications that the creator, Derick Bailey, and many other contributors have been using to build Backbone apps.

Marionette follows a similar philosophy to Backbone in that it provides a suite of components that can be used independently of each other, or used together to create significant advantages for us as developers. But it steps above the structural components of Backbone and provides an application layer, with more than a dozen components and building blocks.

Marionette’s components range greatly in the features they provide, but they all work together to create a composite application layer that can both reduce boilerplate code and provide a much needed application structure. Its core components include various and specialized view types that take the boilerplate out of rendering common Backbone.Model and Backbone.Collection scenarios; an Application object and Module architecture to scale applications across sub-applications, features and files; integration of a command pattern, event aggregator, and request/response mechanism; and many more object types that can be extended in a myriad of ways to create an architecture that facilitates an application’s specific needs.

In spite of the large number of constructs that Marionette provides, though, you’re not required to use all of it just because you want to use some of it. Much like Backbone itself, you can pick and choose which features you want to use and when. This allows you to work with other Backbone frameworks and plugins very easily. It also means that you are not required to engage in an all-or-nothing migration to begin using Marionette.

Boilerplate Rendering Code

Consider the code that it typically requires to render a view with Backbone and Underscore template. We need a template to render, which can be placed in the DOM directly, and we need the JavaScript that defines a view that uses the template and populates it with data from a model.

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

  render: function() {

    // compile the Underscore.js template
    var compiledTemplate = _.template(this.template);

    // render the template with the model data
    var data = _.clone(this.model.attributes);
    var html = compiledTemplate(data);

    // populate the view with the rendered html
    this.$el.html(html);
  }
});

Once this is in place, you need to create an instance of your view and pass your model into it. Then you can take the view’s el and append it to the DOM in order to display the view.


var Person = Backbone.Model.extend({
  defaults: {
    "firstName": "Jeremy",
    "lastName": "Ashkenas",
    "email":    "jeremy@example.com"
  }
});

var Derick = new Person({
  firstName: 'Derick',
  lastName: 'Bailey',
  email: 'derickbailey@example.com'
});

var myView = new MyView({
  model: Derick
});

myView.setElement("#content");
myView.render();

This is a standard set up for defining, building, rendering, and displaying a view with Backbone. This is also what we call “boilerplate code” - code that is repeated over and over and over again, across every project and every implementation with the same functionality. It gets to be tedious and repetitious very quickly.

Enter Marionette’s ItemView - a simple way to reduce the boilerplate of defining a view.

Reducing Boilerplate With Marionette.ItemView

All of Marionette’s view types - with the exception of Marionette.View - include a built-in render method that handles the core rendering logic for you. We can take advantage of this by changing the MyView instance to inherit from one of these rather than Backbone.View. Instead of having to provide our own render method for the view, we can let Marionette render it for us. We’ll still use the same Underscore.js template and rendering mechanism, but the implementation of this is hidden behind the scenes. Thus, we can reduce the amount of code needed for this view.

var MyView = Marionette.ItemView.extend({
  template: '#my-view-template'
});

And that’s it - that’s all you need to get the exact same behaviour as the previous view implementation. Just replace Backbone.View.extend with Marionette.ItemView.extend, then get rid of the render method. You can still create the view instance with a model, call the render method on the view instance, and display the view in the DOM the same way that we did before. But the view definition has been reduced to a single line of configuration for the template.

Memory Management

In addition to the reduction of code needed to define a view, Marionette includes some advanced memory management in all of its views, making the job of cleaning up a view instance and its event handlers easy.

var ZombieView = Backbone.View.extend({
  template: '#my-view-template',

  initialize: function() {

    // bind the model change to re-render this view
    this.listenTo(this.model, 'change', this.render);

  },

  render: function() {

    // This alert is going to demonstrate a problem
    alert('We`re rendering the view');

  }
});

If we create two instances of this view using the same variable name for both instances, and then change a value in the model, how many times will we see the alert box?


var Derick = new Person({
  firstName: 'Derick',
  lastName: 'Bailey',
  email: 'derick@example.com'
});


// create the first view instance
var zombieView = new ZombieView({
  model: Derick
});

// create a second view instance, re-using
// the same variable name to store it
zombieView = new ZombieView({
  model: Derick
});

Derick.set('email', 'derickbailey@example.com');

Since we’re re-using the same zombieView variable for both instances, the first instance of the view will fall out of scope immediately after the second is created. This allows the JavaScript garbage collector to come along and clean it up, which should mean the first view instance is no longer active and no longer going to respond to the model’s “change” event.

The problem is caused by the model event binding in the view’s initialize method. Whenever we pass this.render as the callback method to the model’s on event binding, the model itself is being given a direct reference to the view instance. Since the model is now holding a reference to the view instance, replacing the zombieView variable with a new view instance is not going to let the original view fall out of scope. The model still has a reference, therefore the view is still in scope.

Since the original view is still in scope, and the second view instance is also in scope, changing data on the model will cause both view instances to respond.

Fixing this is easy, though. You just need to call stopListening when the view is done with its work and ready to be closed. To do this, add a close method to the view.

var ZombieView = Backbone.View.extend({
  template: '#my-view-template',

  initialize: function() {
    // bind the model change to re-render this view
    this.listenTo(this.model, 'change', this.render);
  },

  close: function() {
    // unbind the events that this view is listening to
    this.stopListening();
  },

  render: function() {

    // This alert is going to demonstrate a problem
    alert('We`re rendering the view');

  }
});

Then call close on the first instance when it is no longer needed, and only one view instance will remain alive. For more information about the listenTo and stopListening functions, see the earlier Backbone Basics chapter and Derick’s post on Managing Events As Relationships, Not Just Resources.

var Jeremy = new Person({
  firstName: 'Jeremy',
  lastName: 'Ashkenas',
  email: 'jeremy@example.com'
});

// create the first view instance
var zombieView = new ZombieView({
  model: Jeremy
})
zombieView.close(); // double-tap the zombie

// create a second view instance, re-using
// the same variable name to store it
zombieView = new ZombieView({
  model: Jeremy
})

Jeremy.set('email', 'jeremyashkenas@example.com');

Rather than having to manually remove these event handlers, though, we can let Marionette do it for us.

var ZombieView = Marionette.ItemView.extend({
  template: '#my-view-template',

  initialize: function() {

    // bind the model change to re-render this view
    this.listenTo(this.model, 'change', this.render);

  },

  render: function() {

    // This alert is going to demonstrate a problem
    alert('We`re rendering the view');

  }
});

Notice in this case we are using a method called listenTo. This method comes from Backbone.Events, and is available in all objects that mix in Backbone.Events - including most Marionette objects. The listenTo method signature is similar to that of the on method, with the exception of passing the object that triggers the event as the first parameter.

Marionette’s views also provide a close event, in which the event bindings that are set up with the listenTo are automatically removed. This means we no longer need to define a close method directly, and when we use the listenTo method, we know that our events will be removed and our views will not turn into zombies.

But how do we automate the call to close on a view, in the real application? When and where do we call that? Enter the Marionette.Region - an object that manages the lifecycle of an individual view.

Region Management

After a view is created, it typically needs to be placed in the DOM so that it becomes visible. This is usually done with a jQuery selector and setting the html() of the resulting object:

var Joe = new Person({
  firstName: 'Joe',
  lastName: 'Bob',
  email: 'joebob@example.com'
});

var myView = new MyView({
  model: Joe
})

myView.render();

// show the view in the DOM
$('#content').html(myView.el)

This, again, is boilerplate code. We shouldn’t have to manually call render and manually select the DOM elements to show the view. Furthermore, this code doesn’t lend itself to closing any previous view instance that might be attached to the DOM element we want to populate. And we’ve seen the danger of zombie views already.

To solve these problems, Marionette provides a Region object - an object that manages the lifecycle of individual views, displayed in a particular DOM element.

// create a region instance, telling it which DOM element to manage
var myRegion = new Marionette.Region({
  el: '#content'
});

// show a view in the region
var view1 = new MyView({ /* ... */ });
myRegion.show(view1);

// somewhere else in the code,
// show a different view
var view2 = new MyView({ /* ... */ });
myRegion.show(view2);

There are several things to note, here. First, we’re telling the region what DOM element to manage by specifying an el in the region instance. Second, we’re no longer calling the render method on our views. And lastly, we’re not calling close on our view, either, though this is getting called for us.

When we use a region to manage the lifecycle of our views, and display the views in the DOM, the region itself handles these concerns. By passing a view instance into the show method of the region, it will call the render method on the view for us. It will then take the resulting el of the view and populate the DOM element.

The next time we call the show method of the region, the region remembers that it is currently displaying a view. The region calls the close method on the view, removes it from the DOM, and then proceeds to run the render & display code for the new view that was passed in.

Since the region handles calling close for us, and we’re using the listenTo event binder in our view instance, we no longer have to worry about zombie views in our application.

Regions are not limited to just Marionette views, though. Any valid Backbone.View can be managed by a Marionette.Region. If your view happens to have a close method, it will be called when the view is closed. If not, the Backbone.View built-in method, remove, will be called instead.

Marionette Todo app

Having learned about Marionette’s high-level concepts, let’s explore refactoring the Todo application we created in our first exercise to use it. The complete code for this application can be found in Derick’s TodoMVC fork.

Our final implementation will be visually and functionally equivalent to the original app, as seen below.

First, we define an application object representing our base TodoMVC app. This will contain initialization code and define the default layout regions for our app.

var TodoMVC = new Backbone.Marionette.Application();

TodoMVC.addRegions({
  header: '#header',
  main: '#main',
  footer: '#footer'
});

TodoMVC.on('start', function() {
  Backbone.history.start();
});

Regions are used to manage the content that’s displayed within specific elements, and the addRegions method on the TodoMVC object is just a shortcut for creating Region objects. We supply a jQuery selector for each region to manage (e.g., #header, #main, and #footer) and then tell the region to show various Backbone views within that region.

Once the application object has been initialized, we call Backbone.history.start() to route the initial URL.

Next, we define our Layouts. A layout is a specialized type of view that directly extends Marionette.ItemView. This means it’s intended to render a single template and may or may not have a model (or item) associated with the template.

One of the main differences between a Layout and an ItemView is that the layout contains regions. When defining a Layout, we supply it with both a template and the regions that the template contains. After rendering the layout, we can display other views within the layout using the regions that were defined.

This captures some of the view logic that was previously in our AppView and TodoView.

Note that Marionette modules (such as the below) offer a simple module system which is used to create privacy and encapsulation in Marionette apps. These certainly don’t have to be used however, and later on in this section we’ll provide links to alternative implementations using RequireJS + AMD instead.

TodoMVC.module('Layout', function(Layout, App, Backbone, Marionette, $, _) {
  
  // Layout Header View
  // ------------------

  Layout.Header = Backbone.Marionette.ItemView.extend({
    template: '#template-header',

    // UI Bindings create cached attributes that
    // point to jQuery selected objects.
    ui: {
      input: '#new-todo'
    },

    events: {
      'keypress #new-todo': 'onInputKeypress',
      'blur #new-todo': 'onTodoBlur'
    },

    onTodoBlur: function(){
      var todoText = this.ui.input.val().trim();
      this.createTodo(todoText);
    },

    onInputKeypress: function(e) {
      var ENTER_KEY = 13;
      var todoText = this.ui.input.val().trim();

      if ( e.which === ENTER_KEY && todoText ) {
        this.createTodo(todoText);
        }
      },

    completeAdd: function() {
      this.ui.input.val('');
    },

    createTodo: function(todoText) {
      if (todoText.trim() === ""){ return; }

      this.collection.create({
        title: todoText
      });

      this.completeAdd();
    }
  });

  // Layout Footer View
  // ------------------

  Layout.Footer = Marionette.Layout.extend({
    template: '#template-footer',

    // UI Bindings create cached attributes that
    // point to jQuery selected objects.
    ui: {
      todoCount: '#todo-count .count',
      todoCountLabel: '#todo-count .label',
      clearCount: '#clear-completed .count',
      filters: "#filters a"
    },

    events: {
      "click #clear-completed": "onClearClick"
    },

    initialize: function() {
      this.bindTo( App.vent, "todoList: filter", this.updateFilterSelection, this );
      this.bindTo( this.collection, 'all', this.updateCount, this );
    },

    onRender: function() {
      this.updateCount();
    },

    updateCount: function() {
      var activeCount = this.collection.getActive().length,
      completedCount = this.collection.getCompleted().length;
      this.ui.todoCount.html(activeCount);

      this.ui.todoCountLabel.html(activeCount === 1 ? 'item' : 'items');
      this.ui.clearCount.html(completedCount === 0 ? '' : '(' + completedCount + ')');
    },

    updateFilterSelection: function( filter ) {
      this.ui.filters
        .removeClass('selected')
        .filter( '[href="#' + filter + '"]')
        .addClass( 'selected' );
    },

    onClearClick: function() {
      var completed = this.collection.getCompleted();
      completed.forEach(function destroy(todo) {
        todo.destroy();
      });
    }
  });

});

Next, we tackle application routing and workflow, such as controlling Layouts in the page which can be shown or hidden.

Recall how Backbone routes trigger methods within the Router as shown below in our original Workspace router from our first exercise:

  var Workspace = Backbone.Router.extend({
    routes: {
      '*filter': 'setFilter'
    },

    setFilter: function(param) {
      // Set the current filter to be used
      window.app.TodoFilter = param.trim() || '';

      // Trigger a collection filter event, causing hiding/unhiding
      // of Todo view items
      window.app.Todos.trigger('filter');
    }
  });

Marionette uses the concept of an AppRouter to simplify routing. This reduces the boilerplate for handling route events and allows routers to be configured to call methods on an object directly. We configure our AppRouter using appRoutes which replaces the '*filter': 'setFilter' route defined in our original router and invokes a method on our Controller.

The TodoList Controller, also found in this next code block, handles some of the remaining visibility logic originally found in AppView and TodoView, albeit using very readable Layouts.

TodoMVC.module('TodoList', function(TodoList, App, Backbone, Marionette, $, _) {

  // TodoList Router
  // ---------------
  //
  // Handle routes to show the active vs complete todo items

  TodoList.Router = Marionette.AppRouter.extend({
    appRoutes: {
      '*filter': 'filterItems'
    }
  });

  // TodoList Controller (Mediator)
  // ------------------------------
  //
  // Control the workflow and logic that exists at the application
  // level, above the implementation detail of views and models
  
  TodoList.Controller = function() {
    this.todoList = new App.Todos.TodoList();
  };

  _.extend(TodoList.Controller.prototype, {

    // Start the app by showing the appropriate views
    // and fetching the list of todo items, if there are any
    start: function() {
      this.showHeader(this.todoList);
      this.showFooter(this.todoList);
      this.showTodoList(this.todoList);
      
  App.bindTo(this.todoList, 'reset add remove', this.toggleFooter, this);
      this.todoList.fetch();
    },

    showHeader: function(todoList) {
      var header = new App.Layout.Header({
        collection: todoList
      });
      App.header.show(header);
    },

    showFooter: function(todoList) {
      var footer = new App.Layout.Footer({
        collection: todoList
      });
      App.footer.show(footer);
    },

    showTodoList: function(todoList) {
      App.main.show(new TodoList.Views.ListView({
        collection: todoList
      }));
    },
    
    toggleFooter: function() {
      App.footer.$el.toggle(this.todoList.length);
    },

    // Set the filter to show complete or all items
    filterItems: function(filter) {
      App.vent.trigger('todoList:filter', filter.trim() || '');
    }
  });

  // TodoList Initializer
  // --------------------
  //
  // Get the TodoList up and running by initializing the mediator
  // when the the application is started, pulling in all of the
  // existing Todo items and displaying them.
  
  TodoList.addInitializer(function() {

    var controller = new TodoList.Controller();
    new TodoList.Router({
      controller: controller
    });

    controller.start();

  });

});

In this particular app, note that Controllers don’t add a great deal to the overall workflow. In general, Marionette’s philosophy on routers is that they should be an afterthought in the implementation of applications. Quite often, we’ve seen developers abuse Backbone’s routing system by making it the sole controller of the entire application workflow and logic.

This inevitably leads to mashing every possible combination of code into the router methods - view creation, model loading, coordinating different parts of the app, etc. Developers such as Derick view this as a violation of the single-responsibility principle (SRP) and separation of concerns.

Backbone’s router and history exist to deal with a specific aspect of browsers - managing the forward and back buttons. Marionette’s philosophy is that it should be limited to that, with the code that gets executed by the navigation being somewhere else. This allows the application to be used with or without a router. We can call a controller’s “show” method from a button click, from an application event handler, or from a router, and we will end up with the same application state no matter how we called that method.

Derick has written extensively about his thoughts on this topic, which you can read more about on his blog:

CompositeView

Our next task is defining the actual views for individual Todo items and lists of items in our TodoMVC application. For this, we make use of Marionette’s CompositeViews. The idea behind a CompositeView is that it represents a visualization of a composite or hierarchical structure of leaves (or nodes) and branches.

Think of these views as being a hierarchy of parent-child models, and recursive by default. The same CompositeView type will be used to render each item in a collection that is handled by the composite view. For non-recursive hierarchies, we are able to override the item view by defining an itemView attribute.

For our Todo List Item View, we define it as an ItemView, then our Todo List View is a CompositeView where we override the itemView setting and tell it to use the Todo List Item View for each item in the collection.

TodoMVC.module('TodoList.Views', function(Views, App, Backbone, Marionette, $, _) {

  // Todo List Item View
  // -------------------
  //
  // Display an individual todo item, and respond to changes
  // that are made to the item, including marking completed.

  Views.ItemView = Marionette.ItemView.extend({
      tagName: 'li',
      template: '#template-todoItemView',

      ui: {
        edit: '.edit'
      },

      events: {
        'click .destroy': 'destroy',
        'dblclick label': 'onEditClick',
        'keypress .edit': 'onEditKeypress',
        'blur .edit'    : 'onEditBlur',
        'click .toggle' : 'toggle'
      },

      initialize: function() {
        this.bindTo(this.model, 'change', this.render, this);
      },

      onRender: function() {
        this.$el.removeClass( 'active completed' );
      
        if ( this.model.get( 'completed' )) {
          this.$el.addClass( 'completed' );
        } else { 
          this.$el.addClass( 'active' );
        }
      },

      destroy: function() {
        this.model.destroy();
      },

      toggle: function() {
        this.model.toggle().save();
      },

      onEditClick: function() {
        this.$el.addClass('editing');
        this.ui.edit.focus();
      },
      
      updateTodo : function() {
        var todoText = this.ui.edit.val();
        if (todoText === '') {
          return this.destroy();
        }
        this.setTodoText(todoText);
        this.completeEdit();
      },

      onEditBlur: function(e){
        this.updateTodo();
      },

      onEditKeypress: function(e) {
        var ENTER_KEY = 13;
        var todoText = this.ui.edit.val().trim();

        if ( e.which === ENTER_KEY && todoText ) {
          this.model.set('title', todoText).save();
          this.$el.removeClass('editing');
        }
      },
      
      setTodoText: function(todoText){
        if (todoText.trim() === ""){ return; }
        this.model.set('title', todoText).save();
      },

      completeEdit: function(){
        this.$el.removeClass('editing');
      }
  });

  // Item List View
  // --------------
  //
  // Controls the rendering of the list of items, including the
  // filtering of active vs completed items for display.

  Views.ListView = Backbone.Marionette.CompositeView.extend({
      template: '#template-todoListCompositeView',
      childView: Views.ItemView,
      childViewContainer: '#todo-list',

      ui: {
        toggle: '#toggle-all'
      },

      events: {
        'click #toggle-all': 'onToggleAllClick'
      },

      initialize: function() {
        this.bindTo(this.collection, 'all', this.update, this);
      },

      onRender: function() {
        this.update();
      },

      update: function() {
        function reduceCompleted(left, right) { 
          return left && right.get('completed'); 
        }
        
        var allCompleted = this.collection.reduce(reduceCompleted,true);
        this.ui.toggle.prop('checked', allCompleted);
        this.$el.parent().toggle(!!this.collection.length);
      },

      onToggleAllClick: function(e) {
        var isChecked = e.currentTarget.checked;
        this.collection.each(function(todo) {
          todo.save({'completed': isChecked});
        });
      }
  });

  // Application Event Handlers
  // --------------------------
  //
  // Handler for filtering the list of items by showing and
  // hiding through the use of various CSS classes
  
  App.vent.on('todoList:filter',function(filter) {
    filter = filter || 'all';
    $('#todoapp').attr('class', 'filter-' + filter);
  });

});

At the end of the last code block, you will also notice an event handler using vent. This is an event aggregator that allows us to handle filterItem triggers from our TodoList controller.

Finally, we define the model and collection for representing our Todo items. These are semantically not very different from the original versions we used in our first exercise and have been re-written to better fit in with Derick’s preferred style of coding.

TodoMVC.module('Todos', function(Todos, App, Backbone, Marionette, $, _) {

  // Local Variables
  // ---------------

  var localStorageKey = 'todos-backbone-marionettejs';

  // Todo Model
  // ----------
  
  Todos.Todo = Backbone.Model.extend({
    localStorage: new Backbone.LocalStorage(localStorageKey),

    defaults: {
      title: '',
      completed: false,
      created: 0
    },

    initialize: function() {
      if (this.isNew()) {
        this.set('created', Date.now());
      }
    },

    toggle: function() {
      return this.set('completed', !this.isCompleted());
    },

    isCompleted: function() { 
      return this.get('completed'); 
    }
  });

  // Todo Collection
  // ---------------

  Todos.TodoList = Backbone.Collection.extend({
    model: Todos.Todo,

    localStorage: new Backbone.LocalStorage(localStorageKey),

    getCompleted: function() {
      return this.filter(this._isCompleted);
    },

    getActive: function() {
      return this.reject(this._isCompleted);
    },

    comparator: function(todo) {
      return todo.get('created');
    },

    _isCompleted: function(todo) {
      return todo.isCompleted();
    }
  });

});

We finally kick-start everything off in our application index file, by calling start on our main application object:

      $(function() {
        // Start the TodoMVC app (defined in js/TodoMVC.js)
        TodoMVC.start();
      });

Is the Marionette implementation of the Todo app more maintainable?

Derick feels that maintainability largely comes down to modularity, separating responsibilities (Single Responsibility Principle and Separation of Concerns) by using patterns to keep concerns from being mixed together. It can, however, be difficult to simply extract things into separate modules for the sake of extraction, abstraction, or dividing the concept down into its simplest parts.

The Single Responsibility Principle (SRP) tells us quite the opposite - that we need to understand the context in which things change. What parts always change together, in this system? What parts can change independently? Without knowing this, we won’t know what pieces should be broken out into separate components and modules versus put together into the same module or object.

The way Derick organizes his apps into modules is by creating a breakdown of concepts at each level. A higher level module is a higher level of concern - an aggregation of responsibilities. Each responsibility is broken down into an expressive API set that is implemented by lower level modules (Dependency Inversion Principle). These are coordinated through a mediator - which he typically refers to as the Controller in a module.

The way Derick organizes his files also plays directly into maintainability and he has also written posts about the importance of keeping a sane application folder structure that I recommend reading:

Marionette And Flexibility

Marionette is a flexible framework, much like Backbone itself. It offers a wide variety of tools to help create and organize an application architecture on top of Backbone, but like Backbone itself, it doesn’t dictate that you have to use all of its pieces in order to use any of them.

The flexibility and versatility in Marionette is easiest to understand by examining three variations of TodoMVC implemented with it that have been created for comparison purposes:

The simple version: This version of TodoMVC shows some raw use of Marionette’s various view types, an application object, and the event aggregator. The objects that are created are added directly to the global namespace and are fairly straightforward. This is a great example of how Marionette can be used to augment existing code without having to re-write everything around Marionette.

The RequireJS version: Using Marionette with RequireJS helps to create a modularized application architecture - a tremendously important concept in scaling JavaScript applications. RequireJS provides a powerful set of tools that can be leveraged to great advantage, making Marionette even more flexible than it already is.

The Marionette module version: RequireJS isn’t the only way to create a modularized application architecture, though. For those that wish to build applications in modules and namespaces, Marionette provides a built-in module and namespacing structure. This example application takes the simple version of the application and re-writes it into a namespaced application architecture, with an application controller (mediator / workflow object) that brings all of the pieces together.

Marionette certainly provides its share of opinions on how a Backbone application should be architected. The combination of modules, view types, event aggregator, application objects, and more, can be used to create a very powerful and flexible architecture based on these opinions.

But as you can see, Marionette isn’t a completely rigid, “my way or the highway” framework. It provides many elements of an application foundation that can be mixed and matched with other architectural styles, such as AMD or namespacing, or provide simple augmentation to existing projects by reducing boilerplate code for rendering views.

This flexibility creates a much greater opportunity for Marionette to provide value to you and your projects, as it allows you to scale the use of Marionette with your application’s needs.

And So Much More

This is just the tip of the proverbial iceberg for Marionette, even for the ItemView and Region objects that we’ve explored. There is far more functionality, more features, and more flexibility and customizability that can be put to use in both of these objects. Then we have the other dozen or so components that Marionette provides, each with their own set of behaviors built in, customization and extension points, and more.

To learn more about Marionette’s components, the features they provide and how to use them, check out the Marionette documentation, links to the wiki, to the source code, the project core contributors, and much more at http://marionettejs.com.

Thorax

Part of Backbone’s appeal is that it provides structure but is generally un-opinionated, in particular when it comes to views. Thorax makes an opinionated decision to use Handlebars as its templating solution. Some of the patterns found in Marionette are found in Thorax as well. Marionette exposes most of these patterns as JavaScript APIs while in Thorax they are often exposed as template helpers. This chapter assumes the reader has knowledge of Handlebars.

Thorax was created by Ryan Eastridge and Kevin Decker to create Walmart’s mobile web application. This chapter is limited to Thorax’s templating features and patterns implemented in Thorax that you can utilize in your application regardless of whether you choose to adopt Thorax. To learn more about other features implemented in Thorax and to download boilerplate projects visit the Thorax website.

Hello World

In Backbone, when creating a new view, options passed are merged into any default options already present on a view and are exposed via this.options for later reference.

Thorax.View differs from Backbone.View in that there is no options object. All arguments passed to the constructor become properties of the view, which in turn become available to the template:

    var view = new Thorax.View({
        greeting: 'Hello',
        template: Handlebars.compile('{{greeting}} World!')
    });
    view.appendTo('body');

In most examples in this chapter a template property will be specified. In larger projects including the boilerplate projects provided on the Thorax website a name property would instead be used and a template of the same file name in your project would automatically be assigned to the view.

If a model is set on a view, its attributes also become available to the template:

Embedding child views

The view helper allows you to embed other views within a view. Child views can be specified as properties of the view:

    var parent = new Thorax.View({
        child: new Thorax.View(...),
        template: Handlebars.compile('{{view child}}')
    });

Or the name of a child view to initialize as well as any optional properties you wish to pass. In this case the child view must have previously been created with extend and given a name property:

    var ChildView = Thorax.View.extend({
        name: 'child',
        template: ...
    });
  
    var parent = new Thorax.View({
        template: Handlebars.compile('{{view "child" key="value"}}')
    });

The view helper may also be used as a block helper, in which case the block will be assigned as the template property of the child view:

    {{#view child}}
        child will have this block
        set as its template property
    {{/view}}

Handlebars is string based, while Backbone.View instances have a DOM el. Since we are mixing metaphors, the embedding of views works via a placeholder mechanism where the view helper in this case adds the view passed to the helper to a hash of children, then injects placeholder HTML into the template such as:

    <div data-view-placeholder-cid="view2"></div>

Then once the parent view is rendered, we walk the DOM in search of all the placeholders we created, replacing them with the child views’ els:

    this.$el.find('[data-view-placeholder-cid]').forEach(function(el) {
        var cid = el.getAttribute('data-view-placeholder-cid'),
            view = this.children[cid];
        view.render();
        $(el).replaceWith(view.el);
    }, this);

View helpers

One of the most useful constructs in Thorax is Handlebars.registerViewHelper (not to be confused with Handlebars.registerHelper). This method will register a new block helper that will create and embed a HelperView instance with its template set to the captured block. A HelperView instance is different from that of a regular child view in that its context will be that of the parent’s in the template. Like other child views it will have a parent property set to that of the declaring view. Many of the built-in helpers in Thorax including the collection helper are created in this manner.

A simple example would be an on helper that re-rendered the generated HelperView instance each time an event was triggered on the declaring / parent view:

An example use of this would be to have a counter that would increment each time a button was clicked. This example makes use of the button helper in Thorax which simply makes a button that triggers a view event when clicked:

    {{#on "incremented"}}{{i}}{{/on}}
    {{#button trigger="incremented"}}Add{{/button}}

    new Thorax.View({
        events: {
            incremented: function() {
                ++this.i;
            }
        },
        initialize: function() {
            this.i = 0;
        },
        template: ...
    });

collection helper

The collection helper creates and embeds a CollectionView instance, creating a view for each item in a collection, updating when items are added, removed, or changed in the collection. The simplest usage of the helper would look like:

    {{#collection kittens}}
      <li>{{name}}</li>
    {{/collection}}

    new Thorax.View({
      kittens: new Thorax.Collection(...),
      template: ...
    });

The block in this case will be assigned as the template for each item view created, and the context will be the attributes of the given model. This helper accepts options that can be arbitrary HTML attributes, a tag option to specify the type of tag containing the collection, or any of the following:

Options and blocks can be used in combination, in this case creating a KittenView class with a template set to the captured block for each kitten in the collection:

    {{#collection kittens item-view="KittenView" tag="ul"}}
      <li>{{name}}</li>
    {{else}}
      <li>No kittens!</li>
    {{/collection}}

Note that multiple collections can be used per view, and collections can be nested. This is useful when there are models that contain collections that contain models that contain…

    {{#collection kittens}}
      <h2>{{name}}</h2>
      <p>Kills:</p>
      {{#collection miceKilled tag="ul"}}
        <li>{{name}}</li>
      {{/collection}}
    {{/collection}}

Custom HTML data attributes

Thorax makes heavy use of custom HTML data attributes to operate. While some make sense only within the context of Thorax, several are quite useful to have in any Backbone project for writing other functions against, or for general debugging. In order to add some to your views in non-Thorax projects, override the setElement method in your base view class:

  MyApplication.View = Backbone.View.extend({
    setElement: function() {
        var response = Backbone.View.prototype.setElement.apply(this, arguments);
        this.name && this.$el.attr('data-view-name', this.name);
        this.$el.attr('data-view-cid', this.cid);
        this.collection && this.$el.attr('data-collection-cid', this.collection.cid);
        this.model && this.$el.attr('data-model-cid', this.model.cid);
        return response;
    }
  });

In addition to making your application more immediately comprehensible in the inspector, it’s now possible to extend jQuery / Zepto with functions to lookup the closest view, model or collection to a given element. In order to make it work you have to save references to each view created in your base view class by overriding the _configure method:

    MyApplication.View = Backbone.View.extend({
        _configure: function() {
            Backbone.View.prototype._configure.apply(this, arguments);
            Thorax._viewsIndexedByCid[this.cid] = this;
        },
        dispose: function() {
            Backbone.View.prototype.dispose.apply(this, arguments);
            delete Thorax._viewsIndexedByCid[this.cid];
        }
    });

    $.fn.view = function() {
        var el = $(this).closest('[data-view-cid]');
        return el && Thorax._viewsIndexedByCid[el.attr('data-view-cid')];
    };

    $.fn.model = function(view) {
        var $this = $(this),
            modelElement = $this.closest('[data-model-cid]'),
            modelCid = modelElement && modelElement.attr('[data-model-cid]');
        if (modelCid) {
            var view = $this.view();
            return view && view.model;
        }
        return false;
    };

Now instead of storing references to models randomly throughout your application to lookup when a given DOM event occurs you can use $(element).model(). In Thorax, this can particularly useful in conjunction with the collection helper which generates a view class (with a model property) for each model in the collection. An example template:

    {{#collection kittens tag="ul"}}
      <li>{{name}}</li>
    {{/collection}}

    Thorax.View.extend({
      events: {
        'click li': function(event) {
          var kitten = $(event.target).model();
          console.log('Clicked on ' + kitten.get('name'));
        }
      },
      kittens: new Thorax.Collection(...),
      template: ...
    });

A common anti-pattern in Backbone applications is to assign a className to a single view class. Consider using the data-view-name attribute as a CSS selector instead, saving CSS classes for things that will be used multiple times:

  [data-view-name="child"] {

  }

Thorax Resources

No Backbone related tutorial would be complete without a todo application. A Thorax implementation of TodoMVC is available, in addition to this far simpler example composed of this single Handlebars template:

  {{#collection todos tag="ul"}}
    <li{{#if done}} class="done"{{/if}}>
      <input type="checkbox" name="done"{{#if done}} checked="checked"{{/if}}>
      <span>{{item}}</span>
    </li>
  {{/collection}}
  <form>
    <input type="text">
    <input type="submit" value="Add">
  </form>

  var todosView = Thorax.View({
      todos: new Thorax.Collection(),
      events: {
          'change input[type="checkbox"]': function(event) {
              var target = $(event.target);
              target.model().set({done: !!target.attr('checked')});
          },
          'submit form': function(event) {
              event.preventDefault();
              var input = this.$('input[type="text"]');
              this.todos.add({item: input.val()});
              input.val('');
          }
      },
      template: '...'
  });
  todosView.appendTo('body');

Common Problems & Solutions

In this section, we will review a number of common problems developers often experience once they’ve started to work on relatively non-trivial projects using Backbone.js, as well as present potential solutions.

Perhaps the most frequent of these questions surround how to do more with Views. If you are interested in discovering how to work with nested Views, learn about view disposal and inheritance, this section will hopefully have you covered.

Working With Nested Views

What is the best approach for rendering and appending nested Views (or Subviews) in Backbone.js?

Since pages are composed of nested elements and Backbone views correspond to elements within the page, nesting views is an intuitive approach to managing a hierarchy of elements.

...
initialize : function () {
    //...
},

render : function () {

    this.$el.empty();

    this.innerView1 = new Subview({options});
    this.innerView2 = new Subview({options});

    this.$('.inner-view-container')
        .append(this.innerView1.el)
        .append(this.innerView2.el);
}

Beginners sometimes also try using setElement to solve this problem, however keep in mind that using this method is an easy way to shoot yourself in the foot. Avoid using this approach when the first solution is a viable option:


// Where we have previously defined a View, SubView
// in a parent View we could do:

...
initialize : function () {

    this.innerView1 = new Subview({options});
    this.innerView2 = new Subview({options});
},

render : function () {

    this.$el.html(this.template());

    this.innerView1.setElement('.some-element1').render();
    this.innerView2.setElement('.some-element2').render();
}

Here we are creating subviews in the parent view’s initialize() method and rendering the subviews in the parent’s render() method. The elements managed by the subviews exist in the parent’s template and the View.setElement() method is used to re-assign the element associated with each subview.

setElement() changes a view’s element, including re-delegating event handlers by removing them from the old element and binding them to the new element. Note that setElement() returns the view, allowing us to chain the call to render().

This works and has some positive qualities: you don’t need to worry about maintaining the order of your DOM elements when appending, views are initialized early, and the render() method doesn’t need to take on too many responsibilities at once.

Unfortunately, downsides are that you can’t set the tagName property of subviews and events need to be re-delegated. The first solution doesn’t suffer from this problem.


var OuterView = Backbone.View.extend({
    initialize: function() {
        this.inner = new InnerView();
    },

    render: function() {
        // Detach InnerView before reseting OuterView's $el
        this.inner.$el.detach(); 

        // or this.$el.empty() if you have no template
        // this.$el.html(template); 

        this.$el.append(this.inner.$el);
    }
});

var InnerView = Backbone.View.extend({
    render: function() {
        this.$el.html(template);
    }
});

Note that InnerView needs to call View.delegateEvents() to bind its event handlers to its new DOM since it is replacing the content of its element.

A better solution, which is more clean but has the potential to affect performance is:


var OuterView = Backbone.View.extend({
    initialize: function() {
        this.render();
    },

    render: function() {
        this.$el.html(template); // or this.$el.empty() if you have no template
        this.inner = new InnerView();
        this.$el.append(this.inner.$el);
    }
});

var InnerView = Backbone.View.extend({
    initialize: function() {
        this.render();
    },

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

If multiple views need to be nested at particular locations in a template, a hash of child views indexed by child view cids’ should be created. In the template, use a custom HTML attribute named data-view-cid to create placeholder elements for each view to embed. Once the template has been rendered and its output appended to the parent view’s $el, each placeholder can be queried for and replaced with the child view’s el.


var OuterView = Backbone.View.extend({
    initialize: function() {
        this.children = {};
        this.child = new Backbone.View();
        this.children[this.child.cid] = this.child;
    },

    render: function() {
        this.$el.html('<div data-view-cid="' + this.child.cid + '"></div>');
        _.each(this.children, function(view, cid) {
            this.$('[data-view-cid="' + cid + '"]').replaceWith(view.el);
        }, this);
    }
};

The use of cids (client ids) here is useful because it illustrates separating a model and its views by having views referenced by their instances and not their attributes. It’s quite common to ask for all views that satisfy an attribute on their models, but if you have recursive subviews or repeated views (a common occurrence), you can’t simply ask for views by attributes. That is, unless you specify additional attributes that separate duplicates. Using cids solves this problem as it allows for direct references to views.

The Backbone extensions Marionette and Thorax provide logic for nesting views, and rendering collections where each item has an associated view. Marionette provides APIs in JavaScript while Thorax provides APIs via Handlebars template helpers. We will examine both of these in an upcoming chapter.

Managing Models In Nested Views

In order to reach attributes on related models in a nested setup, models require some prior knowledge of each other, something which Backbone doesn’t implicitly handle out of the box.

One approach is to make sure each child model has a ‘parent’ attribute. This way you can traverse the nesting first up to the parent and then down to any siblings that you know of. So, assuming we have models modelA, modelB and modelC:


// When initializing modelA, I would suggest setting a link to the parent
// model when doing this, like this:

ModelA = Backbone.Model.extend({

    initialize: function(){
        this.modelB = new modelB();
        this.modelB.parent = this;
        this.modelC = new modelC();
        this.modelC.parent = this;
    }
}

This allows you to reach the parent model in any child model function through this.parent.

Now, we have already discussed a few options for how to construct nested Views using Backbone. For the sake of simplicity, let us imagine that we are creating a new child view ViewB from within the initialize() method of ViewA below. ViewB can reach out over the ViewA model and listen out for changes on any of its nested models.


// Define View A
ViewA = Backbone.View.extend({

    initialize: function(){
       // Create an instance of View B
       this.viewB = new ViewB();

       // Create a reference back to this (parent) view
       this.viewB.parentView = this;

       // Append ViewB to ViewA
       $(this.el).append(this.viewB.el);
    }
});

// Define View B
ViewB = Backbone.View.extend({

    //...,

    initialize: function(){
        // Listen for changes to the nested models in our parent ViewA
        this.listenTo(this.model.parent.modelB, "change", this.render);
        this.listenTo(this.model.parent.modelC, "change", this.render);

        // We can also call any method on our parent view if it is defined
        // $(this.parentView.el).shake();
    }

});

// Create an instance of ViewA with ModelA
// viewA will create its own instance of ViewB
// from inside the initialize() method
var viewA = new ViewA({ model: ModelA });

Rendering A Parent View From A Child View

In a scenario where you have a view containing another view, such as a photo gallery containing a larger view modal, you may find that you need to render or re-render the parent view from the child. The good news is that solving this problem is quite straight-forward.

If however inversion of control is desired, events may be used to provide an equally valid solution.

Say we wish to begin rendering when a particular event has occurred. For the sake of example, let us call this event ‘somethingHappened’. The parent view can bind notifications on the child view to know when the event has occurred. It can then render itself.

// Parent initialize
this.listenTo(this.childView, 'somethingHappened', this.render);

// Parent removal
this.stopListening(this.childView, 'somethingHappened');


// After the event has occurred
this.trigger('somethingHappened');

The child will trigger a “somethingHappened” event and the parent’s render function will be called.

Disposing View Hierarchies

Where your application is setup with multiple Parent and Child Views, it is also common to desire removing any DOM elements associated with such views as well as unbinding any event handlers tied to child elements when you no longer require them.

The solution in the last question should be enough to handle this use case, but if you require a more explicit example that handles children, we can see one below:

Backbone.View.prototype.close = function() {
    if (this.onClose) {
        this.onClose();
    }
    this.remove();
};

NewView = Backbone.View.extend({
    initialize: function() {
       this.childViews = [];
    },
    renderChildren: function(item) {
        var itemView = new NewChildView({ model: item });
        $(this.el).prepend(itemView.render());
        this.childViews.push(itemView);
    },
    onClose: function() {
      _(this.childViews).each(function(view) {
        view.close();
      });
    }
});

NewChildView = Backbone.View.extend({
    tagName: 'li',
    render: function() {
    }
});

Here, a close() method for views is implemented which disposes of a view when it is no longer needed or needs to be reset.

In most cases, the view removal should not affect any associated models. For example, if you are working on a blogging application and you remove a view with comments, perhaps another view in your app shows a selection of comments and resetting the collection would affect those views as well.

Note: You may also be interested in reading about the Marionette Composite Views in the Extensions part of the book.

Rendering View Hierarchies

Let us say you have a Collection, where each item in the Collection could itself be a Collection. You can render each item in the Collection, and indeed can render any items which themselves are Collections. The problem you might have is how to render HTML that reflects the hierarchical nature of the data structure.

The most straight-forward way to approach this problem is to use a framework like Derick Bailey’s Backbone.Marionette. In this framework is a type of view called a CompositeView.

The basic idea of a CompositeView is that it can render a model and a collection within the same view.

It can render a single model with a template. It can also take a collection from that model and for each model in that collection, render a view. By default it uses the same composite view type that you’ve defined to render each of the models in the collection. All you have to do is tell the view instance where the collection is, via the initialize method, and you’ll get a recursive hierarchy rendered.

Working With Nested Models Or Collections

Backbone doesn’t include support for nested models or collections out of the box, favoring the use of good patterns for modeling your structured data on the client side. How do I work around this?

As we’ve seen, it’s common to create collections representing groups of models using Backbone. It’s also however common to wish to nest collections within models, depending on the type of application you are working on.

Take for example a Building model that contains many Room models which could sit in a Rooms collection.

You could expose a this.rooms collection for each building, allowing you to lazy-load rooms once a building has been opened.

var Building = Backbone.Model.extend({

    initialize: function(){
        this.rooms = new Rooms;
        this.rooms.url = '/building/' + this.id + '/rooms';
        this.rooms.on("reset", this.updateCounts);
    },

    // ...

});

// Create a new building model
var townHall = new Building;

// once opened, lazy-load the rooms
townHall.rooms.fetch({reset: true});

There are also a number of Backbone plugins which can help with nested data structures, such as Backbone Relational. This plugin handles one-to-one, one-to-many and many-to-one relations between models for Backbone and has some excellent documentation.

Better Model Property Validation

As we learned earlier in the book, the validate method on a Model is called by set (when the validate option is set) and save. It is passed the model attributes updated with the values passed to these methods.

By default, when we define a custom validate method, Backbone passes all of a model’s attributes through this validation each time, regardless of which model attributes are being set.

This means that it can be a challenge to determine which specific fields are being set or validated without being concerned about the others that aren’t being set at the same time.

To illustrate this problem better, let us look at a typical registration form use case that:

We have a form where a user focuses and blurs first name, last name, and email HTML input boxes without entering any data. A “this field is required” message should be presented next to each form field.

Basic validation that could be written using the current Backbone validate method to work with this form could be implemented using something like:

validate: function(attrs) {

    if(!attrs.firstname) return 'first name is empty';
    if(!attrs.lastname) return 'last name is empty';
    if(!attrs.email) return 'email is empty';

}

Unfortunately, this method would trigger a firstname error each time any of the fields were blurred and only an error message next to the first name field would be presented.

One potential solution to the problem is to validate all fields and return all of the errors:

validate: function(attrs) {
  var errors = {};

  if (!attrs.firstname) errors.firstname = 'first name is empty';
  if (!attrs.lastname) errors.lastname = 'last name is empty';
  if (!attrs.email) errors.email = 'email is empty';

  if (!_.isEmpty(errors)) return errors;
}

This can be adapted into a solution that defines a Field model for each input in our form and works within the parameters of our use case as follows:


$(function($) {

  var User = Backbone.Model.extend({
    validate: function(attrs) {
      var errors = this.errors = {};

      if (!attrs.firstname) errors.firstname = 'firstname is required';
      if (!attrs.lastname) errors.lastname = 'lastname is required';
      if (!attrs.email) errors.email = 'email is required';

      if (!_.isEmpty(errors)) return errors;
    }
  });

  var Field = Backbone.View.extend({
    events: {blur: 'validate'},
    initialize: function() {
      this.name = this.$el.attr('name');
      this.$msg = $('[data-msg=' + this.name + ']');
    },
    validate: function() {
      this.model.set(this.name, this.$el.val(), {validate: true});
      this.$msg.text(this.model.errors[this.name] || '');
    }
  });

  var user = new User;

  $('input').each(function() {
    new Field({el: this, model: user});
  });

});

This works fine as the solution checks the validation for each attribute individually and sets the message for the correct blurred field. A demo of the above by @braddunbar is also available.

Unfortunately, this solution does perform validation on all fields every time, even though we are only displaying errors for the field that has changed. If we have multiple client-side validation methods, we may not want to have to call each validation method on every attribute every time, so this solution might not be ideal for everyone.

Backbone.validateAll

A potentially better alternative to the above is to use @gfranko’s Backbone.validateAll plugin, specifically created to validate specific Model properties (or form fields) without worrying about the validation of any other Model properties (or form fields).

Here is how we would setup a partial User Model and validate method using this plugin for our use case:


// Create a new User Model
var User = Backbone.Model.extend({

      // RegEx Patterns
      patterns: {

          specialCharacters: '[^a-zA-Z 0-9]+',

          digits: '[0-9]',

          email: '^[a-zA-Z0-9._-]+@[a-zA-Z0-9][a-zA-Z0-9.-]*[.]{1}[a-zA-Z]{2,6}$'
      },

    // Validators
      validators: {

          minLength: function(value, minLength) {
            return value.length >= minLength;

          },

          maxLength: function(value, maxLength) {
            return value.length <= maxLength;

          },

          isEmail: function(value) {
            return User.prototype.validators.pattern(value, User.prototype.patterns.email);

          },

          hasSpecialCharacter: function(value) {
            return User.prototype.validators.pattern(value, User.prototype.patterns.specialCharacters);

          },
         ...

    // We can determine which properties are getting validated by
    // checking to see if properties are equal to null

        validate: function(attrs) {

          var errors = this.errors = {};

          if(attrs.firstname != null) {
              if (!attrs.firstname) {
                  errors.firstname = 'firstname is required';
                  console.log('first name isEmpty validation called');
              }

              else if(!this.validators.minLength(attrs.firstname, 2))
                errors.firstname = 'firstname is too short';
              else if(!this.validators.maxLength(attrs.firstname, 15))
                errors.firstname = 'firstname is too large';
              else if(this.validators.hasSpecialCharacter(attrs.firstname)) errors.firstname = 'firstname cannot contain special characters';
          }

          if(attrs.lastname != null) {

              if (!attrs.lastname) {
                  errors.lastname = 'lastname is required';
                  console.log('last name isEmpty validation called');
              }

              else if(!this.validators.minLength(attrs.lastname, 2))
                errors.lastname = 'lastname is too short';
              else if(!this.validators.maxLength(attrs.lastname, 15))
                errors.lastname = 'lastname is too large';
              else if(this.validators.hasSpecialCharacter(attrs.lastname)) errors.lastname = 'lastname cannot contain special characters';

          }

This allows the logic inside of our validate methods to determine which form fields are currently being set/validated, and ignore the model properties that are not being set.

It’s fairly straight-forward to use as well. We can simply define a new Model instance and then set the data on our model using the validateAll option to use the behavior defined by the plugin:

var user = new User();
user.set({ 'firstname': 'Greg' }, {validate: true, validateAll: false});

That’s it. The Backbone.validateAll logic doesn’t override the default Backbone logic by default and so it’s perfectly capable of being used for scenarios where you might care more about field-validation performance as well as those where you don’t. Both solutions presented in this section should work fine however.

Backbone.Validation

As we’ve seen, the validate method Backbone offers is undefined by default and you need to override it with your own custom validation logic to get model validation in place. Often developers run into the issue of implementing this validation as nested ifs and elses, which can become unmaintainable when things get complicated.

Another helpful plugin for Backbone called Backbone.Validation attempts to solve this problem by offering an extensible way to declare validation rules on the model and overrides the validate method behind the scenes.

One of the useful methods this plugin includes is (pseudo) live validation via a preValidate method. This can be used to check on key-press if the input for a model is valid without changing the model itself. You can run any validators for a model attribute by calling the preValidate method, passing it the name of the attribute along with the value you would like validated.

// If the value of the attribute is invalid, a truthy error message is returned
// if not, it returns a falsy value

var errorMsg = user.preValidate('firstname', 'Greg');

Form-specific validation classes

That said, the most optimal solution to this problem may not be to stick validation in your model attributes. Instead, you could have a function specifically designed for validating a specific form and there are many good JavaScript form validation libraries out there that can help with this.

User.validate = function(formElement) {
  //...
};

For more information on validation plugins available for Backbone, see the Backbone wiki.

Avoiding Conflicts With Multiple Backbone Versions

In instances out of your control, you may have to work around having more than one version of Backbone in the same page. How do you work around this without causing conflicts?

Like most client-side projects, Backbone’s code is wrapped in an immediately-invoked function expression:

(function(){
  // Backbone.js
}).call(this);

Several things happen during this configuration stage. A Backbone namespace is created, and multiple versions of Backbone on the same page are supported through the noConflict mode:

var root = this;
var previousBackbone = root.Backbone;

Backbone.noConflict = function() {
  root.Backbone = previousBackbone;
  return this;
};

Multiple versions of Backbone can be used on the same page by calling noConflict like this:

var Backbone19 = Backbone.noConflict();
// Backbone19 refers to the most recently loaded version,
// and `window.Backbone` will be restored to the previously
// loaded version

Building Model And View Hierarchies

How does inheritance work with Backbone? How can I share code between similar models and views? How can I call methods that have been overridden?

For its inheritance, Backbone internally uses an inherits function inspired by goog.inherits, Google’s implementation from the Closure Library. It’s basically a function to correctly setup the prototype chain.

 var inherits = function(parent, protoProps, staticProps) {
      ...

The only major difference here is that Backbone’s API accepts two objects containing instance and static methods.

Following on from this, for inheritance purposes all of Backbone’s objects contain an extend method as follows:

Model.extend = Collection.extend = Router.extend = View.extend = extend;

Most development with Backbone is based around inheriting from these objects, and they’re designed to mimic a classical object-oriented implementation.

The above isn’t quite the same as ECMAScript 5’s Object.create, as it’s actually copying properties (methods and values) from one object to another. As this isn’t enough to support Backbone’s inheritance and class model, the following steps are performed:

extend can be used for a great deal more and developers who are fans of mixins will like that it can be used for this too. You can define functionality on any custom object, and then quite literally copy & paste all of the methods and attributes from that object to a Backbone one:

var MyMixin = {
  foo: 'bar',
  sayFoo: function(){alert(this.foo);}
};

var MyView = Backbone.View.extend({
 // ...
});

_.extend(MyView.prototype, MyMixin);

var myView = new MyView();
myView.sayFoo(); //=> 'bar'

We can take this further and also apply it to View inheritance. The following is an example of how to extend one View using another:

var Panel = Backbone.View.extend({
});

var PanelAdvanced = Panel.extend({
});

However, if you have an initialize() method in Panel, then it won’t be called if you also have an initialize() method in PanelAdvanced, so you would have to call Panel’s initialize method explicitly:

var Panel = Backbone.View.extend({
  initialize: function(options){
    console.log('Panel initialized');
    this.foo = 'bar';
  }
});

var PanelAdvanced = Panel.extend({
  initialize: function(options){
    Panel.prototype.initialize.call(this, options);
    console.log('PanelAdvanced initialized');
    console.log(this.foo); // Log: bar
  }
});

// We can also inherit PanelAdvanced if needed
var PanelAdvancedExtra = PanelAdvanced.extend({
  initialize: function(options){
    PanelAdvanced.prototype.initialize.call(this, options);
    console.log('PanelAdvancedExtra initialized');
  }
});

new Panel();
new PanelAdvanced();
new PanelAdvancedExtra();

This isn’t the most elegant of solutions because if you have a lot of Views that inherit from Panel, then you’ll have to remember to call Panel’s initialize from all of them.

It’s worth noting that if Panel doesn’t have an initialize method now but you choose to add it in the future, then you’ll need to go to all of the inherited classes in the future and make sure they call Panel’s initialize.

So here’s an alternative way to define Panel so that your inherited views don’t need to call Panel’s initialize method:

var Panel = function (options) {
  // put all of Panel's initialization code here
  console.log('Panel initialized');
  this.foo = 'bar';

  Backbone.View.apply(this, [options]);
};

_.extend(Panel.prototype, Backbone.View.prototype, {
  // put all of Panel's methods here. For example:
  sayHi: function () {
    console.log('hello from Panel');
  }
});

Panel.extend = Backbone.View.extend;

// other classes then inherit from Panel like this:
var PanelAdvanced = Panel.extend({
  initialize: function (options) {
    console.log('PanelAdvanced initialized');
    console.log(this.foo);
  }
});

var panelAdvanced = new PanelAdvanced(); //Logs: Panel initialized, PanelAdvanced initialized, bar
panelAdvanced.sayHi(); // Logs: hello from Panel

When used appropriately, Underscore’s extend method can save a great deal of time and effort writing redundant code.

Backbone-Super by Lukas Olson adds a *_super* method to Backbone.Model using John Resig’s Inheritance script. Rather than using Backbone.Model.prototype.set.call as per the Backbone.js documentation, _super can be called instead:

// This is how we normally do it
var OldFashionedNote = Backbone.Model.extend({
  set: function(attributes, options) {
    // Call parent's method
    Backbone.Model.prototype.set.call(this, attributes, options);
    // some custom code here
    // ...
  }
});

After including this plugin, you can do the same thing with the following syntax:

// This is how we can do it after using the Backbone-super plugin
var Note = Backbone.Model.extend({
  set: function(attributes, options) {
    // Call parent's method
    this._super(attributes, options);
    // some custom code here
    // ...
  }
});

Event Aggregators And Mediators

Using an Event Aggregator. It’s common for developers to think of Mediators when faced with this problem, so let’s explore what an Event Aggregator is, what the Mediator pattern is and how they differ.

Design patterns often differ only in semantics and intent. That is, the language used to describe the pattern is what sets it apart, more than an implementation of that specific pattern. It often comes down to squares vs rectangles vs polygons. You can create the same end result with all three, given the constraints of a square are still met – or you can use polygons to create an infinitely larger and more complex set of things.

When it comes to the Mediator and Event Aggregator patterns, there are some times where it may look like the patterns are interchangeable due to implementation similarities. However, the semantics and intent of these patterns are very different. And even if the implementations both use some of the same core constructs, I believe there is a distinct difference between them. I also believe they should not be interchanged or confused in communication because of the differences.

The core idea of the Event Aggregator, according to Martin Fowler, is to channel multiple event sources through a single object so that other objects needing to subscribe to the events don’t need to know about every event source.

The easiest event aggregator to show is that of Backbone.js – it’s built into the Backbone object directly.

var View1 = Backbone.View.extend({
  // ...

  events: {
    "click .foo": "doIt"
  },

  doIt: function(){
    // trigger an event through the event aggregator
    Backbone.trigger("some:event");
  }
});

var View2 = Backbone.View.extend({
  // ...

  initialize: function(){
    // subscribe to the event aggregator's event
    Backbone.on("some:event", this.doStuff, this);
  },

  doStuff: function(){
    // ...
  }
})

In this example, the first view is triggering an event when a DOM element is clicked. The event is triggered through Backbone’s built-in event aggregator – the Backbone object. Of course, it’s trivial to create your own event aggregator in Backbone, and there are some key things that we need to keep in mind when using an event aggregator, to keep our code simple.

Did you know that jQuery has a built-in event aggregator? They don’t call it this, but it’s in there and it’s scoped to DOM events. It also happens to look like Backbone’s event aggregator:

This code sets up an event handler function that waits for an unknown number of event sources to trigger a “click” event, and it allows any number of listeners to attach to the events of those event publishers. jQuery just happens to scope this event aggregator to the DOM.

A Mediator is an object that coordinates interactions (logic and behavior) between multiple objects. It makes decisions on when to call which objects, based on the actions (or inaction) of other objects and input.

Backbone doesn’t have the idea of a mediator built into it like a lot of MV* frameworks do. But that doesn’t mean you can’t write one using a single line of code:

var mediator = {};

Yes, of course this is just an object literal in JavaScript. Once again, we’re talking about semantics here. The purpose of the mediator is to control the workflow between objects and we really don’t need anything more than an object literal to do this.

var orgChart = {

  addNewEmployee: function(){

    // getEmployeeDetail provides a view that users interact with
    var employeeDetail = this.getEmployeeDetail();

    // when the employee detail is complete, the mediator (the 'orgchart' object)
    // decides what should happen next
    employeeDetail.on("complete", function(employee){

      // set up additional objects that have additional events, which are used
      // by the mediator to do additional things
      var managerSelector = this.selectManager(employee);
      managerSelector.on("save", function(employee){
        employee.save();
      });

    });
  },

  // ...
}

This example shows a very basic implementation of a mediator object with Backbone-based objects that can trigger and subscribe to events. I’ve often referred to this type of object as a “workflow” object in the past, but the truth is that it is a mediator. It is an object that handles the workflow between many other objects, aggregating the responsibility of that workflow knowledge into a single object. The result is workflow that is easier to understand and maintain.

There are, without a doubt, similarities between the event aggregator and mediator examples that I’ve shown here. The similarities boil down to two primary items: events and third-party objects. These differences are superficial at best, though. When we dig into the intent of the pattern and see that the implementations can be dramatically different, the nature of the patterns become more apparent.

Both the event aggregator and mediator use events, in the above examples. An event aggregator obviously deals with events – it’s in the name after all. The mediator only uses events because it makes life easy when dealing with Backbone, though. There is nothing that says a mediator must be built with events. You can build a mediator with callback methods, by handing the mediator reference to the child object, or by any of a number of other means.

The difference, then, is why these two patterns are both using events. The event aggregator, as a pattern, is designed to deal with events. The mediator, though, only uses them because it’s convenient.

Both the event aggregator and mediator, by design, use a third-party object to facilitate things. The event aggregator itself is a third-party to the event publisher and the event subscriber. It acts as a central hub for events to pass through. The mediator is also a third party to other objects, though. So where is the difference? Why don’t we call an event aggregator a mediator? The answer largely comes down to where the application logic and workflow is coded.

In the case of an event aggregator, the third party object is there only to facilitate the pass-through of events from an unknown number of sources to an unknown number of handlers. All workflow and business logic that needs to be kicked off is put directly into the object that triggers the events and the objects that handle the events.

In the case of the mediator, though, the business logic and workflow is aggregated into the mediator itself. The mediator decides when an object should have its methods called and attributes updated based on factors that the mediator knows about. It encapsulates the workflow and process, coordinating multiple objects to produce the desired system behaviour. The individual objects involved in this workflow each know how to perform their own task. But it’s the mediator that tells the objects when to perform the tasks by making decisions at a higher level than the individual objects.

An event aggregator facilitates a “fire and forget” model of communication. The object triggering the event doesn’t care if there are any subscribers. It just fires the event and moves on. A mediator, though, might use events to make decisions, but it is definitely not “fire and forget”. A mediator pays attention to a known set of input or activities so that it can facilitate and coordinate additional behavior with a known set of actors (objects).

Understanding the similarities and differences between an event aggregator and mediator is important for semantic reasons. It’s equally as important to understand when to use which pattern, though. The basic semantics and intent of the patterns does inform the question of when, but actual experience in using the patterns will help you understand the more subtle points and nuanced decisions that have to be made.

In general, an event aggregator is used when you either have too many objects to listen to directly, or you have objects that are entirely unrelated.

When two objects have a direct relationship already – say, a parent view and child view – then there might be little benefit in using an event aggregator. Have the child view trigger an event and the parent view can handle the event. This is most commonly seen in Backbone’s Collection and Model, where all Model events are bubbled up to and through its parent Collection. A Collection often uses model events to modify the state of itself or other models. Handling “selected” items in a collection is a good example of this.

jQuery’s on method as an event aggregator is a great example of too many objects to listen to. If you have 10, 20 or 200 DOM elements that can trigger a “click” event, it might be a bad idea to set up a listener on all of them individually. This could quickly deteriorate performance of the application and user experience. Instead, using jQuery’s on method allows us to aggregate all of the events and reduce the overhead of 10, 20, or 200 event handlers down to 1.

Indirect relationships are also a great time to use event aggregators. In Backbone applications, it is very common to have multiple view objects that need to communicate, but have no direct relationship. For example, a menu system might have a view that handles the menu item clicks. But we don’t want the menu to be directly tied to the content views that show all of the details and information when a menu item is clicked. Having the content and menu coupled together would make the code very difficult to maintain, in the long run. Instead, we can use an event aggregator to trigger “menu:click:foo” events, and have a “foo” object handle the click event to show its content on the screen.

A mediator is best applied when two or more objects have an indirect working relationship, and business logic or workflow needs to dictate the interactions and coordination of these objects.

A wizard interface is a good example of this, as shown with the “orgChart” example, above. There are multiple views that facilitate the entire workflow of the wizard. Rather than tightly coupling the view together by having them reference each other directly, we can decouple them and more explicitly model the workflow between them by introducing a mediator.

The mediator extracts the workflow from the implementation details and creates a more natural abstraction at a higher level, showing us at a much faster glance what that workflow is. We no longer have to dig into the details of each view in the workflow, to see what the workflow actually is.

The crux of the difference between an event aggregator and a mediator, and why these pattern names should not be interchanged with each other, is illustrated best by showing how they can be used together. The menu example for an event aggregator is the perfect place to introduce a mediator as well.

Clicking a menu item may trigger a series of changes throughout an application. Some of these changes will be independent of others, and using an event aggregator for this makes sense. Some of these changes may be internally related to each other, though, and may use a mediator to enact those changes. A mediator, then, could be set up to listen to the event aggregator. It could run its logic and process to facilitate and coordinate many objects that are related to each other, but unrelated to the original event source.

var MenuItem = Backbone.View.extend({

  events: {
    "click .thatThing": "clickedIt"
  },

  clickedIt: function(e){
    e.preventDefault();

    // assume this triggers "menu:click:foo"
    Backbone.trigger("menu:click:" + this.model.get("name"));
  }

});

// ... somewhere else in the app

var MyWorkflow = function(){
  Backbone.on("menu:click:foo", this.doStuff, this);
};

MyWorkflow.prototype.doStuff = function(){
  // instantiate multiple objects here.
  // set up event handlers for those objects.
  // coordinate all of the objects into a meaningful workflow.
};

In this example, when the MenuItem with the right model is clicked, the “menu:click:foo” event will be triggered. An instance of the “MyWorkflow” object, assuming one is already instantiated, will handle this specific event and will coordinate all of the objects that it knows about, to create the desired user experience and workflow.

An event aggregator and a mediator have been combined to create a much more meaningful experience in both the code and the application itself. We now have a clean separation between the menu and the workflow through an event aggregator and we are still keeping the workflow itself clean and maintainable through the use of a mediator.

There is one overriding point to make in all of this discussion: semantics. Communicating intent and semantics through the use of named patterns is only viable and only valid when all parties in a communication medium understand the language in the same way.

If I say “apple”, what am I talking about? Am I talking about a fruit? Or am I talking about a technology and consumer products company? As Sharon Cichelli says: “semantics will continue to be important, until we learn how to communicate in something other than language”.

Modular Development

Introduction

When we say an application is modular, we generally mean it’s composed of a set of highly decoupled, distinct pieces of functionality stored in modules. As you probably know, loose coupling facilitates easier maintainability of apps by removing dependencies where possible. When this is implemented efficiently, it’s quite easy to see how changes to one part of a system may affect another.

Unlike some more traditional programming languages, the current iteration of JavaScript (ECMA-262) doesn’t provide developers with the means to import such modules of code in a clean, organized manner.

Instead, developers are left to fall back on variations of the module or object literal patterns combined with script tags or a script loader. With many of these, module scripts are strung together in the DOM with namespaces being described by a single global object where it’s still possible to have name collisions. There’s also no clean way to handle dependency management without some manual effort or third party tools.

Whilst native solutions to these problems may be arriving via ES6 (the next version of the official JavaScript specification) modules proposal, the good news is that writing modular JavaScript has never been easier and you can start doing it today.

In this next part of the book, we’re going to look at how to use AMD modules and RequireJS to cleanly wrap units of code in your application into manageable modules. We’ll also cover an alternate approach called Lumbar which uses routes to determine when modules are loaded.

Organizing modules with RequireJS and AMD

RequireJS is a popular script loader written by James Burke - a developer who has been quite instrumental in helping shape the AMD module format, which we’ll discuss shortly. Amongst other things RequireJS helps you to load multiple script files, define modules with or without dependencies, and load in non-script dependencies such as text files.

Maintainability problems with multiple script files

You might be thinking that there is little benefit to RequireJS. After all, you can simply load in your JavaScript files through multiple <script> tags, which is very straightforward. However, doing it that way has a lot of drawbacks, including increasing the HTTP overhead.

Every time the browser loads in a file you’ve referenced in a <script> tag, it makes an HTTP request to load the file’s contents. It has to make a new HTTP request for each file you want to load, which causes problems.

What tools like RequireJS do is load scripts asynchronously. This means we have to adjust our code slightly, you can’t just swap out <script> elements for a small piece of RequireJS code, but the benefits are very worthwhile:

Need for better dependency management

Dependency management is a challenging subject, in particular when writing JavaScript in the browser. The closest thing we have to dependency management by default is simply making sure we order our <script> tags such that code that depends on code in another file is loaded after the file it depends on. This is not a good approach. As I’ve already discussed, loading multiple files in that way is bad for performance; needing them to be loaded in a certain order is very brittle.

Being able to load code on an as-needed basis is something RequireJS is very good at. Rather than load all our JavaScript code in during initial page load, a better approach is to dynamically load modules when that code is required. This avoids loading all the code when the user first hits your application, consequently speeding up initial load times.

Think about the GMail web client for a moment. When a user initially loads the page on their first visit, Google can simply hide widgets such as the chat module until the user has indicated (by clicking ‘expand’) that they wish to use it. Through dynamic dependency loading, Google could load up the chat module at that time, rather than forcing all users to load it when the page first initializes. This can improve performance and load times and can definitely prove useful when building larger applications. As the codebase for an application grows this becomes even more important.

The important thing to note here is that while it’s absolutely fine to develop applications without a script loader, there are significant benefits to utilizing tools like RequireJS in your application.

Asynchronous Module Definition (AMD)

Writing AMD modules with RequireJS

As discussed above, the overall goal for the AMD format is to provide a solution for modular JavaScript that developers can use today. The two key concepts you need to be aware of when using it with a script-loader are the define() method for defining modules and the require() method for loading dependencies. define() is used to define named or unnamed modules using the following signature:

define(
    module_id /*optional*/,
    [dependencies] /*optional*/,
    definition function /*function for instantiating the module or object*/
);

As you can tell by the inline comments, the module_id is an optional argument which is typically only required when non-AMD concatenation tools are being used (there may be some other edge cases where it’s useful too). When this argument is left out, we call the module ‘anonymous’. When working with anonymous modules, RequireJS will use a module’s file path as its module id, so the adage Don’t Repeat Yourself (DRY) should be applied by omitting the module id in the define() invocation.

The dependencies argument is an array representing all of the other modules that this module depends on and the third argument is a factory that can either be a function that should be executed to instantiate the module or an object.

A barebones module (compatible with RequireJS) could be defined using define() as follows:

// A module ID has been omitted here to make the module anonymous

define(['foo', 'bar'],
    // module definition function
    // dependencies (foo and bar) are mapped to function parameters
    function ( foo, bar ) {
        // return a value that defines the module export
        // (i.e. the functionality we want to expose for consumption)

        // create your module here
        var myModule = {
            doStuff:function(){
                console.log('Yay! Stuff');
            }
        }

        return myModule;
});

Note: RequireJS is intelligent enough to automatically infer the ‘.js’ extension to your script file names. As such, this extension is generally omitted when specifying dependencies.

Alternate syntax

There is also a sugared version of define() available that allows you to declare your dependencies as local variables using require(). This will feel familiar to anyone who’s used node, and can be easier to add or remove dependencies. Here is the previous snippet using the alternate syntax:

// A module ID has been omitted here to make the module anonymous

define(function(require){
        // module definition function
    // dependencies (foo and bar) are defined as local vars
    var foo = require('foo'),
        bar = require('bar');

    // return a value that defines the module export
    // (i.e. the functionality we want to expose for consumption)

    // create your module here
    var myModule = {
        doStuff:function(){
            console.log('Yay! Stuff');
        }
    }

    return myModule;
});

The require() method is typically used to load code in a top-level JavaScript file or within a module should you wish to dynamically fetch dependencies. An example of its usage is:

// Consider 'foo' and 'bar' are two external modules
// In this example, the 'exports' from the two modules loaded are passed as
// function arguments to the callback (foo and bar)
// so that they can similarly be accessed

require( ['foo', 'bar'], function ( foo, bar ) {
    // rest of your code here
    foo.doSomething();
});

Addy’s post on Writing Modular JS covers the AMD specification in much more detail. Defining and using modules will be covered in this book shortly when we look at more structured examples of using RequireJS.

Getting Started with RequireJS

Before using RequireJS and Backbone we will first set up a very basic RequireJS project to demonstrate how it works. The first thing to do is to Download RequireJS. When you load in the RequireJS script in your HTML file, you need to also tell it where your main JavaScript file is located. Typically this will be called something like “app.js”, and is the main entry point for your application. You do this by adding in a data-main attribute to the script tag:

<script data-main="app" src="lib/require.js"></script>

RequireJS Configuration

In the main JavaScript file that you load with the data-main attribute you can configure how RequireJS loads the rest of your application. This is done by calling require.config, and passing in an object:

require.config({
    // your configuration key/values here
    baseUrl: "app", // generally the same directory as the script used in a data-main attribute for the top level script
    paths: {}, // set up custom paths to libraries, or paths to RequireJS plugins
    shim: {}, // used for setting up all Shims (see below for more detail)
});

The main reason you’d want to configure RequireJS is to add shims, which we’ll cover next. To see other configuration options available to you, I recommend checking out the RequireJS documentation.

RequireJS Shims

Ideally, each library that we use with RequireJS will come with AMD support. That is, it uses the define method to define the library as a module. While Backbone and Underscore have added AMD support in recent years, we’re going to show an example of how to shim a library that does not using RequireJS.

To demonstrate this, first let’s shim Underscore, and then we’ll shim Backbone too. Shims are very simple to implement:

require.config({
    shim: {
        'lib/underscore': {
            exports: '_'
        }
    }
});

Note that when specifying paths for RequireJS you should omit the .js from the end of script names.

The important line here is exports: '_'. This line tells RequireJS that the script in 'lib/underscore.js' creates a global variable called _ instead of defining a module. Now when we list Underscore as a dependency RequireJS will know to give us the _ global variable as though it was the module defined by that script. We can set up a shim for Backbone too:

require.config({
    shim: {
        'lib/underscore': {
          exports: '_'
        },
        'lib/backbone': {
            deps: ['lib/underscore', 'jquery'],
            exports: 'Backbone'
        }
    }
});

Again, that configuration tells RequireJS to return the global Backbone variable that Backbone exports, but this time you’ll notice that Backbone’s dependencies are defined. This means whenever this:

require( 'lib/backbone', function( Backbone ) {...} );

Is run, it will first make sure the dependencies are met, and then pass the global Backbone object into the callback function. You don’t need to do this with every library, only the ones that don’t support AMD. For example, jQuery does support it, as of jQuery 1.7.

If you’d like to read more about general RequireJS usage, the RequireJS API docs are incredibly thorough and easy to read.

Custom Paths

Typing long paths to file names like lib/backbone can get tedious. RequireJS lets us set up custom paths in our configuration object. Here, whenever I refer to “underscore”, RequireJS will look for the file lib/underscore.js:

require.config({
    paths: {
        'underscore': 'lib/underscore'
    }
});

require.config({
    paths: {
        'underscore': 'lib/underscore'
    },
    shim: {
        'underscore': {
          exports: '_'
        }
    }
});

Just make sure that you refer to the custom path in your shim settings, too. Now you can do

require( ['underscore'], function(_) {
// code here
});

Require.js and Backbone Examples

Now that we’ve taken a look at how to define AMD modules, let’s review how to go about wrapping components like views and collections so that they can also be easily loaded as dependencies for any parts of your application that require them. At its simplest, a Backbone model may just require Backbone and Underscore.js. These are dependencies, so we can define those when defining the new modules. Note that the following examples presume you have configured RequireJS to shim Backbone and Underscore, as discussed previously.

Wrapping models, views, and other components with AMD

define(['underscore', 'backbone'], function(_, Backbone) {
  var myModel = Backbone.Model.extend({

    // Default attributes
    defaults: {
      content: 'hello world',
    },

    // A dummy initialization method
    initialize: function() {
    },

    clear: function() {
      this.destroy();
      this.view.remove();
    }

  });
  return myModel;
});

Note how we alias Underscore.js’s instance to _ and Backbone to just Backbone, making it very trivial to convert non-AMD code over to using this module format. For a view which might require other dependencies such as jQuery, this can similarly be done as follows:

define([
  'jquery',
  'underscore',
  'backbone',
  'collections/mycollection',
  'views/myview'
  ], function($, _, Backbone, myCollection, myView){

  var AppView = Backbone.View.extend({
  ...

Aliasing to the dollar-sign ($) once again makes it very easy to encapsulate any part of an application you wish using AMD.

Doing it this way makes it easy to organize your Backbone application as you like. It’s recommended to separate modules into folders. For example, individual folders for models, collections, views and so on. RequireJS doesn’t care about what folder structure you use; as long as you use the correct path when using require, it will happily pull in the file.

As part of this chapter I’ve made a very simple Backbone application with RequireJS that you can find on Github. It is a stock application for a manager of a shop. They can add new items and filter down the items based on price, but nothing more. Because it’s so simple it’s easier to focus purely on the RequireJS part of the implementation, rather than deal with complex JavaScript and Backbone logic too.

At the base of this application is the Item model, which describes a single item in the stock. Its implementation is very straight forward:

define( ["lib/backbone"], function ( Backbone ) {
  var Item = Backbone.Model.extend({
    defaults: {
      price: 35,
      photo: "http://www.placedog.com/100/100"
    }
  });
  return Item;
});

Converting an individual model, collection, view or similar into an AMD, RequireJS compliant one is typically very straight forward. Usually all that’s needed is the first line, calling define, and to make sure that once you’ve defined your object - in this case, the Item model, to return it.

define( ["lib/backbone"], function ( Backbone ) {
  var ItemView = Backbone.View.extend({
    tagName: "div",
    className: "item-wrap",
    template: _.template($("#itemTemplate").html()),

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

This view doesn’t actually depend on the model it will be used with, so again the only dependency is Backbone. Other than that it’s just a regular Backbone view. There’s nothing special going on here, other than returning the object and using define so RequireJS can pick it up. Now let’s make a collection to view a list of items. This time we will need to reference the Item model, so we add it as a dependency:

define(["lib/backbone", "models/item"], function(Backbone, Item) {
  var Cart = Backbone.Collection.extend({
    model: Item,
    initialize: function() {
      this.on("add", this.updateSet, this);
    },
    updateSet: function() {
      items = this.models;
    }
  });
  return Cart;
});

I’ve called this collection Cart, as it’s a group of items. As the Item model is the second dependency, I can bind the variable Item to it by declaring it as the second argument to the callback function. I can then refer to this within my collection implementation.

Finally, let’s have a look at the view for this collection. (This file is much bigger in the application, but I’ve taken some bits out so it’s easier to examine).

define(["lib/backbone", "views/itemview"], function(Backbone, ItemView) {
  var ItemCollectionView = Backbone.View.extend({
    el: '#yourcart',
    initialize: function(collection) {
      this.collection = collection;
      this.render();
      this.collection.on("reset", this.render, this);
    },
    render: function() {
      this.$el.html("");
      this.collection.each(function(item) {
        this.renderItem(item);
      }, this);
    },
    renderItem: function(item) {
      var itemView = new ItemView({model: item});
      this.$el.append(itemView.render().el);
    },
    // more methods here removed
  });
  return ItemCollectionView;
});

There really is nothing to it once you’ve got the general pattern. Define each “object” (a model, view, collection, router or otherwise) through RequireJS, and then specify them as dependencies to other objects that need them. Again, you can find this entire application on Github.

Keeping Your Templates External Using RequireJS And The Text Plugin

Moving your templates to external files is actually quite straight-forward, whether they are Underscore, Mustache, Handlebars or any other text-based template format. Let’s look at how we do that with RequireJS.

RequireJS has a special plugin called text.js which is used to load in text file dependencies. To use the text plugin, follow these steps:

require.config( {
    paths: {
        'text': 'libs/require/text',
    },
    baseUrl: 'app'
} );

require(['js/app', 'text!templates/mainView.html'],
    function( app, mainView ) {
        // the contents of the mainView file will be
        // loaded into mainView for usage.
    }
);

<script type="text/template" id="mainViewTemplate">
    <% _.each( person, function( person_item ){ %>
        <li><%= person_item.get('name') %></li>
    <% }); %>
</script>

var compiled_template = _.template( $('#mainViewTemplate').html() );

With RequireJS and the text plugin however, it’s as simple as saving the same template into an external text file (say, mainView.html) and doing the following:

require(['js/app', 'text!templates/mainView.html'],
    function(app, mainView){
        var compiled_template = _.template( mainView );
    }
);

That’s it! Now you can apply your template to a view in Backbone with something like:

collection.someview.$el.html( compiled_template( { results: collection.models } ) );

All templating solutions will have their own custom methods for handling template compilation, but if you understand the above, substituting Underscore’s micro-templating for any other solution should be fairly trivial.

Optimizing Backbone apps for production with the RequireJS Optimizer

Once you’re written your application, the next important step is to prepare it for deployment to production. The majority of non-trivial apps are likely to consist of several scripts and so optimizing, minimizing, and concatenating your scripts prior to pushing can reduce the number of scripts your users need to download.

A command-line optimization tool for RequireJS projects called r.js is available to help with this workflow. It offers a number of capabilities, including:

If you find yourself wanting to ship a single file with all dependencies included, r.js can help with this too. Whilst RequireJS does support lazy-loading, your application may be small enough that reducing HTTP requests to a single script file is feasible.

You’ll notice that I mentioned the word ‘specific’ in the first bullet point. The RequireJS optimizer only concatenates module scripts that have been specified as string literals in require and define calls (which you’ve probably used). As clarified by the optimizer docs this means that Backbone modules defined like this:

define(['jquery', 'backbone', 'underscore', 'collections/sample', 'views/test'],
    function($, Backbone, _, Sample, Test){
        //...
    });

var models = someCondition ? ['models/ab', 'models/ac'] : ['models/ba', 'models/bc'];
define(['jquery', 'backbone', 'underscore'].concat(models),
    function($, Backbone, _, firstModel, secondModel){
        //...
    });

will be ignored. This is by design as it ensures that dynamic dependency/module loading can still take place even after optimization.

Although the RequireJS optimizer works fine in both Node and Java environments, it’s strongly recommended to run it under Node as it executes significantly faster there.

To get started with r.js, grab it from the RequireJS download page or through NPM. To begin getting our project to build with r.js, we will need to create a new build profile.

Assuming the code for our application and external dependencies are in app/libs, our build.js build profile could simply be:

The paths above are relative to the baseUrl for our project and in our case it would make sense to make this the app folder. The out parameter informs r.js that we want to concatenate everything into a single file called main.js under the dist/ directory. Note that here we do need to add the .js extension to the filename. Earlier, we saw that when referencing modules by filenames, you don’t need to use the .js extension, however this is one case in which you do.

Alternatively, we can specify dir, which will ensure the contents of our app directory are copied into this directory. e.g.:

Additional options that can be specified such as modules and appDir are not compatible with out, however let’s briefly discuss them in case you do wish to use them.

modules is an array where we can explicitly specify the module names we would like to have optimized.

appDir - when specified, ourbaseUrl is relative to this parameter. If appDir is not defined, baseUrl is simply relative to the build.js file.

Back to our build profile, the main parameter is used to specify our main module - we are making use of include here as we’re going to take advantage of Almond - a stripped down loader for RequireJS modules which is useful should you not need to load modules in dynamically.

include is another array which specifies the modules we want to include in the build. By specifying “main”, r.js will trace over all modules main depends on and will include them. wrap wraps modules which RequireJS needs into a closure so that only what we export is included in the global environment.

The remainder of the build.js file would be a regular paths configuration object. We can compile our project into a target file by running:

The build profile is usually placed inside the ‘scripts’ or ‘js’ directory of your project. As per the docs, this file can however exist anywhere you wish, but you’ll need to edit the contents of your build profile accordingly.

That’s it. As long as you have UglifyJS/Closure tools setup correctly, r.js should be able to easily optimize your entire Backbone project in just a few key-strokes.

If you would like to learn more about build profiles, James Burke has a heavily commented sample file with all the possible options available.

Exercise 3: Your First Modular Backbone + RequireJS App

In this chapter, we’ll look at our first practical Backbone & RequireJS project - how to build a modular Todo application. Similar to exercise 1, the application will allow us to add new todos, edit new todos and clear todo items that have been marked as completed. For a more advanced practical, see the section on mobile Backbone development.

The complete code for the application can can be found in the practicals/modular-todo-app folder of this repo (thanks to Thomas Davis and Jérôme Gravel-Niquet). Alternatively grab a copy of my side-project TodoMVC which contains the sources to both AMD and non-AMD versions.

Overview

Writing a modular Backbone application can be a straight-forward process. There are however, some key conceptual differences to be aware of if opting to use AMD as your module format of choice:

Now that we’ve reviewed the basics, let’s take a look at developing our application. For reference, the structure of our app is as follows:

Markup

The markup for the application is relatively simple and consists of three primary parts: an input section for entering new todo items (create-todo), a list section to display existing items (which can also be edited in-place) (todo-list) and finally a section summarizing how many items are left to be completed (todo-stats).

The rest of the tutorial will now focus on the JavaScript side of the practical.

Configuration options

If you’ve read the earlier chapter on AMD, you may have noticed that explicitly needing to define each dependency a Backbone module (view, collection or other module) may require with it can get a little tedious. This can however be improved.

In order to simplify referencing common paths the modules in our application may use, we use a RequireJS configuration object, which is typically defined as a top-level script file. Configuration objects have a number of useful capabilities, the most useful being mode name-mapping. Name-maps are basically a key:value pair, where the key defines the alias you wish to use for a path and the value represents the true location of the path.

In the code-sample below, you can see some typical examples of common name-maps which include: backbone, underscore, jquery and depending on your choice, the RequireJS text plugin, which assists with loading text assets like templates.

require.config({
  baseUrl:'../',
  paths: {
    jquery: 'libs/jquery/jquery-min',
    underscore: 'libs/underscore/underscore-min',
    backbone: 'libs/backbone/backbone-optamd3-min',
    text: 'libs/require/text'
  }
});

require(['views/app'], function(AppView){
  var app_view = new AppView;
});

The require() at the end of our main.js file is simply there so we can load and instantiate the primary view for our application (views/app.js). You’ll commonly see both this and the configuration object included in most top-level script files for a project.

In addition to offering name-mapping, the configuration object can be used to define additional properties such as waitSeconds - the number of seconds to wait before script loading times out and locale, should you wish to load up i18n bundles for custom languages. The baseUrl is simply the path to use for module lookups.

For more information on configuration objects, please feel free to check out the excellent guide to them in the RequireJS docs.

Modularizing our models, views and collections

Before we dive into AMD-wrapped versions of our Backbone components, let’s review a sample of a non-AMD view. The following view listens for changes to its model (a Todo item) and re-renders if a user edits the value of the item.

var TodoView = Backbone.View.extend({

    //... is a list tag.
    tagName:  'li',

    // Cache the template function for a single item.
    template: _.template($('#item-template').html()),

    // The DOM events specific to an item.
    events: {
      'click .check'              : 'toggleDone',
      'dblclick div.todo-content' : 'edit',
      'click span.todo-destroy'   : 'clear',
      'keypress .todo-input'      : 'updateOnEnter'
    },

    // The TodoView listens for changes to its model, re-rendering. Since there's
    // a one-to-one correspondence between a **Todo** and a **TodoView** in this
    // app, we set a direct reference on the model for convenience.
    initialize: function() {
      this.listenTo(this.model, 'change', this.render);
      this.model.view = this;
    },
    ...

Note how for templating the common practice of referencing a script by an ID (or other selector) and obtaining its value is used. This of course requires that the template being accessed is implicitly defined in our markup. The following is the ‘embedded’ version of our template being referenced above:

Whilst there is nothing wrong with the template itself, once we begin to develop larger applications requiring multiple templates, including them all in our markup on page-load can quickly become both unmanageable and come with performance costs. We’ll look at solving this problem in a minute.

Let’s now take a look at the AMD-version of our view. As discussed earlier, the ‘module’ is wrapped using AMD’s define() which allows us to specify the dependencies our view requires. Using the mapped paths to ‘jquery’ etc. simplifies referencing common dependencies and instances of dependencies are themselves mapped to local variables that we can access (e.g. ‘jquery’ is mapped to $).

define([
  'jquery',
  'underscore',
  'backbone',
  'text!templates/todos.html'
  ], function($, _, Backbone, todosTemplate){
  var TodoView = Backbone.View.extend({

    //... is a list tag.
    tagName:  'li',

    // Cache the template function for a single item.
    template: _.template(todosTemplate),

    // The DOM events specific to an item.
    events: {
      'click .check'              : 'toggleDone',
      'dblclick div.todo-content' : 'edit',
      'click span.todo-destroy'   : 'clear',
      'keypress .todo-input'      : 'updateOnEnter'
    },

    // The TodoView listens for changes to its model, re-rendering. Since there's
    // a one-to-one correspondence between a **Todo** and a **TodoView** in this
    // app, we set a direct reference on the model for convenience.
    initialize: function() {
      this.listenTo(this.model, 'change', this.render);
      this.model.view = this;
    },

    // Re-render the contents of the todo item.
    render: function() {
      this.$el.html(this.template(this.model.attributes));
      this.setContent();
      return this;
    },

    // Use `jQuery.text` to set the contents of the todo item.
    setContent: function() {
      var content = this.model.get('content');
      this.$('.todo-content').text(content);
      this.input = this.$('.todo-input');
      this.input.on('blur', this.close);
      this.input.val(content);
    },
    ...

From a maintenance perspective, there’s nothing logically different in this version of our view, except for how we approach templating.

Using the RequireJS text plugin (the dependency marked text), we can actually store all of the contents for the template we looked at earlier in an external file (todos.html).

<div class="todo <%= done ? 'done' : '' %>">
    <div class="display">
      <input class="check" type="checkbox" <%= done ? 'checked="checked"' : '' %> />
      <div class="todo-content"></div>
      <span class="todo-destroy"></span>
    </div>
    <div class="edit">
      <input class="todo-input" type="text" value="" />
    </div>
</div>

There’s no longer a need to be concerned with IDs for the template as we can map its contents to a local variable (in this case todosTemplate). We then simply pass this to the Underscore.js templating function _.template() the same way we normally would have the value of our template script.

Next, let’s look at how to define models as dependencies which can be pulled into collections. Here’s an AMD-compatible model module, which has two default values: a content attribute for the content of a Todo item and a boolean done state, allowing us to trigger whether the item has been completed or not.

define(['underscore', 'backbone'], function(_, Backbone) {
  var TodoModel = Backbone.Model.extend({

    // Default attributes for the todo.
    defaults: {
      // Ensure that each todo created has `content`.
      content: 'empty todo...',
      done: false
    },

    initialize: function() {
    },

    // Toggle the `done` state of this todo item.
    toggle: function() {
      this.save({done: !this.get('done')});
    },

    // Remove this Todo from *localStorage* and delete its view.
    clear: function() {
      this.destroy();
      this.view.remove();
    }

  });
  return TodoModel;
});

As per other types of dependencies, we can easily map our model module to a local variable (in this case Todo) so it can be referenced as the model to use for our TodosCollection. This collection also supports a simple done() filter for narrowing down Todo items that have been completed and a remaining() filter for those that are still outstanding.

define([
  'underscore',
  'backbone',
  'libs/backbone/localstorage',
  'models/todo'
  ], function(_, Backbone, Store, Todo){

    var TodosCollection = Backbone.Collection.extend({

    // Reference to this collection's model.
    model: Todo,

    // Save all of the todo items under the `todos` namespace.
    localStorage: new Store('todos'),

    // Filter down the list of all todo items that are finished.
    done: function() {
      return this.filter(function(todo){ return todo.get('done'); });
    },

    // Filter down the list to only todo items that are still not finished.
    remaining: function() {
      return this.without.apply(this, this.done());
    },
    ...

In addition to allowing users to add new Todo items from views (which we then insert as models in a collection), we ideally also want to be able to display how many items have been completed and how many are remaining. We’ve already defined filters that can provide us this information in the above collection, so let’s use them in our main application view.

define([
  'jquery',
  'underscore',
  'backbone',
  'collections/todos',
  'views/todo',
  'text!templates/stats.html'
  ], function($, _, Backbone, Todos, TodoView, statsTemplate){

  var AppView = Backbone.View.extend({

    // Instead of generating a new element, bind to the existing skeleton of
    // the App already present in the HTML.
    el: $('#todoapp'),

    // Our template for the line of statistics at the bottom of the app.
    statsTemplate: _.template(statsTemplate),

    // ...events, initialize() etc. can be seen in the complete file

    // Re-rendering the App just means refreshing the statistics -- the rest
    // of the app doesn't change.
    render: function() {
      var done = Todos.done().length;
      this.$('#todo-stats').html(this.statsTemplate({
        total:      Todos.length,
        done:       Todos.done().length,
        remaining:  Todos.remaining().length
      }));
    },
    ...

Above, we map the second template for this project, templates/stats.html to statsTemplate which is used for rendering the overall done and remaining states. This works by simply passing our template the length of our overall Todos collection (Todos.length - the number of Todo items created so far) and similarly the length (counts) for items that have been completed (Todos.done().length) or are remaining (Todos.remaining().length).

The contents of our statsTemplate can be seen below. It’s nothing too complicated, but does use ternary conditions to evaluate whether we should state there’s “1 item” or “2 items” in a particular state.

The rest of the source for the Todo app mainly consists of code for handling user and application events, but that rounds up most of the core concepts for this practical.

To see how everything ties together, feel free to grab the source by cloning this repo or browse it online to learn more. I hope you find it helpful!

Note: While this first practical doesn’t use a build profile as outlined in the chapter on using the RequireJS optimizer, we will be using one in the section on building mobile Backbone applications.

Route-based module loading

This section will discuss a route based approach to module loading as implemented in Lumbar by Kevin Decker. Like RequireJS, Lumbar is also a modular build system, but the pattern it implements for loading routes may be used with any build system.

The specifics of the Lumbar build tool are not discussed in this book. To see a complete Lumbar based project with the loader and build system see Thorax which provides boilerplate projects for various environments including Lumbar.

JSON-based module configuration

RequireJS defines dependencies per file, while Lumbar defines a list of files for each module in a central JSON configuration file, outputting a single JavaScript file for each defined module. Lumbar requires that each module (except the base module) define a single router and a list of routes. An example file might look like:

Every JavaScript file defined in a module will have a module object in scope which contains the name and routes for the module. In js/routers/pages.js we could define a Backbone router for our pages module like so:

Module loader Router

A little used feature of Backbone.Router is its ability to create multiple routers that listen to the same set of routes. Lumbar uses this feature to create a router that listens to all routes in the application. When a route is matched, this master router checks to see if the needed module is loaded. If the module is already loaded, then the master router takes no action and the router defined by the module will handle the route. If the needed module has not yet been loaded, it will be loaded, then Backbone.history.loadUrl will be called. This reloads the route, causes the master router to take no further action and the router defined in the freshly loaded module to respond.

A sample implementation is provided below. The config object would need to contain the data from our sample configuration JSON file above, and the loader object would need to implement isLoaded and loadModule methods. Note that Lumbar provides all of these implementations, the examples are provided to create your own implementation.

Using NodeJS to handle pushState

window.history.pushState support (serving Backbone routes without a hash mark) requires that the server be aware of what URLs your Backbone application will handle, since the user should be able to enter the app at any of those routes (or hit reload after navigating to a pushState URL).

Another advantage to defining all routes in a single location is that the same JSON configuration file provided above could be loaded by the server, listening to each route. A sample implementation in NodeJS and Express:

This assumes that index.html will be serving out your Backbone application. The Backbone.History object can handle the rest of the routing logic as long as a root option is specified. A sample configuration for a simple application that lives at the root might look like:

An asset package alternative for dependency management

For more than trivial views, DocumentCloud have a home-built asset packager called Jammit, which has easy integration with Underscore.js templates and can also be used for dependency management.

Jammit expects your JavaScript templates (JST) to live alongside any ERB templates you’re using in the form of .jst files. It packages the templates into a global JST object which can be used to render templates into strings. Making Jammit aware of your templates is straight-forward - just add an entry for something like views/**/*.jst to your app package in assets.yml.

To provide Jammit dependencies you simply write out an assets.yml file that either listed the dependencies in order or used a combination of free capture directories (for example: /**/*.js, templates/*.js, and specific files).

A template using Jammit can derive it’s data from the collection object that is passed to it:

Paginating Backbone.js Requests & Collections

Introduction

Pagination is a ubiquitous problem we often find ourselves needing to solve on the web - perhaps most predominantly when working with service APIs and JavaScript-heavy clients which consume them. It’s also a problem that is often under-refined as most of us consider pagination relatively easy to get right. This isn’t however always the case as pagination tends to get more tricky than it initially seems.

Before we dive into solutions for paginating data for your Backbone applications, let’s define exactly what we consider pagination to be:

Pagination is a control system allowing users to browse through pages of search results (or any type of content) which is continued. Search results are the canonical example, but pagination today is found on news sites, blogs, and discussion boards, often in the form of Previous and Next links. More complete pagination systems offer granular control of the specific pages you can navigate to, giving the user more power to find what they are looking for.

It isn’t a problem limited to pages requiring some visual controls for pagination either - sites like Facebook, Pinterest, and Twitter have demonstrated that there are many contexts where infinite paging is also useful. Infinite paging is, of course, when we pre-fetch (or appear to pre-fetch) content from a subsequent page and add it directly to the user’s current page, making the experience feel “infinite”.

Pagination is very context-specific and depends on the content being displayed. In the Google search results, pagination is important as they want to offer you the most relevant set of results in the first 1-2 pages. After that, you might be a little more selective (or random) with the page you choose to navigate to. This differs from cases where you’ll want to cycle through consecutive pages for (e.g., for a news article or blog post).

Pagination is almost certainly content and context-specific, but as Faruk Ates has previously pointed out the principles of good pagination apply no matter what the content or context is. As with everything extensible when it comes to Backbone, you can write your own pagination to address many of these content-specific types of pagination problems. That said, you’ll probably spend quite a bit of time on this and sometimes you just want to use a tried and tested solution that just works.

On this topic, we’re going to go through a set of pagination components I (and a group of contributors) wrote for Backbone.js, which should hopefully come in useful if you’re working on applications which need to page Backbone Collections. They’re part of an extension called Backbone.Paginator.

Backbone.Paginator

Note: As of Backbone.Paginator 2.0, the API to the project has changed and includes updates which break backwards compatibility. The below section refers to Backbone.Paginator 1.0 which can still be downloaded here.

When working with data on the client-side, the three types of pagination we are most likely to run into are:

Requests to a service layer (API) - For example, query for results containing the term ‘Paul’ - if 5,000 results are available only display 20 results per page (leaving us with 250 possible result pages that can be navigated to).

This problem actually has quite a great deal more to it, such as maintaining persistence of other URL parameters (e.g. sort, query, order) which can change based on a user’s search configuration in a UI. One also has to think of a clean way of hooking views up to this pagination so you can easily navigate between pages (e.g., First, Last, Next, Previous, 1,2,3), manage the number of results displayed per page and so on.

Further client-side pagination of data returned - e.g. we’ve been returned a JSON response containing 100 results. Rather than displaying all 100 to the user, we only display 20 of these results within a navigable UI in the browser.

Similar to the request problem, client-pagination has its own challenges like navigation once again (Next, Previous, 1,2,3), sorting, order, switching the number of results to display per page and so on.

Infinite results - with services such as Facebook, the concept of numeric pagination is instead replaced with a ‘Load More’ or ‘View More’ button. Triggering this normally fetches the next ‘page’ of N results but rather than replacing the previous set of results loaded entirely, we simply append to them instead.

A request pager which simply appends results in a view rather than replacing on each new fetch is effectively an ‘infinite’ pager.

Backbone.Paginator is a set of opinionated components for paginating collections of data using Backbone.js. It aims to provide both solutions for assisting with pagination of requests to a server (e.g. an API) as well as pagination of single-loads of data, where we may wish to further paginate a collection of N results into M pages within a view.

Live Examples

If you would like to look at examples built using the components included in the project, links to official demos are included below and use the Netflix API so that you can see them working with an actual data source.

In this section we’re going to walk through using the requestPager. You would use this component when working with a service API which itself supports pagination. This component allows users to control the pagination settings for requests to this API (i.e. navigate to the next, previous, N pages) via the client-side.

The idea is that pagination, searching, and filtering of data can all be done from your Backbone application without the need for a page reload.

First, we define a new Paginated collection using Backbone.Paginator.requestPager() as follows:


var PaginatedCollection = Backbone.Paginator.requestPager.extend({

Within our collection, we then (as normal) specify the model to be used with this collection followed by the URL (or base URL) for the service providing our data (e.g. the Netflix API).

We need to set a base URL. The type of the request is GET by default, and the dataType is jsonp in order to enable cross-domain requests.

    paginator_core: {
      // the type of the request (GET by default)
      type: 'GET',

      // the type of reply (jsonp by default)
      dataType: 'jsonp',

      // the URL (or base URL) for the service
      // if you want to have a more dynamic URL, you can make this a function
      // that returns a string
      url: 'http://odata.netflix.com/Catalog/People(49446)/TitlesActedIn?'
    },

Gotchas!

If you use dataType NOT jsonp, please remove the callback custom parameter inside the server_api configuration.

We need to tell the library how many items per page we would like to see, etc…

    paginator_ui: {
      // the lowest page index your API allows to be accessed
      firstPage: 0,

      // which page should the paginator start from
      // (also, the actual page the paginator is on)
      currentPage: 0,

      // how many items per page should be shown
      perPage: 3,

      // a default number of total pages to query in case the API or
      // service you are using does not support providing the total
      // number of pages for us.
      // 10 as a default in case your service doesn't return the total
      totalPages: 10
    },

Only the base URL won’t be enough for most cases, so you can pass more parameters to the server. Note how you can use functions instead of hardcoded values, and you can also refer to the values you specified in paginator_ui.

    server_api: {
      // the query field in the request
      '$filter': '',

      // number of items to return per request/page
      '$top': function() { return this.perPage },

      // how many results the request should skip ahead to
      // customize as needed. For the Netflix API, skipping ahead based on
      // page * number of results per page was necessary.
      '$skip': function() { return this.currentPage * this.perPage },

      // field to sort by
      '$orderby': 'ReleaseYear',

      // what format would you like to request results in?
      '$format': 'json',

      // custom parameters
      '$inlinecount': 'allpages',
      '$callback': 'callback'
    },

Gotchas!

If you use $callback, please ensure that you did use the jsonp as a dataType inside your paginator_core configuration.

The last thing we need to do is configure our collection’s parse() method. We want to ensure we’re returning the correct part of our JSON response containing the data our collection will be populated with, which below is response.d.results (for the Netflix API).

You might also notice that we’re setting this.totalPages to the total page count returned by the API. This allows us to define the maximum number of (result) pages available for the current/last request so that we can clearly display this in the UI. It also allows us to influence whether clicking say, a ‘next’ button should proceed with a request or not.

        parse: function (response) {
            // Be sure to change this based on how your results
            // are structured (e.g. d.results is Netflix specific)
            var tags = response.d.results;
            //Normally this.totalPages would equal response.d.__count
            //but as this particular NetFlix request only returns a
            //total count of items for the search, we divide.
            this.totalPages = Math.ceil(response.d.__count / this.perPage);
            return tags;
        }
    });

});

For your convenience, the following methods are made available for use in your views to interact with the requestPager:

requestPager collection’s methods .goTo(), .nextPage() and .prevPage() are all extensions of the original Backbone Collection.fetch() methods. As so, they all can take the same option object as a parameter.

This option object can use success and error parameters to pass a function to be executed after server answer.

Collection.goTo(n, {
  success: function( collection, response ) {
    // called is server request success
  },
  error: function( collection, response ) {
    // called if server request fail
  }
});

To manage callback, you could also use the jqXHR returned by these methods to manage callback.

Collection
  .requestNextPage()
  .done(function( data, textStatus, jqXHR ) {
    // called is server request success
  })
  .fail(function( data, textStatus, jqXHR ) {
    // called if server request fail
  })
  .always(function( data, textStatus, jqXHR ) {
    // do something after server request is complete
  });
});

If you’d like to add the incoming models to the current collection, instead of replacing the collection’s contents, pass {update: true, remove: false} as options to these methods.

Collection.prevPage({ update: true, remove: false });

The clientPager is used to further paginate data that has already been returned by the service API. Say you’ve requested 100 results from the service and wish to split this into 5 pages of paginated results, each containing 20 results at a client level - the clientPager makes it trivial to do this.

Use the clientPager when you prefer to get results in a single “load” and thus avoid making additional network requests each time your users want to fetch the next “page” of items. As the results have all already been requested, it’s just a case of switching between the ranges of data actually presented to the user.

As with requestPager, let’s first create a new Paginated Backbone.Paginator.clientPager collection, with a model:

    var PaginatedCollection = Backbone.Paginator.clientPager.extend({

        model: model,

We need to set a base URL. The type of the request is GET by default, and the dataType is jsonp in order to enable cross-domain requests.

    paginator_core: {
      // the type of the request (GET by default)
      type: 'GET',

      // the type of reply (jsonp by default)
      dataType: 'jsonp',

      // the URL (or base URL) for the service
      url: 'http://odata.netflix.com/v2/Catalog/Titles?&'
    },

We need to tell the library how many items per page we would like to see, etc…

    paginator_ui: {
      // the lowest page index your API allows to be accessed
      firstPage: 1,

      // which page should the paginator start from
      // (also, the actual page the paginator is on)
      currentPage: 1,

      // how many items per page should be shown
      perPage: 3,

      // a default number of total pages to query in case the API or
      // service you are using does not support providing the total
      // number of pages for us.
      // 10 as a default in case your service doesn't return the total
      totalPages: 10,

      // The total number of pages to be shown as a pagination
      // list is calculated by (pagesInRange * 2) + 1.
      pagesInRange: 4
    },

    server_api: {
      // the query field in the request
      '$filter': 'substringof(\'america\',Name)',

      // number of items to return per request/page
      '$top': function() { return this.perPage },

      // how many results the request should skip ahead to
      // customize as needed. For the Netflix API, skipping ahead based on
      // page * number of results per page was necessary.
      '$skip': function() { return this.currentPage * this.perPage },

      // field to sort by
      '$orderby': 'ReleaseYear',

      // what format would you like to request results in?
      '$format': 'json',

      // custom parameters
      '$inlinecount': 'allpages',
      '$callback': 'callback'
    },

And finally we have our parse() method, which in this case isn’t concerned with the total number of result pages available on the server as we have our own total count of pages for the paginated data in the UI.

    parse: function (response) {
            var tags = response.d.results;
            return tags;
        }

    });

As mentioned, your views can hook into a number of convenience methods to navigate around UI-paginated data. For clientPager these include:

The goTo(), prevPage(), and nextPage() functions do not require the options param since they will be executed synchronously. However, when specified, the success callback will be invoked before the function returns. For example:

nextPage(); // this works just fine!
nextPage({success: function() { }}); // this will call the success function

The options param exists to preserve (some) interface unification between the requestPaginator and clientPaginator so that they may be used interchangeably in your Backbone.Views.

  this.collection.setFilter(
    {'Name': {cmp_method: 'levenshtein', max_distance: 7}}
    , "Amreican P" // Note the switched 'r' and 'e', and the 'P' from 'Pie'
  );

Also note that the Levenshtein plugin should be loaded and enabled using the useLevenshteinPlugin variable. Last but not less important: performing Levenshtein comparison returns the distance between two strings. It won’t let you search lengthy text. The distance between two strings means the number of characters that should be added, removed or moved to the left or to the right so the strings get equal. That means that comparing “Something” in “This is a test that could show something” will return 32, which is bigger than comparing “Something” and “ABCDEFG” (9). Use Levenshtein only for short texts (titles, names, etc).


  my_collection.setFieldFilter([
    {field: 'release_year', type: 'range', value: {min: '1999', max: '2003'}},
    {field: 'author', type: 'pattern', value: new RegExp('A*', 'igm')}
  ]);

  //Rules:
  //
  //var my_var = 'green';
  //
  //{field: 'color', type: 'equalTo', value: my_var}
  //{field: 'color', type: 'function', value: function(field_value){ return field_value == my_var; } }
  //{field: 'color', type: 'required'}
  //{field: 'number_of_colors', type: 'min', value: '2'}
  //{field: 'number_of_colors', type: 'max', value: '4'}
  //{field: 'number_of_colors', type: 'range', value: {min: '2', max: '4'} }
  //{field: 'color_name', type: 'minLength', value: '4'}
  //{field: 'color_name', type: 'maxLength', value: '6'}
  //{field: 'color_name', type: 'rangeLength', value: {min: '4', max: '6'}}
  //{field: 'color_name', type: 'oneOf', value: ['green', 'yellow']}
  //{field: 'color_name', type: 'pattern', value: new RegExp('gre*', 'ig')}
  //{field: 'color_name', type: 'containsAllOf', value: ['green', 'yellow', 'blue']}

You can use some variables in your View to represent the actual state of the paginator.

<!-- sample template for pagination UI -->
<script type="text/html" id="tmpServerPagination">

  <div class="row-fluid">

    <div class="pagination span8">
      <ul>
        <% _.each (pageSet, function (p) { %>
        <% if (currentPage == p) { %>
          <li class="active"><span><%= p %></span></li>
        <% } else { %>
          <li><a href="#" class="page"><%= p %></a></li>
        <% } %>
        <% }); %>
      </ul>
    </div>

    <div class="pagination span4">
      <ul>
        <% if (currentPage > firstPage) { %>
          <li><a href="#" class="serverprevious">Previous</a></li>
        <% }else{ %>
          <li><span>Previous</span></li>
        <% }%>
        <% if (currentPage < totalPages) { %>
          <li><a href="#" class="servernext">Next</a></li>
        <% } else { %>
          <li><span>Next</span></li>
        <% } %>
        <% if (firstPage != currentPage) { %>
          <li><a href="#" class="serverfirst">First</a></li>
        <% } else { %>
          <li><span>First</span></li>
        <% } %>
        <% if (totalPages != currentPage) { %>
          <li><a href="#" class="serverlast">Last</a></li>
        <% } else { %>
          <li><span>Last</span></li>
        <% } %>
      </ul>
    </div>

  </div>

  <span class="cell serverhowmany"> Show <a href="#"
    class="selected">18</a> | <a href="#" class="">9</a> | <a href="#" class="">12</a> per page
  </span>

  <span class="divider">/</span>

  <span class="cell first records">
    Page: <span class="label"><%= currentPage %></span> of <span class="label"><%= totalPages %></span> shown
  </span>

</script>

Plugins

A plugin for Backbone.Paginator that replaces diacritic characters (´, ˝, ̏, ˚,~ etc.) with characters that match them most closely. This is particularly useful for filtering.

To enable the plugin, set this.useDiacriticsPlugin to true, as can be seen in the example below:

Paginator.clientPager = Backbone.Collection.extend({

    // Default values used when sorting and/or filtering.
    initialize: function(){
      this.useDiacriticsPlugin = true; // use diacritics plugin if available
    ...

Bootstrapping

By default, both the clientPager and requestPager will make an initial request to the server in order to populate their internal paging data. In order to avoid this additional request, it may be beneficial to bootstrap your Backbone.Paginator instance from data that already exists in the dom.


// Extend the Backbone.Paginator.clientPager with your own configuration options
var MyClientPager =  Backbone.Paginator.clientPager.extend({paginator_ui: {}});
// Create an instance of your class and populate with the models of your entire collection
var aClientPager = new MyClientPager([{id: 1, title: 'foo'}, {id: 2, title: 'bar'}]);
// Invoke the bootstrap function
aClientPager.bootstrap();

Note: If you intend to bootstrap a clientPager, there is no need to specify a ‘paginator_core’ object in your configuration (since you should have already populated the clientPager with the entirety of its necessary data)


// Extend the Backbone.Paginator.requestPager with your own configuration options
var MyRequestPager =  Backbone.Paginator.requestPager.extend({paginator_ui: {}});
// Create an instance of your class with the first page of data
var aRequestPager = new MyRequestPager([{id: 1, title: 'foo'}, {id: 2, title: 'bar'}]);
// Invoke the bootstrap function and configure requestPager with 'totalRecords'
aRequestPager.bootstrap({totalRecords: 50});

Note: Both the clientPager and requestPager bootstrap function will accept an options param that will be extended by your Backbone.Paginator instance. However the ‘totalRecords’ property will be set implicitly by the clientPager.

Styling

You’re of course free to customize the overall look and feel of the paginators as much as you wish. By default, all sample applications make use of Twitter Bootstrap for styling links, buttons and drop-downs.

Classes are also available for styling more granular elements like page counts within breadcrumb > pages e.g. .page, .page selected:

There’s a tremendous amount of flexibility available for styling and as you’re in control of templating too, your paginators can be made to look as visually simple or complex as needed.

Conclusions

Although it’s certainly possible to write your own custom pagination classes to work with Backbone Collections, Backbone.Paginator tries to take care of much of this for you.

It’s highly configurable, avoiding the need to write your own paging when working with Collections of data sourced from your database or API. Use the plugin to help tame large lists of data into more manageable, easily navigatable, paginated lists.

Additionally, if you have any questions about Backbone.Paginator (or would like to help improve it), feel free to post to the project issues list.

Backbone Boilerplate And Grunt-BBB

Boilerplates provide us a starting point for working on projects. They’re a base for building upon using the minimum required code to get something functional put together. When you’re working on a new Backbone application, a new Model typically only takes a few lines of code to get working.

That alone probably isn’t enough however, as you’ll need a Collection to group those models, a View to render them and perhaps a router if you’re looking to making specific views of your Collection data bookmarkable. If you’re starting on a completely fresh project, you may also need a build process in place to produce an optimized version of your app that can be pushed to production.

This is where boilerplate solutions are useful. Rather than having to manually write out the initial code for each piece of your Backbone app, a boilerplate could do this for you, also ideally taking care of the build process.

Backbone Boilerplate (or just BB) provides just this. It is an excellent set of best practices and utilities for building Backbone.js applications, created by Backbone contributor Tim Branyen. He took the the gotchas, pitfalls and common tasks he ran into while heavily using Backbone to build apps and crafted BB as a result of this experience.

Grunt-BBB or Boilerplate Build Buddy is the companion tool to BB, which offers scaffolding, file watcher and build capabilities. Used together with BB it provides an excellent base for quickly starting new Backbone applications.

Getting Started

Backbone Boilerplate and Grunt-BBB

To get started we’re going to install Grunt-BBB, which will include Backbone Boilerplate and any third-party dependencies it might need such as the Grunt build tool.

Creating a new project

Let’s create a new directory for our project and run bbb init to kick things off. A number of project sub-directories and files will be stubbed out for us, as shown below:

index.html

This is a fairly standard stripped-down HTML5 Boilerplate foundation with the notable exception of including RequireJS at the bottom of the page.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">

  <title>Backbone Boilerplate</title>

  <!-- Application styles. -->
  <!--(if target dummy)><!-->
  <link rel="stylesheet" href="/app/styles/index.css">
  <!--<!(endif)-->
</head>
<body>
  <!-- Application container. -->
  <main role="main" id="main"></main>

  <!-- Application source. -->
  <!--(if target dummy)><!-->
  <script data-main="/app/config" src="/vendor/js/libs/require.js"></script>
  <!--<!(endif)-->

</body>
</html>

RequireJS - the AMD (Asynchronous Module Definition) module and script loader - will assist us with managing the modules in our application. We’ve already covered it in the last chapter, but let’s recap what this particular block does in terms of the Boilerplate:

The data-main attribute is used to inform RequireJS to load app/config.js (a configuration object) after it has finished loading itself. You’ll notice that we’ve omitted the .js extension here as RequireJS can automatically add this for us, however it will respect your paths if we do choose to include it regardless. Let’s now look at the config file being referenced.

config.js

A RequireJS configuration object allows us to specify aliases and paths for dependencies we’re likely to reference often (e.g., jQuery), bootstrap properties like our base application URL, and shim libraries that don’t support AMD natively.

// Set the require.js configuration for your application.
require.config({

  // Initialize the application with the main application file and the JamJS
  // generated configuration file.
  deps: ["../vendor/jam/require.config", "main"],

  paths: {
    // Put paths here.
  },

  shim: {
    // Put shims here.
  }

});

The first option defined in the above config is deps: ["../vendor/jam/require.config", "main"]. This informs RequireJS to load up additional RequireJS configuration as well a a main.js file, which is considered the entry point for our application.

You may notice that we haven’t specified any other path information for main. Require will infer the default baseUrl using the path from our data-main attribute in index.html. In other words, our baseUrl is app/ and any scripts we require will be loaded relative to this location. We could use the baseUrl option to override this default if we wanted to use a different location.

The next block is paths, which we can use to specify paths relative to the baseUrl as well as the paths/aliases to dependencies we’re likely to regularly reference.

After this comes shim, an important part of our RequireJS configuration which allows us to load libraries which are not AMD compliant. The basic idea here is that rather than requiring all libraries to implement support for AMD, the shim takes care of the hard work for us.

Going back to deps, the contents of our require.config file can be seen below.

var jam = {
    "packages": [
        {
            "name": "backbone",
            "location": "../vendor/jam/backbone",
            "main": "backbone.js"
        },
        {
            "name": "backbone.layoutmanager",
            "location": "../vendor/jam/backbone.layoutmanager",
            "main": "backbone.layoutmanager.js"
        },
        {
            "name": "jquery",
            "location": "../vendor/jam/jquery",
            "main": "jquery.js"
        },
        {
            "name": "lodash",
            "location": "../vendor/jam/lodash",
            "main": "./lodash.js"
        }
    ],
    "version": "0.2.11",
    "shim": {
        "backbone": {
            "deps": [
                "jquery",
                "lodash"
            ],
            "exports": "Backbone"
        },
        "backbone.layoutmanager": {
            "deps": [
                "jquery",
                "backbone",
                "lodash"
            ],
            "exports": "Backbone.LayoutManager"
        }
    }
};

The jam object is to support configuration of Jam - a package manager for the front-end which helps install, upgrade and configure the dependencies used by your project. It is currently the package manager of choice for Backbone Boilerplate.

Under the packages array, a number of dependencies are specified for inclusion, such as Backbone, the Backbone.LayoutManager plugin, jQuery and Lo-dash.

For those curious about Backbone.LayoutManager, it’s a Backbone plugin that provides a foundation for assembling layouts and views within Backbone.

Additional packages you install using Jam will have a corresponding entry added to packages.

main.js

Next, we have main.js, which defines the entry point for our application. We use a global require() method to load an array containing any other scripts needed, such as our application app.js and our main router router.js. Note that most of the time, we will only use require() for bootstrapping an application and a similar method called define() for all other purposes.

The function defined after our array of dependencies is a callback which doesn’t fire until these scripts have loaded. Notice how we’re able to locally alias references to “app” and “router” as app and Router for convenience.

require([
  // Application.
  "app",

  // Main Router.
  "router"
],

function(app, Router) {

  // Define your master router on the application namespace and trigger all
  // navigation from this instance.
  app.router = new Router();

  // Trigger the initial route and enable HTML5 History API support, set the
  // root folder to '/' by default.  Change in app.js.
  Backbone.history.start({ pushState: true, root: app.root });

  // All navigation that is relative should be passed through the navigate
  // method, to be processed by the router. If the link has a `data-bypass`
  // attribute, bypass the delegation completely.
  $(document).on("click", "a[href]:not([data-bypass])", function(evt) {
    // Get the absolute anchor href.
    var href = { prop: $(this).prop("href"), attr: $(this).attr("href") };
    // Get the absolute root.
    var root = location.protocol + "//" + location.host + app.root;

    // Ensure the root is part of the anchor href, meaning it's relative.
    if (href.prop.slice(0, root.length) === root) {
      // Stop the default event to ensure the link will not cause a page
      // refresh.
      evt.preventDefault();

      // `Backbone.history.navigate` is sufficient for all Routers and will
      // trigger the correct events. The Router's internal `navigate` method
      // calls this anyways.  The fragment is sliced from the root.
      Backbone.history.navigate(href.attr, true);
    }
  });

});

Inline, Backbone Boilerplate includes boilerplate code for initializing our router with HTML5 History API support and handling other navigation scenarios, so we don’t have to.

app.js

Let us now look at our app.js module. Typically, in non-Backbone Boilerplate applications, an app.js file may contain the core logic or module references needed to kick start an app.

In this case however, this file is used to define templating and layout configuration options as well as utilities for consuming layouts. To a beginner, this might look like a lot of code to comprehend, but the good news is that for basic apps, you’re unlikely to need to heavily modify this. Instead, you’ll be more concerned with modules for your app, which we’ll look at next.

define([
  "backbone.layoutmanager"
], function() {

  // Provide a global location to place configuration settings and module
  // creation.
  var app = {
    // The root path to run the application.
    root: "/"
  };

  // Localize or create a new JavaScript Template object.
  var JST = window.JST = window.JST || {};

  // Configure LayoutManager with Backbone Boilerplate defaults.
  Backbone.LayoutManager.configure({
    // Allow LayoutManager to augment Backbone.View.prototype.
    manage: true,

    prefix: "app/templates/",

    fetch: function(path) {
      // Concatenate the file extension.
      path = path + ".html";

      // If cached, use the compiled template.
      if (JST[path]) {
        return JST[path];
      }

      // Put fetch into `async-mode`.
      var done = this.async();

      // Seek out the template asynchronously.
      $.get(app.root + path, function(contents) {
        done(JST[path] = _.template(contents));
      });
    }
  });

  // Mix Backbone.Events, modules, and layout management into the app object.
  return _.extend(app, {
    // Create a custom object with a nested Views object.
    module: function(additionalProps) {
      return _.extend({ Views: {} }, additionalProps);
    },

    // Helper for using layouts.
    useLayout: function(name, options) {
      // Enable variable arity by allowing the first argument to be the options
      // object and omitting the name argument.
      if (_.isObject(name)) {
        options = name;
      }

      // Ensure options is an object.
      options = options || {};

      // If a name property was specified use that as the template.
      if (_.isString(name)) {
        options.template = name;
      }

      // Create a new Layout with options.
      var layout = new Backbone.Layout(_.extend({
        el: "#main"
      }, options));

      // Cache the reference.
      return this.layout = layout;
    }
  }, Backbone.Events);

});

Note: JST stands for JavaScript templates and generally refers to templates which have been (or will be) precompiled as part of a build step. When running bbb release or bbb debug, Underscore/Lo-dash templates will be precompiled to avoid the need to compile them at runtime within the browser.

Creating Backbone Boilerplate Modules

Not to be confused with simply being just an AMD module, a Backbone Boilerplate module is a script composed of a:

We can easily create a new Boilerplate module using grunt-bbb once again using init:

// Foo module
define([
  // Application.
  "app"
],

// Map dependencies from above array.
function(app) {

  // Create a new module.
  var Foo = app.module();

  // Default Model.
  Foo.Model = Backbone.Model.extend({

  });

  // Default Collection.
  Foo.Collection = Backbone.Collection.extend({
    model: Foo.Model
  });

  // Default View.
  Foo.Views.Layout = Backbone.Layout.extend({
    template: "foo"
  });

  // Return the module for AMD compliance.
  return Foo;

});

Notice how boilerplate code for a model, collection and view have been scaffolded out for us.

Optionally, we may also wish to include references to plugins such as the Backbone LocalStorage or Offline adapters. One clean way of including a plugin in the above boilerplate could be:

// Foo module
define([
  // Application.
  "app",
  // Plugins
  'plugins/backbone-localstorage'
],

// Map dependencies from above array.
function(app, Store) {

  // Create a new module.
  var Foo = app.module();

  // Default Model.
  Foo.Model = Backbone.Model.extend({
    // Save all of the items under the `"foo"` namespace.
    localStorage: new Store('foo-backbone'),
  });

  // Default Collection.
  Foo.Collection = Backbone.Collection.extend({
    model: Foo.Model
  });

  // Default View.
  Foo.Views.Layout = Backbone.Layout.extend({
    template: "foo"
  });

  // Return the module for AMD compliance.
  return Foo;

});

router.js

Finally, let’s look at our application router which is used for handling navigation. The default router Backbone Boilerplate generates for us includes sane defaults out of the box and can be easily extended.

define([
  // Application.
  "app"
],

function(app) {

  // Defining the application router, you can attach sub routers here.
  var Router = Backbone.Router.extend({
    routes: {
      "": "index"
    },

    index: function() {

    }
  });

  return Router;

});

If however we would like to execute some module-specific logic, when the page loads (i.e. when a user hits the default route), we can pull in a module as a dependency and optionally use the Backbone LayoutManager to attach Views to our layout as follows:

define([
  // Application.
  'app',

  // Modules
  'modules/foo'
],

function(app, Foo) {

  // Defining the application router, you can attach sub routers here.
  var Router = Backbone.Router.extend({
    routes: {
      '': 'index'
    },

    index: function() {
            // Create a new Collection
            var collection = new Foo.Collection();

            // Use and configure a 'main' layout
            app.useLayout('main').setViews({
                    // Attach the bar View into the content View
                    '.bar': new Foo.Views.Bar({
                            collection: collection
                    })
             }).render();
    }
  });

  // Fetch data (e.g., from localStorage)
  collection.fetch();

  return Router;

});

Other Useful Tools & Projects

When working with Backbone, you usually need to write a number of different classes and files for your application. Scaffolding tools such as Grunt-BBB can help automate this process by generating basic boilerplates for the files you need for you.

Yeoman

If you appreciated Grunt-BBB but would like to explore a tool for assisting with your broader development workflow, I’m happy to recommend a tool I’ve been helping with called Yeoman.

Yeoman is a workflow comprised of a collection of tools and best practices for helping you develop more efficiently. It’s comprised of yo (a scaffolding tool), Grunt(a build tool) and Bower (a client-side package manager).

Where Grunt-BBB focuses on offering an opionated start for Backbone projects, Yeoman allows you to scaffold apps using Backbone (or other libraries and frameworks), get Backbone plugins directly from the command-line and compile your CoffeeScript, Sass or other abstractions without additional effort.

You may also be interested in Brunch, a similar project which uses skeleton boilerplates to generate new applications.

Backbone DevTools

When building an application with Backbone, there’s some additional tooling available for your day-to-day debugging workflow.

Backbone DevTools was created to help with this and is a Chrome DevTools extension allowing you to inspect events, syncs, View-DOM bindings and what objects have been instantiated.

A useful View hierarchy is displayed in the Elements panel. Also, when you inspect a DOM element the closest View will be exposed via $view in the console.

Conclusions

In this section we reviewed Backbone Boilerplate and learned how to use the bbb tool to help us scaffold out our application.

If you would like to learn more about how this project helps structure your app, BBB includes some built-in boilerplate sample apps that can be easily generated for review.

These include a boilerplate tutorial project (bbb init:tutorial) and an implementation of my TodoMVC project (bbb init:todomvc). I recommend checking these out as they’ll provide you with a more complete picture of how Backbone Boilerplate, its templates, and so on fit into the overall setup for a web app.

For more about Grunt-BBB, remember to take a look at the official project repository. There is also a related slide-deck available for those interested in reading more.

Backbone & jQuery Mobile

Mobile app development with jQuery Mobile

The mobile web is huge and it is continuing to grow at an impressive rate. Along with the massive growth of the mobile internet comes a striking diversity of devices and browsers. As a result, making your applications cross-platform and mobile-ready is both important and challenging. Creating native apps is expensive. It is very costly in terms of time and it usually requires varied experiences in programming languages like Objective C , C#, Java and JavaScript to support multiple runtime environments.

HTML, CSS, and JavaScript enable you to build a single application targeting a common runtime environment: the browser. This approach supports a broad range of mobile devices such as tablets, smartphones, and notebooks along with traditional PCs.

The challenging task is not only to adapt contents like text and pictures properly to various screen resolutions but also to have same user experience across native apps under different operating systems. Like jQueryUI, jQuery Mobile is a user interface framework based on jQuery that works across all popular phone, tablet, e-Reader, and desktop platforms. It is built with accessibility and universal access in mind.

The main idea of the framework is to enable anyone to create a mobile app using only HTML. Knowledge of a programming language is not required and there is no need to write complex, device specific CSS. For this reason jQMobile follows two main principles we first need to understand in order to integrate the framework to Backbone: progressive enhancement and responsive web design.

The Principle of progressive widget enhancement by jQMobile

JQuery Mobile follows progressive enhancement and responsive web design principles using HTML-5 markup-driven definitions and configurations.

A page in jQuery Mobile consists of an element with a data-role="page" attribute. Within the page container, any valid HTML markup can be used, but for typical pages in jQM, the immediate children are divs with data-role="header", data-role="content", and data-role="footer". The baseline requirement for a page is only a page wrapper to support the navigation system, the rest is optional.

<!DOCTYPE html>
<html>
<head>
    <title>Page Title</title>

    <meta name="viewport" content="width=device-width, initial-scale=1">

    <link rel="stylesheet" href="http://code.jquery.com/mobile/1.3.0/jquery.mobile-1.3.0.min.css" />
    <script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
    <script src="http://code.jquery.com/mobile/1.3.0/jquery.mobile-1.3.0.min.js"></script>
</head>
<body>

<div data-role="page">
  <div data-role="header">
    <h1>Page Title</h1>
  </div>
  <div data-role="content">
     <p>Page content goes here.</p>
     <form>
       <label for="slider-1">Slider with tooltip:</label>
       <input type="range" name="slider-1" id="slider-1" min="0" max="100" value="50" 
        data-popup-enabled="true">
     </form>
  </div>
  <div data-role="footer">
     <h4>Page Footer</h4>
  </div>
</div>
</body>
</html>

JQuery Mobile will transform the written HTML definition to the rendered HTML and CSS using its Progressive Widget Enhancement API. It also executes JavaScript which is conditioned by configurations, attribute properties, and runtime specific settings.

This implies: Whenever HTML content is added or changed, it needs to be handled by the progressive widget enhancement of jQuery Mobile.

Comparison of the user interface of the default HTML to the jQuery Mobile enhanced version

Understanding jQuery Mobile Navigation

The jQuery Mobile navigation system controls its application’s lifecycle by automatically “hijacking” standard links and form submissions and turning them into AJAX requests. Whenever a link is clicked or a form is submitted, that event is automatically intercepted and used to issue an AJAX request based on the href or form action instead of reloading the page.

When the page document is requested, jQuery Mobile searches the document for all elements with the data-role="page" attribute, parses its contents, and inserts that code into the DOM of the original page. Once the new page is prepared, jQuery Mobile’s JavaScript triggers a transition that shows the new page and hides the HTML of the previous page in the DOM.

Next, any widgets in the incoming page are enhanced to apply all the styles and behavior. The rest of the incoming page is discarded so any scripts, stylesheets, or other information will not be included.

Via the multi-page templating feature, you can add as many pages as you want to the same HTML file within the body tag by defining divs with data-role="page" or data-role="dialog" attributes along with an id which can be used in links (preceded by a hashbang):

<html>
  <head>...</head>
  <body>
  ...
  <div data-role="page" id="firstpage">
    ...
   <div data-role="content"> 
     <a href="#secondpage">go to secondpage</a>
   </div>
  </div>
  <div data-role="page" id="secondpage">
    ...
    <div data-role="content" >
       <a href="#firstdialog" data-rel="dialog" >open a page as a dialog</a>
    </div>
  </div>
  <div data-role="dialog" id="firstdialog">
    ...
     <div data-role="content">
       <a href="#firstpage">leave dialog and go to first page</a>
     </div>
  </div>
</body>
</html>

To, for example, navigate to secondpage and have it appear in a modal dialog using a fade-transition, you would just add the data-rel="dialog", data-transition="fade", and href="index.html#secondpage" attributes to an anchor tag.

Roughly speaking, having its own event cycle, jQuery Mobile is a tiny MVC framework which includes features like progressive widget enhancement, pre-fetching, caching, and multi-page templating by HTML configurations innately. In general, a Backbone.js developer does not need to know about its internal event workflow, but will need to know how to apply HTML-based configurations which will take action within the event phase. The Intercepting jQuery Mobile Events section goes into detail regarding how to handle special scenarios when fine-grained JavaScript adaptions need to be applied.

Basic Backbone app setup for jQuery Mobile

The first major hurdle developers typically run into when building applications with jQuery Mobile and an MV* framework is that both frameworks want to handle application navigation.

To combine Backbone and jQuery Mobile, we first need to disable jQuery Mobile’s navigation system and progressive enhancement. The second step will then be to make use of jQM’s custom API to apply configurations and enhance components during Backbone’s application lifecycle instead.

The mobile app example presented here is based on the existing codebase of the TodoMVC Backbone-Require.js example, which was discussed in an earlier chapter, and is enhanced to support jQuery Mobile.

This implementation makes use of Grunt-BBB as well as Handlebars.js. Additional utilities useful for mobile applications will be provided, which can be easily combined and extended. (see the Backbone Boilerplate & Grunt-BBB and Backbone Extensions chapters)

By opening the console in the project directory and then running the Grunt-Backbone command grunt handlebars or grunt watch in the console, it will combine and compile all template files to dist/debug/handlebars_packaged. To start the application, run grunt server.

The head section of index.html needs to load the jquerymobile.css as well as the base.css, which is used by all Todo-MVC apps, and the index.css for some project-specific custom CSS.

<html>
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <meta name="viewport" content="width=device-width,initial-scale=1">

    <title>TodoMVC Jquery Mobile</title>

<!-- widget and responsive design styles -->
    <link rel="stylesheet" href="/assets/css/jquerymobile.css">
<!-- used by all TodoMVC apps -->
    <link rel="stylesheet" href="/assets/css/base.css">
<!-- custom css -->
    <link rel="stylesheet" href="/assets/css/index.css">
</head>

<body>
    <script data-main="/app/config" src="/assets/js/libs/require.js"></script>
</body>
</html>

Workflow with Backbone and jQueryMobile

By delegating the routing and navigation functions of the jQuery Mobile Framework to Backbone, we can profit from its clear separation of application structure to later on easily share application logic between a desktop webpage, tablets, and mobile apps.

We now need to contend with the different ways in which Backbone and jQuery Mobile handle requests. Backbone.Router offers an explicit way to define custom navigation routes, while jQuery Mobile uses URL hash fragments to reference separate pages or views in the same document.

Some of the ideas that have been previously proposed to work-around this problem included manually patching Backbone and jQuery Mobile. The solution demonstrated below will not only simplify the handling of the jQuery Mobile component initialization event-cycle, but also enables use of existing Backbone Router handlers.

To adapt the navigation control from jQuery Mobile to Backbone, we first need to apply some specific settings to the mobileinit event which occurs after the framework has loaded in order to let the Backbone Router decide which page to load.

A configuration which will get jQM to delegate navigation to Backbone and which will also enable manual widget creation triggering is given below:

$(document).bind("mobileinit", function(){

// Disable jQM routing and component creation events   
   // disable hash-routing
   $.mobile.hashListeningEnabled = false;
   // disable anchor-control
   $.mobile.linkBindingEnabled = false;
   // can cause calling object creation twice and back button issues are solved
   $.mobile.ajaxEnabled = false;
   // Otherwise after mobileinit, it tries to load a landing page
   $.mobile.autoInitializePage = false;
   // we want to handle caching and cleaning the DOM ourselves
   $.mobile.page.prototype.options.domCache = false;

// consider due to compatibility issues
   // not supported by all browsers
   $.mobile.pushStateEnabled = false;
   // Solves phonegap issues with the back-button
   $.mobile.phonegapNavigationEnabled = true;
   //no native datepicker will conflict with the jQM component
   $.mobile.page.prototype.options.degradeInputs.date = true;
});

The behaviour and usage of the new workflow will be explained below, grouped by its functionalities:

In the following discussion, the steps 1-11 in the text refer to the new workflow diagram of the mobile application below.

When the hash URL changes, e.g., a link is clicked, the configuration above prevents jQM from triggering its events. Instead, the Backbone Router listens to the hash changes and decides which view to request.

Experience has shown that, for mobile pages, it is a good practice to create basic prototypes for jQM components such as basic pages, popups, and dialogs, as well as for using the jQuery Validation Plugin. This makes it much easier to exchange device-specific view logic at runtime and adopt general strategies. This will also help to add syntax and to support multi-chaining of prototype inheritance with JavaScript and Backbone.

By creating a BasicView superclass, we enable all inheriting view-pages to share a common way of handling jQM along with common usage of a template engine and specific view handling.

When building with Grunt/Yeoman, the semantic templates are compiled by Handlebar.js and the AMDs template files are combined into a single file. By merging all page definitions into a single-file-app, it becomes offline capable, which is important for mobile app.

Management of Mobile Page Templates

Within a concrete View page, you can override properties for static values and functions to return dynamic values of the super class BasicView. These values will be processed later by the BasicView to construct the HTML of a jQuery Mobile page with the help of Handlebars.

Additional dynamic template parameters, e.g., Backbone model information, will be taken from the specific View and merged with the ones from the BasicView.

define([
    "backbone", "modules/view/abstract/BasicView"],
    function (Backbone, BasicView) {
        return BasicView.extend({
            id : "editTodoView", 
            getHeaderTitle : function () {
                return "Edit Todo";
            },
            getSpecificTemplateValues : function () {
                return _.clone(this.model.attributes);
            },
            events : function () {
                // merged events of BasicView, to add an older fix for back button functionality
                return _.extend({
                    'click #saveDescription' : 'saveDescription'
                }, this.constructor.__super__.events);
            },
            saveDescription : function (clickEvent) {
                this.model.save({
                    title : $("#todoDescription", this.el).val()
                });
                return true;
            }
        });
    });

By default, the BasicView uses basic_page_simple.template as the Handlebars template. If you need to use a custom template or want to introduce a new Super abstract View with an alternate template, override the getTemplateID function:

getTemplateID : function(){
  return "custom_page_template";
}

By convention, the id attribute will be taken as the id of the jQM page as well as the filename of the corresponding template file to be inserted as a partial in the basic_page_simple template. In the case of the EditTodoPage view, the name of the file will be editTodoPage.template_partial.

Every concrete page is meant to be a partial, which will be inserted in the data-role="content" element, where the parameter templatePartialPageID is located.

Later on, the result of the getHeaderTitle function from EditTodoPage will replace the headerTitle in the abstract template.

<div data-role="header">
        {{whatis "Specific loaded Handlebars parameters:"}}
        {{whatis this}}
        <h2>{{headerTitle}}</h2>
        <a id="backButton" href="href="javascript:history.go(-1);" data-icon="star" data-rel="back" >back</a>
    </div>
    <div data-role="content">
        {{whatis "Template page trying to load:"}}
        {{whatis templatePartialPageID}}
        {{> templatePartialPageID}}
    </div>
    <div data-role="footer">
        {{footerContent}}
</div>

All the additional parameters being returned by getSpecificTemplateValues will be inserted into the concrete template editTodoPage.template_partial.

Because footerContent is expected to be used rarely, its content is returned by getSpecificTemplateValues.

In the case of the EditTodoPage view, all the model information is being returned and title is used in the concrete partial page:

<div data-role="fieldcontain">
    <label for="todoDescription">Todo Description</label>
    <input type="text" name="todoDescription" id="todoDescription" value="{{title}}" />
</div>
    <a id="saveDescription" href="#" data-role="button" data-mini="true">Save</a>

When render is triggered, the basic_page_simple.template and editTodoView.template_partial templates will be loaded and the parameters from EditTodoPage and BasicView will be combined and generated by Handlebars to generate:

    <div data-role="header">
        <h2>Edit Todo</h2>
        <a id="backButton" href="href="javascript:history.go(-1);" data-icon="star" data-rel="back" >back</a>
    </div>
    <div data-role="content">
      <div data-role="fieldcontain">
       <label for="todoDescription">Todo Description</label>
       <input type="text" name="todoDescription" id="todoDescription" value="Cooking" />
      </div>
      <a id="saveDescription" href="#" data-role="button" data-mini="true">Save</a>
    </div>
    <div data-role="footer">
        Footer
    </div>

Final HTML definition resulting from basic_page_simple_template and editTodoView.template_partial

The next section explains how the template parameters are collected by the BasicView and the HTML definition is loaded.

DOM management and $.mobile.changePage

When render is executed (line 29 is the source code listing below), BasicView first cleans up the DOM by removing the previous page (line 70). To delete the elements from the DOM, $.remove cannot be used, but $previousEl.detach() can be since detach does not remove the element’s attached events and data.

This is important, because jQuery Mobile still needs information (e.g., to trigger transition effects when switching to another page). Keep in mind that the DOM data and events should be cleared later on as well to avoid possible performance issues.

Other strategies than the one used in the function cleanupPossiblePageDuplicationInDOM to cleanup the DOM are viable. To only remove the old page having the same id as the current from the DOM, when it was already requested before, would also be a working strategy of preventing DOM duplication. Depending on what fits best to your application needs, it is also possibly a one-banana problem to exchange it using a caching mechanism.

Next, BasicView collects all template parameters from the concrete View implementation and inserts the HTML of the requested page into the body. This is done in steps 4, 5, 6, and 7 in the diagram above (between lines 23 and 51 in the source listing).

Additionally, the data-role will be set on the jQuery Mobile page. Commonly used attribute values are page, dialog, or popup.

As you can see, (starting at line 74), the goBackInHistory function contains a manual implementation to handle the back button’s action. In certain scenarios, the back button navigation functionality of jQuery Mobile was not working with older versions and disabled jQMobile’s navigation system.

 1 define([
 2     "lodash",
 3     "backbone",
 4     "handlebars",
 5     "handlebars_helpers"
 6 ],
 7 
 8 function (_, Backbone, Handlebars) {
 9     var BasicView = Backbone.View.extend({
10         initialize: function () {
11             _.bindAll();
12             this.render();
13         },
14         events: {
15             "click #backButton": "goBackInHistory"
16         },
17         role: "page",
18         attributes: function () {
19             return {
20                 "data-role": this.role
21             };
22         },
23         getHeaderTitle: function () {
24             return this.getSpecificTemplateValues().headerTitle;
25         },
26         getTemplateID: function () {
27             return "basic_page_simple";
28         },
29         render: function () {
30             this.cleanupPossiblePageDuplicationInDOM();
31             $(this.el).html(this.getBasicPageTemplateResult());
32             this.addPageToDOMAndRenderJQM();
33             this.enhanceJQMComponentsAPI();
34         },
35 // Generate HTML using the Handlebars templates
36         getTemplateResult: function (templateDefinitionID, templateValues) {
37             return window.JST[templateDefinitionID](templateValues);
38         },
39 // Collect all template paramters and merge them
40         getBasicPageTemplateResult: function () {
41             var templateValues = {
42                 templatePartialPageID: this.id,
43                 headerTitle: this.getHeaderTitle()
44             };
45             var specific = this.getSpecificTemplateValues();
46             $.extend(templateValues, this.getSpecificTemplateValues());
47             return this.getTemplateResult(this.getTemplateID(), templateValues);
48         },
49         getRequestedPageTemplateResult: function () {
50             this.getBasicPageTemplateResult();
51         },
52         enhanceJQMComponentsAPI: function () {
53 // changePage
54             $.mobile.changePage("#" + this.id, {
55                 changeHash: false,
56                 role: this.role
57             });
58         },
59 // Add page to DOM
60         addPageToDOMAndRenderJQM: function () {
61             $("body").append($(this.el));
62             $("#" + this.id).page();
63         },
64 // Cleanup DOM strategy
65         cleanupPossiblePageDuplicationInDOM: function () {
66         // Can also be moved to the event "pagehide": or "onPageHide"
67             var $previousEl = $("#" + this.id);
68             var alreadyInDom = $previousEl.length >= 0;
69             if (alreadyInDom) {
70                 $previousEl.detach();
71             }
72         },
73 // Strategy to always support back button with disabled navigation
74         goBackInHistory: function (clickEvent) {
75             history.go(-1);
76             return false;
77         }
78     });
79 
80     return BasicView;
81 });

After the dynamic HTML is added to the DOM, $.mobile.changePage has to be applied at step 8 (code line 54).

This is the most important API call, because it triggers the jQuery Mobile component creation for the current page.

<a data-mini="true" data-role="button" href="#" id="saveDescription" data-corners="true" 
data-shadow="true" data-iconshadow="true" data-wrapperels="span" data-theme="c" 
class="ui-btn ui-shadow ui-btn-corner-all ui-mini ui-btn-up-c">
    <span class="ui-btn-inner">
         <span class="ui-btn-text">Save</span>
     </span>
</a>

Look and feel of the written HTML code and the jQuery Mobile enhanced Todo description page

$.mobile.changePage("#" + this.id, {
                      changeHash: false,
                      role: this.role
                    });

To retain control of hash routing, changeHash has to be set to false and the proper role parameter provided to guarantee proper page appearance. Finally, changePage will show the new page with its defined transition to the user.

For the basic use cases, it is advised to have one View per page, and always render the complete page again by calling $.mobile.changePage when widget enhancement needs to be done.

To progress component enrichment of a newly added HTML-fragment into the DOM, advanced techniques need to be applied to guarantee correct appearance of the mobile components. You need to be very careful when creating partial HTML code and updating values on UI elements. The next section will explain how to handle these situations.

Applying advanced jQM techniques to Backbone

Dynamic DOM Scripting

The solution described above solves the issues of handling routing with Backbone by calling $.mobile.changePage('pageID'). Additionally, it guarantees that the HTML page will be completely enhanced by the markup for jQuery Mobile.

The second tricky part with jQuery Mobile is to dynamically manipulate specific DOM contents (e.g. after loading in content with Ajax). We suggest you use this technique only if there is evidence for an appreciable performance gain.

With the current version (1.3), jQM provides three ways, documented and explained below in the official API, on forums, and blogs.

Sometimes, when creating a component from scratch, the following error can occur: ‘cannot call methods on listview prior to initialization’. This can be avoided, with component initialization prior to markup enhancement, by calling it in the following way:

 $('#mylist').listview().listview('refresh')

To see more details and enhancements for further scripting pages of JQM read their API and follow the release notes frequently.

If you consider using a Model-Binding Plugin, you will need to come up with an automated mechanism to enrich single components.

After having a look at the previous section about Dynamic DOM Scripting, it might not be acceptable to completely re-create a component (e.g. a Listview) which takes a longer time to load and to reduce the complexity of event-delegation. Instead, the component-specific plugins, which will only update the needed parts of the HTML and CSS, should be used.

In the case of a Listview, you would need to call the following function to update the list of added, edited, or removed entries:

$('#mylist').listview()

You need to come up with a means of detecting the component type to in order to decide which plugin method needs to be called. The jQuery Mobile Angular.js Adapter provides such a strategy and solution as well.

Intercepting jQuery Mobile Events

In special situations you will need to take action on a triggered jQuery Mobile event, which can be done as follows:

$('#myPage').live('pagebeforecreate', function(event){
         console.log('page was inserted into the DOM');
    //run your own enhancement scripting here...
          // prevent the page plugin from making its manipulations
    return false;
});

$('#myPage').live('pagecreate', function(event){
          console.log(‘page was enhanced by jQM');
});

In such scenarios, it is important to know when the jQuery Mobile events occur. The following diagram depicts the event cycle (page A is the outgoing page and page B is the incoming page).

An alternative is the jQuery Mobile Router project, which you might use to replace the Backbone Router. With the help of the jQM Router project, you could achieve a powerful way to intercept and route one of the various jQM events. It is an extension to jQuery Mobile, which can be used independently.

Be aware that jQM-Router misses some features of Backbone.Router and is tightly coupled with the jQuery Mobile framework. For these reasons, we did not use it for the TodoMVC app. If you intend to use it, consider using a Backbone.js custom build to exclude the router code. This might save around 25% relative to the max compressed size of 17,1 KB.

Performance

Performance is an important topic on mobile devices. jQuery Mobile provides various tools that create performance logs which can give you a good overview of the actual time spent in routing logic, component enhancement, and visual effects.

Depending on the device, the time spent on transitions can take up to 90% of the load time. To disable all transitions, you can either pass the transition none to $.mobile.changePage(), in the configuration code block:

$(document).bind("mobileinit", function(){
…
// Otherwise, depending on takes up to 90% of loadtime
  $.mobile.defaultPageTransition = "none";
  $.mobile.defaultDialogTransition = "none";
    });
  })

$(document).bind("mobileinit", function(){

  var iosDevice =((navigator.userAgent.match(/iPhone/i))
  || (navigator.userAgent.match(/iPod/i))) ? true : false;

  $.extend(  $.mobile , {
    slideText :  (iosDevice) ? "slide" : "none",
    slideUpText :  (iosDevice) ? "slideup" : "none",
    defaultPageTransition:(iosDevice) ? "slide" : "none",
    defaultDialogTransition:(iosDevice) ? "slide" : "none"
  });

The jQuery Mobile API is frequently enhanced with regards to this topic in each new release. We suggest you take a look at the latest updated API to determine an optimal caching strategy with dynamic scripting that best fits your needs.

Clever Multi-Platform Support Management

Nowadays, a company typically has an existing webpage and management decides to provide an additional mobile app to customers. The code of the web page and the mobile app become independent of each other and the time required for content or feature changes becomes much higher than for the webpage alone.

As the trend is towards an increasing number of mobile platforms and dimensions, the effort required to support them is only increasing as well. Ultimately, creating per-device experiences is not always viable. However, it is essential that content is available to all users, regardless of their browser and platform. This principle must be kept in mind during the design phase.

The mobile app architecture presented in this chapter takes care of a lot of the actual heavy lifting required, as it supports responsive layouts out of the box and even supports browsers which cannot handle media queries. It might not be obvious that jQM is a UI framework not dissimilar to jQuery UI. jQuery Mobile is using the widget factory and is capable of being used for more than just mobile environments.

To support multi-platform browsers using jQuery Mobile and Backbone, you can, in order of increasing time and effort:

The ideal solution, to build a nice-looking desktop application with only one mobile framework, sounds crazy, but is feasible.

If you have a look at the jQuery Mobile API page in a desktop browser, it does not look anything like a mobile application.

Desktop view of the jQuery Mobile API and Docs application (http://view.jquerymobile.com/1.3.0/)

The same goes for the jQuery Mobile design examples, where jQuery Mobile intends to add further user interface experiences.

Design examples of jQuery Mobile for desktop environments, http://jquerymobile.com/designs/#desktop

The accordions, date-pickers, sliders - everything in the desktop UI is re-using what jQM would be providing users on mobile devices. By way of example, adding the attribute data-mini="true" on components will lose the clumsiness of the mobile widgets on a desktop browser.

See http://jquerymobile.com/demos/1.2.0/docs/forms/forms-all-mini.html, Mini-widgets for desktop applications by jQuery Mobile.

Thanks to some media queries, the desktop UI can make optimal use of whitespace, expanding component blocks out and providing alternative layouts while still making use of jQM as the component framework.

The benefit of this is that you don’t need to pull in another widget framework (e.g., jQuery UI) separately to be able to take advantage of these features. Thanks to the ThemeRoller, the components can look pretty much exactly how you would like them to and users of the app can get a jQM UI for lower-resolutions and a jQM-ish UI for everything else.

The take away here is just to remember that if you are not already going through the hassle of conditional script/style loading based on screen-resolution (using matchMedia.js, etc.), there are simpler approaches that can be taken to cross-device component theming. At least the Responsive Design API of jQuery Mobile, which was added since version 1.3.0, is always reasonable because it will work for mobile as well as for desktop. In summary, you can manage jQuery Mobile components to give users a typical desktop appearance and they will not realize a difference.

Also, if you hit your limits of CSS-styling and configurations of your jQuery Mobile application for desktop browsers, the additional effort to use jQuery Mobile and Twitter Bootstrap together can be quite simple. In the case that a desktop browser requests the page and Twitter Bootstrap has been loaded, the mobile TodoMVC app would need conditional code to not trigger the jQM Widget processive enhancement plugins API (demonstrated in the Dynamic DOM Scripting section) in the Backbone.View implementation. Therefore, as explained in the previous sections, we recommend triggering widget enhancements by $.mobile.changePage only once to load the complete page.

Although it is using server-side technologies for templating using the programming language Python, the principle of triggering progressive enhancement at page load is the same as $mobile.changePage.

As you can see, the JavaScript and even the CSS stays the same. The only device-specific conditions and differences in implementations are for selecting the appropriate framework imports, which are located in the HTML template:

...
 {% if is_mobile %}
    <link rel="stylesheet" href="/mobile/jquery.mobile-1.1.0.min.css" />
    {% else %}
      <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
      <link rel="stylesheet" href="/css/style.css" />
      <link rel="stylesheet" href="/css/bootstrap.min.css">
      <link rel="stylesheet" href="/css/bootstrap-responsive.min.css">
    {% endif %}
      <link rel="stylesheet" href="/css/main.css" />

    {% block mediaCSS %}{% endblock %}
...
 {% if is_mobile %}
      <script src="/mobile/jquery.mobile-1.1.0.min.js"></script>
    {% else %}
      <script src="/js/libs/bootstrap.min.js"></script>
    {% endif %}
...

Unit Testing

One definition of unit testing is the process of taking the smallest piece of testable code in an application, isolating it from the remainder of your codebase, and determining if it behaves exactly as expected.

For an application to be considered ‘well-tested’, each function should ideally have its own separate unit tests where it’s tested against the different conditions you expect it to handle. All tests must pass before functionality is considered ‘complete’. This allows developers to both modify a unit of code and its dependencies with a level of confidence about whether these changes have caused any breakage.

A basic example of unit testing is where a developer asserts that passing specific values to a sum function results in the correct value being returned. For an example more relevant to this book, we may wish to assert that adding a new Todo item to a list correctly adds a Model of a specific type to a Todos Collection.

When building modern web-applications, it’s typically considered best-practice to include automated unit testing as a part of your development process. In the following chapters we are going to look at three different solutions for unit testing your Backbone.js apps - Jasmine, QUnit and SinonJS.

Jasmine

Behavior-Driven Development

In this section, we’ll be taking a look at how to unit test Backbone applications using a popular JavaScript testing framework called Jasmine from Pivotal Labs.

Jasmine describes itself as a behavior-driven development (BDD) framework for testing JavaScript code. Before we jump into how the framework works, it’s useful to understand exactly what BDD is.

BDD is a second-generation testing approach first described by Dan North (the authority on BDD) which attempts to test the behavior of software. It’s considered second-generation as it came out of merging ideas from Domain driven design (DDD) and lean software development. BDD helps teams deliver high-quality software by answering many of the more confusing questions early on in the agile process. Such questions commonly include those concerning documentation and testing.

If you were to read a book on BDD, it’s likely that it would be described as being ‘outside-in and pull-based’. The reason for this is that it borrows the idea of ‘pulling features’ from Lean manufacturing which effectively ensures that the right software solutions are being written by a) focusing on the expected outputs of the system and b) ensuring these outputs are achieved.

BDD recognizes that there are usually multiple stakeholders in a project and not a single amorphous user of the system. These different groups will be affected by the software being written in differing ways and will have varying opinions of what quality in the system means to them. It’s for this reason that it’s important to understand who the software will be bringing value to and exactly what in it will be valuable to them.

Finally, BDD relies on automation. Once you’ve defined the quality expected, your team will want to check on the functionality of the solution being built regularly and compare it to the results they expect. In order to facilitate this efficiently, the process has to be automated. BDD relies heavily on the automation of specification-testing and Jasmine is a tool which can assist with this.

What this means is that developers should be able to show Jasmine unit tests to a project stakeholder and (at a high level, thanks to a common vocabulary being used) they’ll ideally be able to understand what the code supports.

Developers often implement BDD in unison with another testing paradigm known as TDD (test-driven development). The main idea behind TDD is using the following development process:

In this chapter we’re going to use BDD (with TDD) to write unit tests for a Backbone application.

Note: I’ve seen a lot of developers also opt for writing tests to validate behavior of their code after having written it. While this is fine, note that it can come with pitfalls such as only testing for behavior your code currently supports, rather than the behavior needed to fully solve the problem.

Suites, Specs, & Spies

When using Jasmine, you’ll be writing suites and specifications (specs). Suites basically describe scenarios while specs describe what can be done in these scenarios.

Each spec is a JavaScript function, described with a call to it() using a description string and a function. The description should describe the behaviour the particular unit of code should exhibit and, keeping in mind BDD, it should ideally be meaningful. Here’s an example of a basic spec:

it('should be incrementing in value', function(){
    var counter = 0;
    counter++;
});

On its own, a spec isn’t particularly useful until expectations are set about the behavior of the code. Expectations in specs are defined using the expect() function and an expectation matcher (e.g., toEqual(), toBeTruthy(), toContain()). A revised example using an expectation matcher would look like:

it('should be incrementing in value', function(){
    var counter = 0;
    counter++;
    expect(counter).toEqual(1);
});

The above code passes our behavioral expectation as counter equals 1. Notice how easy it was to read the expectation on the last line (you probably grokked it without any explanation).

Specs are grouped into suites which we describe using Jasmine’s describe() function, again passing a string as a description and a function as we did for it(). The name/description for your suite is typically that of the component or module you’re testing.

Jasmine will use the description as the group name when it reports the results of the specs you’ve asked it to run. A simple suite containing our sample spec could look like:

describe('Stats', function(){
    it('can increment a number', function(){
        ...
    });

    it('can subtract a number', function(){
        ...
    });
});

Suites also share a functional scope, so it’s possible to declare variables and functions inside a describe block which are accessible within specs:

describe('Stats', function(){
    var counter = 1;

    it('can increment a number', function(){
        // the counter was = 1
        counter = counter + 1;
        expect(counter).toEqual(2);
    });

    it('can subtract a number', function(){
        // the counter was = 2
        counter = counter - 1;
        expect(counter).toEqual(1);
    });
});

Note: Suites are executed in the order in which they are described, which can be useful to know if you would prefer to see test results for specific parts of your application reported first.

Jasmine also supports spies - a way to mock, spy, and fake behavior in our unit tests. Spies replace the function they’re spying on, allowing us to simulate behavior we would like to mock (i.e., test without using the actual implementation).

In the example below, we’re spying on the setComplete method of a dummy Todo function to test that arguments can be passed to it as expected.

var Todo = function(){
};

Todo.prototype.setComplete = function (arg){
    return arg;
}

describe('a simple spy', function(){
    it('should spy on an instance method of a Todo', function(){
        var myTodo = new Todo();
        spyOn(myTodo, 'setComplete');
        myTodo.setComplete('foo bar');

        expect(myTodo.setComplete).toHaveBeenCalledWith('foo bar');

        var myTodo2 = new Todo();
        spyOn(myTodo2, 'setComplete');

        expect(myTodo2.setComplete).not.toHaveBeenCalled();

    });
});

You are more likely to use spies for testing asynchronous behavior in your application such as AJAX requests. Jasmine supports:

This example of the first kind of test shows how to fake an AJAX request and verify that the request was both calling the correct URL and executed a callback where one was provided.

it('the callback should be executed on success', function () {

    // `.and.callFake()` calls a passed function when a spy
    // has been called
    spyOn($, 'ajax').and.callFake(function(options) {
        options.success();
    });

    // Create a new spy
    var callback = jasmine.createSpy();

    // Exexute the spy callback if the
    // request for Todo 15 is successful
    getTodo(15, callback);

    // Verify that the URL of the most recent call
    // matches our expected Todo item.
    expect($.ajax.calls.mostRecent().args[0]['url']).toEqual('/todos/15');

    // `expect(x).toHaveBeenCalled()` will pass if `x` is a
    // spy and was called.
    expect(callback).toHaveBeenCalled();
});

function getTodo(id, callback) {
    $.ajax({
        type: 'GET',
        url: '/todos/' + id,
        dataType: 'json',
        success: callback
    });
}

For the second type of test (asynchronous tests), we can take the above further by taking advantage of three other methods Jasmine supports:

it('should make an actual AJAX request to a server', function () {

    // Create a new spy
    var callback = jasmine.createSpy();

    // Exexute the spy callback if the
    // request for Todo 16 is successful
    getTodo(16, callback);

    // Pause the spec until the callback count is
    // greater than 0
    waitsFor(function() {
        return callback.callCount > 0;
    });

    // Once the wait is complete, our runs() block
    // will check to ensure our spy callback has been
    // called
    runs(function() {
        expect(callback).toHaveBeenCalled();
    });
});

function getTodo(id, callback) {
    $.ajax({
        type: 'GET',
        url: 'todos.json',
        dataType: 'json',
        success: callback
    });
}

Note: It’s useful to remember that when making real requests to a web server in your unit tests, this has the potential to massively slow down the speed at which tests run (due to many factors including server latency). As this also introduces an external dependency that can (and should) be minimized in your unit testing, it is strongly recommended that you opt for spies to remove the dependency on a web server.

beforeEach() and afterEach()

Jasmine also supports specifying code that can be run before each (beforeEach()) and after each (afterEach()) test. This is useful for enforcing consistent conditions (such as resetting variables that may be required by specs). In the following example, beforeEach() is used to create a new sample Todo model which specs can use for testing attributes.

beforeEach(function(){
   this.todo = new Backbone.Model({
      text: 'Buy some more groceries',
      done: false
   });
});

it('should contain a text value if not the default value', function(){
   expect(this.todo.get('text')).toEqual('Buy some more groceries');
});

Each nested describe() in your tests can have their own beforeEach() and afterEach() methods which support including setup and teardown methods relevant to a particular suite.

beforeEach() and afterEach() can be used together to write tests verifying that our Backbone routes are being correctly triggered when we navigate to the URL. We can start with the index action:

describe('Todo routes', function(){

   beforeEach(function(){

        // Create a new router
        this.router = new App.TodoRouter();

        // Create a new spy
        this.routerSpy = jasmine.spy();

        // Begin monitoring hashchange events
        try{
            Backbone.history.start({
                silent:true,
                pushState: true
            });
        }catch(e){
           // ...
        }

        // Navigate to a URL
        this.router.navigate('/js/spec/SpecRunner.html');
   }); 

   afterEach(function(){

        // Navigate back to the URL
        this.router.navigate('/js/spec/SpecRunner.html');

        // Disable Backbone.history temporarily.
        // Note that this is not really useful in real apps but is
        // good for testing routers
        Backbone.history.stop();
   });

   it('should call the index route correctly', function(){
        this.router.bind('route:index', this.routerSpy, this);
        this.router.navigate('', {trigger: true});

        // If everything in our beforeEach() and afterEach()
        // calls have been correctly executed, the following
        // should now pass.
        expect(this.routerSpy).toHaveBeenCalledOnce();
        expect(this.routerSpy).toHaveBeenCalledWith();
   });

});

var App = App || {};
App.TodoRouter = Backbone.Router.extend({
    routes:{
        '': 'index'
    },
    index: function(){
        //...
    }
});

Shared scope

Let’s imagine we have a Suite where we wish to check for the existence of a new Todo item instance. This could be done by duplicating the spec as follows:

describe("Todo tests", function(){
   
   // Spec
   it("Should be defined when we create it", function(){
        // A Todo item we are testing
        var todo = new Todo("Get the milk", "Tuesday");
        expect(todo).toBeDefined();
   }); 

   it("Should have the correct title", function(){
        // Where we introduce code duplication
        var todo = new Todo("Get the milk", "Tuesday");
        expect(todo.title).toBe("Get the milk");
   });

});

As you can see, we’ve introduced duplication that should ideally be refactored into something cleaner. We can do this using Jasmine’s Suite (Shared) Functional Scope.

All of the specs within the same Suite share the same functional scope, meaning that variables declared within the Suite itself are available to all of the Specs in that suite. This gives us a way to work around our duplication problem by moving the creation of our Todo objects into the common functional scope:

describe("Todo tests", function(){
    
    // The instance of Todo, the object we wish to test
    // is now in the shared functional scope
    var todo = new Todo("Get the milk", "Tuesday");

    // Spec
    it("should be correctly defined", function(){
        expect(todo).toBeDefined();
    });

    it("should have the correct title", function(){
        expect(todo.title).toBe("Get the milk");
    });

});

In the previous section you may have noticed that we initially declared this.todo within the scope of our beforeEach() call and were then able to continue using this reference in afterEach().

This is again down to shared function scope, which allows such declarations to be common to all blocks (including runs()).

Variables declared outside of the shared scope (i.e. within the local scope var todo=...) will however not be shared.

Getting set up

Now that we’ve reviewed some fundamentals, let’s go through downloading Jasmine and getting everything set up to write tests.

A standalone release of Jasmine can be downloaded from the official release page.

You’ll need a file called SpecRunner.html in addition to the release. It can be downloaded from https://github.com/pivotal/jasmine/tree/master/lib/jasmine-core/example or as part of a download of the complete Jasmine repo. Alternatively, you can git clone the main Jasmine repository from https://github.com/pivotal/jasmine.git.

Note: Below this section of SpecRunner is code responsible for running the actual tests. Given that we won’t be covering modifying this code, I’m going to skip reviewing it. I do however encourage you to take a look through PlayerSpec.js and SpecHelper.js. They’re a useful basic example to go through how a minimal set of tests might work.

Also note that for the purposes of introduction, some of the examples in this section will be testing aspects of Backbone.js itself, just to give you a feel for how Jasmine works. You generally will not need to write testing ensuring a framework is working as expected.

TDD With Backbone

When developing applications with Backbone, it can be necessary to test both individual modules of code as well as models, views, collections, and routers. Taking a TDD approach to testing, let’s review some specs for testing these Backbone components using the popular Backbone Todo application.

Models

The complexity of Backbone models can vary greatly depending on what your application is trying to achieve. In the following example, we’re going to test default values, attributes, state changes, and validation rules.

describe('Tests for Todo', function() {

Models should ideally have default values for attributes. This helps ensure that when creating instances without a value set for any specific attribute, a default one (e.g., an empty string) is used instead. The idea here is to allow your application to interact with models without any unexpected behavior.

In the following spec, we create a new Todo without any attributes passed then check to find out what the value of the text attribute is. As no value has been set, we expect a default value of '' to be returned.

it('Can be created with default values for its attributes.', function() {
    var todo = new Todo();
    expect(todo.get('text')).toBe('');
});

If testing this spec before your models have been written, you’ll incur a failing test, as expected. What’s required for the spec to pass is a default value for the attribute text. We can set this and some other useful defaults (which we’ll be using shortly) in our Todo model as follows:

window.Todo = Backbone.Model.extend({

    defaults: {
      text: '',
      done:  false,
      order: 0
    }

Next, it is common to include validation logic in your models to ensure that input passed from users or other modules in the application are valid.

A Todo app may wish to validate the text input supplied in case it contains rude words. Similarly if we’re storing the done state of a Todo item using booleans, we need to validate that truthy/falsy values are passed and not just any arbitrary string.

In the following spec, we take advantage of the fact that validations which fail model.validate() trigger an “invalid” event. This allows us to test if validations are correctly failing when invalid input is supplied.

We create an errorCallback spy using Jasmine’s built in createSpy() method which allows us to spy on the invalid event as follows:

it('Can contain custom validation rules, and will trigger an invalid event on failed validation.', function() {

    var errorCallback = jasmine.createSpy('-invalid event callback-');

    var todo = new Todo();

    todo.on('invalid', errorCallback);

    // What would you need to set on the todo properties to
    // cause validation to fail?

    todo.set({done:'a non-boolean value'}, {validate: true});

    var errorArgs = errorCallback.mostRecentCall.args;

    expect(errorArgs).toBeDefined();
    expect(errorArgs[0]).toBe(todo);
    expect(errorArgs[1]).toBe('Todo.done must be a boolean value.');
});

The code to make the above failing test support validation is relatively simple. In our model, we override the validate() method (as recommended in the Backbone docs), checking to make sure a model both has a ‘done’ property and that its value is a valid boolean before allowing it to pass.

validate: function(attrs) {
    if (attrs.hasOwnProperty('done') && !_.isBoolean(attrs.done)) {
        return 'Todo.done must be a boolean value.';
    }
}

If you would like to review the final code for our Todo model, you can find it below:


window.Todo = Backbone.Model.extend({

    defaults: {
      text: '',
      done:  false,
      order: 0
    },

    initialize: function() {
        this.set({text: this.get('text')}, {silent: true});
    },

    validate: function(attrs) {
        if (attrs.hasOwnProperty('done') && !_.isBoolean(attrs.done)) {
            return 'Todo.done must be a boolean value.';
        }
    },

    toggle: function() {
        this.save({done: !this.get('done')});
    }

});

Collections

We now need to define specs to test a Backbone collection of Todo models (a TodoList). Collections are responsible for a number of list tasks including managing order and filtering.

In this section we’re going to cover the first two of these with the third left as an extended exercise you can try on your own.

Testing that Todo models can be added to a collection as objects or arrays is relatively trivial. First, we initialize a new TodoList collection and check to make sure its length (i.e., the number of Todo models it contains) is 0. Next, we add new Todos, both as objects and arrays, checking the length property of the collection at each stage to ensure the overall count is what we expect:

describe('Tests for TodoList', function() {

    it('Can add Model instances as objects and arrays.', function() {
        var todos = new TodoList();

        expect(todos.length).toBe(0);

        todos.add({ text: 'Clean the kitchen' });

        // how many todos have been added so far?
        expect(todos.length).toBe(1);

        todos.add([
            { text: 'Do the laundry', done: true },
            { text: 'Go to the gym'}
        ]);

        // how many are there in total now?
        expect(todos.length).toBe(3);
    });
...

Similar to model attributes, it’s also quite straight-forward to test attributes in collections. Here we have a spec that ensures the collection url (i.e., the url reference to the collection’s location on the server) is what we expect it to be:

it('Can have a url property to define the basic url structure for all contained models.', function() {
        var todos = new TodoList();

        // what has been specified as the url base in our model?
        expect(todos.url).toBe('/todos/');
});

For the third spec (which you will write as an exercise), note that the implementation for our collection will have methods for filtering how many Todo items are done and how many are remaining - we’ll call these done() and remaining(). Consider writing a spec which creates a new collection and adds one new model that has a preset done state of true and two others that have the default done state of false. Testing the length of what’s returned using done() and remaining() will tell us whether the state management in our application is working or needs a little tweaking.

 window.TodoList = Backbone.Collection.extend({

        model: Todo,

        url: '/todos/',

        done: function() {
            return this.filter(function(todo) { return todo.get('done'); });
        },

        remaining: function() {
            return this.without.apply(this, this.done());
        },

        nextOrder: function() {
            if (!this.length) {
                return 1;
            }

            return this.last().get('order') + 1;
        },

        comparator: function(todo) {
            return todo.get('order');
        }

    });

Views

Before we take a look at testing Backbone views, let’s briefly review a jQuery plugin that can assist with writing Jasmine specs for them.

As we know our Todo application will be using jQuery for DOM manipulation, there’s a useful jQuery plugin called jasmine-jquery we can use to help simplify BDD testing of the rendering performed by our views.

The plugin provides a number of additional Jasmine matchers to help test jQuery-wrapped sets such as:

and many others. The complete list of matchers supported can be found on the project homepage. It’s useful to know that similar to the standard Jasmine matchers, the custom matchers above can be inverted using the .not prefix (i.e. expect(x).not.toBe(y)):

expect($('<div>I am an example</div>')).not.toHaveText(/other/)

jasmine-jquery also includes a fixtures module that can be used to load arbitrary HTML content we wish to use in our tests. Fixtures can be used as follows:

loadFixtures('some.fixture.html')
$('some-fixture').myTestedPlugin();
expect($('#some-fixture')).to<the rest of your matcher would go here>

The jasmine-jquery plugin loads fixtures from a directory named spec/javascripts/fixtures by default. If you wish to configure this path you can do so by initially setting jasmine.getFixtures().fixturesPath = 'your custom path'.

Finally, jasmine-jquery includes support for spying on jQuery events without the need for any extra plumbing work. This can be done using the spyOnEvent() and expect(eventName).toHaveBeenTriggeredOn(selector) functions. For example:

spyOnEvent($('#el'), 'click');
$('#el').click();
expect('click').toHaveBeenTriggeredOn($('#el'));

View testing

In this section we will review the three dimensions of specs writing for Backbone Views: initial setup, view rendering, and templating. The latter two of these are the most commonly tested, however we’ll see shortly why writing specs for the initialization of your views can also be of benefit.

Initial setup

At their most basic, specs for Backbone views should validate that they are being correctly tied to specific DOM elements and are backed by valid data models. The reason to consider doing this is that these specs can identify issues which will trip up more complex tests later on. Also, they’re fairly simple to write given the overall value offered.

To help ensure a consistent testing setup for our specs, we use beforeEach() to append both an empty <ul> (#todoList) to the DOM and initialize a new instance of a TodoView using an empty Todo model. afterEach() is used to remove the previous #todoList <ul> as well as the previous instance of the view.

describe('Tests for TodoView', function() {

    beforeEach(function() {
        $('body').append('<ul id="todoList"></ul>');
        this.todoView = new TodoView({ model: new Todo() });
    });


    afterEach(function() {
        this.todoView.remove();
        $('#todoList').remove();
    });

...

The first spec useful to write is a check that the TodoView we’ve created is using the correct tagName (element or className). The purpose of this test is to make sure it’s been correctly tied to a DOM element when it was created.

Backbone views typically create empty DOM elements once initialized, however these elements are not attached to the visible DOM in order to allow them to be constructed without an impact on the performance of rendering.

it('Should be tied to a DOM element when created, based off the property provided.', function() {
    //what html element tag name represents this view?
    expect(this.todoView.el.tagName.toLowerCase()).toBe('li');
});

Once again, if the TodoView has not already been written, we will experience failing specs. Thankfully, solving this is as simple as creating a new Backbone.View with a specific tagName.

var todoView = Backbone.View.extend({
    tagName:  'li'
});

If instead of testing against the tagName you would prefer to use a className instead, we can take advantage of jasmine-jquery’s toHaveClass() matcher:

The toHaveClass() matcher operates on jQuery objects and if the plugin hadn’t been used, an exception would have been thrown. It is of course also possible to test for the className by accessing el.className if you don’t use jasmine-jquery.

You may have noticed that in beforeEach(), we passed our view an initial (albeit unfilled) Todo model. Views should be backed by a model instance which provides data. As this is quite important to our view’s ability to function, we can write a spec to ensure a model is defined (using the toBeDefined() matcher) and then test attributes of the model to ensure defaults both exist and are the values we expect them to be.

it('Is backed by a model instance, which provides the data.', function() {

    expect(this.todoView.model).toBeDefined();

    // what's the value for Todo.get('done') here?
    expect(this.todoView.model.get('done')).toBe(false); //or toBeFalsy()
});

View rendering

Next we’re going to take a look at writing specs for view rendering. Specifically, we want to test that our TodoView elements are actually rendering as expected.

In smaller applications, those new to BDD might argue that visual confirmation of view rendering could replace unit testing of views. The reality is that when dealing with applications that might grow to a large number of views, it makes sense to automate this process as much as possible from the get-go. There are also aspects of rendering that require verification beyond what is visually presented on-screen (which we’ll see very shortly).

We’re going to begin testing views by writing two specs. The first spec will check that the view’s render() method is correctly returning the view instance, which is necessary for chaining. Our second spec will check that the HTML produced is exactly what we expect based on the properties of the model instance that’s been associated with our TodoView.

Unlike some of the previous specs we’ve covered, this section will make greater use of beforeEach() to both demonstrate how to use nested suites and also ensure a consistent set of conditions for our specs. In our first example we’re simply going to create a sample model (based on Todo) and instantiate a TodoView with it.

describe('TodoView', function() {

  beforeEach(function() {
    this.model = new Backbone.Model({
      text: 'My Todo',
      order: 1,
      done: false
    });
    this.view = new TodoView({model:this.model});
  });

  describe('Rendering', function() {

    it('returns the view object', function() {
      expect(this.view.render()).toEqual(this.view);
    });

    it('produces the correct HTML', function() {
      this.view.render();

      // let's use jasmine-jquery's toContain() to avoid
      // testing for the complete content of a todo's markup
      expect(this.view.el.innerHTML)
        .toContain('<label class="todo-content">My Todo</label>');
    });

  });

});

When these specs are run, only the second one (‘produces the correct HTML’) fails. Our first spec (‘returns the view object’), which is testing that the TodoView instance is returned from render(), passes since this is Backbone’s default behavior and we haven’t overwritten the render() method with our own version yet.

Note: For the purposes of maintaining readability, all template examples in this section will use a minimal version of the following Todo view template. As it’s relatively trivial to expand this, please feel free to refer to this sample if needed:

The reason for this is the default behavior for render() doesn’t create any markup. Let’s write a replacement for render() which fixes this:

render: function() {
  var template = '<label class="todo-content">+++PLACEHOLDER+++</label>';
  var output = template
    .replace('+++PLACEHOLDER+++', this.model.get('text'));
  this.$el.html(output);
  return this;
}

The above specifies an inline string template and replaces fields found in the template within the “+++PLACEHOLDER+++” blocks with their corresponding values from the associated model. As we’re also returning the TodoView instance from the method, the first spec will still pass.

It would be impossible to discuss unit testing without mentioning fixtures. Fixtures typically contain test data (e.g., HTML) that is loaded in when needed (either locally or from an external file) for unit testing. So far we’ve been establishing jQuery expectations based on the view’s el property. This works for a number of cases, however, there are instances where it may be necessary to render markup into the document. The most optimal way to handle this within specs is through using fixtures (another feature brought to us by the jasmine-jquery plugin).

describe('TodoView', function() {

  beforeEach(function() {
    ...
    setFixtures('<ul class="todos"></ul>');
  });

  ...

  describe('Template', function() {

    beforeEach(function() {
      $('.todos').append(this.view.render().el);
    });

    it('has the correct text content', function() {
      expect($('.todos').find('.todo-content'))
        .toHaveText('My Todo');
    });

  });

});

What we’re now doing in the above spec is appending the rendered todo item into the fixture. We then set expectations against the fixture, which may be something desirable when a view is setup against an element which already exists in the DOM. It would be necessary to provide both the fixture and test the el property correctly picking up the element expected when the view is instantiated.

Rendering with a templating system

When a user marks a Todo item as complete (done), we may wish to provide them with visual feedback (such as a striked line through the text) to differentiate the item from those that are remaining. This can be done by attaching a new class to the item. Let’s begin by writing a test:

describe('When a todo is done', function() {

  beforeEach(function() {
    this.model.set({done: true}, {silent: true});
    $('.todos').append(this.view.render().el);
  });

  it('has a done class', function() {
    expect($('.todos .todo-content:first-child'))
      .toHaveClass('done');
  });

});

render: function() {
  var template = '<label class="todo-content">' +
    '<%= text %></label>';
  var output = template
    .replace('<%= text %>', this.model.get('text'));
  this.$el.html(output);
  if (this.model.get('done')) {
    this.$('.todo-content').addClass('done');
  }
  return this;
}

However, this can get unwieldy fairly quickly. As the level of complexity and logic in our templates increase, so do the challenges associated with testing them. We can ease this process by taking advantage of modern templating libraries, many of which have already been demonstrated to work well with testing solutions such as Jasmine.

JavaScript templating systems (such as Handlebars, Mustache, and Underscore’s own micro-templating) support conditional logic in template strings. What this effectively means is that we can add if/else/ternery expressions inline which can then be evaluated as needed, allowing us to build even more powerful templates.

In our case, we are going to use the micro-templating found in Underscore.js as no additional files are required to use it and we can easily modify our existing specs to use it without a great deal of effort.

var TodoView = Backbone.View.extend({

  tagName: 'li',
  template: _.template($('#myTemplate').html()),

  initialize: function(options) {
    // ...
  },

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

  ...

});

So, what’s going on here? We’re first defining our template in a script tag with a custom script type (e.g., type=“text/template”). As this isn’t a script type any browser understands, it’s simply ignored, however referencing the script by an id attribute allows the template to be kept separate to other parts of the page.

In our view, we’re the using the Underscore _.template() method to compile our template into a function that we can easily pass model data to later on. In the line this.model.toJSON() we are simply returning a copy of the model’s attributes for JSON stringification to the template method, creating a block of HTML that can now be appended to the DOM.

Note: Ideally all of your template logic should exist outside of your specs, either in individual template files or embedded using script tags within your SpecRunner. This is generally more maintainable.

If you are working with much smaller templates and are not doing this, there is however a useful trick that can be applied to automatically create or extend templates in the Jasmine shared functional scope for each test.

By creating a new directory (say, ‘templates’) in the ‘spec’ folder and including a new script file with the following contents into SpecRunner.html, we can manually add custom attributes representing smaller templates we wish to use:

beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '<label class="todo-content">' +
            '<%= text %>' +
          '</label>'
  });
});

To finish this off, we simply update our existing spec to reference the template when instantiating the TodoView:

describe('TodoView', function() {

  beforeEach(function() {
    ...
    this.view = new TodoView({
      model: this.model,
      template: this.templates.todo
    });
  });

  ...

});

The existing specs we’ve looked at would continue to pass using this approach, leaving us free to adjust the template with some additional conditional logic for Todos with a status of ‘done’:

beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '<label class="todo-content <%= done ? 'done' : '' %>"' +
            '<%= text %>' +
          '</label>'
  });
});

This will now also pass without any issues, however as mentioned, this last approach probably only makes sense if you’re working with smaller, highly dynamic templates.

Conclusions

We have now covered how to write Jasmine tests for Backbone.js models, collections, and views. While testing routing can at times be desirable, some developers feel it can be more optimal to leave this to third-party tools such as Selenium, so do keep this in mind.

Exercise

As an exercise, I recommend now trying the Jasmine Koans in practicals\jasmine-koans and trying to fix some of the purposefully failing tests it has to offer. This is an excellent way of not just learning how Jasmine specs and suites work, but working through the examples (without peeking back) will also put your Backbone skills to the test too.

By Addy Osmani (@addyosmani)

Prelude

Target Audience

Acknowledgements

Credits

Target Version

Reading

Introduction

What Is MVC in Modern Web Development?

What is Backbone.js?

Modern JavaScript Application Architecture

When to Use Backbone.js Today

Setting Expectations

Fundamentals

MVC and Modern Architecture

Classical MVC vs Modern Implementations

Modern Web Context

Client-Side Architecture

Modern Best Practices

Summary

Backbone Basics

Getting set up

Models

Initialization

Getters & Setters

Listening for changes to your model

Validation

Views

Creating new views

What is el?

Collections

Adding and Removing Models

Retrieving Models

Listening for events

Resetting/Refreshing Collections

Underscore utility functions

Chainable API

RESTful Persistence

Events

on(), off(), and trigger()

listenTo() and stopListening()

Events and Views

Routers

Backbone.history

Backbone’s Sync API

Dependencies

Summary

Exercise 1: Todos - Your First Backbone.js App

Static HTML

Header and Scripts

Application HTML

Templates

Todo model

Todo collection

Application View

Individual Todo View

Startup

In action

Completing & deleting todos

Todo routing

Summary

Exercise 2: Book Library - Your First RESTful Backbone.js App

The Library Application

Setting Up

The Book Model

The Library Collection

The Book View

The Library View

Starting the Application

Styling

Important Notes

Testing the Application

Server-Side Implementation

Backbone Extensions

MarionetteJS (Backbone.Marionette)

Boilerplate Rendering Code

Reducing Boilerplate With Marionette.ItemView

Memory Management

Region Management

What is `el`?