In essence, it takes us from this:

var TweetStream = function() {
    this.twitter = new TwitterService();
};
 
TweetStream.prototype.streamTweets = function() {
    …
    var tweets = this.twitter.getTweets();
    …
};
 
var stream = new TweetStream();
stream.streamTweets();

To this:

var TweetStream = function(twitter) {
    this.twitter = twitter;
};
 
TweetStream.prototype.streamTweets = function() {
    …
    var tweets = this.twitter.getTweets();
    …
};
 
var twitter = new TwitterService();
var stream = new TweetStream(twitter);
stream.streamTweets();

So what’s the big deal?

In the first example, TweetStream creates the TwitterService instance. TweetStream is forced to have a knowledge of (1) the exact “class” it should use to communicate with Twitter, (2) where and how to access the constructor, and (3) how to create an instance and appropriately initialize the object (passing parameters to the constructor, calling methods after the fact, etc.).

In the second example, TweetStream does not need to know any of these things since TwitterService is created by a third party and later passed into TweetStream. TweetStream only needs to know how to interact with the instance it is passed.

Although seemingly benign, the additional knowledge that TweetStream is forced to have in the first example increases its coupling to its dependencies while decreasing its own cohesion. The additional coupling leads to code that can be difficult to test and less flexible at runtime. If we were to “inject” the dependencies rather than forcing TweetStream to create or find them, we can easily mock dependencies during unit tests and provide them directly to the subject being tested. At runtime, we can easily swap out the object being provided as a dependency based on rules or contexts.

Inversion Of Control Containers

So what does this have to do with an IoC container? An inversion of control container, or IoC container for short, assists in dependency injection and essentially fills three roles. These roles are often split between a container and an injector, but for simplicity I’ll address them as though they are one in the same. Let’s have a look at each role.

Dependency Rule Registry

In our case study, TweetStream knows it needs a service to talk to Twitter. Depending on the dependency injection implementation, TweetStream can request this dependency in a variety of ways. In JavaScript, where static typing, interfaces, and language-based annotations don’t exist, the dependency would generally be requested by a name in the form of a string. For example, TweetStream may state that it needs “twitterService” or “twitter” or “TheTwits”–whatever name seems reasonable. The important part is that some actor in the system needs to match up this name with a rule for how to create or retrieve the dependency.

That’s where the IoC container comes in. The IoC container might have rules like the following:

• When “twitter” is requested, provide a new instance using the TwitterService constructor.
• When “chat” is requested, provide whatever is returned from ChatFactory.
• When “logger” is requested, provide a singleton instance of AsyncLogger.
• When “dialog” is requested, provide this specific object.
• When “rank” is requested, provide the value 1337.

Injector

Now with our rules defined, we can use them to create or retrieve a dependency. Let’s say our object to receive dependencies–which we’ll call our injectee–is provided to the IoC container for dependency injection. Let’s say, for example, the injectee requests “chat” and “dialog” dependencies. The IoC container looks up the rule mapped to “chat”, runs ChatFactory which happens to instantiate a chat object and configures it so it’s all ready to go, then injects the chat object into the injectee. The container then looks at the rule for “dialog”, and, by golly, when the rule was being configured on the IoC container, a specific object was provided to the IoC container that should always be used when the “dialog” dependency is requested. The IoC container then provides that specific object to the injectee. If another injectee later asked for the “dialog” dependency, the same object would be provided to that injectee as well. As you can see, the rules offer quite a bit of flexibility.

In summary, the injector uses rules to create or retrieve dependencies and inject them into objects requesting them.

Dependency Object And Value Registry

In our first two rules, we use a constructor and a factory to create dependency objects at the moment they are called for:

• When “twitter” is requested, provide a new instance using the TwitterService constructor.
• When “chat” is requested, provide whatever is returned from ChatFactory.

On the other hand, some rules require that the IoC container hold onto dependency objects or values so they can be provided as dependencies to injectees at a later time rather than being re-created each time they are requested. The last three rules I listed pertain here:

• When “logger” is requested, provide a singleton instance of AsyncLogger
• When “dialog” is requested, provide this specific object.
• When “rank” is requested, provide the value 1337.

In each of these, the container is holding onto objects or values so they can be provided as dependencies to injectees at a later time. In this manner, the IoC container becomes a registry of objects and values.

I’m kind of sneaking this in here, but in the case of the rule providing a singleton instance, you can avoid the woes of self-enforced singletons and reap the bounties of context-based singletons. Oh the wonders of IoC containers! Check out this post by Joel Hooks for more on this.

Less Hand-waving, More Code

To make a long story short, I’ve been playing around with dependency injection in JavaScript lately. It’s still fairly new territory in this JavaScript world of ours though is becoming increasingly more popular thanks in large part to AngularJS which provides dependency injection out of the box. DeftJS is also melding dependency injection into frameworks like Ext JS and Sencha Touch.

In my frolicking about a year ago, I felt like cooking up an expressive, dependency-free, lightweight IoC container I called Injector.js which you can find on GitHub. Although the code may happen to prove useful for someone, I mention it here with the mere hope that the examples in the readme and the unit tests can help solidify some of the concepts I’ve discussed here.

In my experience, IoC containers become most powerful when integrated with an application framework that can auto-inject dependencies while requiring as little boilerplate as possible from the developer. Although this isn’t intended to be a sales-pitch, AngularJS has nicely integrated dependency injection and I recommend becoming familiar with its workflow even if just for the learning opportunity it provides.

More Reading And Watching

Check out this fantastic presentation by Miško Hevery on why dependency injection is so important for clean and testable code. Seriously, don’t miss it.

If you’re the reading type, check out this article by Martin Fowler for a more formal and authoritative description of inversion of control and dependency injection.

These are slides from presentations I gave at Adobe on February 5, 2013 and April 30, 2013.

Adobe Developer Connection: Dependency Management with RequireJS
Appliness: Dependency Management with RequireJS ]]> http://aaronhardy.com/javascript/adc-appliness-dependency-management-with-requirejs/feed/ 0 http://aaronhardy.com/javascript/dependency-management-with-requirejs/ http://aaronhardy.com/javascript/dependency-management-with-requirejs/#comments Mon, 22 Oct 2012 23:53:59 +0000 Aaron Hardy http://aaronhardy.com/?p=1421 Presented at 360|Min 2012 in Las Vegas, NV.

In JavaScript Architecture: Organization and Quality, we discussed the importance of breaking apps down into very small, decoupled pieces following the single responsibility principle. Small pieces are generally easier to comprehend than a mess of large peices.

