Featured in JavaScript Weekly.

Backbone.js is a lightweight framework designed to give “structure to web applications by providing models with key-value binding and custom events, collections with a rich API of enumerable functions, views with declarative event handling, and connect[ions to] existing API[s] over a RESTful JSON interface.” Basically, it helps organize your spaghetti.

Unlike a traditional MVC which has three components, Backbone has six main components: (1) Models – store data; (2) Views – display model data; (3) Collections – group models, like a JavaScript array, (4) Events – allow custom events; (5) Routers – create navigation; and (6) Sync – maps Backbone to server side databases. Because of this, Backbone is sometimes referred to as an MV* framework.

Technically, Backbone is a library and, because of this, it is highly customizable. Its main goal is to generate modular code, meaning it breaks down your code into modules which are independent but work together.

If at any point in this tutorial you want further clarification, I suggest referring to the Backbone documentation or the complete code for this tutorial on GitHub. There is also a helpful book Developing Backbone.js Applications available online. If you’d like additional information on the benefits of Backbone, read this.

A final note: In a standard application, you would probably want to break your code into several .js files and save them in the appropriate directories for  models,  views,  collections and  routers. However, for the purpose of this tutorial, I have included everything in application.js (and later in namespaced-application.js) so you can easily follow along.

[line]

Installing Backbone.js

Getting started with Backbone.js is fairly straightforward. Backbone relies on three JavaScript libraries: (1) Backbone, (2) Underscore and (3) jQuery. To get started with Backbone, simply download these three libraries (minified versions are available) and add the scripts to your index.html file as follows:

In the alternative, you can reference these libraries as follows:

Either way, you want to make sure the files are loaded in the following order: (1) jQuery, (2) Underscore, (3) Backbone. Otherwise, your application may not function as expected.

To make sure Backbone is functioning properly, load the index.html page in Chrome, open the console, and begin typing  Backbone. If Backbone is working, this should autocomplete and you should have access to the following:

[line]

Models

According to the Backbone documentation, “Models are the heart of any JavaScript application, containing the interactive data as well as a large part of the logic surrounding it: conversions, validations, computed properties, and access control.”

In a standard JavaScript file, you may create an Animal class as follows:

In Backbone, your model would look slightly different:

The above code defines the Animal model and sets default values. This code will go in your application.js file (you may name this file whatever you prefer, but make sure to reference the file in  index.html). In addition to defining a class and setting default values, the above model sets a  validate function and a  sleep function (more on  validate later).

Now, if you refresh index.html in your browser, you should be able to create a new Animal with default values:

