Backbone.js Cookbook

Let's write down a list of functional requirements for this application. We assume that the end user may want to be able to do the following:

To simplify the process of creating multiple invoices, the user may want to manage information about buyers and his personal details in the specific part of the application before he/she creates an invoice. So, our application should provide additional functionalities to the end user, such as the following:

Of course, we may want to have more functions, but this is enough for demonstrating how to design an application using the MVC pattern.

Next, we architect an application using the MVC pattern.

After we have defined the features of our application, we need to understand what is more related to the model (business logic) and what is more related to the view (presentation). Let's split the functionality into several parts.

Then, we learn how to define models.

Models present data and provide data-specific business logic. Models can be related to each other. In our case, they are as follows:

Then, will define collections of models.

Our application allows users to operate on a number of models, so they need to be organized into a special iterable object named Collection. We need the following collections:

Next, we define views.

View present a model or a collection to the application user. A single model or collection can be rendered to be used by multiple views. The views that we need in our application are as follows:

Finally, we define a controller.

A controller allows users to interact with an application. In MVC, each view can have a different controller that is used to do following:

We define BuyerModel properties.

Then, we define SellerModel properties.

After this, we define BankAccountModel properties.

We define InvoiceItemModel properties.

Next, we define InvoiceItemModel methods.

We don't need to store the item amount in the model, because it always depends on the price and the quantity, so it can be calculated.

Now, we define InvoiceModel properties.

We define InvoiceModel methods.

The invoice amount can easily be calculated as the sum of invoice item amounts.

Finally, we define collections.

In our case, they are InvoiceCollection, InvoiceItemCollection, BuyerCollection, and BankAccountCollection. They are used to store models of an appropriate type and provide some methods to add/remove models to/from the collections.

First, we need to create wireframes for an application.

Let's draw a couple of wireframes in this recipe:

Then, we will define view objects.

According to the previous wireframes, we need to have two main views: EditInvoiceFormView and PreviewInvoicePageView. These views will operate with InvoiceModel; it refers to other objects, such as BankAccountModel and InvoiceItemCollection.

Now, we will split views into subviews.

For each item in the Products or Services table, we may want to recalculate the Amount field depending on what the user enters in the Price and Quantity fields. The first way to do this is to re-render the entire view when the user changes the value in the table; however, it is not an efficient way, and it takes a significant amount of computer power to do this.

We don't need to re-render the entire view if we want to update a small part of it. It is better to split the big view into different, independent pieces, such as subviews, that are able to render only a specific part of the big view. In our case, we can have the following views:

As we can see, EditInvoiceItemTableView and PreviewInvoiceItemTableView render InvoiceItemCollection with the help of the additional views EditInvoiceItemView and PreviewInvoiceItemView that render InvoiceItemModel. Such separation allows us to re-render an item inside a collection when it is changed.

Finally, we will define URL paths that will be associated with a corresponding view. In our case, we can have several URLs to show different views, for example:

Here, we assume that the Edit Invoice view can be used for either creating a new invoice or editing an existing one. In the router implementation, we can load this view and show it on specific URLs.

Download Backbone.js.

Visit http://backbone.js and download the Backbone.js library. There are several versions available: production, development, and an edge version.

You can use the production version for the best performance because it has been optimized and minimized. The development version may be good to use when working on the application, so you can use the code completion and debugging features of your IDE. And finally, you can use the edge version of Backbone, but do it at your own risk, because it may not be fully tested.

Download Backbone dependencies.

Backbone.js depends on the Underscore.js library, which can be downloaded from http://underscorejs.org. Underscore is also shipped in three different versions.

Also, Backbone.js depends on either the jQuery or Zepto libraries. These libraries have the same syntax and both provide useful functionality to the developer. They simplify work with the document tree, event handling, AJAX, and JavaScript animations.

For many examples in this book, we are going to use the jQuery library, which can be downloaded from http://jquery.com. It is provided with both the development and production versions.

Create a project directory structure.

If you follow a specific directory structure, it would be easier to find any file and work with it, because such an application structure brings more order into your project. Here is an example of a directory structure that can be used by a simple Backbone application:

Create the main file of the application, which is index.html. It should include third-party libraries and your application files, as shown in the following code:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Backbone.js Cookbook – Application Template</title>
  
    <script src="lib/jquery.js"></script>
    <script src="lib/underscore.js"></script>
    <script src="lib/backbone.js"></script>

    <script src="js/main.js"></script>
  </head>
  <body></body>

</html>

Create the main JavaScript file named main.js that will contain the code of your application.

(function($){

  // Your code is here
  
})(jQuery);

As we include our scripts into the head tag, they are executed before the body content is processed by a browser and before the whole HTML document is loaded.

In a Backbone application, as in many other JavaScript applications, we want to make sure our program starts to run right after the document is loaded, so main.js should look like the following code snippet:

(function($){

  // Object declarations goes here

  $(document).ready(function () {

   // Start application code goes here

  });
})(jQuery);

Define the model by extending it from the Backbone.Model object.

  var InvoiceItemModel = Backbone.Model.extend({

    // Set default values.
    defaults: {
      price: 0,
      quantity: 0
    },

    // Calculate amount.
    calculateAmount: function() {
      return this.get('price') * this.get('quantity');
    }
  });

In the InvoiceItemModel object, we have initialized the default values and performed the business logic, a function that calculates the total amount.

Create a model instance.

    var invoiceItemModel = new InvoiceItemModel({
      price: 2,
      quantity: 3
    });

Define the view that will render the model.

  var PreviewInvoiceItemView = Backbone.View.extend({

    // Define template using templating engine from
    // Underscore.js.
    template: _.template('\
      Price: <%= price %>.\
      Quantity: <%= quantity %>.\
      Amount: <%= amount %>.\
    '),

    // Render view.
    render: function () {

      // Generate HTML by rendering the template.
      var html = this.template({

        // Pass model properties to the template.
        price: this.model.get('price'),
        quantity: this.model.get('quantity'),

        // Calculate amount and pass it to the template.
        amount: this.model.calculateAmount()
      });

      // Set html for the view element using jQuery.
      $(this.el).html(html);
    }
  });

As we can see, our view uses the this.model and this.el properties that are passed to the view when it is created.

    var previewInvoiceItemView = new PreviewInvoiceItemView({
      model: invoiceItemModel,
      el: 'body'
    });

Inside a view, we used the jQuery library to set the content for the element associated with the view $(this.el).html(html). In our case, this.el contains 'body' that is also a jQuery selector.

Such selectors are similar to CSS selectors and allow jQuery to find an arbitrary HTML element using the $() function.

To render a view, we simply need to execute the render() method.

  previewInvoiceItemView.render();

When rendering a view, we also used a templating engine provided by Underscore.js. This templating engine substitutes templates with data and outputs static HTML. More information about templates is available in the Using templates in a view recipe of Chapter 6, Templates, Forms, and UX Sugar.

Start the application.

There are several ways to start an application. If your application has only a single view, you can create a new instance of it and render it manually.

An application should be started right after the HTML page is loaded. Let's write some code that will start a simple Backbone application:

  // When document is ready create the Model and show
  // the View.
  $(document).ready(function () {

    // Create InvoiceItemModel instance and set
    // model attributes.
    var invoiceItemModel = new InvoiceItemModel({
      price: 2,
      quantity: 3
    });

    // Create PreviewInvoiceItemView instance.
    var previewInvoiceItemView = new PreviewInvoiceItemView({

      // Pass our model.
      model: invoiceItemModel,

      // Set element where to render HTML.
      el: 'body'
    });

    // Render view manually.
    previewInvoiceItemView.render();
  });

Define a router by extending Backbone.Router into the Workspace object and setting pairs of routes and callback functions for them inside the routes property that is passed to the extend() method. This gives the router information of which callback should be executed in case the appropriate route is accessed.

  var Workspace = Backbone.Router.extend({
    routes: {
      // Default path.
      '': 'invoiceList',

      // Usage of static path.
      'invoice': 'invoiceList',
    },
  });

Add a callback method to the router object.

    invoiceList: function() {
      var invoiceListView = new InvoiceListView({
        el: 'body'
      });
      invoiceListView.render();
    }

If the user visits index.html or index.html#invoice, the invoiceList() callback is executed, which renders InvoiceListView. Here, InvoiceListView is a simple stub.

Tell Backbone to use this router and start the application.

  $(document).ready(function () {
    new Workspace();
    Backbone.history.start();
  });

Here, we create a new Workspace object and execute the start() method of the Backbone.history object that is used for global application routing. As always, we should start our application right after the HTML page has loaded completely.

Work on the issue queue.

If you found a bug in Backbone.js or want a new feature to be implemented, you can submit your issue to the issue queue at https://github.com/documentcloud/backbone/issues. Before doing this, make sure there is no similar issue; otherwise, you can update the existing issue queue.

Contribute code.

You can submit your own code to the Backbone project. Such a contribution can be very helpful to the community and the project itself.

By using Backbone, you save your own time. By contributing to the project, you save the time of other developers who use it and your own time in the future instead of having to work on the same issue again.

Detailed guidelines for the code contributing process can be found on the wiki page at https://github.com/documentcloud/backbone/wiki/Contributing-to-Backbone.

Work on the documentation of Backbone.js.

The official documentation, which is located at http://backbonejs.org, is based on a recent version of Backbone.js in the GitHub repository. You can improve the documentation by either updating the index.html file or the docs directory. If you want to add a new example, use the examples folder.