Some devs coming from other languages feel like they can only build a few large, spaghetti JavaScript files for their app. I tend to think this may be caused by three reasons:

• That’s the way JavaScript has been done in the past.
• Loading many JavaScript files requires many HTTP requests resulting in longer load times.
• Dependency management is hard in JavaScript.

Don’t stoop to these excuses. We can do better than that and today there are fantastic libraries and standards that can help us out. However, let’s see what the above problems mean.

That’s the way JavaScript has been done in the past. Unfortunately, that’s true. For years many teams developed within one or two large JavaScript files containing thousands of lines of code. It goes without saying that maintainability was very poor. It’s difficult to wrap our minds and IDEs around thousand of lines of interoperating code and also a nightmare with version control in a team environment. I do believe this is a large contributor to why JavaScript has had a bad wrap in the dev community for so long.

Loading many JavaScript files requires many HTTP requests resulting in longer load times. It’s true. Each time a JavaScript file is loaded it requires the overhead of an inidiviual HTTP request and, unfortunately, if you list many script tags in your page the files will load in sequence, not in parallel.

Dependency management is hard in JavaScript. By splitting code out into many files, you must keep track of which files depend on each other and make sure they’re loaded in the right order. This can be a messy long list and easy to mess up later down the line. For example:

<script src="script3.js"></script>
<script src="script1.js"></script>
<script src="script13.js"></script>
<script src="script7.js"></script>
<script src="script6.js"></script>
<script src="script12.js"></script>
<script src="script4.js"></script>
<script src="script11.js"></script>
<script src="script5.js"></script>
<script src="script9.js"></script>
<script src="script8.js"></script>
<script src="script10.js"></script>
<script src="script2.js"></script>

This is troubling enough on a single-man project but even more-so within a team.

Modules

Let’s get nostalgic for a moment. A few years back, using JavaScript on the server-side was just starting to get hot. Server-side libraries and JavaScript engines were being deployed but they didn’t have a good, standard API for working with one another and defining dependencies. Getting one library to work with another required some finagling and it was obvious that if JavaScript were to scale it would need some common APIs.

In January 2009, Kevin Dangoor wrote a blog post titled What Server Side JavaScript Needs outlining just that–what server-side JavaScript needed. The list included:

• Cross-interpreter standard library
• Standard interfaces
• Standard way to include other modules
• Package up code for deployment and distribution
• Install packages and their dependencies
• Package repository

As a means to fulfill these needs, he created a Google group named ServerJS where like-minded folk could collaborate. Soon enough, the group realized that many of these goals weren’t necessarily limited to the server-side and renamed the group to CommonJS.

One of the standards that CommonJS worked toward was that of a module. A module is a contained piece of code (How’s that for vague?) that defines not only that it is a module itself but which other modules it depends on to correctly function. When calling for module B, module B might call for module G and module M, which might call for modules D and W. By having a module standard, dependency management becomes easier. Rather than keeping some sort of implicit master list that must be kept in order, each module just defines its own dependencies and that mapping can be used to determine required resources and the order in which they must be loaded.

AMD

The module concept was great for server-side development as it addressed how to synchronously load modules based on dependency definitions, but the JavaScript devs on the browser-side got a bit jealous. Why should such awesomeness be confined to the server? Sure, module loading needs to be done asynchronously in the browser, but that didn’t mean the concept of modules and dependency definitions couldn’t be applied.

The Asynchronous Module Definition, or AMD, was born for this purpose. It takes the module and dependency definition API from the server-side and applies it to the asynchronous paradigm of the browser.

RequireJS

So what does RequireJS have to do with this? Well, even though we can define our modules and their dependencies with AMD, we need something smart that can take this dependency map, load the modules, and execute the modules in order. That’s the role RequireJS plays. Both RequireJS and AMD are open source, popular, and well-curated by James Burke.

Defining and Requesting Modules

At this point let’s jump straight into some code and hopefully the concepts will start to solidify. Almost always, a module is defined within a single file and, vice-versa, a single file only contains a single module definition. Defining a module, at its core, is as simple as the code below. Let’s assume it’s within a file called book.js.

define({
    title: "My Sister's Keeper",
    publisher: "Atria"
});

We now have a book module. define() is a RequireJS function. When we call it, we’re essentially saying, “Register what I’m passing you as a module.” By default, RequireJS assumes the module name is the file path following the base url (don’t get your panties in a twist–we’ll get to that in a minute) excluding the extension. In this case, that means that “book” is our assumed module name. When other code asks RequireJS for the “book” module, RequireJS will return the object we just defined above. Now let’s make a “bookshelf” module in a new file named bookshelf.js and see how we can request the book module into it.

define([
	'book'
], function(book) {
	return {
		listBook: function() {
			alert(book.title);
		}
	};
});

Notice this one’s a bit different than the book module. The book module didn’t have any dependencies so it was a bit simpler. Here, we’re defining an array of dependencies for our bookshelf–in this case, book. The second parameter is a callback function. If book.js hasn’t been loaded into the app yet, RequireJS will go fetch it from the server. Once book.js is loaded and the book module is registered, RequireJS will execute our callback function and pass the module (the book object we defined previously) in as a parameter. The argument name isn’t technically significant. We could have just as easily said function(a1337Book) or used whatever name we wanted. In this case, it makes sense to have our argument name match the module name. Whatever object we return from this callback function will be registered with RequireJS as the bookshelf module. In our case, it’s an object with a listBook() method that alerts the book’s title.

RequireJS tries to be as efficient as possible when loading multiple modules. For example, if multiple dependencies are listed, RequireJS will load all the dependencies as fast as possible in parallel.

App Setup

So…how do we get this party started? Let’s first start by getting our html page set up. Here’s how it looks:

<!DOCTYPE html>
<html>
	<head>
		<title>RequireJS Example</title>
		<script data-main="js/main" src="js/libs/require.js"></script>
	</head>
	<body/>
</html>

Quite literally, you can build a large application without adding anything else to your html file just by manipulating the body’s content using JavaScript and loading html snippets/templates using Require. We’ll get there. For now, take notice that there’s a data-main attribute. This tells RequireJS where our bootstrap file is–in our case, it’s main.js that lives under a js directory (it assumes main has a js extension).

main.js is what we could call our bootstrap file. We’ll make ours look like this:

require([
	'bookshelf'
], function(bookshelf) {
	bookshelf.listBook();
});