Accessing attributes is slightly different in Backbone. Instead of simply calling dog.name, you must use the .get function: dog.get('name'). Likewise, you would use .set to set attributes: dog.set('name', 'Biscuit) or:

dog.set({name: 'Biscuit', color: 'brown', sound: 'arf'})  or

var dog = new Animal({name: 'Biscuit', color: 'brown', sound: 'arf'}).

You can easily access all attributes of an object by calling .toJSON as follows:

It’s worthwhile to review the validate section of the Backbone documentation. A few things to remember: (1)  validate is triggered only by .set  or .save, and (2) if you want  validate to be triggered with .set , you need to include {validate: true}:

dog.set('name','a',{validate: true})

For more information on specific error handling, see the Backbone documentation re validate and validationError.

[line]

Views

Backbone views aren’t traditional views like you’d see in a framework such as Rails. In fact, they don’t determine anything about your HTML or CSS. According to the Backbone documentation, “[t]he general idea is to organize your interface into logical views, backed by models, each of which can be updated independently when the model changes, without having to redraw the page. Instead of digging into a JSON object, looking up an element in the DOM, and updating the HTML by hand, you can bind your view’s  render function to the model’s  "change" event — and now everywhere that model data is displayed in the UI, it is always immediately up to date.”

To create an Animal view, you’ll want to first create a custom view class and decide how an Animal will be represented. You may want to override the render function, and specify declarative events, tagName (the HTML element tag),  className or  id. The default tagName is  div, so if you wanted your Animal to be represented as an li, you could add the following to application.js:

The  initialize function watches for changes in a model and executes code as soon as a new model instance is created. As part of the initialize function, you could include a simple console notification which would let you know when a model has been changed (such as through the use of  .set):

The above code watches for all changes. However, if you modified  'change' to 'change:color', it would only watch for color changes.

If you head to your console now, you should be able to create a view and call .el and .$el  (jQuery) on that view, which will show you the view for that object:

el is a reference to a DOM element. All views must have el and use el  to compose their element’s content and insert it into the DOM all at once, making it faster for the browser to render. Upon completion of the above, the following HTML should be rendered by the browser:

Although this works, maintaining this code will be difficult once your views are more complex. To help with this, you may want to render a template.

[line]

Templates

Defining a template function on your views can be helpful when rendering your view by allowing convenient access to instance data. Templates are not a function provided directly by Backbone, but you can define a template using Underscore. Although Underscore is a Backbone dependency, you may want to use a templating engine such as Mustache or Handlebars.js. (I wrote a separate Handlebars.js Tutorial that may be helpful.)

There are internal templates and external templates, and each is as it sounds.

Template syntax may look like the following:

Using the above example, your application.js view code will look like this once you include an inline template:

If you check your console, you will see the same code was rendered from the inline template that was previously included in the render function:

You can also use external templates directly in your HTML:

Once you include the external template, your application.js view code should look like this:

If you head to your console, you should be able to render the same HTML from the external template that you have done twice so far:

[line]

Collections

Collections in Backbone are ordered sets of models. You can bind "change" events so you’re notified when any model in the collection has been modified, listen for "add" and "remove" events,  fetch the collection from the server and access various Underscore methods. Events triggered on a model will also be triggered on the collection, allowing you to listen for changes to the attributes of any model in a collection.

Collections are used when you want to define multiple instances (i.e., instead of defining 10 dogs or 10 animals individually, you can use a collection). The following code can be added to your application.js file:

New models can be added to AnimalCollection individually or as a group. To add models individually, you can add the following to application.js:

If you go to your console, you should see your entire collection:

Adding models individually isn’t very efficient though. If you’d like to add multiple models, you can do so by adding the following to application.js:

As you can see in your console, your collection now contains the above three models:

[line]

Collection Views

Thus far, we have AnimalView for individual Animal models, but we don’t have a view for AnimalCollection that compiles all Animal model views. To create a collection view, add the following to your application.js file:

If you refresh your browser now, the entire collection you added above will be rendered:

[line]

Namespacing

Namespacing helps avoid the potential collision of global variables (declared with  var), thereby reducing the likelihood that your code may break.

I have prepared a separate JavaScript file,  namespaced-application.js, which is now referenced in index.html instead of application.js (and included on GitHub for your reference). Your full namespaced JavaScript file should look like this, while still producing the same output as above:

For more information, see the namespacing chapter in Developing Backbone.js Applications.

[line]

Events

As you recall, three  .click events were included in your Animal view (see above). These events can now be defined. If you start with the first event, alertTest, you should be able to test your click functionality by clicking on each model in the view after adding the following code:

You can now add buttons or bind the click event to some other HTML element with the .edit and .delete classes. Prior to doing so, you want to comment out the alertTest event and function above, otherwise when you click to edit or delete, you’ll continue to receive the test alert.

The external template in index.html will now contain two buttons:

Your browser should render the following:

Now, you have to include the editAnimal and deleteAnimal functions, as well as the modify the  initialize function and add any helper functions, such as  remove:

Some of this code is best understood by reviewing the events section of the Backbone documentation, which explains things like 'change' and 'destroy'.

You could also create a simple form for adding new Animal models.

[line]

Routing

Backbone routing is useful when dealing with hashtags (typically routed as anchors on a page). Routers interpret anything after a  #, so the links in your application should contain a  # (i.e., http://tutorial.com/#backbone). Backbone uses two routing styles – :params (match specific URL components, i.e. http://tutorial.com/:route) and  splats (match a variety of URL components, i.e. http://tutorial.com/*default).

If you’re a Rails developer, this should seem familiar. However, the routing system in Backbone probably closer resembles Sinatra than Rails.

First, add the Router namespace:

Next, define your routes with the Backbone router (typical applications will only include one router, and would probably be included in a separate routes.js file), and start your Backbone history:

If you enter the above routes and watch your console, you should see the following:

Backbone.history handles  hashchange events or pushState in your application. For a better idea of how Backbone routes are used in an actual application, and why they’re important, check out this helpful Code Project article.

For additional information, it may be worthwhile to read the Backbone documentation on routing and history, or this Backbone tutorial on routing.

[line]

Conclusion

As a reminder, the complete code for this tutorial can be found on GitHub. Future tutorials include Handlebars.js and Node.js.

Please feel free to contact me with any questions or comments.

Related Posts