Because we specified this file as our data-main in our html file, RequireJS will load it as soon as possible and it will be immediately executed. You’ll notice this has a lot of similarities to our previous modules but instead of calling define() it calls require(). The define() function–at least when dependencies are defined–really does three things: (1) loads the dependencies specified, (2) calls the callback function once dependencies are loaded, and (3) registers the return value from the callback function as the module. The require() function only does #1 and #2, not #3–hence the function names “define” vs. “require”. In the case of main.js, it’s just a bootstrap file. I don’t need to have a “main” module registered with RequireJS because nothing will be calling for it as a dependency.

Our bootstrap lists our “bookshelf” module as a dependency. Assuming the bookshelf module hasn’t already been registered with RequireJS, it will load bookshelf.js. Once it loads bookshelf.js, it will see that bookshelf has the book module listed as a dependency. If the book module hasn’t already been registered, it will then load book.js. Once that’s done and book and then bookshelf have registered their respective objects as modules with RequireJS, the callback in main.js will be executed and bookshelf will be passed through. At that point we can do whatever we want with bookshelf. If needed, we can list multiple module dependencies and they will all be passed into the callback as soon as they’re all loaded and registered with RequireJS.

Configuration

Previously I mentioned the concept of a base url. By default, the base url is whatever directory contains the bootstrap file. In my case, I put main.js under a js directory along with book.js and bookshelf.js. This means, in my case, my base url is /js/. Now let’s say instead of placing all my js files directly under the js directory, I moved book.js and bookshelf.js to /js/model/. Now my main.js would need to look like this:

require([
	'model/bookshelf'
], function(bookshelf) {
	bookshelf.listBook();
});

Now main knows the correct location of bookshelf.js. Likewise, bookshelf.js would list the book dependency as model/book even though book and bookshelf live in the same directory.

This brings us to RequireJS configuration. At the top of my bootstrap file, I usually perform my configuration. main.js might look like this:

require.config({
	baseUrl: '/another/path',
	paths: {
		'myModule': 'a/b/c/d/myModule'
		'templates': '../templates',
		'text': 'libs/text',
	}
});
 
require([
	'bookshelf'
], function(bookshelf) {
	bookshelf.listBook();
});

In this case, I’ve manually changed my base url to something completely different. Personally, I’ve never needed to configure this but it’s there to demonstrate one of the many configuration options available. I also demonstrated how to configure paths. Paths are really just shortcuts. In this case, rather than having to type out “a/b/c/d/myModule” when listing dependencies, I can just type “myModule”. I’ve set up a path (shortcut) for accessing a templates directory that is a sibling to my js directory. I’ve also set up a path (shortcut) for accessing the RequireJS text! plugin more easily.

Class Modules

So far, our modules have all been object instances; bookshelf was an object and book was an object. In reality, modules are very often classes. When using Backbone, modules are classes much more often than not. The bookshelf class needs the book class, for instance. It can then instantiate a bunch of books or whatever it needs to do using the book class. If an instance of the class needs to be passed to different Backbone views, for example, it would be passed through the recipient view’s constructor or other method. You’ll start to see that listing dependencies is similar to listing imports in languages like Java or ActionScript. It’s essentially giving you access to another class that you can then use within the class you’re defining. You just so happen have the ability to also define and retrieve object instances as modules if you really want to. Hopefully this will become more obvious in the next example.

RequireJS + Backbone

Using the knowledge from the previous articles in this series and our new-found knowledge of modules, let’s see an integrated example. In essence, we have a collection of book models. We’re calling the collection a bookshelf. We have a bookshelf view that loops through the books in the bookshelf, creating a book view for each book in the bookshelf. The book view displays information about the book. The views, frankly, are over-architected for the simple stuff we’re doing here, but I think this demonstrates the integration of RequireJS and Backbone nicely. If it’s still unclear, please post a comment and I’ll do my best to answer.

index.html:

<!DOCTYPE html>
<html>
	<head>
		<title>RequireJS Example</title>
		<script data-main="js/main" src="js/libs/require.js"></script>
	</head>
	<body/>
</html>

js/main.js:

require.config({
	'paths': {
		'jquery': 'libs/jquery',
		'backbone': 'libs/backbone',
		'underscore': 'libs/underscore'
	},
 
	shim: {
		'backbone': {
			// These script dependencies should be loaded 
			// before loading backbone.js
			deps: ['underscore', 'jquery'],
			// Once loaded, use the global 'Backbone' 
			// as the module value.
			exports: 'Backbone'
		},
		'underscore': {
			// Use the global '_' as the module value.
			exports: '_'
		}
	}
});
 
require([
	'view/bookshelf-view'
], function(BookshelfView) {
	$(document).ready(function() {
		new BookshelfView({
			el: $('body')
		});
	});
});

js/view/bookshelf-view.js:

define([
	'backbone',
	'underscore',
	'model/bookshelf',
	'view/book-view'
], function(Backbone, _, Bookshelf, BookView) {
	return Backbone.View.extend({
		initialize: function() {
			this.collection = new Bookshelf([
				{
					title: 'A Tale of Two Cities',
					author: 'Charles Dickens'
				},
				{
					title: 'The Good Earth',
					author: 'Pearl S. Buck'
				}
			]);
 
			this.render();
		},
 
		render: function() {
			this.collection.each(function(book) {
				var bookView = new BookView({
					model: book
				})
				this.$el.append(bookView.$el);
			}, this);
		}
	});
});

js/view/book-view.js:

define([
	'backbone',
	'underscore'
], function(Backbone, _) {
	return Backbone.View.extend({
		initialize: function() {
			this.render();
		},
 
		render: function() {
			this.$el.html('Title: ' + this.model.get('title') +
					'; Author: ' + this.model.get('author'));
		}
	});
});

js/model/bookshelf.js:

define([
	'backbone',
	'model/book'
], function(Backbone, Book) {
	return Backbone.Collection.extend({
		model: Book
	})
});

js/model/book.js:

define([
	'backbone'
], function(Backbone) {
	return Backbone.Model.extend({
		// Intended attributes:
		// title
		// author
		// genre
 
		defaults: {
			genre: 'historical'
		}
	})
});

Loading Non-Modules

Some libraries you want to use in your project don’t conform to the AMD spec. In fact, Backbone and Underscore have had their flirts with conforming to AMD but, at the moment of this writing, aren’t AMD modules. Backbone has no concept of modules, dependency loading, RequireJS, or any of that. It just sets a global variable called Backbone and expects you to use it. This means if we were to just add the backbone.js file to our project and list Backbone as a dependency from one of our modules, it wouldn’t work. RequireJS will load backbone.js, but nothing in backbone.js registers itself as a module with RequireJS. RequireJS will throw up its hands and say something like, “Well, I loaded the file, but I didn’t find any module in there.”

For this reason, RequireJS has provided us the ability to specify a “shim” configuration which you can see in the example above. I’ll repeat it here:

require.config({
	...
 
	shim: {
		'backbone': {
			// These script dependencies should be loaded
			// before loading backbone.js
			deps: ['underscore', 'jquery'],
			// Once loaded, use the global 'Backbone'
			// as the module value.
			exports: 'Backbone'
		},
		'underscore': {
			// Use the global '_' as the module value.
			exports: '_'
		}
	}
});

Like the comments say, for Backbone we need to make sure underscore and jQuery are loaded first since they are dependencies of Backbone (that’s the deps part) and then we’ll make the global Backbone variable act like a module (that’s the exports part). Underscore doesn’t have any dependencies but it’s not AMD compatible so we’ve configured the global variable _ to act like a module.

Now, we don’t always have to make everything act like a module. Let’s say we just want to load a single non-AMD JavaScript library file we downloaded off the web. It doesn’t depend on anything else and we don’t want to set up a shim for it for whatever reason. We just want to make sure the file is loaded and then just access the global variable like we normally would if we weren’t using RequireJS. That’s not a problem; we can load it in and access it using the global variable. Here’s an example of how we would do so:

define([
	'js/libs/coolLib.js'
], function() {
	console.log(window.coolLib);
});

A few things to notice here: First, our path to the file includes everything from the directory where our html file is located. This is unlike loading a module which would include everything after our “base url” (read above if you don’t remember what this is). Second, our path includes the file extension. This is unlike loading a module which would exclude the extension. Third, because it’s not a module, RequireJS won’t pass anything into our callback function. At that point we just reference coolLib however the coolLib library dictates. RequireJS is just loading the file and, once it’s loaded, calls our callback function. Nothing special.

Loading Templates

Back in JavaScript Architecture: Underscore.js, we discussed how to break our HTML into templates to prevent it from mingling too closely with our JavaScript. In the examples we used, we put our HTML templates within script tags. I then posed the question, “You might rightfully be wondering how this is scalable if you start to have hundreds of templates in your html file or how you might be able to load them asynchronously only when needed.” This is also where RequireJS helps out.

RequireJS has a nice plugin called text!. You might think I’m really excited about it because I put an exclamation point next to it. While I do admit it’s pretty south-beach sexy, really that’s just the nomenclature of RequireJS plugins because you type something like “text!myTemplate” when using them. The text! plugin allows us to load in files of text–in our case, HTML templates. Let’s see how this works.

First we’ll download and place the text! plugin file in js/libs.

We’ll place book.tpl.html located under a templates directory that’s a sibling to our js directory:

<span class="label">Title:</span><span class="value"><%= title %></span><br/>
<span class="label">Author:</span><span class="value"><%= author %></span><br/>
<span class="label">Genre:</span><span class="value"><%= genre %></span>

Add some paths to our RequireJS configuration in our main.js to make it easier to use in our modules:

require.config({
	'paths': {
		'jquery': 'libs/jquery',
		'backbone': 'libs/backbone',
		'underscore': 'libs/underscore',
		'templates': '../templates',
		'text': 'libs/text'
	}
});

Then use the template in book-view.js:

define([
	'backbone',
	'underscore',
	'text!templates/book.tpl.html'
], function(Backbone, _, template) {
	return Backbone.View.extend({
		_template: _.template(template),
 
		initialize: function() {
			this.render();
		},
 
		render: function() {
			this.$el.html(this._template(this.model.toJSON()));
		}
	});
});

Notice that the template argument is a string variable holding the exact html as found in our template html file. Then, we use underscore to convert it to a compiled template. We run our book model attributes through the template on render(). Finally, we update our element’s inner html with the result.

So what about all those potential HTTP requests? Here’s where we optimize…

Optimization

We’ve broken down all our JavaScript and HTML into granular pieces. Now we potentially have hundreds of files and unless we do some optimization we would be making hundreds of HTTP requests. Fortunately, we can leverage the RequireJS optimizer.

Generally, you set up the optimizer to run on your server before deploying code. The RequireJS optimizer takes your app files, minifies them (shortens your code to make the files really small), and then concatenates them (smashes them together to make a single file). In the end, you end up with a single file that contains both your JavaScript and your HTML templates. After index.html loads RequireJS, it will load our main.js file. Our main.js file, this time, will not only contain our expected main.js code but all the minified, concatenated code of the rest of our app–both JavaScript and HTML templates. Everything in the file will register itself with RequireJS. When main starts asking for dependencies and those dependencies start asking for dependencies, RequireJS will recognize that all those modules have already been loaded and forego loading them again.

The optimizer has a smattering of options. You can optimize your app down to a few different files representing sections of your app instead of a single large file. You can also use different minifier libraries, exclude files from concatenation, or even minify CSS.

Learn More

We’ve covered a lot of content but there’s plenty more to learn about dependency management. I’ve written a separate article on the Adobe Developer Connection that might catch your interest. Also, the RequireJS website is a great place to start. If you’re interested in seeing more examples of Backbone + RequireJS, dig into this Todos App example. And, as always, feel free to provide feedback or ask questions below!

In JavaScript Architecture: Backbone.js Views we discussed how to build dynamic apps that change views on the fly using JavaScript. Because view-switching is done without reloading the page or transferring control to a separate page, these are called single-page applications. Single-page applications pose a few issues we need to address:

• When users hit their browser’s back button, they will be taken away from the app completely rather than back to a previous view within the app itself.
• Users are only able to link to or bookmark the app itself–not a specific view within the app.
• Deep views within the app may not be crawlable by search engines.

We want a great experience for our users. Successful apps behave as users would logically expect and users should feel like they can easily navigate back to where they were previously.

Like the topics we’ve addressed before, these issues aren’t specific to Backbone. It’s an issue that naturally arises in any single-page app. Fortunately, Backbone does a great job at addressing it and has a simple API.

Examples

This concept is most easily taught by example so let’s assume we’re building an app that sells shirts. We’ve built it out so we show a grid of shirt images and when the user clicks on a shirt, a panel slides out that covers half of the window and contains more details regarding that specific shirt. Without some extra work, if users are on this extra details view and click the back button in the browser, they will be taken out of the app completely rather than just hiding the extra details view.  This is because, technically, the details view is not a new html page–it’s just another “view” within the same html page.

The browser has no concept of views that are changing within your app and therefore cannot automatically register history steps in this regard. As we discussed in JavaScript Architecture: Backbone.js Views, the definition and granularity of a view can become very blurry. For example, if we pop up a settings panel after a user clicks on a gear icon, does the settings panel merit a history step in the browser so that if the user clicks the back button the panel closes? As much as we would like browsers to figure this out automatically, it’s really a user experience judgement call on our part and we must tell the browser when to register a new history step. This gives us a lot of power.

For starters, let’s take a look at a simple example with Backbone:

<!DOCTYPE html>
<html>
	<head>
		<meta http-equiv="content-type" content="text/html; charset=UTF-8">
		<title>Backbone Example</title>
	</head>
	<body>
		<script src="js/libs/jquery.js"></script>
		<script src="js/libs/underscore.js"></script>
		<script src="js/libs/backbone.js"></script>
		<script type="text/javascript">
			$(function() {
				var AppRouter = Backbone.Router.extend({
					routes: {
						"shirt/id/:id": "showShirt"
					},
 
					showShirt: function(id) {
						alert('Show shirt with id ' + id + '.');
					}
				});
 
				var appRouter = new AppRouter();
				Backbone.history.start();
			});
		</script>
 
		<a href="#shirt/id/5">Shirt with id of 5</a><br>
		<a href="#shirt/id/10">Shirt with id of 10</a><br>
		<a href="#shirt/id/15">Shirt with id of 15</a><br>
	</body>
</html>

You can see we have three links each linking to a shirt with a different id. Notice that the pound sign at the beginning of each link url (e.g., #shirt/id/5) is important as it tells the browser we’re neither moving to a new html page nor refreshing the current page. It’s formally known as a fragment identifier and has been a web standard for quite a while.

In our example, We’ve also set up a backbone router with “routes” which are essentially url patterns that are meaningful to our app. In this case, we have set up a single route, shirt/id/:id, with a handler of showShirt(). The :id portion is called a parameter part. If a user navigates to the url <current_page>/#shirt/id/123123, the fragment would qualify as a match and the id (123123) would be passed as a parameter to the showShirt() function. In our example, if the user clicks the first link we set up, the url will be changed to <current_page>/#shirt/id/5 and Backbone will subsequently call showShirt(5).

To have a little fun, let’s go nuts for donuts and get crazy up in here:

<!DOCTYPE html>
<html>
	<head>
		<meta http-equiv="content-type" content="text/html; charset=UTF-8">
		<title>Backbone Example</title>
	</head>
	<body>
		<script src="js/libs/jquery.js"></script>
		<script src="js/libs/underscore.js"></script>
		<script src="js/libs/backbone.js"></script>
		<script type="text/javascript">
			$(function() {
				var AppRouter = Backbone.Router.extend({
					routes: {
						":product/:attribute/:value": "showProduct"
					},
 
					showProduct: function(product, attribute, value) {
						alert('Show ' + product + ' where ' + attribute + ' = ' + value + '.');
					}
				});
 
				var appRouter = new AppRouter();
				Backbone.history.start();
			});
		</script>
 
		<a href="#shoe/size/12">Size 12 shoes</a><br>
		<a href="#shirt/id/5">Shirt with id of 15</a><br>
		<a href="#hat/color/black">Black hats</a>
	</body> 
</html>

This time we set up our route with three parameter parts. Because there are three parameter parts, three parameters will be passed into showProduct(). Easy enough.

Deep-linking

Now that we have our routes set up, we can deep-link to a specific view within our app. For example, a user might click on the size 12 shoes link which changes the url in their browser to http://code.aaronhardy.com/backbone-router-multi-param/#shirt/id/5. The user may want to share that shirt with a friend so they copy the link and send it in an email. When the user clicks on the link, the app loads, and backbone sees that the url already matches a route. showProduct() will then be automatically called which will immediately show the product details panel to the user. Go ahead, click on the link above and see the concept in action.

Showing requested content

In the above examples we’re just alerting information about the parameter parts. In a real app, the user would expect the app to switch to an appropriate view and load appropriate data. How you handle going from the showProduct() function to switching views has been left up to you. However, one option is, rather than calling a function within the router itself, views can watch the router for route events and update themselves accordingly:

<!DOCTYPE html>
<html>
	<head>
		<meta http-equiv="content-type" content="text/html; charset=UTF-8">
		<title>Backbone Example</title>
	</head>
	<body>
		<script src="js/libs/jquery.js"></script>
		<script src="js/libs/underscore.js"></script>
		<script src="js/libs/backbone.js"></script>
		<script type="text/javascript">
			$(function() {
				var AppRouter = Backbone.Router.extend({
					routes: {
						":product/:attribute/:value": "showProduct"
					}
				});
 
				var appRouter = new AppRouter();
 
				var MyView = Backbone.View.extend({
					initialize: function(options) {
						options.router.on('route:showProduct', function(product, attribute, value) {
							alert('Update to show ' + product + ' where ' + attribute + ' = ' + value + '.');
						});
					}
				});
 
				window.myView = new MyView({router: appRouter});
 
				Backbone.history.start();
			});
		</script>
 
		<a href="#shoe/size/12">Size 12 shoes</a><br>
		<a href="#shirt/id/5">Shirt with id of 5</a><br>
		<a href="#hat/color/black">Black hats</a>
	</body>
</html>

Another option is to share a backbone model amongst the router and views. The router can then set a property on the model and the views can then respond to change events coming from the model.

Fragment identifier vs. pushState

Using fragment identifiers (#) or hashbangs/shebangs (#!) in the manner described above or as used by Twitter (https://twitter.com/#!/Aaronius), Grooveshark (http://grooveshark.com/#!/artist/Gotye/49212), or GMail (https://mail.google.com/mail/ca/#label/isys) doesn’t come without controversy, controversy, and more controversy.

In the end, the answer to the controversy is to use the new HTML5 History (more commonly known as pushState) standard that allows us to change the browser url and manage history steps without using fragment identifiers or forcing a page refresh on the user. The biggest roadblock to this new standard is obtaining browser support, particularly Internet Explorer support. For browsers that don’t support HTML5 History, a fallback must be available which usually entails page refreshes as the user navigates through the app.

Once you’re ready to support pushState, you’ll be glad to know Backbone supports it on an opt-in basis. Read more about how to set up Backbone for pushState.

More Juiciness

Backbone’s router and history have even more options and features so I suggest you check out their respective documentation. Thanks for reading and, as always, feel free to post a comment.

Tech-agnostic concepts

At this point of the series I really want to emphasize that the core concepts I’ve explained and will explain are not unique to Backbone; they’re unique to apps with state and dynamic views. I’m merely using Backbone as an illustration of a concrete tool that can be used to solve problems common to this type of app in general. The concept of “views” is no different.

What is a view?

If you’re coming from a different language or even a different library, you may be familiar with words like component, widget, or control. You can ask 10 engineers what they think those terms mean and you’ll likely get 10 different answers…or 30 if they think the terms are different from each other. The term view is just another one to throw on the pile and is equally ambiguous. It’s not all that unfortunate. Indeed, its usage can be quite flexible and its granularity disparate.

In the traditional web of requesting a new page for each section of a website, we may consider each page a view. Indeed, it is. In modern apps, it’s more common to have a single page and, as the user interacts with the page, portions of the page change. Those dynamic portions could likewise be called views. Within a dynamic portion of the page, there may be a toolbar that affects a list of customers. The toolbar could be considered a view. The list of customers could be another view. Each customer row inside the list of customers may be its own view. The row may contain a toggle button which is yet another view. The point is, in the Backbone world, the term view doesn’t necessary mean “a section of your website”. It can be, and oftentimes should be, much more granular than that.

At a technical level, a Backbone view is simply a JavaScript object that manages a specific DOM element and its descendants. If view A manages DOM element A and its descendants, no other view should touch DOM element A or its descendants. That’s view A’s domain. If you want to change the DOM elements of view A, go through view A’s API.

That said, a view can have sub views. In the example above, I mentioned a list of customers being a view and each customer row being a view. The customer row owns its DOM elements. The parent list view should not touch DOM elements within the customer row view. Is there a model the row should render? Pass the model to the customer row view. At that point, it’s the row view’s job. Throw it over the wall and forget about it.

With jQuery you’ll be heavily tempted to just change elements anywhere on the page willy-nilly because it’s so easy. It’s the fastest way to accomplish your task before the demo with your boss that starts in five minutes. The unfortunate truth is that structure, robustness, and scalability are not the easiest path in the short-term. In the long-term, though, they are absolutely critical to the success and future of the product and ultimately will establish the easiest path.

View granularity

So how granular should a view be? You’ll be hard-pressed to find a definite answer but here are a few guidelines. Is your view getting bloated with hundreds of lines of code? Try to break it up into smaller views. Is a single view accomplishing multiple, unrelated tasks (termed as having low cohesion)? Break it up into smaller views with distinct tasks. Do you find yourself wanting to copy-paste a portion of a view into other views? That portion should likely be its own view. Does your view manage a single DOM element that has no DOM descendants and is very simple like a single html link? It can likely be safely merged up with the parent view. When in doubt, choose many small views over a few large ones.

For you visual learners, take my current Twitter feed as an example. Look around this page and think about how you might divide it up into views and why.

I’m not going to tell you there’s a right answer, but here’s an idea of how I might divide it up:

View isolation and synchronization

We’ve talked about eventful models and collections and how they can be used to synchronize and drive multiple views without the views having to be aware of each other. The idea of view isolation and black-boxing is a very, very critical concept. So important we’re going to cover it again.

Let’s take a closer look at my Twitter feed. Let’s say I put my cursor in the “What’s happening?” textarea, type my tweet, then hit the tweet button. What should happen at that moment on the page?

1. My number of tweets on the right side of the page should be incremented.
2. My tweet should be added to my timeline.
3. The “What’s happening?” textarea should be cleared.

While coding the event handler for the tweet button, it’d be really easy to just say, “Well, I know the id of the tweet count DOM element. I’ll just grab the element using jQuery and increment the number inside it.” What’s wrong with this? We just reached outside our view and manipulated the DOM element of another view. Like I’ve said before, this will lead to a giant web of dag-nasty in the long run. Avoid it. In fact, avoid forcing the two views to know about each other at all.

Instead, let’s create a model that contains the number of tweets. Both the “What’s happening?” view and the tweet count view share the model. When the user clicks the tweet button, we increment the number on the model. The tweet count view will be notified by the model that the number of tweets has changed. The tweet count view will then update its DOM element. The views can carry on blissfully unaware of each other.

Likewise, we can have a collection containing the tweets that should show up in our timeline. We add a tweet model to the collection from the “What’s happening?” view and the collection notifies the timeline view of the addition. The timeline view creates a single tweet view, shoves the tweet model into the tweet view, then adds the tweet view’s DOM element as the first child of the timeline’s DOM element. This last part will hopefully make more sense later, but notice the timeline does not know how the tweet view is showing the tweet or what its DOM element contains. It doesn’t care. It just throws the model over the wall.

View properties

Okay, let’s get to the meat. Backbone views have several special properties you should know about:

• el – Each view has a DOM element it is managing. el is a reference to this DOM element. It can be set from the parent or it can be created and set from within the view itself.
• $el – A jQuery-wrapped version of el.
• id – If the view automatically creates a DOM element because el wasn’t set through the constructor, the automatically-created DOM element will receive an id as specified by the id property.
• model – Each view will likely be dealing with a model specified using the model property.
• collection – Or the view will be dealing with a collection specified using the collection property.
• tagName – During instantiation, the view will determine if el was set through the constructor. If it wasn’t, the view will automatically create an element and will set it as the value for the el property. The type of element the view will automatically create is determined by tagName. By default, tagName is set to div, meaning the view will create a div element and set it as the el property if el wasn’t set through the constructor.
• className – If the view automatically creates a DOM element because el wasn’t set through the constructor, the automatically-created DOM element will receive a CSS class name as specified by the className property.

What’s so special about these properties? Let’s take a look:

var TweetRow = Backbone.View.extend({
	initialize: function(options) {
		alert('I can access this.model directly! ' +
				'The tweet text is ' + this.model.get('text'));
 
		alert('I can only access my notSoSpecialProp through options: ' +
				options.notSoSpecialProp);
 
		alert('I didn\'t even pass in el but the view made a ' +
				this.el.tagName + ' for me!');
	}
});
 
var tweet = new Backbone.Model({
	avatar: 'aaronius.jpg',
	alias: 'Aaronius',
	text: 'Honey roasted peanuts rock my sox.'
});
 
var row = new TweetRow({
	model: tweet,
	notSoSpecialProp: 42
});

Here I passed in an options object into my tweet row view. The options object is passed into the initialize() method which is automatically called by Backbone.View. Behind the scenes, though, the view first takes the special properties in the options object and merges them as first-class properties of the view. Now we can access them directly (e.g., this.model, this.el). On the other hand, anything that’s not considered special by the view is only accessible through the options object itself; they aren’t merged to the view as direct properties.

Rendering

Now we have a model or collection we’re dealing with (this.model or this.collection) and also a DOM element we’re managing (this.el). Now it’s time to render something. In JavaScript Architecture: Underscore.js we talked about how to use templates to render pieces of UI. Let’s take a look at how we would use our model and template to render a tweet row. In this example, I’m going to include the full HTML file I’m working with. This is far from a fully baked app, but I want you to get your hands on something that will actually run in a browser:

<!DOCTYPE html>
<html>
	<head>
		<meta http-equiv="content-type" content="text/html; charset=UTF-8">
		<title>Backbone Example</title>
	</head>
	<body>
		<script src="libs/jquery.js"></script>
		<script src="libs/underscore.js"></script>
		<script src="libs/backbone.js"></script>
		<script type="text/javascript">
			$(document).ready(function() {
				var TweetRow = Backbone.View.extend({
					_template: _.template($('#tweet-row-template').html()),
 
					initialize: function() {
						this.render();
					},
 
					render: function() {
						this.$el.html(this._template(this.model.toJSON()));
						return this;
					}
				});
 
				var App = Backbone.View.extend({
					initialize: function() {
						this.render();
					},
 
					render: function() {
						var tweet = new Backbone.Model({
							avatar: 'avatar.jpg',
							username: 'Aaronius',
							text: 'Honey roasted peanuts rock my sox.'
						});
 
						var row = new TweetRow({
							model: tweet
						});
 
						this.$el.append(row.$el);
						return this;
					}
				});
 
				var app = new App({el: $('body')});
			});
		</script>
 
		<script type="text/template" id="tweet-row-template">
			<div style="float: left"><img src="<%= avatar %>"/></div>
			<div style="margin-left: 60px">
				<p><%= username %></p>
				<p><%= text %></p>
			</div>
		</script>
	</body>
</html>

You’ll see in TweetRow we’ve created a render() method which populates the inner HTML of the view’s DOM element (in this case, a div that was automatically created by Backbone.View). By default, Backbone.View already has a render() method but it doesn’t perform any operation. Nothing in Backbone even calls it either. Truthfully, the render() method is more of a convention than anything, but I highly suggest you follow it. The render() method should do any work needed to update the view’s DOM element. Keep in mind that optimally you should be able to call render() multiple times if needed and your view should still render and function properly. Also, it’s recommended you return this; at the end to allow for method chaining.

There are some differences in the Backbone community regarding how render() should be called. You’ll often see examples that show the parent view calling the render() method of a child view. In our case, that would mean rather than calling render() from our initialize() method within the view we would call it later outside of the view before we append the element to a parent DOM element:

<code>this.$el.append(row.render().$el);</code>

I prefer to only call render() from within the view itself–never from another view–even a parent view. It’s my opinion that views should not be concerned with when other views need to be rendered or re-rendered. Others may disagree and I reserve the right to join them someday. :)

Model-View knowledge

It may be tempting to store a view or two on a model. Steer clear of this. Views should know about models and be able to bind to their events but not the other way around. This is standard MVC protocol and for good reason. Logic flow and interaction among application actors can easily become unwieldy when introducing views into models.

Event delegation

A helpful nugget Backbone views offer is event delegation. Normally when dealing with DOM element interactions you would have to query for elements using jQuery and then bind to their events. It’s not difficult, but Backbone provides a shortcut for doing so:

var DocumentView = Backbone.View.extend({
	events: {
		"dblclick"                : "open",
		"click .icon.doc"         : "select",
		"mouseover .title .date"  : "showTooltip"
	},
 
	render: function() {
		...
	},
 
	open: function() {
		...
	},
 
	select: function() {
		...
	},
 
	showTooltip: function() {
		...
	},
});

As you can see, an events property is set. Each entry could be read as follows:

• When this.el is double-clicked, call the open() method.
• When descendants of this.el matching the .icon.doc CSS selector are clicked, call the select() method.
• When descendants of this.el matching the .title .date CSS selector are moused over, call the showTooltip() method.

Another bonus about this shortcut is that referencing the this context from within the callback methods will still refer to the view–not the DOM element that triggered the event. If you’ve used JavaScript for much time, you’ll know that handling the this context can be a pain.

This event delegation generally is handled for you transparently. However, if you ever replace this.el with a different DOM element, be sure to call this.setElement(newEl) instead of just this.el = newEl. The setElement() function will properly remove the event delegation from the old element and add it to the new element. It will also set up the this.$el variable for you. Hopefully that will save you from pulling your hair out sometime.

Other functionality

jQuery allows us to search for elements only within this.el:

var paragraphs = $('p', this.el);

As a convenience, Backbone provides a shortcut to do the same thing:

var paragraphs = this.$('p');

With the appropriate usage of views we can build more maintainable, scalable apps. I invite you to read more in the Backbone.View documentation.

Collections of items are amazingly pervasive in applications. Gmail deals with collections of emails. Twitter deals with collections of tweets. Facebook deals with collections of friends, updates, and apps. Very often these collections contain living data. The app may be constantly updating with new, changed, or removed items from the server. Maybe users are able to filter, sort, add, edit, or delete items and maybe they can do so from multiple views that need to be synchronized.

Usually when we think of collections of items in software terms with think of an array. Objects can be added and removed from an array easily enough but a native array on its own has no ability to broadcast notice of the change. Why do we care? Let’s say we’re building an RSS reader that shows the user a feed of articles from their subscriptions. The articles come from an array we loaded from the server. Each article contains a remove button next to it that allows the user to remove the article from the feed. Let’s also say in the top-right corner of the screen, separate from the feed of articles, we have a little counter that shows the user how many articles they currently have remaining in the feed. Assume that the feed has a JavaScript object managing it and the counter has a separate JavaScript object managing it.

When the user clicks a remove button to remove an article from the feed, it’s easy enough for us to remove the article from the feed itself and the accompanying array of articles, but how do we update the counter? The most direct approach is to give the feed view a reference to the counter view. That way the feed can just call a function on the counter view to tell it to refresh itself, right? Noooooooooo! Sure, it might function, but that’s a very good way to couple our views and reduce our flexibility. Our views would know more than necessary about each other. In this case, the data should drive the views instead of the views driving each other. Unfortunately, it’s difficult for our data (the array of articles) to drive the view using a native array because the counter can’t “watch” the array for a removal of an article. Native arrays do not broadcast events when items are added or removed.

You’ll notice a great similarity between what I’ve written above regarding native arrays resulting in view coupling and what I wrote in my previous post about native objects resulting in view coupling. Indeed, there are a lot of similarities and they are both resolved by implementing the observer pattern within our data structures. Just as a native object can be wrapped by a Backbone model in order to broadcast attribute changes, an array can be wrapped by a Backbone collection to broadcast additions and removals.

Eventful collections

Collections trigger events when models are added or removed. Let’s take a look at how this might look:

// Create individual models.
var taleOfTwoCities = new Backbone.Model({
	title: 'A Tale of Two Cities',
	author: 'Charles Dickens',
	publisher: 'Chapman & Hall'
});
 
var goodEarth = new Backbone.Model({
	title: 'The Good Earth',
	author: 'Pearl S. Buck',
	publisher: 'John Day'
});
 
// Create collection, passing in A Tale of Two Cities that will make up
// our initial collection.  Alternatively, we could have passed in nothing 
// and then called books.add(taleOfTwoCities) later.
var books = new Backbone.Collection([taleOfTwoCities]);
 
// Set up the handler for when a model is added.
var onAdd = function(book, books, options) {
	alert('Book ' + book.get('title') + ' added at index ' + options.at + '. ' +
		'The collection now contains ' + books.length + ' models.');
};
 
// Set up the handler for when a model is removed.
var onRemove = function(book, books, options) {
	alert('Book ' + book.get('title') + ' removed from index ' + options.index);
}
 
// Set up event listeners.
books.on('add', onAdd);
books.on('remove', onRemove);
 
// Add good earth and index 0 (before the Tale of Two Cities).
books.add(goodEarth, {at: 0});
// Remove both books.
books.remove([taleOfTwoCities, goodEarth]);
// We could have removed just a single book like this:
// books.remove(goodEarth);

I’ve added several comments inline, but let’s review what’s going on here. When we add a model to the collection, we use the add() function. Optionally, you can pass the index where you want the model to be added. We specify 0 so goodEarth will be placed at the start of the collection. By default, it will be added at the end. When we add the model, the add event is automatically triggered by the collection and any respective handlers are called. In our case, the onAdd function is called. The three arguments are:

1. The added model.
2. The collection to which the model was added.
3. Any options used to add the model.

You can add one or more models at a time.

We then removed both our book models at the same time. Even though we remove them using a single remove() call, the onRemove handler is called twice–once for each model being removed. The three arguments are:

1. The removed model.
2. The collection from which the model was removed.
3. Any options used to remove the model.

You can remove one or more models at a time. Notice that even though we didn’t explicitly pass any options object as a second parameter to remove(), the options argument coming into onRemove does exist and is populated with the index at which the model resided.

The above code produces the following alerts, in order:

1. Book The Good Earth added at index 0. The collection now contains 2 models.
2. Book A Tale of Two Cities removed from index 1.
3. Book The Good Earth removed from index 0.

What if you wanted to know when the title of any model in the collection changes? Looping through all the models and adding an event listener to each one is a pain, especially when we have to remember to always add event listeners to models being added and remove event listeners from models being removed. Fortunately, Backbone collections bucket-brigade events coming from the models themselves which can be very handy. Let’s see how this works:

var taleOfTwoCities = new Backbone.Model({
	title: 'A Tale of Two Cities',
	author: 'Charles Dickens',
	publisher: 'Chapman & Hall'
});
 
var goodEarth = new Backbone.Model({
	title: 'The Good Earth',
	author: 'Pearl S. Buck',
	publisher: 'John Day'
});
 
var books = new Backbone.Collection([taleOfTwoCities, goodEarth]);
 
var onTitleChange = function(book, value) {
	alert('Book title changed from ' + book.previousAttributes().title + ' to ' + value);
};
 
books.on('change:title', onTitleChange);
goodEarth.set({title: 'Good Earth, The'});

Notice we didn’t add an event listener for change:title on each individual book model, but only on the collection containing the book models. I even threw a little bonus nugget in there to show how we can retrieve the previous title.

Model configuration

So far we’ve been instantiating our own Backbone models before adding them to a collection. However, we can configure our collection to use a certain model class. We can then just pass a native object to the collection. Under the hood, the collection will then instantiate the configured model class for us and pass our native object into its constructor:

var Book = Backbone.Model.extend({
	defaults: {
		genre: 'historical'
	}
});
 
var BookCollection = Backbone.Collection.extend({
	model: Book
});
 
var books = new BookCollection();
 
books.add({
	title: 'A Tale of Two Cities',
	author: 'Charles Dickens',
	publisher: 'Chapman & Hall'
});
 
books.add({
	title: 'The Good Earth',
	author: 'Pearl S. Buck',
	publisher: 'John Day'
});

Notice in this case we actually extended Backbone.Collection and set the model property. Another option is to just set the model property on a newly instantiated collection:

var books = new Backbone.Collection();
books.model = Book;

If you don’t configure the model class, Backbone.Collection uses Backbone.Model by default. Configuring a collection with a model class may not seem very beneficial at the moment, but hopefully it will make more sense when talking about loading data into a collection.

Persistence

Similar to Backbone models, collections also have the ability to fetch data from persistence. Let’s see how this works:

var Book = Backbone.Model.extend({
	defaults: {
		genre: 'historical'
	}
});
 
var onSuccess = function(books) {
	var firstBook = books.at(0);
	alert(firstBook.get('title') + ' is of genre ' + firstBook.get('genre'));
};
 
var books = new Backbone.Collection();
books.model = Book;
books.url = '/books.php';
books.fetch({
	success: onSuccess
});

Like our previous example, we’ve configured a collection to use the Book model class. We’ve also configured an endpoint url of /books.php. When we call fetch(), the collection will issue a GET request to the endpoint. In my case, I’ve set up the endpoint to return a JSON array of books. Once the JSON is returned, the collection will loop through the array, instantiating and populating a model (in our case, a Book model) for each item. Then, the model will be added to the collection itself.

The example above will alert A Tale of Two Cities is of genre historical. The interesting part here is the genre was never sent from the server. Instead, the model picked up the default genre, historical, because we extended Backbone.Model to create our Book class and set the default genre there. Hopefully you can now see the benefit of configuring collections to use a specific model class.

Additional functionality

We’ve only covered a subset of the functionality of Backbone collections. Beyond what we’ve discussed, collections can be sorted and reset. Models can be retrieved by id. Models can be both saved to the server and added to the collection in one method call.

Collections can also be configured, for example, to load and parse data in a specific manner.

Beyond that, all collections have a bucketload of underscore functions baked in. In JavaScript Architecture: Underscore.js, I showed an example of how we can get an array of usernames from an array of user objects using the Underscore pluck() function:

var usernames = _.pluck(users, 'username');

Since collections have Underscore functions baked in, we can likewise get an array of all titles of the books in the collection in an even more concise manner:

var titles = books.pluck('title');

Nice! There are many other Underscore functions baked into collections you should check out as well. These will make your life easier and trim down your code.

Read more in the Backbone.Collection documentation.