JavaScript development has changed markedly from how it looked when it was first conceived. It’s easy to forget how far the language has come from its initial implementation in Netscape’s browser, to the powerful engines of today, such as Google’s V8. It’s been a rocky path involving renaming, merging, and the eventual standardization as ECMAScript. The capabilities we have today are beyond the wildest dreams of those early innovators.

Despite its success and popularity, JavaScript is still widely misunderstood. Few people know that it’s a powerful and dynamic object-oriented language. They’re surprised to learn about some of its more advanced features, such as prototypal inheritance, modules, and namespaces. So, why is JavaScript so misunderstood?

Part of the reason is due to previous buggy JavaScript implementations, and part of it is due to the name—the Java prefix suggests it’s somehow related to Java; in reality, it’s a totally different language. However, I think the real reason is the way most developers are introduced to the language. With other languages, such as Python and Ruby, developers usually make a concerted effort to learn the language with the help of books, screencasts, and tutorials. Until recently, though, JavaScript wasn’t given that endorsement. Developers would get requests to add a bit of form validation—maybe a lightbox or a photo gallery—to existing code, often on a tight schedule. They’d use scripts they’d find on the Internet, calling it a day with little understanding of the language behind it. After that basic exposure, some of them might even add JavaScript to their resumes.

Recently, JavaScript engines and browsers have become so powerful that building full-blown applications in JavaScript is not only feasible, but increasingly popular. Applications like Gmail and Google Maps have paved the way to a completely different way of thinking about web applications, and users are clamoring for more. Companies are hiring full-time JavaScript developers. No longer is JavaScript a sublanguage relegated to simple scripts and a bit of form validation—it is now a standalone language in its own right, realizing its full potential.

This influx of popularity means that a lot of new JavaScript applications are being built. Unfortunately, and perhaps due to the language’s history, many of them are constructed very poorly. For some reason, when it comes to JavaScript, acknowledged patterns and best practices fly out the window. Developers ignore architectural models like the Model View Controller (MVC) pattern, instead blending their applications into a messy soup of HTML and JavaScript.

This book won’t teach you much about JavaScript as a language—other books are better suited for that, such as Douglas Crockford’s JavaScript: The Good Parts (O’Reilly). However, this book will show you how to structure and build complex JavaScript applications, allowing you to create incredible web experiences.

The secret to making large JavaScript applications is to not make large JavaScript applications. Instead, you should decouple your application into a series of fairly independent components. The mistake developers often make is creating applications with a lot of interdependency, with huge linear JavaScript files generating a slew of HTML tags. These sorts of applications are difficult to maintain and extend, so they should be avoided at all costs.

Paying a bit of attention to an application’s structure when you start building it can make a big difference to the end result. Ignore any preconceived notions you have about JavaScript and treat it like the object-oriented language that it is. Use classes, inheritance, objects, and patterns the same way you would if you were building an application in another language, such as Python or Ruby. Architecture is critical to server-side applications, so why shouldn’t the same apply to client-side apps?

The approach this book advocates is the MVC pattern, a tried and tested way of architecting applications that ensures they can be effectively maintained and extended. It’s also a pattern that applies particularly well to JavaScript applications.

MVC is a design pattern that breaks an application into three parts: the data (Model), the presentation layer (View), and the user interaction layer (Controller). In other words, the event flow goes like this:

Or, to give a real example, Figure 1-1 shows how sending a new chat message would work with Holla.

Figure 1-1. Sending a new chat message from Holla

The MVC architectural pattern can even be implemented without libraries or frameworks. The key is to divide up the responsibilities of the MVC components into clearly defined sections of code, keeping them decoupled. This allows for independent development, testing, and maintenance of each component.

Let’s explore the components of MVC in detail.

var user = users["foo"];
destroyUser(user);

var user = User.find("foo");
user.destroy();

// template.html
<div>
  <script>
    function formatDate(date) {
      /* ... */
    };
  </script>
  ${ formatDate(this.date) }
</div>

// helper.js
var helper = {};
helper.formatDate = function(){ /* ... */ };

// template.html
<div>
  ${ helper.formatDate(this.date) }
</div>

var Controller = {};

// Use a anonymous function to encapsulate scope
(Controller.users = function($){

  var nameClick = function(){
    /* ... */
  };

  // Attach event listeners on page load
  $(function(){
    $("#view .name").click(nameClick);
  });

})(jQuery);

Before we get to the nitty-gritty of MVC, we’re going to cover some preliminary concepts, such as JavaScript classes and events. This will give you a solid foundation before moving on to some of the more advanced concepts.

JavaScript object literals are fine for static classes, but it’s often useful to create classical classes with inheritance and instances. It’s important to emphasize that JavaScript is a prototype language, and as such doesn’t include a native class implementation. However, support can be emulated fairly easily.

Classes in JavaScript often get a bad rap, criticized for not being part of the “JavaScript Way,” a term that means essentially nothing. jQuery is effectively neutral when it comes to structural methodology or inheritance patterns. This can lead JavaScript developers to believe they shouldn’t consider structure—i.e., that classes aren’t available or shouldn’t be used. In reality, classes are just another tool, and as a pragmatist, I believe they’re as useful in JavaScript as in any other modern language.

Rather than class definitions, JavaScript has constructor functions and the new operator. A constructor function can specify an object’s initial properties and values when it is instantiated. Any JavaScript function can be used as a constructor. Use the new operator with a constructor function to create a new instance.

The new operator changes a function’s context, as well as the behavior of the return statement. In practice, using new and constructors is fairly similar to languages with native class implementations:

var Person = function(name) {
  this.name = name;
};

// Instantiate Person
var alice = new Person('alice');

// Check instance
assert( alice instanceof Person );

By convention, constructor functions are upper camel-cased to differentiate them from normal functions. This is important because you don’t ever want to call a constructor function without the new prefix.

// Don't do this!
Person('bob'); //=> undefined

The function will just return undefined, and since the context is the window (global) object, you’ve unintentionally created a global variable, name. Always call constructor functions using the new keyword.

When a constructor function is called with the new keyword, the context switches from global (window) to a new and empty context specific to that instance. So, the this keyword refers to the current instance. Although it might sound complicated, in practice, you can treat it like native class implementations in other languages.

By default, if you don’t return anything from a constructor function, this—the current context—will be returned. Otherwise, you can return any nonprimitive type. For example, we could return a function that would set up a new class, the first step in building our own class emulation library:

var Class = function(){
  var klass = function(){
    this.init.apply(this, arguments);
  };
  klass.prototype.init  = function(){};
  return klass;
};

var Person = new Class;

Person.prototype.init = function(){
  // Called on Person instantiation
};

// Usage:
var person = new Person;

Confusingly, due to a JavaScript 2 specification that was never implemented, class is a reserved keyword. The common convention is instead to name class variables as _class or klass.

Adding class functions to a constructor function is the same as adding a property onto any object in JavaScript:

Person.find = function(id){ /*...*/ };

var person = Person.find(1);

To add instance functions to a constructor function, you need to use the constructor’s prototype:

Person.prototype.breath = function(){ /*...*/ };

var person = new Person;
person.breath();

A common pattern is to alias a class’ prototype to fn, which is a bit less verbose:

Person.fn = Person.prototype;

Person.fn.run = function(){ /*...*/ };

In fact, you’ll see this pattern throughout jQuery plug-ins, which essentially just add functions to jQuery’s prototype, aliased to jQuery.fn.

Currently, our class library includes functionality for instantiating and initializing instances. Adding properties to classes is the same as adding properties to constructor functions.

Properties set directly on the class will be equivalent to static members:

var Person = new Class;

// Static functions are added directly on the class
Person.find = function(id){ /* ... */ };

// And now we can call them directly
var person = Person.find(1);

And properties set on the class’ prototype are also available on instances:

var Person = new Class;

// Instance functions are on the prototype
Person.prototype.save = function(){ /* ... */ };

// And now we can call them on instances
var person = new Person;
person.save();

However, in my opinion, that syntax is a little convoluted, impractical, and repetitive. It’s difficult to see, at a glance, a list of your class’ static and instance properties. Instead, let’s create a different way of adding properties to our classes using two functions, extend() and include():

var Class = function(){
  var klass = function(){
    this.init.apply(this, arguments);
  };

  klass.prototype.init  = function(){};

  // Shortcut to access prototype
  klass.fn = klass.prototype;

  // Shortcut to access class
  klass.fn.parent = klass;

  // Adding class properties
  klass.extend = function(obj){
    var extended = obj.extended;
    for(var i in obj){
      klass[i] = obj[i];
    }
    if (extended) extended(klass)
  };

  // Adding instance properties
  klass.include = function(obj){
    var included = obj.included;
    for(var i in obj){
      klass.fn[i] = obj[i];
    }
    if (included) included(klass)
  };

  return klass;
};

In the improved class library above, we’re adding an extend() function to generated classes, which accepts an object. The object’s properties are iterated through and copied directly onto the class:

var Person = new Class;

Person.extend({
  find:   function(id) { /* ... */ },
  exists: function(id) { /* ... */ }
});

var person = Person.find(1);

The include() function works in exactly the same way, except properties are copied onto the class’ prototype, rather than directly onto the class. In other words, the properties are on the class’ instance, rather than statically on the class.

var Person = new Class;

Person.include({
  save:    function(id) { /* ... */ },
  destroy: function(id) { /* ... */ }
});

var person = new Person;
person.save();

We’re also implementing support for extended and included callbacks. If these properties are present on the passed object, they’ll be invoked:

Person.extend({
  extended: function(klass) {
    console.log(klass, " was extended!");
  }
});

If you’ve used classes in Ruby, this should all look very familiar. The beauty of this approach is that we’ve now got support for modules. Modules are reusable pieces of code, and they can be used as an alternative to inheritance for sharing common properties among classes.

var ORMModule = {
  save: function(){
    // Shared function
  }
};

var Person = new Class;
var Asset  = new Class;

Person.include(ORMModule);
Asset.include(ORMModule);

We’ve been using the prototype property a lot, but it hasn’t really been explained yet. Let’s take a closer look at what it is exactly and how to use it to implement a form of inheritance in our classes.

JavaScript is a prototype-based language and—rather than make distinctions between classes and instances—it has the notions of a prototypical object: an object used as a template from which to get the initial properties for a new object. Any object can be associated as a prototype of another object, sharing its properties. In practice, you can look at this as a form of inheritance.

When you fetch a property on an object, JavaScript will search the local object for the property. If it isn’t found, JavaScript will start searching the object’s prototype and continue up the prototype tree, eventually reaching Object.prototype. If the property is found, its value is returned; otherwise, undefined will be returned.

In other words, if you start adding properties to Array.prototype, they’ll be reflected across every JavaScript array.

To subclass a class and inherit its properties, you need to first define a constructor function. Then, you need to assign a new instance of the parent class as the prototype for your constructor function. It looks like this:

var Animal = function(){};

Animal.prototype.breath = function(){
  console.log('breath');
};

var Dog = function(){};

// Dog inherits from Animal
Dog.prototype = new Animal;

Dog.prototype.wag = function(){
  console.log('wag tail');
};

Now, we can check to see whether the inheritance works:

var dog = new Dog;
dog.wag();
dog.breath(); // Inherited property

Let’s add inheritance to our custom class library. We’ll pass through an optional parent class when creating a new class:

var Class = function(parent){
  var klass = function(){
    this.init.apply(this, arguments);
  };

  // Change klass' prototype
  if (parent) {
    var subclass = function() { };
    subclass.prototype = parent.prototype;
    klass.prototype = new subclass;
  };

  klass.prototype.init = function(){};

  // Shortcuts
  klass.fn = klass.prototype;
  klass.fn.parent = klass;
  klass._super = klass.__proto__;

  /* include/extend code... */

  return klass;
};

If a parent is passed to the Class constructor, we make sure any subclasses share the same prototype. This little dance around creating a temporary anonymous function prevents instances from being created when a class is inherited. The caveat here is that only instance properties, not class properties, are inherited. There isn’t yet a cross-browser way of setting an object’s __proto__;. Libraries like Super.js get around this problem by copying the properties, rather than implementing proper dynamic inheritance.

Now, we can perform simple inheritance by passing parent classes to Class:

var Animal = new Class;

Animal.include({
  breath: function(){
    console.log('breath');
  }
});

var Cat = new Class(Animal)

// Usage
var tommy = new Cat;
tommy.breath();

Like everything else in JavaScript, functions are just objects. However, unlike other objects, they can be invoked. The context inside the function—i.e., the value of this—depends on where and how it’s invoked.

Apart from using brackets, there are two other ways to invoke a function: apply() and call(). The difference between them has to do with the arguments you want to pass to the function.

The apply() function takes two parameters: a context and an array of arguments. If the context is null, the global context is used. For example:

function.apply(this, [1, 2, 3])

The call() function has exactly the same behavior, yet it is used differently. The first argument is the context, while each subsequent argument is delegated to the invocation. In other words, you use multiple arguments—rather than an array like with apply()—to pass arguments to the function.

function.call(this, 1, 2, 3);

Why would you want to change the context? This is a valid question because other languages get on fine without allowing explicit context changes. JavaScript uses context changes to share state, especially during event callbacks. (Personally, I feel this was a mistake in the design of the language, as it can be confusing for beginners and introduce bugs. However, it’s too late to change it now, so you need to learn how it works.)

jQuery takes advantage of apply() and call() throughout its API to change context—for example, when using event handlers or iterating using each(). This can be confusing at first, but it’s useful when you understand what’s happening:

$('.clicky').click(function(){
  // 'this' refers to the element
  $(this).hide();
});

$('p').each(function(){
  // 'this' refers to the current iteration
  $(this).remove();
});

To access the original context, a common pattern stores the value of this in a local variable. For example:

var clicky = {
  wasClicked: function(){
    /* ... */
  },

  addListeners: function(){
    var self = this;
    $('.clicky').click(function(){
      self.wasClicked()
    });
  }
};

clicky.addListeners();

However, we can use apply to make this much cleaner, wrapping the callback within another anonymous function, which preserves the original context:

var proxy = function(func, thisObject){
  return(function(){
    return func.apply(thisObject, arguments);
  });
};

var clicky = {
  wasClicked: function(){
    /* ... */
  },

  addListeners: function(){
    $('.clicky').click(proxy(this.wasClicked, this));
  }
};

So, in the above example, we specify the context to be used inside the click callback; the context jQuery invokes the function in is ignored. In fact, jQuery’s API includes something to do just this—you guessed it, jQuery.proxy():

$('.clicky').click($.proxy(function(){ /* ... */ }, this));

There are other useful reasons to use apply() and call(), such as delegating. We can delegate calls from one function to another, and even alter the passed arguments:

var App = {
  log: function(){
    if (typeof console == "undefined") return;

    // Turn arguments into a proper array
    var args = jQuery.makeArray(arguments);

    // Insert a new argument
    args.unshift("(App)");

    // Delegate to the console
    console.log.apply(console, args);
  }
};

Above, we’re making an array of arguments and then adding our own. Finally, the call is delegated to console.log(). If you’re not familiar with the arguments variable, it’s set by the interpreter and contains an array of arguments with which the current scope was called. It’s not a true array though—for example, it’s not mutable—so we have to convert it to something usable with jquery.makeArray().

The proxy function described in the previous section is such a useful pattern that we should add it to our class library. We’ll add a proxy function on both classes and instances, allowing us to keep the class’ scope when handing functions off to event handlers and the like:

var Class = function(parent){
  var klass = function(){
    this.init.apply(this, arguments);
  };
  klass.prototype.init = function(){};
  klass.fn = klass.prototype;

  // Adding a proxy function
  klass.proxy = function(func){
    var self = this;
    return(function(){
      return func.apply(self, arguments);
    });
  }

  // Add the function on instances too
  klass.fn.proxy = klass.proxy;

  return klass;
};

We can now use the proxy() function to wrap up functions, making sure they’re invoked in the right scope:

var Button = new Class;

Button.include({
  init: function(element){
    this.element = jQuery(element);

    // Proxy the click function
    this.element.click(this.proxy(this.click));
  },

  click: function(){ /* ... */ }
});

If we didn’t wrap the click() callback with a proxy, it would be called within the context of this.element, rather than Button, causing all sorts of problems. A new specification of JavaScript—ECMAScript, 5th Edition (ES5)—has also added support for controlling invocation scope with the bind() function. bind() is called on a function, making sure the function is called in the context of the specified this value. For example:

Button.include({
  init: function(element){
    this.element = jQuery(element);

    // Bind the click function
    this.element.click(this.click.bind(this));
  },

  click: function(){ /* ... */ }
});

This example is equivalent to our proxy() function, and it makes sure the click() function is called with the correct context. Older browsers don’t support bind() but, luckily, support can be shimmed easily and implemented manually if needed. A shim basically implements a compatibility layer on legacy browsers, directly extending the relevant object’s prototypes, allowing you to use features of ES5 today without worrying about older browsers. For example, a shim that would support bind() would look like this:

if ( !Function.prototype.bind ) {
  Function.prototype.bind = function( obj ) {
    var slice = [].slice,
        args = slice.call(arguments, 1),
        self = this,
        nop = function () {},
        bound = function () {
          return self.apply( this instanceof nop ? this : ( obj || {} ),
                              args.concat( slice.call(arguments) ) );
        };

    nop.prototype = self.prototype;

    bound.prototype = new nop();

    return bound;
  };
}

Function’s prototype is only overwritten if the feature doesn’t already exist: newer browsers will continue to use their native implementations. Shimming is especially useful for arrays, which have had a bunch of new features added in recent JavaScript versions. I personally use the es5-shim project because it covers as many of the new features in ES5 as possible.

So far, any property we’ve added to our classes has been open to the world and can be changed at any time. Let’s now explore how to add private properties to our classes.

A lot of developers end up prefixing private properties with an underscore (_). Although these can still be changed, it makes it obvious that they’re part of a private API. I try to steer clear of this approach because it looks rather ugly.

JavaScript does have support for immutable properties; however, this isn’t implemented across the main browsers, so we’ll have to wait before using this method. Instead, we’ll use JavaScript anonymous functions to create a private scope, which can only be accessed internally:

var Person = function(){};

(function(){

  var findById = function(){ /* ... */ };

  Person.find = function(id){
    if (typeof id == "number")
      return findById(id);
  };

})();

We’re wrapping all our class’ properties in an anonymous function, then creating local variables (findById), which can only be accessed in the current scope. The Person variable is defined in the global scope, so it can be accessed from anywhere.

Never define a variable without using the var operator, since it always creates a global variable. If you need to define a global variable, do so in the global scope or as a property on window:

(function(exports){
  var foo = "bar";

  // Expose variable
  exports.foo = foo;
})(window);

assertEqual(foo, "bar");

As with a lot of concepts in this book, it’s good to understand the theory behind classes, but often in practice, you’ll use a library. jQuery doesn’t include class support natively, but it can easily be added with a plug-in like HJS. HJS lets you define classes by passing a set of properties to $.Class.create:

var Person = $.Class.create({
  // constructor
  initialize: function(name) {
    this.name = name;
  }
});

To inherit classes, pass their parent as an argument when creating them:

var Student = $.Class.create(Person, {
  pay: function() { /* ... */ }
});

var alex = new Student("Alex");
alex.pay();

To add class properties, set them directly on the class:

Person.find = function(id){ /* ... */ };

HJS’ API also includes a few utility functions, such as clone() and equal():

var alex = new Student("Alex");
var bill = alex.clone();

assert( alex.equal(bill) );

HJS isn’t your only option; Spine also has a class implementation. To use it, just include spine.js in the page:

<script src="http://maccman.github.com/spine/spine.js"> </script>
<script>
  var Person = Spine.Class.create();

  Person.extend({
    find: function() { /* ... */ }
  });

  Person.include({
    init: function(atts){
      this.attributes = atts || {};
    }
  });

  var person = new Person();
</script>

Spine’s class library has a similar API to the library we’ve been building throughout this chapter. Use extend() to add class properties and include() to add instance properties. To inherit from them, pass parent classes to the Spine.Class instantiator.

If you’re widening your gaze beyond jQuery, Prototype is definitely worth checking out. It has an excellent class API that was the inspiration for a lot of other libraries.

jQuery’s John Resig has an interesting post on implementing classical inheritance with the library. It’s well worth reading, especially if you’re interested in the nitty-gritty behind the JavaScript prototype system.

Events revolve around a function called addEventListener(), which takes three arguments: type (e.g., click), listener (i.e., callback), and useCapture (we’ll cover useCapture later). Using the first two arguments, we can attach a function to a DOM element, which is invoked when that particular event, such as click, is triggered on the element:

var button = document.getElementById("createButton");

button.addEventListener("click", function(){ /* ... */ }, false);

We can remove the listener using removeEventListener(), passing the same arguments we gave addEventListener(). If the listener function is anonymous and there’s no reference to it, it can’t be removed without destroying the element:

var div = document.getElementById("div");

var listener = function(event) { /* ... */ };
div.addEventListener("click", listener, false);
div.removeEventListener("click", listener, false);

As its first argument, the listener function is passed an event object, which you can use to get information about the event, such as timestamp, coordinates, and target. It also contains various functions to stop the event propagation and prevent the default action.

As for event types, the supported ones vary from browser to browser, but all modern browsers have the following:

Check out Quirksmode, which has a full event compatibility table.

Before we go any further, it’s important to discuss event ordering. If an element and one of its ancestors have an event handler for the same event type, which one should fire first when the event is triggered? Well, you won’t be surprised to hear that Netscape and Microsoft had different ideas.

Netscape 4 supported event capturing, which triggers event listeners from the top-most ancestor to the element in question—i.e., from the outside in.

Microsoft endorsed event bubbling, which triggers event listeners from the element, propagating up through its ancestors—i.e., from the inside out.

Event bubbling makes more sense to me, and it is likely to be the model used in day-to-day development. The W3C compromised and stipulated support for both event models in their specification. Events conforming to the W3C model are first captured until they reach the target element; then, they bubble up again.

You can choose the type of event handler you want to register, capturing or bubbling, which is where the useCapture argument to addEventListener() comes into the picture. If the last argument to addEventListener() is true, the event handler is set for the capturing phase; if it is false, the event handler is set for the bubbling phase:

// Use bubbling by passing false as the last argument
button.addEventListener("click", function(){ /* ... */ }, false);

The vast majority of the time, you’ll probably be using event bubbling. If in doubt, pass false as the last argument to addEventListener().

When the event is bubbling up, you can stop its progress with the stopPropagation() function, located on the event object. Any handlers on ancestor elements won’t be invoked:

button.addEventListener("click", function(e){
  e.stopPropagation();
  /* ... */
}, false);

Additionally, some libraries like jQuery support a stopImmediatePropagation() function, preventing any further handlers from being called at all—even if they’re on the same element.

Browsers also give default actions to events. For example, when you click on a link, the browser’s default action is to load a new page, or when you click on a checkbox, the browser checks it. This default action happens after all the event propagation phases and can be canceled during any one of those. You can prevent the default action with the preventDefault() function on the event object. Alternatively, you can just return false from the handler:

form.addEventListener("submit", function(e){
  /* ... */
  return confirm("Are you super sure?");
}, false);

If the call to confirm() returns false—i.e., the user clicks cancel in the confirmation dialog—the event callback function will return false, canceling the event and form submission.

As well as the aforementioned functions—stopPropagation() and preventDefault()—the event object contains a lot of useful properties. Most of the properties in the W3C specification are documented below; for more information, see the full specification.

Type of event:

Properties reflecting the environment when the event was executed:

Properties specific to keyboard events:

Where the event happened:

Elements associated with the event:

These properties vary in browsers, especially among those that are not W3C-compliant. Luckily, libraries like jQuery and Prototype will smooth out any differences.

In all likelihood you’ll end up using a JavaScript library for event management; otherwise, there are just too many browser inconsistencies. I’m going to show you how to use jQuery’s event management API, although there are many other good choices, such as Prototype, MooTools, and YUI. Refer to their respective APIs for more in-depth documentation.

jQuery’s API has a bind() function for adding cross-browser event listeners. Call this function on jQuery instances, passing in an event name and handler:

jQuery("#element").bind(eventName, handler);

For example, you can register a click handler on an element like so:

jQuery("#element").bind("click", function(event) {
  // ...
});

jQuery has some shortcuts for event types like click, submit, and mouseover. It looks like this:

$("#myDiv").click(function(){
  // ...
});

It’s important to note that the element must exist before you start adding events to it—i.e., you should do so after the page has loaded. All you need to do is listen for the window’s load event, and then start adding listeners:

jQuery(window).bind("load", function() {
  $("#signinForm").submit(checkForm);
});

However, there’s a better event to listen for than the window’s load, and that’s DOMContentLoaded. It fires when the DOM is ready, but before the page’s images and stylesheets have downloaded. This means the event will always fire before users can interact with the page.

The DOMContentLoaded event isn’t supported in every browser, so jQuery abstracts it with a ready() function that has cross-browser support:

jQuery(document).ready(function($){
  $("#myForm").bind("submit", function(){ /* ... */ });
});

In fact, you can skip the ready() function and pass the handler straight to the jQuery object:

jQuery(function($){
  // Called when the page is ready
});

One thing that’s often confusing about events is how the context changes when the handler is invoked. When using the browser’s native addEventListener(), the context is changed from the local one to the targeted HTML element:

new function(){
  this.appName = "wem";

  document.body.addEventListener("click", function(e){
    // Context has changed, so appName will be undefined
    alert(this.appName);
  }, false);
};

To preserve the original context, wrap the handler in an anonymous function, keeping a reference to it. We covered this pattern in Chapter 1, where we used a proxy function to maintain the current context. It’s such a common pattern that jQuery includes a proxy() function—just pass in the function and context in which you want it to be invoked:

$("signinForm").submit($.proxy(function(){ /* ... */ }, this));

It may have occurred to you that since events bubble up, we could just add a listener on a parent element, checking for events on its children. This is exactly the technique that frameworks like SproutCore use to reduce the number of event listeners in the application:

// Delegating events on a ul list
list.addEventListener("click", function(e){
  if(  e.target.tagName == "li" )
  {
    return false;
  }
});

jQuery has a great way of doing this; simply pass the delegate() function a child selector, event type, and handler. The alternative to this approach would be to add a click event to every li element. However, by using delegate(), you’re reducing the number of event listeners, improving performance:

// Don't do this! It adds a listener to every 'li' element (expensive)
$("ul li").click(function(){ /* ... */ });

// This only adds one event listener
$("ul").delegate("li", "click", /* ... */);

Another advantage to event delegation is that any children added dynamically to the element would still have the event listener. So, in the above example, any li elements added to the list after the page loaded would still invoke the click handler.

Beyond events that are native to the browser, you can trigger and bind them to your own custom events. Indeed, it’s a great way of architecting libraries—a pattern a lot of jQuery plug-ins use. The W3C spec for custom events has been largely ignored by the browser vendors; you’ll have to use libraries like jQuery or Prototype for this feature.

jQuery lets you fire custom events using the trigger() function. You can namespace event names, but namespaces are separated by full stops and reversed. For example:

// Bind custom event
$(".class").bind("refresh.widget", function(){});

// Trigger custom event
$(".class").trigger("refresh.widget");

And to pass data to the event handler, just pass it as an extra parameter to trigger(). The data will be sent to callbacks as extra arguments:

$(".class").bind("frob.widget", function(event, dataNumber){
  console.log(dataNumber);
});

$(".class").trigger("frob.widget", 5);

Like native events, custom events will propagate up the DOM tree.

Custom events, often used to great effect in jQuery plug-ins, are a great way to architect any piece of logic that interacts with the DOM. If you’re unfamiliar with jQuery plug-ins, skip ahead to Appendix B, which includes a jQuery primer.

If you’re adding a piece of functionality to your application, always consider whether it could be abstracted and split out in a plug-in. This will help with decoupling and could leave you with a reusable library.

For example, let’s look at a simple jQuery plug-in for tabs. We’re going to have a ul list that will respond to click events. When the user clicks on a list item, we’ll add an active class to it and remove the active class from the other list items:

<ul id="tabs">
  <li data-tab="users">Users</li>
  <li data-tab="groups">Groups</li>
</ul>

<div id="tabsContent">
  <div data-tab="users"> ... </div>
  <div data-tab="groups"> ... </div>
</div>

In addition, we have a tabsContent div that contains the actual contents of the tabs. We’ll also be adding and removing the active class from the div’s children, depending on which tab was clicked. The actual displaying and hiding of the tabs will be done by CSS—our plug-in just toggles the active class:

jQuery.fn.tabs = function(control){
  var element = $(this);
  control = $(control);

  element.find("li").bind("click", function(){
    // Add/remove active class from the list-item
    element.find("li").removeClass("active");
    $(this).addClass("active");

    // Add/remove active class from tabContent
    var tabName = $(this).attr("data-tab");
    control.find(">[data-tab]").removeClass("active");
    control.find(">[data-tab='" + tabName + "']").addClass("active");
  });

  // Activate first tab
  element.find("li:first").addClass("active");

  // Return 'this' to enable chaining
  return this;
};

The plug-in is on jQuery’s prototype, so it can be called on jQuery instances:

$("ul#tabs").tabs("#tabsContent");

What’s wrong with the plug-in so far? Well, we’re adding a click event handler onto all the list items, which is our first mistake. Instead, we should be using the delegate() function covered earlier in this chapter. Also, that click handler is massive, so it’s difficult to see what’s going on. Furthermore, if another developer wanted to extend our plug-in, he’d probably have to rewrite it.

Let’s see how we can use custom events to clean up our code. We’ll fire a change.tabs event when a tab is clicked, and bind several handlers to change the active class as appropriate:

jQuery.fn.tabs = function(control){
  var element = $(this)
  control = $(control);

  element.delegate("li", "click", function(){
    // Retrieve tab name
    var tabName = $(this).attr("data-tab");

    // Fire custom event on tab click
    element.trigger("change.tabs", tabName);
  });

  // Bind to custom event
  element.bind("change.tabs", function(e, tabName){
    element.find("li").removeClass("active");
    element.find(">[data-tab='" + tabName + "']").addClass("active");
  });

  element.bind("change.tabs", function(e, tabName){
    control.find(">[data-tab]").removeClass("active");
    control.find(">[data-tab='" + tabName + "']").addClass("active");
  });

  // Activate first tab
  var firstName = element.find("li:first").attr("data-tab");
  element.trigger("change.tabs", firstName);

  return this;
};

See how much cleaner the code is with custom event handlers? It means we can split up the tab change handlers, and it has the added advantage of making the plug-in much easier to extend. For example, we can now programmatically change tabs by firing our change.tabs event on the observed list:

$("#tabs").trigger("change.tabs", "users");

We could also tie up the tabs with the window’s hash, adding back button support:

$("#tabs").bind("change.tabs", function(e, tabName){
  window.location.hash = tabName;
});

$(window).bind("hashchange", function(){
  var tabName = window.location.hash.slice(1);
  $("#tabs").trigger("change.tabs", tabName);
});

The fact that we’re using custom events gives other developers a lot of scope when extending our work.

Event-based programming is very powerful because it decouples your application’s architecture, leading to better self-containment and maintainability. Events aren’t restricted to the DOM though, so you can easily write your own event handler library. The pattern is called Publish/Subscribe, and it’s a good one to be familiar with.

Publish/Subscribe, or Pub/Sub, is a messaging pattern with two actors, publishers, and subscribers. Publishers publish messages to a particular channel, and subscribers subscribe to channels, receiving notifications when new messages are published. The key here is that publishers and subscribers are completely decoupled—they have no idea of each other’s existence. The only thing the two share is the channel name.

The decoupling of publishers and subscribers allows your application to grow without introducing a lot of interdependency and coupling, improving the ease of maintenance, as well as adding extra features.

So, how do you actually go about using Pub/Sub in an application? All you need to do is record handlers associated with an event name and then have a way of invoking them. Here’s an example PubSub object, which we can use for adding and triggering event listeners:

var PubSub = {
  subscribe: function(ev, callback) {
    // Create _callbacks object, unless it already exists
    var calls = this._callbacks || (this._callbacks = {});

    // Create an array for the given event key, unless it exists, then
    // append the callback to the array
    (this._callbacks[ev] || (this._callbacks[ev] = [])).push(callback);
    return this;
  },

  publish: function() {
    // Turn arguments object into a real array
    var args = Array.prototype.slice.call(arguments, 0);

    // Extract the first argument, the event name
    var ev   = args.shift();

    // Return if there isn't a _callbacks object, or
    // if it doesn't contain an array for the given event
    var list, calls, i, l;
    if (!(calls = this._callbacks)) return this;
    if (!(list  = this._callbacks[ev])) return this;

    // Invoke the callbacks
    for (i = 0, l = list.length; i < l; i++)
      list[i].apply(this, args);
    return this;
  }
};

// Example usage
PubSub.subscribe("wem", function(){
  alert("Wem!");
});

PubSub.publish("wem");

You can namespace events by using a separator, such as a colon (:).

PubSub.subscribe("user:create", function(){ /* ... */ });

If you’re using jQuery, there’s an even easier library by Ben Alman. It’s so short, in fact, that we can put it inline:

/*!
 * jQuery Tiny Pub/Sub - v0.3 - 11/4/2010
 * http://benalman.com/
 *
 * Copyright (c) 2010 "Cowboy" Ben Alman
 * Dual licensed under the MIT and GPL licenses.
 * http://benalman.com/about/license/
 */

(function($){
  var o = $({});

  $.subscribe = function() {
    o.bind.apply( o, arguments );
  };

  $.unsubscribe = function() {
    o.unbind.apply( o, arguments );
  };

  $.publish = function() {
    o.trigger.apply( o, arguments );
  };
})(jQuery);

The API takes the same arguments as jQuery’s bind() and trigger() functions. The only difference is that the functions reside directly on the jQuery object, and they are called publish() and subscribe():

$.subscribe( "/some/topic", function( event, a, b, c ) {
  console.log( event.type, a + b + c );
});

$.publish("/some/topic", ["a", "b", "c"]);

We’ve been using Pub/Sub for global events, but it’s just as easy to scope it. Let’s take the PubSub object we created previously and scope it to an object:

var Asset = {};

// Add PubSub
jQuery.extend(Asset, PubSub);

// We now have publish/subscribe functions
Asset.subscribe("create", function(){
  // ...
});

We’re using jQuery’s extend() to copy PubSub’s properties onto our Asset object. Now, all calls to publish() and subscribe() are scoped by Asset. This is useful in lots of scenarios, including events in an object-relational mapping (ORM), changes in a state machine, or callbacks once an Ajax request has finished.

Ensuring that there’s a clear separation between your application’s views, state, and data is crucial to keeping its architecture uncluttered and sustainable. With the MVC pattern, data management happens in models (the “M” of MVC). Models should be decoupled from views and controllers. Any logic associated with data manipulation and behavior should reside in models and be namespaced properly.

In JavaScript, you can namespace functions and variables by making them properties of an object. For example:

var User = {
  records: [ /* ... */ ]
};

The array of users is namespaced properly under User.records. Functions associated with users can also be namespaced under the User model. For example, we can have a fetchRemote() function for fetching user data from a server:

var User = {
  records: [],
  fetchRemote: function(){ /* ... */ }
};

Keeping all of a model’s properties under a namespace ensures that you don’t get any conflicts and that it’s MVC-compliant. It also prevents your code from spiraling down into a tangled mess of functions and callbacks.

You can take namespacing a step further and keep any functions specific to user instances on the actual user objects. Let’s say we had a destroy() function for user records; it refers to specific users, so it should be on User instances:

var user = new User;
user.destroy()

To achieve that, we need to make User a class, rather than a plain object:

var User = function(atts){
  this.attributes = atts || {};
};

User.prototype.destroy = function(){
  /* ... */
};

Any functions and variables that don’t relate to specific users can be properties directly on the User object:

User.fetchRemote = function(){
  /* ... */
};

For more information about namespacing, visit Peter Michaux’s blog, where he’s written an excellent article on the subject.

Object-relational mappers, or ORMs, are typically used in languages other than JavaScript. However, they’re a very useful technique for data management as well as a great way of using models in your JavaScript application. With an ORM, for example, you can tie up a model with a remote server—any changes to model instances will send background Ajax requests to the server. Or, you could tie up a model instance with an HTML element—any changes to the instance will be reflected in the view. I’ll elaborate on those examples later, but for now, let’s look at creating a custom ORM.

Essentially, an ORM is just an object layer wrapping some data. Typically, ORMs are used to abstract SQL databases, but in our case, the ORM will just be abstracting JavaScript data types. The advantage of this extra layer is that we can enhance the basic data with more functionality by adding our own custom functions and properties. This lets us add things like validation, observers, persistence, and server callbacks while still being able to reuse a lot of code.

if (typeof Object.create !== "function")
    Object.create = function(o) {
      function F() {}
      F.prototype = o;
      return new F();
    };

var Model = {
  inherited: function(){},
  created: function(){},

  prototype: {
    init: function(){}
  },

  create: function(){
    var object = Object.create(this);
    object.parent = this;
    object.prototype = object.fn = Object.create(this.prototype);

    object.created();
    this.inherited(object);
    return object;
  },

  init: function(){
    var instance = Object.create(this.prototype);
    instance.parent = this;
    instance.init.apply(instance, arguments);
    return instance;
  }
};

var Asset = Model.create();
var User  = Model.create();

var user = User.init();

// Add object properties
jQuery.extend(Model, {
  find: function(){}
});

// Add instance properties
jQuery.extend(Model.prototype, {
  init: function(atts) {
    if (atts) this.load(atts);
  },

  load: function(attributes){
    for(var name in attributes)
      this[name] = attributes[name];
  }
});

assertEqual( typeof Asset.find, "function" );

var Model = {
  /* ... snip ... */

  extend: function(o){
    var extended = o.extended;
    jQuery.extend(this, o);
    if (extended) extended(this);
  },

  include: function(o){
    var included = o.included;
    jQuery.extend(this.prototype, o);
    if (included) included(this);
  }
};

// Add object properties
Model.extend({
  find: function(){}
});

// Add instance properties
Model.include({
  init: function(atts) { /* ... */ },
  load: function(attributes){ /* ... */ }
});

var asset = Asset.init({name: "foo.png"});

// An object of saved assets
Model.records = {};

Model.include({
  newRecord: true,

  create: function(){
    this.newRecord = false;
    this.parent.records[this.id] = this;
  },

  destroy: function(){
    delete this.parent.records[this.id];
  }
});

Model.include({
  update: function(){
    this.parent.records[this.id] = this;
  }
});

// Save the object to the records hash, keeping a reference to it
Model.include({
  save: function(){
    this.newRecord ? this.create() : this.update();
  }
});

Model.extend({
  // Find by ID, or raise an exception
  find: function(id){
    var record = this.records[id];
    if ( !record ) throw new Error("Unknown record");
    return record;
  }
});

var asset  = Asset.init();
asset.name = "same, same";
asset.id   = 1
asset.save();

var asset2  = Asset.init();
asset2.name = "but different";
asset2.id   = 2;
asset2.save();

assertEqual( Asset.find(1).name, "same, same" );

asset2.destroy();

At the moment, every time we save a record we have to specify an ID manually. This sucks, but fortunately, it’s something we can automate. First, we need a way of generating IDs, which we can do with a Globally Unique Identifier (GUID) generator. Well, technically, JavaScript can’t generate official, bona fide 128-bit GUIDs for API reasons—it can only generate pseudorandom numbers. Generating truly random GUIDs is a notoriously difficult problem, and operating systems calculate them using the MAC address, mouse position, and BIOS checksums, or by measuring electrical noise or radioactive decay—and even lava lamps! However, JavaScript’s native Math.random(), although pseudorandom, will be enough for our needs.

Robert Kieffer has written an easy and succinct GUID generator that uses Math.random() to generate pseudorandom GUIDs. It’s so simple that we can put it inline:

Math.guid = function(){
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    var r = Math.random()*16|0, v = c == 'x' ? r : (r&0x3|0x8);
    return v.toString(16);
  }).toUpperCase();
};

Now that we have a function to generate GUIDs, integrating that into our ORM is simple; all we need to change is the create() function:

Model.include({
  create: function(){
    if ( !this.id ) this.id = Math.guid();
    this.newRecord = false;
    this.parent.records[this.id] = this;
  }
});

Now, any newly created records have random GUIDs as their ID:

var asset = Asset.init();
asset.save();

asset.id //=> "54E52592-313E-4F8B-869B-58D61F00DC74"

If you’ve been observing closely, you might have spotted a bug relating to the references in our ORM. We’re not cloning instances when they’re returned by find() or when we’re saving them, so if we change any properties, they’re changed on the original asset. This is a problem because we only want assets to update when we call the update() function:

var asset = Asset.init({name: "foo"});
asset.save();

// Assert passes correctly
assertEqual( Asset.find(asset.id).name, "foo" );

// Let's change a property, but not call update()
asset.name = "wem";

// Oh dear! This assert fails, as the asset's name is now "wem"
assertEqual( Asset.find(asset.id).name, "foo" );

Let’s fix that by creating a new object during the find() operation. We’ll also need to duplicate the object whenever we create or update the record:

Model.extend({
  find: function(id){
    var record = this.records[id];
    if ( !record ) throw("Unknown record");
    return record.dup();
  }
});

Model.include({
  create: function(){
    this.newRecord = false;
    this.parent.records[this.id] = this.dup();
  },

  update: function(){
    this.parent.records[this.id] = this.dup();
  },

  dup: function(){
    return jQuery.extend(true, {}, this);
  }
});

We have another problem—Model.records is an object shared by every model:

assertEqual( Asset.records, Person.records );

This has the unfortunate side effect of mixing up all the records:

var asset = Asset.init();
asset.save();

assert( asset in Person.records );

The solution is to set a new records object whenever we create a new model. Model.created() is the callback for new object creation, so we can set any objects that are specific to the model in there:

Model.extend({
  created: function(){
    this.records = {};
  }
});

Unless your web application is entirely restricted to the browser, you’ll need to load in remote data from a server. Typically, a subset of data is loaded when the application starts, and more data is loaded after the interaction. Depending on the type of application and the amount of data, you may be able to load everything you need on the initial page load. This is ideal, so users never have to wait for more data to be loaded. However, this isn’t feasible for a lot of applications because there’s too much data to fit comfortably in a browser’s memory.

Preloading data is crucial to making your application feel slick and fast to your users, keeping any waiting time to a minimum. However, there’s a fine line between preloading data that’s actually accessed and loading redundant data that’s never used. You need to predict what sort of data your users will want (or use metrics once your application is live).

If you’re displaying a paginated list, why not preload the next page so transitions are instant? Or, even better, just display a long list and automatically load and insert data as the list is scrolled (the infinite scroll pattern). The less latency a user feels, the better.

When you do fetch new data, make sure the UI isn’t blocked. Display some sort of loading indicator, but make sure the interface is still usable. There should be very few scenarios, if any, that require blocking the UI.

Data can be present inline in the initial page or loaded with separate HTTP requests through Ajax or JSONP. Personally, I would recommend the latter two technologies, as including a lot of data inline increases the page size, whereas parallel requests load faster. AJAX and JSON also let you cache the HTML page, rather than dynamically render it for every request.

<script type="text/javascript">
  var User = {};
  User.records = <%= raw @users.to_json %>;
</script>

<script type="text/javascript">
  var User = {};
  User.records = [{"first_name": "Alex"}];
</script>

jQuery.ajax({
  url: "/ajax/endpoint",
  type: "GET",
  success: function(data) {
    alert(data);
  }
});

jQuery.get("/ajax/endpoint", function(data){
  $(".ajaxResult").text(data);
});

jQuery.get("/ajax/endpoint", {foo: "bar"}, function(data){
  /* ... */
});

jQuery.getJSON("/json/endpoint", function(json){
  /* ... */
});

jQuery.post("/users", {first_name: "Alex"}, function(result){
  /* Ajax POST was a success */
});

Access-Control-Allow-Origin: example.com
Access-Control-Request-Method: GET,POST

Access-Control-Request-Headers: Authorization

var req = new XMLHttpRequest();
req.open("POST", "/endpoint", true);
req.setRequestHeader("Authorization", oauth_signature);

<script src="http://example.com/data.json"> </script>

jsonCallback({"data": "foo"})

window.jsonCallback = function(result){
  // Do stuff with the result
}

jQuery.getJSON("http://example.com/data.json?callback=?", function(result){
  // Do stuff with the result
});

Populating our ORM with data is pretty straightforward. All we need to do is fetch the data from the server and then update our model’s records. Let’s add a populate() function to the Model object, which will iterate over any values given, create instances, and update the records object:

Model.extend({
  populate: function(values){
    // Reset model & records
    this.records = {};

    for (var i=0, il = values.length; i < il; i++) {
      var record = this.init(values[i]);
      record.newRecord = false;
      this.records[record.id] = record;
    }
  }
});

Now, we can use the Model.populate() function with the result of our request for data:

jQuery.getJSON("/assets", function(result){
  Asset.populate(result);
});

Any records the server returned will now be available in our ORM.

In the past, local data storage was a pain in the neck. The only options available to use were cookies and plug-ins like Adobe Flash. Cookies had an antiquated API, couldn’t store much data, and sent all the data back to the server on every request, adding unnecessary overhead. As for Flash, well, let’s try and steer clear of plug-ins if possible.

Fortunately, support for local storage was included in HTML5 and is implemented in the major browsers. Unlike cookies, data is stored exclusively on the client side and is never sent to servers. You can also store a great deal more data—the maximum amount differs per browser (and version number, as listed below), but they all offer at least 5 MB per domain:

HTML5 storage comes under the HTML5 Web Storage specification, and consists of two types: local storage and session storage. Local storage persists after the browser is closed; session storage persists only for the lifetime of the window. Any data stored is scoped by domain and is only accessible to scripts from the domain that originally stored the data.

You can access and manipulate local storage and session storage using the localStorage and sessionStorage objects, respectively. The API is very similar to setting properties on a JavaScript object and, apart from the two objects, is identical for both local and session storage:

// Setting a value
localStorage["someData"] = "wem";

There are a few more features to the WebStorage API:

// How many items are stored
var itemsStored = localStorage.length;

// Set an item (aliased to a hash syntax)
localStorage.setItem("someData", "wem");

// Get a stored item, returning null if unknown
localStorage.getItem("someData"); //=> "wem";

// Delete an item, returning null if unknown
localStorage.removeItem("someData");

// Clear all items
localStorage.clear();

Data is stored as strings, so if you intend on saving any objects or integers, you’ll have to do your own conversion. To do this using JSON, serialize the objects into JSON before you save them, and deserialize the JSON strings when fetching them:

var object = {some: "object"};

// Serialize and save an object
localStorage.setItem("seriData", JSON.stringify(object));

// Load and deserialize an object
var result = JSON.parse(localStorage.getItem("seriData"));

If you go over your storage quota (usually 5 MB per host), a QUOTA_EXCEEDED_ERR will be raised when saving additional data.

Let’s add local storage support to our ORM so that records can be persisted between page refreshes. To use the localStorage object, we need to serialize our records into a JSON string. The problem is that, at the moment, serialized objects look like this:

var json = JSON.stringify(Asset.init({name: "foo"}));
json //=> "{"parent":{"parent":{"prototype":{}},"records":[]},"name":"foo"}"

So, we need to override JSON’s serialization of our models. First, we need to determine which properties need to be serialized. Let’s add an attributes array to the Model object, which individual models can use to specify their attributes:

Model.extend({
  created: function(){
    this.records = {};
    this.attributes = [];
  }
});

Asset.attributes = ["name", "ext"];

Because every model has different attributes—and therefore can’t share the same array reference—the attributes property isn’t set directly on the Model. Instead, we’re creating a new array when a model is first created, similar to what we’re doing with the records object.

Now, let’s create an attributes() function, which will return an object of attribute names to values:

Model.include({
  attributes: function(){
    var result = {};
    for(var i in this.parent.attributes) {
      var attr = this.parent.attributes[i];
      result[attr] = this[attr];
    }
    result.id = this.id;
    return result;
  }
});

Now, we can set an array of attributes for every model:

Asset.attributes = ["name", "ext"];

And the attributes() function will return an object with the correct properties:

var asset = Asset.init({name: "document", ext: ".txt"});
asset.attributes(); //=> {name: "document", ext: ".txt"};

As for the overriding of JSON.stringify(), all that’s needed is a toJSON() method on model instances. The JSON library will use that function to find the object to serialize, rather than serializing the records object as-is:

Model.include({
  toJSON: function(){
    return(this.attributes());
  }
});

Let’s try serializing the records again. This time, the resultant JSON will contain the correct properties:

var json = JSON.stringify(Asset.records);
json //= "{"7B2A9E8D...":"{"name":"document","ext":".txt","id":"7B2A9E8D..."}"}"

Now that we’ve got JSON serializing working smoothly, adding local storage support to our models is trivial. We’ll add two functions onto our Model: saveLocal() and loadLocal(). When saving, we’ll convert the Model.records object into an array, serialize it, and send it to localStorage:

Model.LocalStorage = {
  saveLocal: function(name){
    // Turn records into an array
    var result = [];
    for (var i in this.records)
      result.push(this.records[i])

    localStorage[name] = JSON.stringify(result);
  },

  loadLocal: function(name){
    var result = JSON.parse(localStorage[name]);
    this.populate(result);
  }
};

Asset.extend(Model.LocalStorage);

It’s probably a good idea for the records to be read from the local storage when the page loads and to be saved when the page is closed. That, however, will be left as an exercise for the reader.

Earlier, we covered how to use jQuery’s post() function to send data to the server. The function takes three arguments: the endpoint URL, request data, and a callback:

jQuery.post("/users", {first_name: "Alex"}, function(result){
  /* Ajax POST was a success */
});

Now that we have an attributes() function, creating records to the server is simple—just POST the record’s attributes:

jQuery.post("/assets", asset.attributes(), function(result){
  /* Ajax POST was a success */
});

If we’re following REST conventions, we’ll want to do an HTTP POST when creating a record and a PUT request when updating the record. Let’s add two functions to Model instances—createRemote() and updateRemote()—which will send the correct HTTP request type to our server:

Model.include({
  createRemote: function(url, callback){
    $.post(url, this.attributes(), callback);
  },

  updateRemote: function(url, callback){
    $.ajax({
      url:     url,
      data:    this.attributes(),
      success: callback,
      type:    "PUT"
    });
  }
});

Now if we call createRemote() on an Asset instance, its attributes will be POSTed to the server:

// Usage:
Asset.init({name: "jason.txt"}).createRemote("/assets");

The module pattern is a great way to encapsulate logic and prevent global namespace pollution. It’s all made possible by anonymous functions, which are arguably the single best feature of JavaScript. We’ll just create an anonymous function and execute it immediately. All the code residing within the function runs inside a closure, providing a local and private environment for our application’s variables:

(function(){
  /* ... */
})();

We have to surround the anonymous function with braces () before we can execute it. JavaScript requires this so it can interpret the statement correctly.

(function($){
  /* ... */
})(jQuery);

(function($, exports){

  exports.Foo = "wem";

})(jQuery, window);

assertEqual( Foo, "wem" );

Using a local context is a useful way of structuring modules, especially when it comes to registering callbacks to events. As it stands, the context inside our module is global—this is equal to window:

(function(){
  assertEqual( this, window );
})();

If we want to scope the context, we need to start adding functions onto an object. For example:

(function(){
  var mod = {};

  mod.contextFunction = function(){
    assertEqual( this, mod );
  };

  mod.contextFunction();
})();

The context inside contextFunction() is now local to our mod object. We can start using this without worrying about creating global variables. To give you a better indication of how it would be used in practice, let’s further flesh out that example:

(function($){

  var mod = {};

  mod.load = function(func){
    $($.proxy(func, this));
  };

  mod.load(function(){
    this.view = $("#view");
  });

  mod.assetsClick = function(e){
    // Process click
  };

  mod.load(function(){
    this.view.find(".assets").click(
      $.proxy(this.assetsClick, this)
    );
  });

})(jQuery);

We’re creating a load() function that takes a callback, executing it when the page has loaded. Notice that we’re using jQuery.proxy() to ensure that the callback is invoked in the correct context.

Then, when the page loads, we’re adding a click handler onto an element, giving it a local function, assetsClick(), as a callback. Creating a controller doesn’t need to be any more complicated than that. What’s important is that all of the controller’s state is kept local and encapsulated cleanly into a module.

(function($, exports){
  var mod = function(includes){
    if (includes) this.include(includes);
  };
  mod.fn = mod.prototype;

  mod.fn.proxy = function(func){
    return $.proxy(func, this);
  };

  mod.fn.load = function(func){
    // Invokes the function when the DOM is ready
    $(this.proxy(func));
  };

  mod.fn.include = function(ob){
    $.extend(this, ob);
  };

  exports.Controller = mod;
})(jQuery, window);

(function($, Controller){

  var mod = new Controller;

  mod.toggleClass = function(e){
    this.view.toggleClass("over", e.data);
  };

  mod.load(function(){
    this.view = $("#view");
    this.view.mouseover(this.proxy(this.toggleClass));
    this.view.mouseout(this.proxy(this.toggleClass));
  });

})(jQuery, Controller);

Controller.fn.unload = function(func){
  jQuery(window).bind("unload", this.proxy(func));
};

var mod = new Controller;
mod.include(StateMachine);

// Use global context, rather than the window
// object, to create global variables
var exports = this;

(function($){
  var mod = {};

  mod.create = function(includes){
    var result = function(){
      this.init.apply(this, arguments);
    };

    result.fn = result.prototype;
    result.fn.init = function(){};

    result.proxy    = function(func){ return $.proxy(func, this); };
    result.fn.proxy = result.proxy;

    result.include = function(ob){ $.extend(this.fn, ob); };
    result.extend  = function(ob){ $.extend(this, ob); };
    if (includes) result.include(includes)

    return result;
  };

  exports.Controller = mod;
})(jQuery);

jQuery(function($){
  var ToggleView = Controller.create({
    init: function(view){
      this.view = $(view);
      this.view.mouseover(this.proxy(this.toggleClass), true);
      this.view.mouseout(this.proxy(this.toggleClass), false);
    },

    toggleClass: function(e){
      this.view.toggleClass("over", e.data);
    }
  });

  // Instantiate controller, calling init()
  new ToggleView("#view");
});

// ...
init: function(view){
  this.view = $(view);
  this.form = this.view.find("form");
}

elements: {
  "form.searchForm": "searchForm",
  "form input[type=text]": "searchInput"
}

var exports = this;

jQuery(function($){
  exports.SearchView = Controller.create({
    // Map of selectors to local variable names
    elements: {
      "input[type=search]": "searchInput",
      "form": "searchForm"
    },

    // Called upon instantiation
    init: function(element){
      this.el = $(element);
      this.refreshElements();
      this.searchForm.submit(this.proxy(this.search));
    },

    search: function(){
      console.log("Searching:", this.searchInput.val());
    },

    // Private

    $: function(selector){
      // An `el` property is required, and scopes the query
      return $(selector, this.el);
    },

    // Set up the local variables
    refreshElements: function(){
      for (var key in this.elements) {
        this[this.elements[key]] = this.$(key);
      }
    }
  });

  new SearchView("#users");
});

events: {
  "submit form": "submit"
}

var exports = this;

jQuery(function($){
  exports.SearchView = Controller.create({
    // Map all the event names,
    // selectors, and callbacks
    events: {
      "submit form": "search"
    },

    init: function(){
      // ...
      this.delegateEvents();
    },

    search: function(e){ /* ... */ },

    // Private

    // Split on the first space
    eventSplitter: /^(\w+)\s*(.*)$/,

    delegateEvents: function(){
      for (var key in this.events) {
        var methodName = this.events[key];
        var method     = this.proxy(this[methodName]);

        var match      = key.match(this.eventSplitter);
        var eventName  = match[1], selector = match[2];

        if (selector === '') {
          this.el.bind(eventName, method);
        } else {
          this.el.delegate(selector, eventName, method);
        }
      }
    }
  });

  var exports = this;

  jQuery(function($){
    exports.SearchView = Controller.create({
      elements: {
        "input[type=search]": "searchInput",
        "form": "searchForm"
      },

      events: {
        "submit form": "search"
      },

      init: function(){ /* ... */ },

      search: function(){
        alert("Searching: " + this.searchInput.val());
        return false;
      },
    });

    new SearchView({el: "#users"});
  });

State machines—or to use their proper term, Finite State Machines (FSMs)—are a great way to program UIs. Using state machines, you can easily manage multiple controllers, showing and hiding views as necessary. So, what exactly is a state machine? At its core, a state machine consists of two things: states and transitions. It has only one active state, but it has a multitude of passive states. When the active state switches, transitions between the states are called.

How does this work in practice? Well, consider having a few application views that need to be displayed independently—say, a view for showing contacts and a view for editing contacts. These two views need to be displayed exclusively—when one is shown, the other view needs to be hidden. This is a perfect scenario to introduce a state machine because it will ensure that only one view is active at any given time. Indeed, if we want to add additional views, such as a settings view, using a state machine makes this trivial.

Let’s flesh out a practical example that will give you a good idea of how state machines can be implemented. The example is simple and doesn’t cater to different transition types, but it is sufficient for our needs. First, we’re going to create an Events object that will use jQuery’s event API (as discussed in Chapter 2) to add the ability to bind and trigger events on our state machine:

var Events = {
  bind: function(){
    if ( !this.o ) this.o = $({});
    this.o.bind.apply(this.o, arguments);
  },

  trigger: function(){
    if ( !this.o ) this.o = $({});
    this.o.trigger.apply(this.o, arguments);
  }
};

The Events object is essentially extending jQuery’s existing event support outside the DOM so that we can use it in our own library. Now let’s set about creating the StateMachine class, which will have one main function, add():

var StateMachine = function(){};
StateMachine.fn  = StateMachine.prototype;

// Add event binding/triggering
$.extend(StateMachine.fn, Events);

StateMachine.fn.add = function(controller){
  this.bind("change", function(e, current){
    if (controller == current)
      controller.activate();
    else
      controller.deactivate();
  });

  controller.active = $.proxy(function(){
    this.trigger("change", controller);
  }, this);
};

The state machine’s add() function adds the passed controller to the list of states and creates an active() function. When active() is called, the active state will transition to the controller. The state machine will call activate() on the active controller and deactivate() on all the other controllers. We can see how this works by creating two example controllers, adding them to the state machine, and then activating one of them:

var con1 = {
  activate:   function(){ /* ... */ },
  deactivate: function(){ /* ... */ }
};

var con2 = {
  activate:   function(){ /* ... */ },
  deactivate: function(){ /* ... */ }
};

// Create a new StateMachine and add states
var sm = new StateMachine;
sm.add(con1);
sm.add(con2);

// Activate first state
con1.active();

The state machine’s add() function works by creating a callback for the change event, calling the activate() or deactivate() function, depending on which is appropriate. Although the state machine gives us an active() function, we can also change the state by manually triggering the change event:

sm.trigger("change", con2);

Inside our controller’s activate() function, we can set up and display its view, adding and showing elements. Likewise, inside the deactivate() function, we can tear down anything that is hiding the view. CSS classes offer a good way of hiding and showing views. Simply add a class—say, .active—when the view is active, and remove it upon deactivation:

var con1 = {
  activate: function(){
    $("#con1").addClass("active");
  },
  deactivate: function(){
    $("#con1").removeClass("active");
  }
};

var con2 = {
  activate: function(){
    $("#con2").addClass("active");
  },
  deactivate: function(){
    $("#con2").removeClass("active");
  }
};

Then, in your stylesheets, make sure that the views have a .active class; otherwise, they’re hidden:

#con1, #con2 { display: none; }
#con1.active, #con2.active { display: block; }

You can see the full examples in assets/ch04/state_machine.html.

Our application is now running from a single page, which means its URL won’t change. This is a problem for our users because they’re accustomed to having a unique URL for a resource on the Web. Additionally, people are used to navigating the Web with the browser’s back and forward buttons.

To resolve this, we want to tie the application’s state to the URL. When the application’s state changes, so will the URL. The reverse is true, too—when the URL changes, so will the application’s state. During the initial page load, we’ll check the URL and set up the application’s initial state.

http://twitter.com/#!/maccman

// Set the hash
window.location.hash = "foo";
assertEqual( window.location.hash , "#foo" );

// Strip "#"
var hashValue = window.location.hash.slice(1);
assertEqual( hashValue, "foo" );

window.addEventListener("hashchange", function(){ /* ... */ }, false);

$(window).bind("hashchange", function(event){
  // hash changed, change state
});

jQuery(function($){
  var hashValue = location.hash.slice(1);
  if (hashValue)
    $(window).trigger("hashchange");
});

http://twitter.com/#!/maccman

http://twitter.com/?_escaped_fragment_=/maccman

curl -v http://twitter.com/?_escaped_fragment_=/maccman
  302 redirected to http://twitter.com/maccman

// The data object is arbitrary and is passed with the popstate event
var dataObject = {
    createdAt: '2011-10-10',
    author:    'donnamoss'
};

var url = '/posts/new-url';
history.pushState(dataObject, document.title, url);

window.addEventListener("popstate", function(event){
  if (event.state) {
    // history.pushState() was called
  }
});

$(window).bind("popstate", function(event){
  event = event.originalEvent;
  if (event.state) {
    // history.pushState() was called
  }
});

One way to create views is pragmatically via JavaScript. You can create DOM elements using document.createElement(), setting their contents and appending them to the page. When it’s time to redraw the view, just empty the view and repeat the process:

var views = document.getElementById("views");
views.innerHTML = ""; // Empty the element

var container = document.createElement("div");
container.id = "user";

var name = document.createElement("span");
name.innerHTML = data.name;

container.appendChild(name);
views.appendChild(container);

Or, for a more succinct API with jQuery:

$("#views").empty();

var container = $("<div />").attr({id: "user"});
var name      = $("<span />").text(data.name);

$("#views").append(container.append(name));

I’d only advocate this if the view you need to render is very small, perhaps just a couple of elements. Placing view elements in your controllers or states compromises the application’s MVC architecture.

Instead of creating the elements from scratch, I advise including the static HTML in the page—hiding and showing it when necessary. This will keep any view-specific code in your controllers to an absolute minimum, and you can just update the element’s contents when necessary.

For example, let’s create an HTML fragment that will serve as our view:

<div id="views">
  <div class="groups"> ... </div>
  <div class="user">
    <span></span>
  </div>
</div>

Now, we can use jQuery selectors to update the view and to toggle the display of the various elements:

$("#views div").hide();

var container = $("#views .user");
container.find("span").text(data.name);
container.show();

This method is preferable to generating the elements because it keeps the view and controller as separate as possible.

If you’re used to interpolating server variables in HTML, templating will be familiar. There are a variety of templating libraries out there—your choice will probably depend on which DOM library you’re using. However, most of them share a similar syntax, which I’ll describe below.

The gist of JavaScript templates is that you can take an HTML fragment interpolated with template variables and combine it with a JavaScript object, replacing those template variables with values from the object. Overall, JavaScript templating works in much the same way as templating libraries in other languages, such as PHP’s Smarty, Ruby’s ERB, and Python’s string formatting.

We’re going to use the jQuery.tmpl library as the basis for the templating examples. If you aren’t using jQuery, or if you want to use a different templating library, the examples should still be useful; the templating syntax for most libraries is very similar, if not identical. If you want a good alternative, check out Mustache, which has implementations in a lot of languages, including JavaScript.

Created by Microsoft, jQuery.tmpl is a templating plug-in based on John Resig’s original work. It’s a well-maintained library and is fully documented on the jQuery site. The library has one main function, jQuery.tmpl(), to which you can pass a template and some data. It renders a template element that you can append to the document. If the data is an array, the template is rendered once for every data item in the array; otherwise, a single template is rendered:

var object = {
  url: "http://example.com",
  getName: function(){ return "Trevor"; }
};

var template = '<li><a href="${url}">${getName()}</a></li>';

var element = jQuery.tmpl(template, object);
// Produces: <li><a href="http://example.com">Trevor</a></li>

$("body").append(element);

So, you can see we’re interpolating variables using the ${} syntax. Whatever is inside the brackets is evaluated in the context of the object passed to jQuery.tmpl(), regardless of whether it is a property or a function.

However, templates are much more powerful than mere interpolation. Most templating libraries have advanced features like conditional flow and iteration. You can control flow by using if and else statements, the same as with pure JavaScript. The difference here is that we need to wrap the keyword with double brackets so that the templating engine can pick them up:

{{if url}}
  ${url}
{{/if}}

The if block will be executed if the specified attribute value doesn’t evaluate to false, 0, null, "", Nan, or undefined. As you can see, the block is closed with a {{/if}}, so don’t forget to include that! A common pattern is to display a message when an array—say, of chat messages—is empty:

{{if messages.length}}
  <!-- Display messages... -->
{{else}}
  <p>Sorry, there are no messages</p>
{{/if}}

No templating library can afford to be without iteration. With JS templating libraries, you can iterate over any JavaScript type—Object or Array—using the {{each}} keyword. If you pass an Object to {{each}}, it will iterate a block over the object’s properties. Likewise, passing an array results in the block iterating over every index in the array.

When inside the block, you can access the value currently being iterated over using the $value variable. Displaying the value is the same as the interpolation example above, which uses ${$value}. Consider this object:

var object = {
  foo: "bar",
  messages: ["Hi there", "Foo bar"]
};

Then, use the following template to iterate through the messages array, displaying each message. Additionally, the current iteration’s index is also exposed using the $index variable.

<ul>
  {{each messages}}
    <li>${$index + 1}: <em>${$value}</em></li>
  {{/each}}
</ul>

As you can see, the jQuery.tmpl templating API is very straightforward. As I mentioned earlier, most of the alternative templating libraries have a similar API, although many offer more advanced features, such as lambdas, partials, and comments.

<div>
  ${ this.data.replace(
/((http|https|ftp):\/\/[\w?=&.\/-;#~%-]+(?![\w\s?&.\/;#~%"=-]*>))/g,
'<a target="_blank" href="$1">$1</a> ') }
</div>

// helper.js
var helper = {};
helper.autoLink = function(data){
  var re = /((http|https|ftp):\/\/[\w?=&.\/-;#~%-]+(?![\w\s?&.\/;#~%"=-]*>))/g;
  return(data.replace(re, '<a target="_blank" href="$1">$1</a> ') );
};

// template.html
<div>
  ${ helper.autoLink(this.data) }
</div>

<script type="text/x-jquery-tmpl" id="someTemplate">
  <span>${getName()}</span>
</script>

<script>
  var data = {
    getName: function(){ return "Bob" }
  };
  var element = $("#someTemplate").tmpl(data);
  element.appendTo($("body"));
</script>

Binding is where you start to see the real benefits of view rendering on the client side. Essentially, binding hooks together a view element and a JavaScript object (usually a model). When the JavaScript object changes, the view automatically updates to reflect the newly modified object. In other words, once you’ve got your views and models bound together, the views will rerender automatically when the application’s models are updated.

Binding is a really big deal. It means your controllers don’t have to deal with updating views when changing records, because it all happens automatically in the background. Structuring your application using binders also paves the way for real-time applications, which we’ll cover in depth in Chapter 8.

So, in order to bind JavaScript objects and views, we need to get a callback that instructs the view to update when an object’s property changes. The trouble is that JavaScript doesn’t provide a native method for doing that. The language doesn’t have any method_missing functionality like in Ruby or Python, and it isn’t yet possible to emulate the behavior using JavaScript getters and setters. However, because JavaScript is a very dynamic language, we can roll our own change callback:

var addChange = function(ob){
  ob.change = function(callback){
    if (callback) {
      if ( !this._change ) this._change = [];
      this._change.push(callback);
    } else {
      if ( !this._change ) return;
      for (var i=0; i < this._change.length; i++)
        this._change[i].apply(this);
    }
  };
};

The addChange() function adds a change() function onto any object it’s passed. The change() function works exactly the same as the change event in jQuery. You can add callbacks by invoking change() with a function, or trigger the event by calling change() without any arguments. Let’s see it in practice:

var object = {};
object.name = "Foo";

addChange(object);

object.change(function(){
  console.log("Changed!", this);
  // Potentially update view
});

object.change();

object.name = "Bar";
object.change();

So, you see we’ve added a change() callback to the object, allowing us to bind and trigger change events.

<script>
  var User = function(name){
    this.name = name;
  };

  User.records = []

  User.bind = function(ev, callback) {
    (this._callbacks[ev] || (this._callbacks[ev] = [])).push(callback);
  };

  User.trigger = function(ev) {
    var list, calls, i, l;
    if (!(calls = this._callbacks)) return this;
    if (!(list  = calls[ev])) return this;
    jQuery.each(list, function(){ this() })
  };

  User.create = function(name){
    this.records.push(new this(name));
    this.trigger("change")
  };

  jQuery(function($){
    User.bind("change", function(){
      var template = $("#userTmpl").tmpl(User.records);

      $("#users").empty();
      $("#users").append(template);
    });
  }):
</script>

<script id="userTmpl" type="text/x-jquery-tmpl">
  <li>${name}</li>
</script>

<ul id="users">
</ul>

User.create("Sam Seaborn");

As JavaScript has moved to the server side, several proposals have been put forward for dependency management. SpiderMonkey and Rhino offer a load() function, but they do not have any specific patterns for namespacing. Node.js has the require() function for loading in extra source files, as well as its own module system. The code wasn’t interchangeable, though, so what happens when you want to run your Rhino code on Node.js?

It became obvious that a standard was needed to ensure code interoperability, which all JavaScript implementations could abide by, allowing us to use libraries across all the environments. Kevin Dangoor started the CommonJS initiative to do just that. It began with a blog post in which Kevin advocated a shared standard for JavaScript interpreters and for developers to band together and write some specs:

A mailing list was set up, and CommonJS was born. It quickly gathered momentum with support from the major players. It is now the de facto module format for JavaScript with a growing set of standards, including IO interfaces, Socket streams, and Unit tests.

// maths.js
exports.per = function(value, total) {
  return( (value / total) * 100 );
};

// application.js
var Maths = require("./maths");
assertEqual( Maths.per(50, 100), 50 );

// maths.js
require.define("maths", function(require, exports){

  exports.per = function(value, total) {
    return( (value / total) * 100 );
  };

});

// application.js
require.define("application", function(require, exports){

  var per = require("./maths").per;
  assertEqual( per(50, 100), 50 );

}, ["./maths"]); // List dependencies (maths.js)

To use CommonJS modules on the client side, we need to use a module loader library. There is a variety of options, each with its own strengths and weaknesses. I’ll cover the most popular ones and you can choose which one best suits your needs.

The CommonJS module format is still in flux, with various proposals under review. As it stands, there’s no officially blessed transport format, which unfortunately complicates things. The two main module implementations in the wild are Transport C and Transport D. If you use any of the wrapping tools mentioned in the sections below, you’ll have to make sure it generates wrapped modules in a format your loader supports. Fortunately, many module loaders also come with compatible wrapping tools, or they specify supported ones in their documentation.

<script src="https://github.com/jbrantly/yabble/raw/master/lib/yabble.js"> </script>
<script>
  require.setModuleRoot("javascripts");

  // We can use script tags if the modules
  // are wrapped in the transport format
  require.useScriptTags();

  require.ensure(["application", "utils"], function(require) {
    // Application is loaded
  });
</script>

<script>
  require.ensure(["application", "utils"], function(require) {
    var utils = require("utils");
    assertEqual( utils.per( 50, 200 ), 25 );
  });
</script>

<script>
  require(["lib/application", "lib/utils"], function(application, utils) {
    // Loaded!
  });
</script>

require(["lib/jquery.js"], function($) {
  // jQuery loaded
  $("#el").show();
});

<script data-main="lib/application" src="lib/require.js"></script>

// Inside lib/application.js
require(["jquery", "models/asset", "models/user"], function($, Asset, User) {
    //...
});

define(["underscore", "./utils"], function(_, Utils) {
  return({
    size: 10
  })
});

define(function(require, exports) {
  var mod = require("./relative/name");

  exports.value = "exposed";
});

At this stage, we’ve got dependency management and namespacing, but there’s still the original problem: all those HTTP requests. Any module we depend on has to be loaded in remotely, and even though this happens asynchronously, it’s still a big performance overhead, slowing the startup of our application.

We’re also hand-wrapping our modules in the transport format which, while necessary for asynchronous loading, is fairly verbose. Let’s kill two birds with one stone by using a server-side step to concatenate the modules into one file. This means the browser has to fetch only one resource to load all the modules, which is much more efficient. The build tools available are intelligent, too—they don’t just bundle the modules arbitrarily, but statically analyze them to resolve their dependencies recursively. They’ll also take care of wrapping the modules up in the transport format, saving some typing.

In addition to concatenation, many module build tools also support minification, further reducing the request size. In fact, some tools—such as rack-modulr and Transporter—integrate with your web server, handling module processing automatically when they’re first requested.

For example, here’s a simple Rack CommonJS module server using rack-modulr:

require "rack/modulr"

use Rack::Modulr, :source => "lib", :hosted_at => "/lib"
run Rack::Directory.new("public")

You can start the server with the rackup command. Any CommonJS modules contained inside the lib folder are now concatenated automatically with all their dependencies and are wrapped in a transport callback. Our script loader can then request modules when they’re needed, loading them into the page:

>> curl "http://localhost:9292/lib/application.js"
      require.define("maths"....

If Ruby’s not your thing, there is a multitude of other options from which to choose. FlyScript is a CommonJS module wrapper written in PHP, Transporter is one for JSGI servers, and Stitch integrates with Node.js servers.

You may decide not to go the module route, perhaps because you’ve already got a lot of existing code and libraries to support that can’t be easily converted. Luckily, there are some great alternatives, such as Sprockets. Sprockets adds synchronous require() support to your JavaScript. Comments beginning with //= act as directives to the Sprockets preprocessor. For example, the //= require directive instructs Sprockets to look in its load path for the library, fetch it, and include it inline:

//= require <jquery>
//= require "./states"

In the example above, jquery.js is in Sprockets’ load path, and states.js is required relative to the current file. Sprockets is clever enough to include a library only once, regardless of the amount of time required. As with all the CommonJS module wrappers, Sprockets supports caching and minification. During development, your server can parse and concatenate files on demand in the course of the page load. When the site is live, the JavaScript files can be preconcatenated and served statically, increasing performance.

Although Sprockets is a command-line tool, there are some great integrations to Rack and Rails, such as rack-sprockets. There are even some PHP implementations. The downside to Sprockets—and indeed all these module wrappers—is that all your JavaScript files need to be preprocessed, either by the server or via the command-line tool.

<script>
  $LAB
  .script('/js/json2.js')
  .script('/js/jquery.js').wait()
  .script('/js/jquery-ui.js')
  .script('/js/vapor.js');
</script>

One thing to watch out for with any of these script loaders is that during the page load, users may see a flash of unbehaviored content (FUBC)—i.e., a glimpse at the raw page before any JavaScript is executed. This won’t be a problem if you’re not relying on JavaScript to style or manipulate the initial page. But if you are, address this issue by setting some initial styles in CSS, perhaps hiding a few elements, or by displaying a brief loading splash screen.

Support for the new HTML5 file APIs is not universal, but certainly enough browsers have implementations that it’s worth your while to integrate them.

As there’s no IE support yet, you’ll have to use progressive enhancement. Give users the option of a traditional file input for uploading, as well as allowing the more advanced drag/dropping of files. Detecting support is simple—just check whether the relevant objects are present:

if (window.File && window.FileReader && window.FileList) {
  // API supported
}

The main security consideration behind HTML5’s file handling is that only files selected by the user can be accessed. This can be done by dragging the file onto the browser, selecting it in a file input, or pasting it into a web application. Although there has been some work to expose a filesystem to JavaScript, access has always been sandboxed. Obviously, it would be a tremendous security flaw if JavaScript could read and write arbitrary files on your system.

Files are represented in HTML5 by File objects, which have three attributes:

For security reasons, a file’s path information is never exposed.

Multiple files are exposed as FileList objects, which you can essentially treat as an array of File objects.

File inputs, which have been around since the dawn of the Web, are the traditional way of letting users upload files. HTML5 improves on them, reducing some of their drawbacks. One of the long-standing bugbears for developers was allowing multiple file uploads. In the past, developers had to resort to a mass of file inputs or rely on a plug-in like Adobe Flash. HTML5 addresses this with the multiple attribute. By specifying multiple on a file input, you’re indicating to the browser that users should be allowed to select multiple files. Older browsers that don’t support HTML5 will simply ignore the attribute:

<input type="file" multiple>

The UI isn’t perfect, though; to select multiple files, users need to hold down the Shift key. You may want to show users a message to this effect. For example, Facebook found that 85% of users who uploaded a photo would upload only one photo. By adding a tip that explains how to select multiple photos to the uploading process, as shown in Figure 7-1, the metrics dropped from 85% to 40%.

Another problem for developers was not having any information about which files had been selected. Often, it’s useful to validate the selected files, making sure they’re a certain type or not above a certain size. HTML5 makes this possible now by giving you access to the input’s selected files, using the files attribute.

The read-only files attribute returns a FileList, which you can iterate through, performing your validation, and then informing the user of the result:

var input = $("input[type=file]");

input.change(function(){
  var files = this.files;

  for (var i=0; i < files.length; i++)
    assert( files[i].type.match(/image.*/) )      
});

Figure 7-1. Uploading multiple files on Facebook

Having access to the selected files doesn’t limit you to validation, though. For example, you could read the file’s contents, displaying an upload preview. Or, rather than having the UI block as the files are uploaded, you could upload them in the background using Ajax, displaying a live progress bar. All this and more is covered in the subsequent sections.

Drag and drop support was originally “designed” and implemented by Microsoft back in 1999 for Internet Explorer 5.0, and IE has supported it ever since. The HTML5 specification has just documented what was already there, and now Safari, Firefox, and Chrome have added support, emulating Microsoft’s implementation. However, to put it kindly, the specification is rather a mess, and it requires a fair bit of hoop-jumping to satisfy its often pointless requirements.

There are no less than seven events associated with drag and drop: dragstart, drag, dragover, dragenter, dragleave, drop, and dragend. I’ll elaborate on each in the sections below.

Even if your browser doesn’t support the HTML5 file APIs, it’s likely that you can still use the drag and drop APIs. Currently, the browser requirements are:

<div id="dragme" draggable="true">Drag me!</div>

var element = $("#dragme");

element.bind("dragstart", function(event){
  // We don't want to use jQuery's abstraction
  event = event.originalEvent;

  event.dataTransfer.effectAllowed = "move";
  event.dataTransfer.setData("text/plain", $(this).text());
  event.dataTransfer.setData("text/html", $(this).html());
  event.dataTransfer.setDragImage("/images/drag.png", -10, -10);
});

// Dragging links
event.dataTransfer.setData("text/uri-list", "http://example.com");
event.dataTransfer.setData("text/plain", "http://example.com");

// Multiple links are separated by a new line
event.dataTransfer.setData("text/uri-list", "http://example.com\nhttp://google.com");
event.dataTransfer.setData("text/plain", "http://example.com\nhttp://google.com");

$("#preview").bind("dragstart", function(e){
  e.originalEvent.dataTransfer.setData("DownloadURL", [
    "application/octet-stream",    // MIME type 
    "File.exe",                    // File name
    "http://example.com/file.png"  // File location
  ].join(":"));
});

var element = $("#dropzone");

element.bind("dragenter", function(e){
  // Cancel event
  e.stopPropagation();
  e.preventDefault();
});

element.bind("dragover", function(e){
  // Set the cursor
  e.originalEvent.dataTransfer.dropEffect = "copy";

  // Cancel event
  e.stopPropagation();
  e.preventDefault();
});

element.bind("drop", function(event){
  // Cancel redirection
  event.stopPropagation();
  event.preventDefault();

  event = event.originalEvent;

  // Access dragged files
  var files = event.dataTransfer.files;

  for (var i=0; i < files.length; i++)
    alert("Dropped " + files[i].name);
});

var text = event.dataTransfer.getData("Text");

var dt = event.dataTransfer
for (var i=0; i < dt.types.length; i++)
  console.log( dt.types[i], dt.getData(dt.types[i]) );

$("body").bind("dragover", function(e){
  e.stopPropagation();
  e.preventDefault();
  return false;
});

In addition to drag-and-drop desktop integration, some browsers have support for copying and pasting. The API hasn’t been standardized, and it isn’t part of the HTML5 spec, so you’ll need to determine how to cater to the various browsers.

Again, funnily enough, IE is the pioneer here, with support dating back to IE 5.0. WebKit has taken Microsoft’s API and improved it somewhat, bringing it inline with the drag-and-drop API. Both are virtually identical, except for the different objects: clipboardData rather than dataTransfer.

Firefox has no support yet, and although it has a proprietary API for accessing the clipboard, it’s unwieldy to say the least. WebKit (Safari/Chrome) has good support, and I imagine the W3C will eventually standardize its take on clipboard APIs. Browser support is as follows:

$("textarea").bind("copy", function(event){
  event.stopPropagation();
  event.preventDefault();

  var cd = event.originalEvent.clipboardData;

  // For IE
  if ( !cd ) cd = window.clipboardData;

  // For Firefox
  if ( !cd ) return;

  cd.setData("text/plain", $(this).text());
});

$("textarea").bind("paste", function(event){
  event.stopPropagation();
  event.preventDefault();

  event = event.originalEvent;

  var cd = event.clipboardData;

  // For IE
  if ( !cd ) cd = window.clipboardData;

  // For Firefox
  if ( !cd ) return;

  $("#result").text(cd.getData("text/plain"));

  // Safari event support file pasting
  var files = cd.files;
});

Once you’ve obtained a File reference, you can instantiate a FileReader object to read its contents into memory. Files are read asynchronously—you provide a callback to the FileReader instance, which will be invoked when the file is ready.

FileReader gives you four functions to read file data. Which you use depends on which data format you want returned.

FileReader instances have a number of events that are triggered when one of the above read functions is called. The main ones with which you need to be concerned are:

To use FileReader, just instantiate an instance, add the events, and use one of the read functions. The onload event contains a result attribute, specifying read data in the appropriate format:

var reader = new FileReader();  
reader.onload = function(e) { 
  var data = e.target.result;
};
reader.readAsDataURL(file);

For example, we can use the data variable above as an image source, displaying a thumbnail of the specified file:

var preview = $("img#preview")

// Check to see whether file is an image type, and isn't 
// so big a preview that it would cause the browser problems
if (file.type.match(/image.*/) && 
      file.size < 50000000) {

  var reader = new FileReader();  
  reader.onload = function(e) { 
    var data    = e.target.result;
    preview.attr("src", data);
  };
  reader.readAsDataURL(file);
}

var bufferSize = 1024;
var pos = 0;

var onload = function(e){
  console.log("Read: ", e.target.result);
};

var onerror = function(e){
  console.log("Error!", e);
};

while (pos < file.size) {
  var blob = file.slice(pos, bufferSize);

  var reader = new FileReader();
  reader.onload  = onload;
  reader.onerror = onerror;
  reader.readAsText(blob);

  pos += bufferSize;
}

Opening a file-browsing dialog programmatically is a common use case. In other words, a styled Browse or Attachment button immediately brings up a browse dialog when clicked, without the user having to interact with a traditional file input. However, for security reasons, this is trickier than it sounds. File inputs have no browse function, and, with the exception of Firefox, you can’t just trigger a custom click event on a file input.

The current solution may sound like a hack, but it works rather well. When a user mouses over a browse button, overlay a transparent file input that has the same position and dimensions as the button. The transparent file input will catch any click events, opening a browse dialog.

Inside this book’s assets/ch07 folder, you’ll find jquery.browse.js, a jQuery plug-in that does just that. To create a custom browse button, just call the browseElement() function on a jQuery instance. The function will return a file input that you can add a change event listener to, detecting when the user has selected some files.

var input = $("#attach").browseElement();

input.change(function(){
  var files = $(this).attr("files");
});

It’s got full cross-browser support, and it couldn’t be easier!

Part of the XMLHttpRequest Level 2 specification was the ability to upload files. File uploads have long been a painful experience for users. Once they’ve browsed and selected a file, the page reloads and they have to wait for ages while it uploads, with no indication of progress or feedback—quite the usability nightmare. Luckily for us, XHR 2 solves this problem. It allows us to upload files in the background, and it even gives us progress events so that we can provide the user with a real-time progress bar. It’s generally well supported by the major browsers:

File uploads can be done via the existing XMLHttpRequest API, using the send() function, or alternatively by using a FormData instance. A FormData instance just represents the contents of a form in an easy-to-manipulate interface. You can build a FormData object from scratch, or by passing in an existing form element when instantiating the object:

var formData = new FormData($("form")[0]);

// You can add form data as strings
formData.append("stringKey", "stringData");

// And even add File objects
formData.append("fileKey", file);

Once you’ve finished with the FormData, you can POST it to your server using XMLHttpRequest. If you’re using jQuery for Ajax requests, you’ll need to set the processData option to false so that jQuery doesn’t try to serialize the supplied data. Don’t set the Content-Type header because the browser will set it automatically to multipart/form-data, along with a multipart boundary:

jQuery.ajax({
  data: formData,
  processData: false,
  url: "http://example.com",
  type: "POST"
})

The alternative to using FormData is to pass the file directly to the XHR object’s send() function:

var req = new XMLHttpRequest();
req.open("POST", "http://example.com", true);
req.send(file);

Or, with jQuery’s Ajax API, you can upload files like this:

$.ajax({
  url: "http://example.com",
  type: "POST",
  success: function(){ /* ... */ },
  processData: false,
  data: file
});

It’s worth noting that this upload is a bit different from the traditional multipart/form-data one. Usually, information about the file, such as the name, would be included in the upload. Not so in this case—the upload is pure file data. To pass information about the file, we can set custom headers, such as X-File-Name. Our servers can read these headers and process the file properly:

$.ajax({
  url: "http://example.com",
  type: "POST",
  success: function(){ /* ... */ },
  processData: false,
  contentType: "multipart/form-data",

  beforeSend: function(xhr, settings){
    xhr.setRequestHeader("Cache-Control", "no-cache");
    xhr.setRequestHeader("X-File-Name", file.fileName);
    xhr.setRequestHeader("X-File-Size", file.fileSize);
  },

  data: file
});

Unfortunately, many servers will have trouble receiving the upload because pure data is a more unfamiliar format than multipart or URL-encoded form parameters. Using this method, you may have to parse the request manually. For this reason, I advocate using FormData objects, and sending the upload serialized as a multipart/form-data request. In the assets/ch07 folder, you’ll find jquery.upload.js, a jQuery plug-in that abstracts file uploading into a simple $.upload(url, file) interface.

var req = new XMLHttpRequest();

req.addEventListener("progress", updateProgress, false);
req.addEventListener("load", transferComplete, false);
req.open();

var req = new XMLHttpRequest();

req.upload.addEventListener("progress", updateProgress, false);
req.upload.addEventListener("load", transferComplete, false);
req.open();

$.ajax({
  url: "http://example.com",
  type: "POST",
  success: function(){ /* ... */ },
  processData: false,
  dataType: "multipart/form-data",

  beforeSend: function(xhr, settings){
    var upload = xhr.upload;

    if (settings.progress)
      upload.addEventListener("progress", settings.progress, false);

    if (settings.load)
      upload.addEventListener("load", settings.load, false);

    var fd = new FormData;

    for (var key in settings.data)
      fd.append(key, settings.data[key]);

    settings.data = fd;
  },

  data: file
});

var progress = function(event){
  var percentage = Math.round((event.position / event.total) * 100);
  // Set progress bar
}

var startStamp = new Date();
var progress = function(e){
  var lapsed = startStamp - e.timeStamp;
  var eta    = lapsed * e.total / e.position - lapsed;
};

So, let’s put all that knowledge into practice by building a drag-and-drop file uploader. We’re going to need several libraries: jquery.js for the backbone, jquery.ui.js for the progress bar, jquery.drop.js to abstract the drag-and-drop APIs, and jquery.upload.js for the Ajax upload. All our logic will go inside jQuery.ready(), so it will be run when the DOM is ready:

//= require <jquery>
//= require <jquery.ui>
//= require <jquery.drop>
//= require <jquery.upload>

jQuery.ready(function($){
  /* ... */
});

var view = $("#drop");
view.dropArea();

view.bind("drop", function(e){ 
  e.stopPropagation();
  e.preventDefault();

  var files = e.originalEvent.dataTransfer.files;
  for ( var i = 0; i < files.length; i++)
    uploadFile(files[i]);

  return false;
});

var uploadFile = function(file){
  var element = $("<div />");
  element.text(file.fileName);

  var bar = $("<div />");
  element.append(bar);
  $("#progress").append(element);

  var onProgress = function(e){
    var per = Math.round((e.position / e.total) * 100);
    bar.progressbar({value: per});
  };

  var onSuccess = function(){
    element.text("Complete");
    element.delay(1000).fade();
  };

  $.upload("/uploads", file, {upload: {progress: onProgress}, success: onSuccess});
};

Traditionally, the Web was built around the request/response model of HTTP: a client requests a web page, the server delivers it, and nothing happens again until the client requests another page. Then, Ajax came along and made web pages feel a bit more dynamic—requests to the server could now be made in the background. However, if the server had additional data for clients, there was no way of notifying them after the page was loaded; live data couldn’t be pushed to clients.

Lots of solutions were devised. The most basic was polling: just asking the server over and over again for any new information. This gave users the perception of real time. In practice, it introduced latency and performance problems because servers had to process a huge number of connections a second, with both TCP handshake and HTTP overheads. Although polling is still used, it’s by no means ideal.

Then, more advanced transports were devised under the umbrella term Comet. These techniques consisted of iframes (forever frames), xhr-multipart, htmlfiles, and long polling. With long polling, a client opens an XMLHttpRequest (XHR) connection to a server that never closes, leaving the client hanging. When the server has new data, it’s duly sent down the connection, which then closes. The whole process then repeats itself, essentially allowing server push.

Comet techniques were unstandardized hacks, and as such, browser compatibility was a problem. On top of that, there were performance issues. Every connection to the server contained a full set of HTTP headers, so if you needed low latency, this could be quite a problem. That’s not to knock Comet, though—it was a valid solution when there were no other alternatives.

Browser plug-ins, such as Adobe Flash and Java, were also used for server push. These would allow raw TCP socket connections with servers, which could be used for pushing real-time data out to clients. The caveat was that these plug-ins weren’t guaranteed to be installed, and they often suffered from firewall issues, especially on corporate networks.

There are now alternative solutions as part of the HTML5 specification. However, it will be a while before all the browsers, particularly Internet Explorer, are up to speed with the current developments. Until then, Comet will remain a useful tool in any frontend developer’s arsenal.

WebSockets are part of the HTML5 specification, providing bidirectional, full-duplex sockets over TCP. This means that servers can push data to clients without developers resorting to long polling or browser plug-ins, which is quite an improvement. Although a number of browsers have implemented support, the protocol is still in flux due to security issues. However, that shouldn’t put you off; the teething problems will soon get ironed out and the spec will be finalized. In the meantime, browsers that don’t support WebSockets can fall back to legacy methods like Comet or polling.

WebSockets have significant advantages over previous server push transports because they are full-duplex, aren’t over HTTP, and persist once opened. The real drawback to Comet was the overhead of HTTP—every request also had a full set of HTTP headers. Then there was the overhead of multiple extraneous TCP handshakes, which was significant at high levels of requests.

With WebSockets, once a handshake is completed between client and server, messages can be sent back and forth without the overhead of HTTP headers. This greatly reduces bandwidth usage, thus improving performance. Since there is an open connection, servers can reliably push updates to clients as soon as new data becomes available (no polling is required). In addition, the connection is duplex, so clients can also send messages back to the server, again without the overhead of HTTP.

This is what Google’s Ian Hickson, the HTML5 specification lead, said about WebSockets:

So, let’s look at WebSocket support in the browsers:

Although Firefox and Opera have WebSocket implementations, it’s currently disabled due to recent security scares. This will all get sorted out though, probably by the time this book goes to print. In the meantime, you can gracefully degrade with older technologies like Comet and Adobe Flash. IE support is nowhere on the map at the moment, and it probably won’t be added until after IE9.

Detecting support for WebSockets is very straightforward:

var supported = ("WebSocket" in window);
if (supported) alert("WebSockets are supported");

From a browser perspective, the WebSocket API is clear and logical. You instantiate a new socket using the WebSocket class, passing the socket server endpoint—in this case, ws://example.com:

var socket = new WebSocket("ws://example.com");

Then, we can add some event listeners to the socket:

// The connection has connected
socket.onopen = function(){ /* ... */ }

// The connection has some new data
socket.onmessage = function(data){ /* ... */ }

// The connection has closed
socket.onclose = function(){ /* ... */ }

When the server sends some data, onmessage will be called. Clients, in turn, can call the send() function to transmit data back to the server. Clearly, we should call that only after the socket has connected and the onopen event has fired:

socket.onmessage = function(msg){
  console.log("New data - ", msg);
};

socket.onopen = function(){
  socket.send("Why, hello there").
};

When sending and receiving messages, only strings are supported. However, it’s simple enough to serialize and deserialize the message strings into JSON, creating your own protocol:

var rpc = {
  test: function(arg1, arg2) { /* ... */ }
};

socket.onmessage = function(data){
  // Parse JSON
  var msg = JSON.parse(data);

  // Invoke RPC function
  rpc[msg.method].apply(rpc, msg.args);
};

Above, we’ve created a remote procedure call (RPC) script. Our server can send some simple JSON, like the following, to invoke functions on the client side:

{"method": "test", "args": [1, 2]}

Notice we’re restricting invocation to the rpc object. This is important for security reasons—we don’t want to expose clients to hackers by evaluating arbitrary JavaScript.

To terminate the connection, just call the close() function:

var socket = new WebSocket("ws://localhost:8000/server");

You’ll notice when instantiating a WebSocket that we’re using the WebSocket scheme, ws://, rather than http://. WebSockets also allow encrypted connections via TLS using the wss:// schema. By default, WebSockets will use port 80 for nonencrypted connections and port 443 for encrypted ones. You can override this by providing a custom port in the URL. Keep in mind that not all ports are available to clients; firewalls may block the more uncommon ones.

At this stage, you may be thinking, “I can’t possibly use this in production—the standard’s a moving target and there’s no IE support.” Well, those are valid concerns, but luckily there’s a solution. Web-socket-js is a WebSocket implementation powered by Adobe Flash. You can use this library to provide legacy browsers a WebSocket fallback to Flash, a plug-in that’s almost ubiquitously available. It mirrors the WebSocket API exactly, so when WebSockets have better penetration, you’ll only need to remove the library—not change the code.

Although the client-side API is fairly straightforward, things aren’t quite so simple server side. The WebSocket protocol has been through several incompatible iterations: drafts 75 and 76. Servers need to take account of both drafts by detecting the type of handshake clients use.

WebSockets work by first performing an HTTP “upgrade” request to your server. If your server has WebSocket support, it will perform the WebSocket handshake and a connection will be initiated. Included in the upgrade request is information about the origin domain (where the request is coming from). Clients can make WebSocket connections to any domain—it’s the server that decides which clients can connect, often by using a whitelist of allowed domains.

From conception, WebSockets were designed to work well with firewalls and proxies, using popular ports and HTTP headers for the initial connection. However, things rarely work out so simply in the wild Web. Some proxies change the WebSockets upgrade headers, breaking them. Others don’t allow long-lived connections and will time out after a while. In fact, the most recent update to the protocol draft (version 76) unintentionally broke compatibility with reverse-proxies and gateways. There are a few steps you can take to give your WebSockets the best chance of success:

So, what server options are there? Luckily, there is a multitude of implementations in languages like Ruby, Python, and Java. Make sure any implementation supports at least draft 76 of the protocol, as this is most common in clients.

var socket = new io.Socket(); 

socket.on("connect", function(){ 
  socket.send('hi!'); 
});

socket.on("message", function(data){ 
  alert(data);
});

socket.on("disconnect", function(){});

It’s all very well being able to push data to clients in theory, but how does that integrate with a JavaScript application? Well, if your application is modeled correctly, it’s actually remarkably straightforward. We’re going to go through all the steps involved in making your application real time, specifically following the PubSub pattern. The first thing to understand is the process that updates go through to reach clients.

A real-time architecture is event-driven. Typically, events are driven by user interaction: a user changes a record and events are propagated throughout the system until data is pushed to connected clients, updating them. When you’re thinking about making your application real time, you need to consider two things:

It may be that when a model changes, you want to send notifications to all connected clients. This would be the case for a real-time activity feed on the home page, for example, where every client saw the same information. However, the common use case is when you have a resource associated with a particular set of users. You need to notify those users of that resource change.

Let’s consider an example scenario of a chat room:

The process details are specific to your chosen backend. However, if you’re using Rails, Holla is a good example. When Message records are created, the JuggernautObserver updates relevant clients.

That brings us to the next question: how can we send notifications to specific users? Well, an excellent way of doing so is with the PubSub pattern: clients subscribe to particular channels and servers publish to those channels. A user just subscribes to a unique channel containing an identifier, perhaps the user’s database ID; then, the server simply needs to publish to that unique channel to send notifications to that specific user.

For example, a particular user could subscribe to the following channel:

/observer/0765F0ED-96E6-476D-B82D-8EBDA33F4EC4

where the random set of digits is a unique identifier for the currently logged-in user. To send notifications to that particular user, the server just needs to publish to that same channel.

You may be wondering how the PubSub pattern works with transports like WebSockets and Comet. Fortunately, there are already a lot of solutions, such as Juggernaut and Pusher, both mentioned previously. PubSub is a common abstraction on top of WebSockets, and its API should be fairly similar to whatever service or library you end up choosing.

Once notifications have been pushed to clients, you’ll see the real beauty of the MVC architecture. Let’s go back to our chat example. The notification we sent out to clients could look like this.

{
  "klass":  "Chat",
  "type":   "create",
  "id":     "3",
  "record": {"body": "New chat"}
}

It contains the model that’s changed, the type of change, and any relevant attributes. Using this, our client can create a new Chat record locally. As the client’s models are bound to the UI, the interface is automatically updated to reflect the new chat message.

What’s brilliant is that none of this is specific to the Chat model. If we want to make another model real time, it’s just a case of adding another observer server side, making sure clients are updated when it changes. Our backend and client-side models are now tied together. Any changes to the backend models get automatically propagated to all the relevant clients, updating their UI. With this architecture, the application is truly real time. Any interaction a user makes is instantly broadcast to other users.

Speed is a critical but often neglected part of UI design because it makes a huge difference to the user experience (UX) and can have a direct impact on revenue. Companies, such as the following, are studying its implications all the time:

Perceived speed is just as important as actual speed because this is what users are going to notice. So, the key is to make users think an application is fast, even if in reality it isn’t. The ability to do this is one of the benefits of JavaScript applications—UI doesn’t block, even if a background request is taking a while.

Let’s take the chat room scenario again. A user sends a new message, firing off an Ajax request to the server. We could wait until the message performs a roundtrip through the server and clients before appending it to the chat log. However, that would introduce a couple of seconds’ latency between the time a user submitted a new message and when it appeared in her chat log. The application would seem slow, which would definitely hurt the user experience.

Instead, why not create the new message locally, thereby immediately adding it to the chat log? From a user’s perspective, it seems like the message has been sent instantly. Users won’t know (or care) that the message hasn’t yet been delivered to other clients in the chat room. They’ll just be happy with a fast and snappy user experience.

Aside from interactions, one of the slowest parts of Web applications is loading in new data. It’s important to do intelligent preloading to try to[ predict what a user will need before he actually asks for it. Then, cache the data in memory; if the user needs it subsequently, you shouldn’t have to request it again from the server. Upon startup, the application should preload commonly used data. Users are more likely to be forgiving of slower initial load times than once the application’s loaded.

You should always give users feedback when they interact with your application, usually with some sort of visual indicator. In business jargon this is called expectation managment, making sure clients are aware of a project’s status and ETA. The same applies to UX—users will be more patient if they’re given an indication that something’s happening. While users are waiting for new data, show them a message or a spinner. If a file’s being uploaded, show a progress bar and an estimated duration. All this gives a perception of speed, improving the user experience.

Manual testing is like integration testing, making sure that your application works from a high level. Unit testing is much more low level, ensuring that particular pieces of code behind the scenes are performing as expected. Unit testing is much more likely to reveal cross-browser issues, but it allows you to resolve them quickly, because you need to examine only small sections of code.

The other advantage to unit testing is that it paves the way for automation. We’ll cover this in more detail later in this chapter, but unit tests make it possible to set up a continuous integration server, running the application’s tests every time the code is committed. This is much quicker than running through your whole application manually, and making sure that changes to one piece of code aren’t having any side effects elsewhere in the application.

There are lots of JavaScript libraries out there for unit testing, each with pros and cons. We’re going to cover the most popular ones, but the general principles should apply to any you choose to use.

var assert = function(value, msg) {
  if ( !value )
    throw(msg || (value + " does not equal true"));
};

// Assertion fails
assert( false );
assert( "" );
assert( 0 );

// If the statement is null, the assertion fails
assert( User.first() );

var assertEqual = function(val1, val2, msg) {
  if (val1 !== val2)
    throw(msg || (val1 + " does not equal " + val2));
};

// Assertion passes
assertEqual("one", "one");

QUnit

QUnit is one of the most popular and well-maintained libraries, originally developed to test jQuery. So, how do you set up a QUnit testing environment? The first step is to download the project files locally, and then create a static test runner page:

<!DOCTYPE html>
<html>
<head>
    <title>QUnit Test Suite</title>
    <link rel="stylesheet" href="qunit/qunit.css" type="text/css" media="screen">
</head>
<body>
    <div id="qunit"></div>
    <script src="qunit/qunit.js"></script>
    <!-- include tests here... -->
</body>
</html>

To create assertions, you should put them into a test case. For example, let’s create a test suite for that ORM we built in Chapter 3:

test("load()", function(){
  var Asset = Model.setup();

  var a = Asset.init();
  a.load({
    local: true,
    name: "test.pdf"
  });

  ok(a.local, "Load sets properties");
  equal(a.name, "test.pdf", "load() sets properties (2)");

  var b = Asset.init({
    name: "test2.pdf"
  });

  equal(b.name, "test2.pdf", "Calls load() on instantiation");
});

We are defining a new case by calling test() and giving it the name of the test and the test callback (where the magic happens). Inside the callback we’ve got various assertions: ok() asserts that its first argument resolves to true, and equal() compares its two arguments. All the assertions take a last string argument, which is the name of the assertion, letting us easily see what passes and fails.

Let’s add that test to the page and give it a refresh, as shown in Figure 9-1.

Figure 9-1. QUnit test results

That’s pretty powerful! At a glance, we can see which tests have passed and failed—all it takes is a page refresh. We can now begin to test every browser our application supports, making sure our unit tests pass in all of them.

Tests are separated by the module() function, which takes a name and options. Let’s clean up the first example by passing a setup option to module(), containing a callback that will be executed for every test that runs in the module. In this case, all our tests will need an Asset model, so we’ll create that in the setup:

module("Model test", {
  setup: function(){
    this.Asset = Model.setup();
  }
});

test("load()", function(){
  var a = this.Asset.init();
  a.load({
    local: true,
    name: "test.pdf"
  });

  ok(a.local, "Load sets properties");
  equal(a.name, "test.pdf", "load() sets properties (2)");

  var b = this.Asset.init({
    name: "test2.pdf"
  });

  equal(b.name, "test2.pdf", "Calls load() on instantiation");
});

That’s a bit cleaner, and it will be useful when adding further tests. module() also takes a teardown option, which is a callback that will be executed after every test in the module. Let’s add another test to our suite:

test("attributes()", function(){
  this.Asset.attributes = ["name"];

  var a = this.Asset.init();
  a.name = "test.pdf";
  a.id   = 1;

  equal(a.attributes(), {
    name: "test.pdf",
    id: 1
  });
});

If you try this out, you’ll see that the test has failed, like the page shown in Figure 9-2.

Figure 9-2. Failing tests in QUnit

This is because the equal() function uses the == comparison operator, which will fail for objects and arrays. Instead, we need to use the deepEqual() function, which does a deep comparison, and our test suite will pass again:

test("attributes()", function(){
  this.Asset.attributes = ["name"];

  var a = this.Asset.init();
  a.name = "test.pdf";
  a.id   = 1;

  deepEqual(a.attributes(), {
    name: "test.pdf",
    id: 1
  });
});

QUnit includes a couple of other assertion types, such as notEqual() and raises(). For full examples of their usage, see assets/ch09/qunit/model.test.js or the QUnit docs.

Jasmine

Jasmine is another popular testing library (and my personal favorite). Rather than unit tests, Jasmine has specs that describe the behavior of specific objects inside your application. In practice, they’re similar to unit tests, just with a different terminology.

Jasmine’s advantage is that it doesn’t require any other libraries, or even a DOM. This means it can run in any JavaScript environment, such as on the server side with Node.js.

As with QUnit, we need to set up a static HTML page that will load all the specs, run them, and display the result:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>Jasmine Test Runner</title>
  <link rel="stylesheet" type="text/css" href="lib/jasmine.css">
  <script type="text/javascript" src="lib/jasmine.js"></script>
  <script type="text/javascript" src="lib/jasmine-html.js"></script>

  <!-- include source files here... -->
  <!-- include spec files here... -->
</head>
<body>

  <script type="text/javascript">
    jasmine.getEnv().addReporter(new jasmine.TrivialReporter());
    jasmine.getEnv().execute();
  </script>

</body>
</html>

Let’s take a look at writing some Jasmine specs. We’ll test some more of the ORM library from Chapter 3:

describe("Model", function(){
  var Asset;

  beforeEach(function(){
    Asset = Model.setup();
    Asset.attributes = ["name"];
  });

  it("can create records", function(){
    var asset = Asset.create({name: "test.pdf"});
    expect(Asset.first()).toEqual(asset);
  });

  it("can update records", function(){
    var asset = Asset.create({name: "test.pdf"});

    expect(Asset.first().name).toEqual("test.pdf");

    asset.name = "wem.pdf";
    asset.save();

    expect(Asset.first().name).toEqual("wem.pdf");
  });

  it("can destroy records", function(){
    var asset = Asset.create({name: "test.pdf"});

    expect(Asset.first()).toEqual(asset);

    asset.destroy();

    expect(Asset.first()).toBeFalsy();
  });
});

Specs are grouped into suites using the describe() function, which takes the name of the spec and an anonymous function. In the example above, we’re using the beforeEach() function as a setup utility to be run before every function. Jasmine also includes a teardown function, afterEach(), which is called after every spec is run. We’re defining the variable Asset outside the beforeEach() function, so it’s local to the suite and can be accessed inside each spec.

A spec begins with the it() function, which gets passed the name of the spec and the anonymous function containing the assertions. Assertions are created by passing the relevant value to the expect() function, and then calling a matcher, such as one of the following:

expect(x).toEqual(y)

Compares objects or primitives x and y, and passes if they are equivalent

expect(x).toBe(y)

Compares objects or primitives x and y, and passes if they are the same object

expect(x).toMatch(pattern)

Compares x to string or regular expression pattern, and passes if they match

expect(x).toBeNull()

Passes if x is null

expect(x).toBeTruthy()

Passes if x evaluates to true

expect(x).toBeFalsy()

Passes if x evaluates to false

expect(x).toContain(y)

Passes if array or string x contains y

expect(fn).toThrow(e)

Passes if function fn throws exception e when executed

Jasmine includes lots of other matchers, and it even lets you write your own custom ones.

Figure 9-3 shows an overview of running the Jasmine Test Runner using the example specs above.

Figure 9-3. Jasmine test results

Although by using a testing library we now have a degree of automation, there’s still the problem of running your tests in lots of different browsers. It’s not exactly productive having developers refresh the tests in five different browsers before every commit. Drivers were developed to solve exactly this problem. They’re daemons that integrate with various browsers, running your JavaScript tests automatically and notifying you when they fail.

It can be quite a lot of work implementing a driver setup on every developer’s machine, so most companies have a single continuous integration server, which will use a post-commit hook to run all the JavaScript tests automatically, making sure they all pass successfully.

Watir, pronounced “water,” is a Ruby driver library that integrates with Chrome, Firefox, Safari, and Internet Explorer (dependent on the platform). After installation, you can give Watir some Ruby commands to drive the browser, clicking links and filling in forms the same as a person would. During this process, you can run a few test cases and assert that things are working as expected:

# FireWatir drives Firefox
require "firewatir"

browser = Watir::Browser.new
browser.goto("http://bit.ly/watir-example")

browser.text_field(:name => "entry.0.single").set "Watir"
browser.button(:name => "logon").click

Due to limitations on which browsers can be installed on which operating systems, if you’re testing with Internet Explorer, your continuous integration server will have to run a version of Windows. Likewise, to test in Safari, you’ll also need a server running Mac OS X.

Another very popular browser-driving tool is Selenium. The library provides a domain scripting language (DSL) to write tests in a number of programming languages, such as C#, Java, Groovy, Perl, PHP, Python, and Ruby. Selenium can run locally; typically, it runs in the background on a continuous integration server, keeping out of your way as you commit code, but notifying you when tests fail. Selenium’s strengths lie in the number of languages it supports, as well as the Selenium IDE, a Firefox plug-in that records and plays back actions inside the browser, greatly simplifying authoring tests.

Figure 9-4. Recording instructions with Selenium

In Figure 9-4, we’re using the Selenium IDE tool to record clicking on a link, filling in a form, and finally submitting it. Once a session has been recorded, you can play it back using the green play button. The tool will emulate our recorded actions, navigating to and completing the test form.

We can then export the recorded Test Case to a variety of formats, as shown in Figure 9-5.

For example, here’s the exported Test Case as a Ruby Test::Unit case. As you can see, Selenium’s IDE has conveniently generated all the relevant driver methods, greatly reducing the amount of work needed to test the page:

class SeleniumTest < Test::Unit::TestCase
  def setup
    @selenium = Selenium::Client::Driver.new \
      :host => "localhost",
      :port => 4444,
      :browser => "*chrome",
      :url => "http://example.com/index.html",
      :timeout_in_second => 60

    @selenium.start_new_browser_session
  end

  def test_selenium
    @selenium.open "http://example.com/index.html"
    @selenium.click "link=Login.html"
    @selenium.wait_for_page_to_load "30000"
    @selenium.type "email", "test@example.com"
    @selenium.type "password", "test"
    @selenium.click "//input[@value='Continue →']"
    @selenium.wait_for_page_to_load "30000"
  end
end

Figure 9-5. Exporting Selenium test cases to various formats

We can now make assertions on the @selenium object, such as ensuring that a particular bit of text is present:

def test_selenium
  # ...
  assert @selenium.is_text_present("elvis")
end

For more information about Selenium, visit the website and watch the introduction screencast.

With the development of server-side JavaScript implementations such as Node.js and Rhino comes the possibility of running your tests outside the browser in a headless environment via the command line. This has the advantage of speed and ease of setup, as it does away with the multitude of browsers and the continuous integration environment. The disadvantage, of course, is that the tests aren’t being run in a real-world environment.

This might not be as big a problem as it sounds, as you’ll find that most of the JavaScript you write is application logic and not browser-dependent. In addition, libraries like jQuery have taken care of a lot of browser incompatibilities when it comes to the DOM and event management. For smaller applications, as long as you have a staging environment when deploying and some high-level cross-browser integration tests (whether manual or automated), you should be fine.

Envjs is a library originally developed by John Resig, creator of the jQuery JavaScript framework. It offers an implementation of the browser and DOM APIs on top of Rhino, Mozilla’s Java implementation of JavaScript. You can use the env.js library together with Rhino to run JavaScript tests on the command line.

// Fill email, password, and submit form.
browser.
  fill("email", "zombie@underworld.dead").
  fill("password", "eat-the-living").
  pressButton("Sign Me Up!", function(err, browser) {
   // Form submitted, new page loaded.
   assert.equal(browser.text("title"), "Welcome to Brains Depot");
  });

var zombie  = require("zombie");

vows.describe("Zombie lunch").addBatch({
  "visiting home page": {
    topic: function() {
      var browser = new zombie.Browser;
      browser.cookies("localhost").update("session_id=5678");
      browser.visit("http://localhost:3003/", this.callback);
    },
    "should find no brains": function(browser) {
      assert.isEmpty(browser.css(".brains"));
    }
  }
});

$ macgem install ichabod

$ ichabod --jasmine http://path/to/jasmine/specs.html
$ ichabod --qunit http://path/to/qunit/tests.html

$ ichabod --jasmine ./tests/index.html
    ...
    Finished in 0.393 seconds
    1 test, 5 assertions, 0 failures

One solution to cross-browser testing is outsourcing the problem to a dedicated cluster of browsers. This is exactly the approach of TestSwarm:

Rather than using plug-ins and extensions to integrate with browsers at a low level, TestSwarm takes the reverse approach. Browsers open up the TestSwarm endpoint, and automatically process tests pushed toward them. They can be located on any machine or operating system—all it takes to add a new browser is to navigate to the TestSwarm endpoint inside it.

This simple approach takes a lot of the pain and hassle out of running a continuous integration server. All that’s involved is ensuring a decent number of browsers are connected to the swarm. Indeed, this is something you could outsource if you have an active community, achieving probably the most realistic testbed you could hope for, as shown in Figure 9-6.

Figure 9-6. TestSwarm returns results to browsers as a grid of test suites

The alternative is to use a company like Sauce Labs to manage and run all those browsers in the cloud. Simply upload any Selenium tests and their service will do the rest, running the tests on different browsers and platforms, making sure they all pass.

However many tests you write for your application, the likelihood is that there will always be bugs. The best thing to do is to accept this fact and prepare for users to come across bugs and errors. Provide an easy way for users to submit bug reports and set up a ticketing system to manage support requests.

JavaScript development and debugging has come a long way from the alert() calls of the past. Most of the major browsers now include powerful element inspectors and debuggers, which simplifies and improves web development dramatically. We’re going to cover the two main inspectors next, but the general concepts should transfer over to any inspector you choose to use.

Web Inspector

Web Inspector is available on both the Safari and Google Chrome browsers. The inspector’s interface differs slightly between the two browsers, but the functionality is fairly consistent.

In Safari, you have to enable it explicitly by checking the advanced preference, “Show Develop menu in menu bar,” as shown in Figure 9-7.

Figure 9-7. Enabling Safari Inspector

Chrome has a developer toolbar under the View toolbar, which you can use to enable the inspector. The alternative in both browsers is to right-click on an element and select “inspect”.

Web Inspector, shown in Figure 9-8, is an incredibly useful tool, letting you inspect HTML elements, edit styles, debug JavaScript, and more. If it isn’t the case already, the inspector should be part of your day-to-day JavaScript development.

We’re going to cover more of its features in detail, but here’s a basic overview of Web Inspector’s components:

Elements

Inspect HTML elements, edit styles

Resources

Page resources and assets

Network

HTTP requests

Scripts

JavaScript files and debugger

Timeline

Detailed view of browser rendering

Audits

Code and memory auditor

Console

Execute JavaScript and see logging

Figure 9-8. Safari’s Web Inspector lets you inspect the DOM

Firebug

Firefox doesn’t include a JavaScript inspector natively, but it has an excellent add-on to do the job: Firebug. See Figure 9-9.

Figure 9-9. Inspecting the DOM and CSS with FireBug

You’ll see that although the various components to Firebug have different names to their counterparts in Web Inspector, their functionality is very similar:

Console

Execute JavaScript and see logging

HTML

Inspect elements, edit styles

CSS

See and edit the page’s CSS

Script

JavaScript files and debugger

DOM

Global variable inspection

Net

HTTP requests

Firebug’s team has developed a Firefox-independent version, Firebug Lite. It has the vast majority of features from Firebug, as well as the same look and feel, and it’s compatible with all major browsers. Firebug Lite is especially useful for debugging Internet Explorer (it’s rather superior to IE’s built-in tools). Firebug Lite doesn’t require any installation, and it can be added to a web page using a simple script tag:

<script type="text/javascript" src="https://getfirebug.com/firebug-lite.js"></script>

Alternatively, you can install the bookmarklet from the Firebug Lite website.

The console lets you easily execute JavaScript and examine the pages’ global variables. One of the major advantages to the console is that you can log directly to it, using the console.log() function. The call is asynchronous, can take multiple arguments, and inspects those arguments, rather than converting them to strings:

console.log("test");
console.log(1, 2, {3: "three"});

There are additional types of logging. You can use console.warn() and console.error() to elevate the logging level, giving an early indication that something might be going wrong:

console.warn("a diabolical warning");
console.error("something broke!");

try {
  // Raises something
} catch(e) {
  console.error("App error!", e);
}

It’s also possible to namespace log calls by using a proxy function:

var App = {trace: true};
App.log = function(){
  if (!this.trace) return;
  if (typeof console == "undefined") return;
  var slice = Array.prototype.slice;
  var args  = slice.call(arguments, 0);
  args.unshift("(App)");
  console.log.apply(console, args);
};

The App.log() function prepends the string "App" to its arguments and then passes the call onto console.log().

Keep in mind that when using the console for logging, the variable console may not be defined. In browsers that don’t have support for the console—such as Internet Explorer or Firefox without Firebug—the console object won’t be defined, causing errors if you try to use it. This is a good reason for using a proxy function like App.log() when logging inside your application.

You can output the scripts’ current stack trace to the console using console.trace(). This is especially useful if you’re trying to work out how a function is being called because it traces the stack back through the program:

// Log stack trace
console.trace();

The application’s errors will also appear in the console and, unless the browser’s JIT compiler has optimized the function call, the console will show a full stack trace.

// $0 is the currently selected element
$0.style.color = "green";

// Or, using jQuery
jQuery($0).css({background: "black"});

$("user").addEventListener("click", function(){ /* ... */});

// Select elements with a class of .users
var users = $$(".users");
users.forEach(function(){ /* ... */ });

// Select all forms
var checkboxes = $x("/html/body//form");

clear();

dir({one: 1});

inspect($("user"));

// Returns ["two"]
keys({two: 2});

// Returns [2]
values({two: 2});

The JavaScript debugger is one of the best-kept secrets in JavaScript development. It’s a full-featured debugger that allows you to place breakpoints, watch expressions, examine variables, and work out exactly what’s going on.

Placing a breakpoint is easy—just add the debugger statement inside the script at the point you want the debugger to pause execution:

var test = function(){
  // ...
  debugger
};

Alternatively, you can go to the Scripts panel in the inspector, select the relevant script, and click on the line number where you want to place the breakpoint. Figure 9-10 shows an example.

Figure 9-10. Setting a breakpoint with Safari’s Web Inspector

The latter approach is probably preferable because you don’t want to risk getting any debugger statements in production code. When the JavaScript execution reaches the breakpoint, it’s paused, letting you examine the current scope, as shown in Figure 9-11.

Figure 9-11. Debugging a breakpoint with Safari’s Web Inspector

On the right of the inspector’s Scripts panel, you can see the full call stack, the local and global variables, and other relevant debugging information. You can hover the mouse over any variable to see its current value. The console is even scoped to the breakpoint, allowing you to manipulate variables and call other functions.

You can continue code execution, step into or over the next function call, and navigate up the current stack using the Debugger toolbar on the right. The Debugger toolbar icons are specific to the browser, but you can determine each button’s function by hovering the mouse over it, which displays a yellow information bubble.

It’s important to remember that breakpoints remain between page reloads. If you want to remove a breakpoint, simply toggle its line number, or uncheck it in the breakpoint list. The JavaScript debugger is a wonderful alternative to console.log(), as it helps you work out exactly what’s happening inside your application.

As shown in Figure 9-12, the inspector’s network section shows all the HTTP requests the page is making, how long they took, and when they completed.

Figure 9-12. Analyzing network requests with Web Inspector

You can see the initial request’s latency, which is a slightly transparent color. Then, when data starts getting received, the timeline’s color goes opaque. In the example above, jQuery’s file size is much bigger than the stylesheets’, so although the initial request latency is similar, the script takes longer to download.

If you’re not using the async or defer option with your scripts (see Chapter 10), you’ll notice that JavaScript files are downloaded sequentially rather than in parallel. Scripts are requested only after the previous referenced script has been fully downloaded and executed. All other resources are downloaded in parallel.

The lines in the network timeline indicate the pages’ load status. The blue line appears at the time the document’s DOMContentLoaded event was fired or, in other words, when the DOM is ready. The red line appears once the window’s load event is triggered, when all the page’s images have been fully downloaded and the page has finished loading.

The network section also shows the full request and response headers for every request, which is especially useful for making sure any caching is being applied correctly. See Figure 9-13.

Figure 9-13. Viewing an in-depth analysis of network requests, such as request and response headers

When you’re building large JavaScript apps, you need to keep an eye on performance, especially if you’ve got mobile clients. Both Web Inspector and Firebug include profiling and timing utilities that can help keep things ticking smoothly.

Profiling code is simple—just surround any code you want to profile with console.profile() and console.profileEnd():

console.profile();
// ...
console.profileEnd();

As soon as profileEnd() is called, a profile will be created, listing all the functions (and the time taken in each one) that were called between the two statements. See Figure 9-14 for an illustration.

Figure 9-14. Profiling function execution rates with Web Inspector

Alternatively, you can use the record feature of the inspector’s profiler, which is equivalent to wrapping code with the profile console statements. By seeing which functions are being called and which functions are taking longer to complete, you can discover and optimize bottlenecks in your code.

The profiler also allows you to take a snapshot of the page’s current heap, as illustrated in Figure 9-15. This will show you how many objects have been allocated and the amount of memory the page is using. This is a great way of finding memory leaks because you can see whether any objects are being unwittingly stored, and are subsequently unable to be garbage collected.

Figure 9-15. Seeing a bird’s-eye view of the heap with Web Inspector

The console also lets you time how long it takes to execute some code. The API is similar to the profiler—simply wrap the code with console.time(name) and console.timeEnd(name). Unless you manage to fit everything on one line, you won’t be able to time code from inside the JavaScript console accurately; instead, you will have to add the timing statements directly into your scripts:

console.time("timeName");
// ...
console.timeEnd("timeName");

When timeEnd() is called, the time taken between the two timing statements is sent to the console’s log in milliseconds. Using the console’s timing API, you could potentially incorporate benchmarking into your application’s tests, ensuring that additional code wasn’t significantly hurting the application’s existing performance.

One of the simplest ways of increasing performance is also the most obvious: minimize the amount of HTTP requests. Every HTTP request contains a lot of header information, as well as the TCP overhead. Keeping separate connections to an absolute minimum will ensure pages load faster for users. This clearly extends to the amount of data the server needs to transfer. Keeping a page and its assets’ file size low will decrease any network time—the real bottleneck to any application on the Web.

Concatenating scripts into a single script and combining CSS into a single stylesheet will reduce the amount of HTTP connections needed to render the page. You can do this upon deployment or at runtime. If it’s the latter, make sure any files generated are cached in production.

Use CSS sprites to combine images into one comprehensive image. Then, use the CSS background-image and background-position properties to display the relevant images in your page. You just have to scope the background position coordinates to cover the desired image.

Avoiding redirects also keeps the number of HTTP requests to a minimum. You may think these are fairly uncommon, but one of the most frequent redirect scenarios occurs when a trailing slash (/) is missing from a URL that should otherwise have one. For example, going to http://facebook.com currently redirects you to http://facebook.com/. If you’re using Apache, you can fix this by using Alias or mod_rewrite.

It’s also important to understand how your browser downloads resources. To speed up page rendering, modern browsers download required resources in parallel. However, the page can’t start rendering until all the stylesheets and scripts have finished downloading. Some browsers go even further, blocking all other downloads while any JavaScript files are being processed.

However, most scripts need to access the DOM and add things like event handlers, which are executed after the page loads. In other words, the browser is needlessly restricting the page rendering until everything’s finished downloading, decreasing performance. You can solve this by setting the defer attribute on scripts, letting the browser know the script won’t need to manipulate the DOM until after the page has loaded:

<script src="foo.js" type="text/javascript" charset="utf-8" defer></script>

Scripts with the defer attribute set to “defer” will be downloaded in parallel with other resources and won’t prevent page rendering. HTML5 has also introduced a new mode of script downloading and execution called async. By setting the async attribute, the script will be executed at the first opportunity after it’s finished downloading. This means it’s possible (and likely) that async scripts are not executed in the order in which they occur in the page, leaving an opportunity for dependency errors. If the script doesn’t have any dependencies, though, async is a useful tool. Google Analytics, for example, takes advantage of it by default:

<script src="http://www.google-analytics.com/ga.js" async></script>

If it weren’t for caching, the Web would collapse under network traffic. Caching stores recently requested resources locally so subsequent requests can serve them up from the disk, rather than downloading them again. It’s important to explicitly tell browsers what you want cached. Some browsers like Chrome will make their own default decisions, but you shouldn’t rely on that.

For static resources, make the cache “never” expire by adding a far future Expires header. This will ensure that the browser only ever downloads the resource once, and it should then be set on all static components, including scripts, stylesheets, and images.

Expires: Thu, 20 March 2015 00:00:00 GMT

You should set the expiry date in the far future relative to the current date. The example above tells the browser the cache won’t be stale until March 20th, 2015. If you’re using the Apache web server, you can set a relative expiration date easily using ExpiresDefault:

ExpiresDefault "access plus 5 years"

But what if you want to expire the resource before that time? A useful technique is to append the file’s modified time (or mtime) as a query parameter on URLs referencing it. Rails, for example, does this by default. Then, whenever the file is modified, the resource’s URL will change, clearing out the cache.

<link rel="stylesheet" href="master.css?1296085785" type="text/css">

HTTP 1.1. introduced a new class of headers, Cache-Control, to give developers more advanced caching and to address the limitations of Expires. The Cache-Control control header can take a number of options, separated by commas:

Cache-Control: max-age=3600, must-revalidate

To see the full list of options, visit the specification. The ones you’re likely to use now are listed below:

Adding a Last-Modified header to the served resource can also help caching. With subsequent requests to the resource, browsers can specify the If-Modified-Since header, which contains a timestamp. If the resource hasn’t been modified since the last request, the server can just return a 304 (not modified) status. The browser still has to make the request, but the server doesn’t have to include the resource in its response, saving network time and bandwidth:

# Request
GET /example.gif HTTP/1.1
Host:www.example.com
If-Modified-Since:Thu, 29 Apr 2010 12:09:05 GMT

# Response
HTTP/1.1 200 OK
Date: Thu, 20 March 2009 00:00:00 GMT
Server: Apache/1.3.3 (Unix)
Cache-Control: max-age=3600, must-revalidate
Expires: Fri, 30 Oct 1998 14:19:41 GMT
Last-Modified: Mon, 17 March 2009 00:00:00 GMT
Content-Length: 1040
Content-Type: image/gif

There is an alternative to Last-Modified: ETags. Comparing ETags is like comparing the hashes of two files; if the ETags are different, the cache is stale and must be revalidated. This works in a similar way to the Last-Modified header. The server will attach an ETag to a resource with an ETag header, and a client will check ETags with an If-None-Match header:

 # Request
 GET /example.gif HTTP/1.1
 Host:www.example.com
 If-Modified-Since:Thu, 29 Apr 2010 12:09:05 GMT
 If-None-Match:"48ef9-14a1-4855efe32ba40"

 # Response
 HTTP/1.1 304 Not Modified

ETags are typically constructed with attributes specific to the server—i.e., two separate servers will give different ETags for the same resource. With clusters becoming more and more common, this is a real issue. Personally, I advise you to stick with Last-Modified and turn off ETags altogether.

JavaScript minification reduces unnecessary characters from scripts without changing any functionality. These characters include whitespace, new lines, and comments. The better minifiers can interpret JavaScript. Therefore, they can safely shorten variables and function names, further reducing characters. Smaller file sizes are better because there’s less data to transfer over the network.

It’s not just JavaScript that can be minified. Stylesheets and HTML can also be processed. Stylesheets in particular tend to have a lot of redundant whitespace. Minification is something best done on deployment because you don’t want to be debugging any minified code. If there’s an error in production, try to reproduce it in a development environment first—you’ll find it much easier to debug the problem.

Minification has the additional benefit of obscuring your code. It’s true that a sufficiently motivated person could probably reconstruct it, but it’s a barrier to entry for the casual observer.

There are a lot of minimizing libraries out there, but I advise you to choose one with a JavaScript engine that can actually interpret the code. YUI Compressor is my favorite because it is well maintained and supported. Created by Yahoo! engineer Julien Lecomte, its goal was to shrink JavaScript files even further than JSMin by applying smart optimizations to the source code. Suppose we have the following function:

function per(value, total) {
  return( (value / total) * 100 );
}

YUI Compressor will, in addition to removing whitespace, shorten the local variables, saving yet more characters:

function per(b,a){return((b/a)*100)};

Because YUI Compressor actually parses the JavaScript, it can usually replace variables—without introducing code errors. However, this isn’t always the case; sometimes the compressor can’t fathom your code, so it leaves it alone. The most common reason for this is the use of an eval() or with() statement. If the compressor detects you’re using either of those, it won’t perform variable name replacement. In addition, both eval() and with() can cause performance problems—the browser’s JIT compiler has the same issue as the compressor. My advice is to stay well clear of either of these statements.

The simplest way to use YUI Compressor is by downloading the binaries, which require Java, and executing them on the command line:

java -jar yuicompressor-x.y.z.jar foo.js > foo.min.js

However, you can do this programmatically on deployment. If you’re using a library like Sprockets or Less, they’ll do this for you. Otherwise, there are several interface libraries to YUI Compressor, such as Sam Stephenson’s Ruby-YUI-compressor gem or the Jammit library.

Gzip is the most popular and supported compression method on the Web. It was developed by the GNU project, and support for it was added in HTTP/1.1. Web clients indicate their support for compression by sending an Accept-Encoding header along with the request:

Accept-Encoding: gzip, deflate

If the web server sees this header and supports any of the compression types listed, it may compress its response and indicate this via the Content-Encoding header:

Content-Encoding: gzip

Browsers can then decode the response properly. Obviously, compressing the data can reduce network time, but the true extent of this is often not realized. Gzip generally reduces the response size by 70%, a massive reduction that greatly speeds up the time it takes for your site to load.

Servers generally have to be configured over which file types should be gzipped. A good rule of thumb is to gzip any text response, such as HTML, JSON, JavaScript, and stylesheets. If the files are already compressed, such as images and PDFs, they shouldn’t be served with gzip because the recompression doesn’t reduce their size.

Configuring gzip depends on your web server, but if you use Apache 2.x or later, the module you need is mod_deflate. For other web servers, see their documentation.

A content delivery network, or CDN, can serve static content on your behalf, reducing its load time. The user’s proximity to the web server can have an impact on load times. CDNs can deploy your content across multiple geographically dispersed servers, so when a user requests a resource, it can be served up from a server near them (ideally in the same country). Yahoo! has found that CDNs can improve enduser response times by 20% or more.

Depending on how much you can afford to spend, there are lot of companies out there offering CDNs, such as Akamai Technologies, Limelight Networks, EdgeCast, and Level 3 Communications. Amazon Web Services has recently released an affordable option called Cloud Front that ties into its S3 service closely and may be a good option for startups.

Google offers a free CDN and loading architecture for many popular open source JavaScript libraries, including jQuery and jQueryUI. One of the advantages of using Google’s CDN is that many other sites use it too, increasing the likelihood that any JavaScript files you reference are already cached in a user’s browser.

Check out the list of available libraries. If, say, you want to include the jQuery library, you can either use Google’s JavaScript loader library or, more simply, a plain old script tag:

<!-- minimized version of the jQuery library -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js"></script>

<!-- minimized version of the jQuery UI library -->
<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1.8.6/jquery-ui.min.js">
</script>

You’ll notice that in the example above we haven’t specified a protocol; instead, // is used. This is a little-known trick that ensures the script file is fetched using the same protocol as the host page. In other words, if your page was loaded securely over HTTPS, the script file will be as well, eliminating any security warnings. A relative URL without a scheme is valid and compliant to the RTF spec. More importantly, it’s got support across the board; heck, protocol-relative URLs even work in Internet Explorer 3.0.

There are some really good tools to give you a quick heads up regarding your site’s performance. YSlow is an extension of Firebug, which is in turn a Firefox extension. You’ll need to install all three to use it. Once it’s installed, you can use it to audit web pages. The extension will run through a series of checks, including caching, minification, gzipping, and CDNs. It will give your site a grade, depending on how it fares, and then offer advice on how to improve your score.

Google Chrome and Safari also have auditors, but these are built right into the browser. As shown in Chrome in Figure 10-1, simply go to the Audits section of Web Inspector and click Run. This is a great way of seeing what things your site could improve on to increase its performance.

Figure 10-1. Auditing web page performance with Web Inspector

Both Yahoo! and Google have invested a huge amount into analyzing web performance. Increasing sites’ render speed is obviously in their best interest, both for their own services and for the user experience of their customers when browsing the wider Web. Indeed, Google now takes speed into account with its Pagerank algorithm, which helps determine where sites are ranked for search queries. Both companies have excellent resources on improving performance, which you can find on the Google and Yahoo! developer sites.

Simply download Spine from the project’s repository and include it in your page; Spine has no dependencies:

<script src="spine.js" type="text/javascript" charset="utf-8"></script>

Spine is completely namespaced behind the Spine variable, so it shouldn’t conflict with any other variables. You can safely include libraries like jQuery, Zepto, or Prototype without any complications.

Pretty much every object in Spine is encapsulated in a class. However, Spine’s classes are constructed using Object.create() and pure prototypal inheritance, as covered in Chapter 3, which is different from how most class abstractions are constructed.

To create a new class, call Spine.Class.create([instanceProperties, classProperties]), passing an optional set of instance and class properties:

var User = Spine.Class.create({
  name: "Caroline"
});

In the example above, instances of User now have a default name property. Behind the scenes, create() is creating a new object whose prototype is set to Spine.Class —i.e., it’s inheriting from it. If you want to create subsequent subclasses, simply call create() on their parent class:

var Friend = User.create();

Friend is now a subclass of User and will inherit all of its properties:

assertEqual( Friend.prototype.name, "Caroline" );

var user = new User;
assertEqual( user.name,  "Caroline" );

user.name = "Trish";
assertEqual( user.name, "Trish" );

var User = Spine.Class.create({
  init: function(name){
    this.name = name;
  }
});

var user = new User("Martina");
assertEqual( user.name, "Martina" );

User.include({
  // Instance properties
});

User.extend({
  // Class properties
});

var ORM = {
  extended: function(){
    // invoked when extended
    //   this === User
  },
  find:  function(){ /* ... */ },
  first: function(){ /* ... */ }
};

User.extend( ORM );

var Friend = User.create();

User.include({
  email: "info@eribium.org"
});

assertEqual( (new Friend).email, "info@eribium.org" );

var Controller = Spine.Class.create({
  init: function(){
    // Add event listener
    $("#destroy").click(this.destroy);
  },

  destroy: function(){
    // This destroy function is called with the wrong context,
    // so any references to `this` will cause problems
    // The following assertion will fail:
    assertEqual( this, Controller.fn );
  }
});

var Controller = Spine.Class.create({
  init: function(){
    $("#destroy").click(this.proxy(this.destroy));
  },

  destroy: function(){ }
});

Events are key to Spine, and they are frequently used internally. Spine’s event functionality is contained inside the module Spine.Events, which can be included wherever it’s needed. For example, let’s add some event support to a Spine class:

var User = Spine.Class.create();
User.extend(Spine.Events);

Spine.Events gives you three functions for handling events:

If you’ve used jQuery’s event API, this will look very familiar to you. For example, let’s bind and trigger an event on our User class:

User.bind("create", function(){ /* ... */ });
User.trigger("create");

To bind multiple events with a single callback, just separate them with spaces:

User.bind("create update", function(){ /* ... */ });

trigger() takes an event name and passes optional arguments along to the event’s callbacks:

User.bind("countChange", function(count){
  // `count` is passed by trigger
  assertEqual(count, 5);
});

User.trigger("countChange", 5);

You will most commonly use Spine’s events with data binding, hooking up your application’s models with its views. We’ll cover that in detail later in the section Building a Contacts Manager.

If you take a peek at Spine’s source code, you’ll see that the vast majority of it deals with models, and rightly so—models are the central part of any MVC application. Models deal with storing and manipulating your application’s data, and Spine simplifies this by providing a full ORM.

Rather than use the create() function to make a new model, which is already reserved, use Spine.Model.setup(name, attrs), passing in the model name and an array of attribute names:

// Create the Task model.
var Task = Spine.Model.setup("Task", ["name", "done"]);

Use include() and extend() to add instance and class properties:

Task.extend({
  // Return all done tasks.
  done: function(){ /* ... */ }
});

Task.include({
  // Default name
  name: "Empty...",
  done: false,

  toggle: function(){
    this.done = !this.done;
  }
});

When instantiating a record, you can pass an optional object containing the record’s initial properties:

var task = new Task({name: "Walk the dog"});
assertEqual( task.name, "Walk the dog" );

Setting and retrieving attributes is the same as setting and getting properties on a normal object. In addition, the attributes() function returns an object literal containing all the record’s attributes:

var task = new Task;
task.name = "Read the paper";
assertEqual( task.attributes(), {name: "Read the paper"} );

Saving new or existing records is as simple as calling the save() function. When saving a record, an ID will be generated if it doesn’t already exist; then, the record will be persisted locally in memory:

var task = new Task({name: "Finish book"});
task.save();

task.id //=> "44E1DB33-2455-4728-AEA2-ECBD724B5E7B"

Records can be retrieved using the model’s find() function, passing in the record’s ID:

var task = Task.find("44E1DB33-2455-4728-AEA2-ECBD724B5E7B");
assertEqual( task.name, "Finish book" );

If no record exists for the given ID, an exception will be raised. You can check whether a record exists without fear of an exception using the exists() function:

var taskExists = Task.exists("44E1DB33-2455-4728-AEA2-ECBD724B5E7B");
assert( taskExists );

You can remove a record from the local cache by using the destroy() function:

var task = Task.create({name: "Thanks for all the fish"});

assert( task.exists() );
task.destroy();
assertEqual( task.exists(), false );

// Return all tasks
Task.all(); //=> [Object]

// Return all tasks with a false done attribute
var pending = Task.select(function(task){ return !task.done });

// Invoke a callback for each task
Task.each(function(task){ /* ... */ });

// Finds first task with the specified attribute value
Task.findByAttribute(name, value);    //=> Object

// Finds all tasks with the specified attribute value
Task.findAllByAttribute(name, value); //=> [Object]

Task.bind("save", function(record){
  console.log(record.name, "was saved!");
});

Task.first().bind("save", function(){
  console.log(this.name, "was saved!")
});

Task.first().updateAttributes({name: "Tea with the Queen"});

Task.include({
  validate: function(){
    if ( !this.name ) return "Name required";
  }
});

Task.bind("error", function(record, msg){
  // Very basic error notification
  alert("Task didn't save: " + msg);
});

// Save with local storage
Task.extend(Spine.Model.Local);
Task.fetch();

Task.bind("refresh", function(){
  // New tasks!
  renderTemplate(Task.all());
});

// Save to server
Task.extend(Spine.Model.Ajax);

// Add a custom URL
Task.extend({
  url: "/tasks"
});

// Fetch new tasks from the server
Task.fetch();

read    → GET    /collection
create  → POST   /collection
update  → PUT    /collection/id
destroy → DELETE /collection/id

POST /tasks HTTP/1.0
Host: localhost:3000
Origin: http://localhost:3000
Content-Length: 66
Content-Type: application/json

{"id": "44E1DB33-2455-4728-AEA2-ECBD724B5E7B", "name": "Buy eggs"}

PUT /tasks/44E1DB33-2455-4728-AEA2-ECBD724B5E7B HTTP/1.0
Host: localhost:3000
Origin: http://localhost:3000
Content-Length: 71
Content-Type: application/json

{"id": "44E1DB33-2455-4728-AEA2-ECBD724B5E7B", "name": "Buy more eggs"}

Task.bind("ajaxError", function(record, xhr, settings, error){
  // Invalid response
});

Controllers are the last component to Spine, and they provide the glue that will tie the rest of your application together. Controllers generally add event handlers to DOM elements and models, render templates, and keep the view and models in sync. To create a Spine controller, you need to subclass Spine.Controller by calling create():

jQuery(function(){
  window.Tasks = Spine.Controller.create({
    // Controller properties
  });
});

It’s recommended to load controllers only after the rest of the page has loaded, so you don’t have to deal with different page states. In all the Spine examples, you’ll notice each controller is contained inside a call to jQuery(). This ensures that the controller will be created only when the document’s ready.

In Spine, the convention is to give controllers camel-cased plural names—usually, the plural of the model with which they’re associated. Most controllers just have instance properties, as they’re used after instantiation only. Instantiating controllers is the same as instantiating any other class, by using the new keyword:

var tasks = new Tasks;

Controllers always have a DOM element associated with them, which can be accessed through the el property. You can optionally pass this through on instantiation; otherwise, the controller will generate a default div element:

var tasks = new Tasks({el: $("#tasks")});
assertEqual( tasks.el.attr("id"), "tasks" );

This element can be used internally to append templates and render views:

window.Tasks = Spine.Controller.create({
  init: function(){
    this.el.html("Some rendered text");
  }
});

var tasks = new Tasks();
$("body").append(tasks.el);

In fact, any arguments you pass when instantiating the controller will be set as properties on the controller. For example:

var tasks = new Tasks({item: Task.first()});
assertEqual( Task.first(), tasks.item );

// The `input` instance variable
var Tasks = Spine.Controller.create({
  elements: {
    "form input[type=text]": "input"
  },

  init: function(){
    // this.input refers to the form's input
    console.log( this.input.val() );
  }
});

var Tasks = Spine.Controller.create({
  events: {
    "keydown form input[type=text]": "keydown"
  },

  keydown: function(e){ /* ... */ }
});

var Sidebar = Spine.Controller.create({
  events: {
    "click [data-name]": this.click
  },

  init: function(){
    this.bind("change", this.change);
  },

  change: function(name){ /* ... */ },

  click: function(e){
    this.trigger("change", $(e.target).attr("data-name"));
  }

  // ...
});

var sidebar = new Sidebar({el: $("#sidebar")});
sidebar.bind("change", function(name){
  console.log("Sidebar changed:", name);
})

var Sidebar = Spine.Controller.create({

  init: function(){
    Spine.bind("change", this.proxy(this.change));
  },

  change: function(name){ /* ... */ }
});

Spine.trigger("change", "messages");

var Tasks = Spine.Controller.create({
  init: function(){
    Task.bind("refresh change", this.proxy(this.render));
  },

  template: function(items){
    return($("#tasksTemplate").tmpl(items));
  },

  render: function(){
    this.el.html(this.template(Task.all()));
  }
});

var TasksItem = Spine.Controller.create({
  // Delegate the click event to a local handler
  events: {
    "click": "click"
  },

  // Bind events to the record
  init: function(){
    this.item.bind("update", this.proxy(this.render));
    this.item.bind("destroy", this.proxy(this.remove));
  },

  // Render an element
  render: function(item){
    if (item) this.item = item;

    this.el.html(this.template(this.item));
    return this;
  },

  // Use a template, in this case via jQuery.tmpl.js
  template: function(items){
    return($("#tasksTemplate").tmpl(items));
  },

  // Called after an element is destroyed
  remove: function(){
    this.el.remove();
  },

  // We have fine control over events, and
  // easy access to the record too
  click: function(){ /* ... */ }
});

var Tasks = Spine.Controller.create({
  init: function(){
    Task.bind("refresh", this.proxy(this.addAll));
    Task.bind("create",  this.proxy(this.addOne));
  },

  addOne: function(item){
    var task = new TasksItem({item: item});
    this.el.append(task.render().el);
  },

  addAll: function(){
    Task.each(this.addOne);
  }
});

So, let’s take our knowledge of Spine’s API and apply it to something practical, like a contacts manager. We want to give users a way of reading, creating, updating, and deleting contacts, as well as searching them.

Figure 11-1 shows the finished result so you can have an idea of what we’re creating.

Figure 11-1. Listing contacts in a Spine application

The contact manager is one of a set of open source Spine examples. You can follow along with the tutorial below, or download the full code from the project’s repository.

As you can see in Figure 11-1, the contact manager has two main sections, the sidebar and the contacts view. These two will make up our respective controllers, Sidebar and Contacts. As for models, the manager only has one: the Contact model. Before we expand on each individual component, let’s take a look at the initial page structure:

<div id="sidebar">
  <ul class="items">
  </ul>

  <footer>
    <button>New contact</button>
  </footer>
</div>

<div class="vdivide"></div>

<div id="contacts">
  <div class="show">
    <ul class="options">
      <li class="optEdit">Edit contact</li>
      <li class="optEmail">Email contact</li>
    </ul>
    <div class="content"></div>
  </div>

  <div class="edit">
    <ul class="options">
      <li class="optSave default">Save contact</li>
      <li class="optDestroy">Delete contact</li>
    </ul>
    <div class="content"></div>
  </div>
</div>

We have a #sidebar div and a #contacts div for our respective sections. Our application is going to fill the .items list with contact names and have a currently selected contact showing in #contacts. We’ll listen to clicks on .optEmail and .optSave, toggling between the show and edit states as required. Finally, we’ll listen for click events on .optDestroy, which destroys the current contact and selects another.

// Create the model
var Contact = Spine.Model.setup("Contact", ["first_name", "last_name", "email"]);

// Persist model between page reloads
Contact.extend(Spine.Model.Local);

// Add some instance functions
Contact.include({
  fullName: function(){
    if ( !this.first_name && !this.last_name ) return;
    return(this.first_name + " " + this.last_name);
  }
});

jQuery(function($){

  window.Sidebar = Spine.Controller.create({
    // Create instance variables:
    //  this.items //=> <ul></ul>
    elements: {
      ".items": "items"
    },

    // Attach event delegation
    events: {
      "click button": "create"
    },

    // Render template
    template: function(items){
      return($("#contactsTemplate").tmpl(items));
    },

    init: function(){
      this.list = new Spine.List({
        el: this.items,
        template: this.template
      });

      // When the list's current item changes, show the contact
      this.list.bind("change", this.proxy(function(item){
        Spine.trigger("show:contact", item);
      }));

      // When the current contact changes, i.e., when a new contact is created,
      // change the list's currently selected item
      Spine.bind("show:contact edit:contact", this.list.change);

      // Rerender whenever contacts are populated or changed
      Contact.bind("refresh change", this.proxy(this.render));
    },

    render: function(){
      var items = Contact.all();
      this.list.render(items);
    },

    // Called when 'Create' button is clicked
    create: function(){
      var item = Contact.create();
      Spine.trigger("edit:contact", item);
    }
  });

});

<script type="text/x-jquery-tmpl" id="contactsTemplate">
  <li class="item">
    {{if fullName()}}
      <span>${fullName()}</span>
    {{else}}
      <span>No Name</span>
    {{/if}}
  </li>
</script>

jQuery(function($){

  window.Contacts = Spine.Controller.create({
    // Populate internal element properties
    elements: {
      ".show": "showEl",
      ".show .content": "showContent",
      ".edit": "editEl"
    },

    init: function(){
      // Initial view shows contact
      this.show();

      // Rerender the view when the contact is changed
      Contact.bind("change", this.proxy(this.render));

      // Bind to global events
      Spine.bind("show:contact", this.proxy(this.show));
    },

    change: function(item){
      this.current = item;
      this.render();
    },

    render: function(){
      this.showContent.html($("#contactTemplate").tmpl(this.current));
    },

    show: function(item){
      if (item && item.model) this.change(item);

      this.showEl.show();
      this.editEl.hide();
    }
  });

<script type="text/x-jquery-tmpl" id="contactTemplate">
  <label>
    <span>Name</span>
    ${first_name} ${last_name}
  </label>

  <label>
    <span>Email</span>
    {{if email}}
      ${email}
    {{else}}
      <div class="empty">Blank</div>
    {{/if}}
  </label>
</script>

jQuery(function($){

  window.Contacts = Spine.Controller.create({
    // Populate internal element properties
    elements: {
      ".show": "showEl",
      ".edit": "editEl",
      ".show .content": "showContent",
      ".edit .content": "editContent"
    },

    // Delegate events
    events: {
      "click .optEdit": "edit",
      "click .optDestroy": "destroy",
      "click .optSave": "save"
    },

    init: function(){
      this.show();
      Contact.bind("change",        this.proxy(this.render));
      Spine.bind("show:contact", this.proxy(this.show));
      Spine.bind("edit:contact", this.proxy(this.edit));
    },

    change: function(item){
      this.current = item;
      this.render();
    },

    render: function(){
      this.showContent.html($("#contactTemplate").tmpl(this.current));
      this.editContent.html($("#editContactTemplate").tmpl(this.current));
    },

    show: function(item){
      if (item && item.model) this.change(item);

      this.showEl.show();
      this.editEl.hide();
    },

    // Called when the 'edit' button is clicked
    edit: function(item){
      if (item && item.model) this.change(item);

      this.showEl.hide();
      this.editEl.show();
    },

    // Called when the 'delete' button is clicked
    destroy: function(){
      this.current.destroy();
    },

    // Called when the 'save' button is clicked
    save: function(){
      var atts = this.editEl.serializeForm();
      this.current.updateAttributes(atts);
      this.show();
    }
  });

});

<script type="text/x-jquery-tmpl" id="editContactTemplate">
  <label>
    <span>First name</span>
    <input type="text" name="first_name" value="${first_name}" autofocus>
  </label>

  <label>
    <span>Last name</span>
    <input type="text" name="last_name" value="${last_name}">
  </label>

  <label>
    <span>Email</span>
    <input type="text" name="email" value="${email}">
  </label>
</script>

App Controller

So, we’ve got two controllers—Sidebar and Contacts—that deal with selecting, displaying, and editing Contact records. Now all that’s needed is an App controller that instantiates every other controller, passing them the page elements they require:

jQuery(function($){
  window.App = new Spine.Controller.create({
    el: $("body"),

    elements: {
      "#sidebar": "sidebarEl",
      "#contacts": "contactsEl"
    },

    init: function(){
      this.sidebar = new Sidebar({el: this.sidebarEl});
      this.contact = new Contacts({el: this.contactsEl});

      // Fetch contacts from local storage
      Contact.fetch();
    }
  })
});

Notice we’re instantiating the class with new immediately after creating the App controller. We’re also calling fetch() on the Contact model, retrieving all the contacts from local storage.

So, that’s all there is to it! Two main controllers (Sidebar and Contacts), one model (Contact), and a couple of views. To see the finished product, check out the source repository and see Figure 11-2.

Figure 11-2. Editing contacts in the example Spine application

Let’s start with probably the most key component to MVC: models. Models are where your application’s data is kept. Think of models as a fancy abstraction upon the application’s raw data, adding utility functions and events. You can create Backbone models by calling the extend() function on Backbone.Model:

var User = Backbone.Model.extend({
  initialize: function() {
    // ...
  }
});

The first argument to extend() takes an object that becomes the instance properties of the model. The second argument is an optional class property hash. You can call extend() multiple times to generate subclasses of models, which inherit all their parents’ class and instance properties:

var User = Backbone.Model.extend({
  // Instance properties
  instanceProperty: "foo"
}, {
  // Class properties
  classProperty: "bar"
});

assertEqual( User.prototype.instanceProperty, "foo" );
assertEqual( User.classProperty, "bar" );

When a model is instantiated, the model’s initialize() instance function is called with any instantiation arguments. Behind the scenes, Backbone models are constructor functions, so you can instantiate a new instance by using the new keyword:

var User = Backbone.Model.extend({
  initialize: function(name) {
    this.set({name: name});
  }
});

var user = new User("Leo McGarry");
assertEqual( user.get("name"), "Leo McGarry");

var user = new User();
user.set({name: "Donna Moss"})

assertEqual( user.get("name"), "Donna Moss" );
assertEqual( user.attributes, {name: "Donna Moss"} );

var User = Backbone.Model.extend({
  validate: function(atts){
    if (!atts.email || atts.email.length < 3) {
      return "email must be at least 3 chars";
    }
  }
});

var user = new User;

user.bind("error", function(model, error) {
  // Handle error
});

user.set({email: "ga"});

// Or add an error handler onto the specific set
user.set({"email": "ga"}, {error: function(model, error){
  // ...
}});

var Chat = Backbone.Model.extend({
  defaults: {
    from: "anonymous"
  }
});

assertEqual( (new Chat).get("from"), "anonymous" );

In Backbone, arrays of model instances are stored in collections. It might not be immediately obvious why it’s useful to separate collections from models, but it’s actually quite a common scenario. If you were recreating Twitter, for example, you’d have two collections, Followers and Followees, both populated by User instances. Although both collections are populated by the same model, each contains an array of different User instances; as a result, they are separate collections.

As with models, you can create a collection by extending Backbone.Collection:

var Users = Backbone.Collection.extend({
  model: User
});

In the example above, you can see we’re overriding the model property to specify which model we want associated with the collection—in this case, the User model. Although it’s not absolutely required, it’s useful to set this to give the collection a default model to refer to if it’s ever required. Normally, a collection will contain instances of only a single model type, rather than a multitude of different ones.

When creating a collection, you can optionally pass an initial array of models. Like with Backbone’s models, if you define an initialize instance function, it will be invoked on instantiation:

var users = new Users([{name: "Toby Ziegler"}, {name: "Josh Lyman"}]);

Alternatively, you can add models to the collection using the add() function:

var users = new Users;

// Add an individual model
users.add({name: "Donna Moss"});

// Or add an array of models
users.add([{name: "Josiah Bartlet"}, {name: "Charlie Young"}]);

When you add a model to the collection, the add event is fired:

users.bind("add", function(user) {
  alert("Ahoy " + user.get("name") + "!");
});

Similarly, you can remove a model from the collection using remove(), which triggers a remove event:

users.bind("remove", function(user) {
  alert("Adios " + user.get("name") + "!");
});

users.remove( users.models[0] );

Fetching a specific model is simple; if the model’s ID is present, you can use the controller’s get() function:

var user = users.get("some-guid");

If you don’t have a model’s ID, you can fetch a model by cid—the client ID created automatically by Backbone whenever a new model is created:

var user = users.getByCid("c-some-cid");

In addition to the add and remove events, whenever the model in a collection has been modified, a change event will be fired:

var user = new User({name: "Adam Buxton"});

var users = new Backbone.Collection;
users.bind("change", function(rec){
  // A record was changed!
});
users.add(user);

user.set({name: "Joe Cornish"});

var Users = Backbone.Collection.extend({
  comparator: function(user){
    return user.get("name");
  }
});

Backbone views are not templates themselves, but are control classes that handle a model’s presentation. This can be confusing, because many MVC implementations refer to views as chunks of HTML or templates that deal with events and rendering in controllers. Regardless, in Backbone, it is a view “because it represents a logical chunk of UI, responsible for the contents of a single DOM.”

Like models and collections, views are created by extending one of Backbone’s existing classes—in this case, Backbone.View:

var UserView = Backbone.View.extend({
  initialize: function(){ /* ... */ },
  render: function(){ /* ... */ }
});

Every view instance has the idea of a current DOM element, or this.el, regardless of whether the view has been inserted into the page. el is created using the attributes from the view’s tagName, className, or id properties. If none of these is specified, el is an empty div:

var UserView = Backbone.View.extend({
  tagName: "span",
  className: "users"
});

assertEqual( (new UserView).el.className, "users" );

If you want to bind the view onto an existing element in the page, simply set el directly. Clearly, you need to make sure this view is set up after the page has loaded; otherwise, the element won’t yet exist:

var UserView = Backbone.View.extend({
  el: $(".users")
});

You can also pass el as an option when instantiating a view, as with the tagName, className, and id properties:

new UserView({id: "followers"});

var TodoView = Backbone.View.extend({
  template: _.template($("#todo-template").html()),

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

new TodoView({model: new Todo});

var TodoView = Backbone.View.extend({
  events: {
    "change input[type=checkbox]" : "toggleDone",
    "click .destroy"              : "clear",
  },

  toggleDone: function(e){ /* ... */},
  clear: function(e){ /* ... */}
});

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

  close: function(){ /* ... */ }
});

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

  remove: function(){
    $(this.el).remove();
  }
});

Backbone controllers connect the application’s state to the URL’s hash fragment, providing shareable, bookmarkable URLs. Essentially, controllers consist of a bunch of routes and the functions that will be invoked when those routes are navigated to.

Routes are a hash—the key consisting of paths, parameters, and splats—and the value is set to the function associated with the route:

routes: {                            // Matches:
  "help":                 "help",    //  #help
  "search/:query":        "search",  //  #search/kiwis
  "search/:query/p:page": "search",   //  #search/kiwis/p7
  "file/*path":           "file"     //  #file/any/path.txt
}

You can see in the example above that parameters start with a : and then the name of the parameter. Any parameters in a route will be passed to its action when the route is invoked. Splats, specified by a *, are basically a wildcard, matching anything. As with parameters, splats will be passed matched values onto their route’s action.

Routes are parsed in the reverse order they’re specified in the hash. In other words, your most general “catch all” routes should be located at the beginning of the routes hash.

Per usual, controllers are created by extending Backbone.Controllers, passing in an object containing instance properties:

var PageController = Backbone.Controller.extend({
  routes: {
    "":                     "index",
    "help":                 "help",    // #help
    "search/:query":        "search",  // #search/kiwis
    "search/:query/p:page": "search"   // #search/kiwis/p7
  },

  index: function(){ /* ... */ },

  help: function() {
    // ...
  },

  search: function(query, page) {
    // ...
  }
});

In the example above, when the user navigates to http://example.com#search/coconut, whether manually or by pushing the back button, the search() function will be invoked with the query variable pointing to "coconut".

If you want to make your application compliant with the Ajax Crawling specification and indexable by search engines (as discussed in Chapter 4), you need to prefix all your routes with !/, as in the following example:

var PageController = Backbone.Controller.extend({
  routes: {
    "!/page/:title": "page", // #!/page/foo-title
  }
  // ...
}):

You’ll also need to make changes server side, as described by the specification.

If you need more route functionality, such as making sure certain parameters are integers, you can pass a regex directly to route():

var PageController = Backbone.Controller.extend({
  initialize: function(){
    this.route(/pages\/(\d+)/, 'id', function(pageId){
      // ...
    });
  }
}):

So, routes tie up changes to the URL’s fragment with controllers, but how about setting the fragment in the first place? Rather than setting window.location.hash manually, Backbone provides a shortcut—saveLocation(fragment):

Backbone.history.saveLocation("/page/" + this.model.id);

When saveLocation() is called and the URL’s fragment is updated, none of the controller’s routes will be invoked. This means you can safely call saveLocation() in a view’s initialize() function, for example, without any controller intervention.

Internally, Backbone will listen to the onhashchange event in browsers that support it, or implement a workaround using iframes and timers. However, you’ll need to initiate Backbone’s history support by calling the following:

Backbone.history.start();

You should only start Backbone’s history once the page has loaded and all of your views, models, and collections are available. As it stands, Backbone doesn’t support the new HTML5 pushState() and replaceState() history API. This is because pushState() and replaceState() currently need special handling on the server side and aren’t yet supported by Internet Explorer. Backbone may add support once those issues have been addressed. For now, all routing is done by the URL’s hash fragment.

By default, whenever you save a model, Backbone will notify your server with an Ajax request, using either the jQuery or Zepto.js library. Backbone achieves this by calling Backbone.sync() before a model is created, updated, or deleted. Backbone will then send off a RESTful JSON request to your server which, if successful, will update the model client side.

To take advantage of this, you need to define a url instance property on your model and have a RESTfully compliant server. Backbone will take care of the rest:

var User = Backbone.Model.extend({
  url: '/users'
});

The url property can either be a string or a function that returns a string. The path can be relative or absolute, but it must return the model’s endpoint.

Backbone maps create, read, update, and delete (CRUD) actions into the following methods:

create → POST   /collection
read   → GET    /collection[/id]
update → PUT    /collection/id
delete → DELETE /collection/id

For example, if you were creating a User instance, Backbone would send off a POST request to /users. Similarly, updating a User instance would send off a PUT request to the endpoint /users/id, where id is the model’s identifier. Backbone expects you to return a JSON hash of the instance’s attributes in response to POST, PUT, and GET requests, which will be used to update the instance.

To save a model to the server, call the model’s save([attrs], [options]) function, optionally passing in a hash of attributes and request options. If the model has an id, it is assumed to exist on the server side, and save() sends will be a PUT (update) request. Otherwise, save() will send a POST (create) request:

var user = new User();
user.set({name: "Bernard"});

user.save(null, {success: function(){
  // user saved successfully
}});

All calls to save() are asynchronous, but you can listen to the Ajax request callbacks by passing the success and failure options. In fact, if Backbone is using jQuery, any options passed to save() will also be passed to $.ajax(). In other words, you can use any of jQuery’s Ajax options, such as timeout, when saving models.

If the server returns an error and the save fails, an error event will be triggered on the model. If it succeeds, the model will be updated with the server’s response:

var user = new User();

user.bind("error", function(e){
  // The server returns an error!
});

user.save({email: "Invalid email"});

You can refresh a model by using the fetch() function, which will request the model’s attributes from the server (via a GET request). A change event will trigger if the remote representation of the model differs from its current attributes:

var user = Users.get(1);
user.fetch();

var Followers = Backbone.Collection.extend({
  model: User,
  url: "/followers"
});

Followers.fetch();

<script type="text/javascript">
  Followers.refresh(<%= @users.to_json %>);
</script>

create → POST   /collection
read   → GET    /collection
read   → GET    /collection/id
update → PUT    /collection/id
delete → DELETE /collection/id

{"name": "Yasmine"}

def update
  user = User.find(params[:id])
  user.update_attributes!(params)
  render :json => user
end

{"user": {"name": "Daniela"}}

# config/initializers/json.rb
ActiveRecord::Base.include_root_in_json = false

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

Todo.prototype.sync = function(method, model, options){ /* ... */ };

// Save all of the todo items under the "todos" localStorage namespace.
Todos.prototype.localStorage = new Store("todos");

// Override Backbone.sync() to use a delegate to the model or collection's
// localStorage property, which should be an instance of Store.
Backbone.sync = function(method, model, options) {

  var resp;
  var store = model.localStorage || model.collection.localStorage;

  switch (method) {
    case "read":    resp = model.id ? store.find(model) : store.findAll(); break;
    case "create":  resp = store.create(model);                            break;
    case "update":  resp = store.update(model);                            break;
    case "delete":  resp = store.destroy(model);                           break;
  }

  if (resp) {
    options.success(resp);
  } else {
    options.error("Record not found");
  }
};

Let’s put what we’ve learned about Backbone into practice with a simple to-do list application. We want the user to be able to CRUD to-dos, and we want items to be persisted between page refreshes. You can build the application using the examples below, or see the finished application in assets/ch12/todos.

The initial page structure looks like the following; we’re loading in CSS, JavaScript libraries, and our Backbone application contained in todos.js:

<html>
<head>
  <link href="todos.css" media="all" rel="stylesheet" type="text/css"/>
  <script src="lib/json2.js"></script>
  <script src="lib/jquery.js"></script>
  <script src="lib/jquery.tmpl.js"></script>
  <script src="lib/underscore.js"></script>
  <script src="lib/backbone.js"></script>
  <script src="lib/backbone.localstorage.js"></script>
  <script src="todos.js"></script>
</head>

<body>
  <div id="todoapp">
    <div class="title">
      <h1>Todos</h1>
    </div>

    <div class="content">
      <div id="create-todo">
        <input id="new-todo" placeholder="What needs to be done?" type="text" />
      </div>

      <div id="todos">
        <ul id="todo-list"></ul>
      </div>
    </div>
  </div>
</body>
</html>

The page structure is very straightforward; it just contains a text input for creating new to-dos (#new-todo) and a list showing existing to-dos (#todo-list).

Now let’s move on to the todos.js script, where the core of our Backbone application is located. We’re going to wrap everything we put in this class with jQuery(), ensuring that it will be run only after the page has loaded:

// todos.js
jQuery(function($){
  // Application goes here...
})

Let’s create a basic Todo model that has content and done attributes. We’re providing a toggle() helper for easily inverting the model’s done attribute:

window.Todo = Backbone.Model.extend({
  defaults: {
    done: false
  },

  toggle: function() {
    this.save({done: !this.get("done")});
  }
});

We’re setting the Todo model on the window object to ensure that it’s accessible globally. Also, by using this pattern, it’s easy to see which global variables a script is declaring—just look through the script for window references.

The next step is to set up a TodoList collection, where the array of Todo models will be stored:

window.TodoList = Backbone.Collection.extend({
  model: Todo,

  // Save all of the to-do items under the "todos" namespace.
  localStorage: new Store("todos"),

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

  remaining: function() {
    return this.without.apply(this, this.done());
  }
});

// Create our global collection of Todos.
window.Todos = new TodoList;

We’re using the Backbone local storage provider (backbone.localstorage.js), which requires us to set a localStorage attribute on any collections or models wanting to store data. The other two functions in TodoList, done(), and remaining() deal with filtering the collection, returning to-do models that have or have not been completed. Because there will only ever be one TodoList, we’re instantiating a globally available instance of it: window.Todos.

And now for the view that will show individual to-dos, TodoView. This will bind to the change event on Todo models, rerendering the view when it’s triggered:

window.TodoView = Backbone.View.extend({

  // View is a list tag.
  tagName:  "li",

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

  // Delegate events to view functions
  events: {
    "change   .check"        : "toggleDone",
    "dblclick .todo-content" : "edit",
    "click    .todo-destroy" : "destroy",
    "keypress .todo-input"   : "updateOnEnter",
    "blur     .todo-input"   : "close"
  },

  initialize: function() {
    // Make sure functions are called in the right scope
    _.bindAll(this, 'render', 'close', 'remove');

    // Listen to model changes
    this.model.bind('change', this.render);
    this.model.bind('destroy', this.remove);
  },

  render: function() {
    // Update el with stored template
    var element = jQuery.tmpl(this.template, this.model.toJSON());
    $(this.el).html(element);
    return this;
  },

  // Toggle model's done status when the checkbox is checked
  toggleDone: 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 to-do.
  close: function(e) {
    this.model.save({content: this.input.val()});
    $(this.el).removeClass("editing");
  },

  // If you hit `enter`, we're through editing the item.
  // Fire the blur event on the input, triggering close()
  updateOnEnter: function(e) {
    if (e.keyCode == 13) e.target.blur();
  },

  // Remove element when model is destroyed
  remove: function() {
    $(this.el).remove();
  },

  // Destroy model when '.todo-destroy' is clicked
  destroy: function() {
    this.model.destroy();
  }
});

You can see we’re delegating a bunch of events to the view that manage updating, completing, and deleting the to-do. For example, whenever the checkbox is changed, toggleDone() gets called, toggling the model’s done attribute. That in turn triggers the model’s change event, which causes the view to rerender.

We’re using jQuery.tmpl for the HTML templating, replacing the contents of el with a regenerated template whenever the view renders. The template refers to an element with an ID of #item-template, which we haven’t yet defined. Let’s do that now, placing the template inside our index.html body tags:

<script type="text/template" id="item-template">
  <div class="todo {{if done}}done{{/if}}">
    <div class="display" title="Double click to edit...">
      <input class="check" type="checkbox" {{if done}}checked="checked"{{/if}} />
      <div class="todo-content">${content}</div>
      <span class="todo-destroy"></span>
    </div>
    <div class="edit">
      <input class="todo-input" type="text" value="${content}" />
    </div>
  </div>
</script>

That templating syntax should look fairly familiar to you if you’ve read Chapter 5, where jQuery.tmpl is covered in some depth. Essentially, we’re interoperating the to-do’s contents inside the #todo-content and #todo-input elements. Additionally, we’re making sure the checkbox has the correct “checked” state.

TodoView is pretty self-contained—we just need to give it a model on instantiation and append its el attribute to the to-do list. This is basically the job of AppView, which ensures that our initial to-do list is populated by instantiating TodoView instances. The other role AppView performs is creating new Todo records when a user hits Return on the #new-todo text input:

// Our overall AppView is the top-level piece of UI.
window.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"),

  events: {
    "keypress #new-todo":  "createOnEnter",
    "click .todo-clear a": "clearCompleted"
  },

  // 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 to-dos that might be saved in *localStorage*.
  initialize: function() {
    _.bindAll(this, 'addOne', 'addAll', 'render');

    this.input = this.$("#new-todo");

    Todos.bind('add',     this.addOne);
    Todos.bind('refresh', this.addAll);

    Todos.fetch();
  },

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

  // Add all items in the Todos collection at once.
  addAll: function() {
    Todos.each(this.addOne);
  },

  // If you hit return in the main input field, create new Todo model
  createOnEnter: function(e) {
    if (e.keyCode != 13) return;

    var value = this.input.val();
    if ( !value ) return;

    Todos.create({content: value});
    this.input.val('');
  },

  clearCompleted: function() {
    _.each(Todos.done(), function(todo){ todo.destroy(); });
    return false;
  }
});

// Finally, we kick things off by creating the App.
window.App = new AppView;

When the page initially loads, the Todos collection will be populated and the refresh event called. This invokes addAll(), which fetches all the Todo models, generates TodoView views, and appends them to #todo-list. Additionally, when new Todo models are added to Todos, the Todos add event is triggered, invoking addOne() and appending a new TodoView to the list. In other words, the initial population and Todo creation is being handled by AppView, while the individual TodoView views handle updating and destroying themselves.

Now let’s refresh the page and see the result of our handiwork. Notwithstanding any bugs and typos, you should see something like Figure 12-1.

Figure 12-1. The finished Backbone Todo application

We have functionality for adding, checking, updating, and removing to-dos, all with a relatively small amount of code. Because we’re using the local storage Backbone adapter, to-dos are persisted between page reloads. This example should give you a good idea of how useful Backbone is, as well as how to go about creating your own applications.

You can find the full application inside this book’s accompanying files, in assets/ch12/todos.

Every Ember.js app starts by creating an application object:

window.App = Ember.Application.create();

Calling create() on an Ember object returns a new instance of that class. Here, we’re creating a new instance of Ember.Application and assigning it to the global variable App.

The Application object serves a number of important roles in your application. The most obvious is that it serves as a namespace, into which all of the other classes you define will be placed. For example, you might have a controller called App.UsersController or a model called App.User.

Less obvious is what the Application is doing for you behind-the-scenes: creating instances of your controllers, finding templates in DOM and compiling them, and kicking off routing. While advanced users can tweak what happens here to their heart’s content, the default behavior for all of these things should be enough to get you started.

Another nice feature the Application instance gives you is sane toString() semantics. As you’re developing your Ember.js application, try it in the console—it makes debugging much easier:

user.toString();
// => "<App.User:ember123>"

Models are objects that represent persistent data. They are responsible for loading data from your server, making it available to templates, then sending it back to the server if there are any changes to be saved.

App.Store = DS.Store.extend();

App.Store = DS.Store.extend({
  adapter: 'App.AwesomeWebSocketsAdapter'
});

App.User = DS.Model.extend({
  name: DS.attr('string')
});

App.User = DS.Model.extend({
  name: DS.attr('string'),
  commentCount: DS.attr('number'),

  isVIP: function() {
    return this.get('commentCount') > 100;
  }.property('commentCount')
});

var user = App.User.createRecord({
  name: "Tyrion Lannister",
  commentCount: 99
});

user.get('name');
assertEqual( user.get('name'), "Tyrion Lannister" );
assertEqual( user.get('isVIP'), false );

user.set('commentCount', 100);

// Now that commentCount has changed, the isVIP
// computed property updates automatically.
assertEqual( user.get('isVIP'), true );

App.Post = DS.Model.extend({
  comments: DS.hasMany('App.Comment')
});

App.Comment = DS.Model.extend({
  post: DS.belongsTo('App.Post')
});

var post = App.Post.createRecord();
var comment = App.Post.createRecord();

// You can set the `belongsTo` side
comment.set('post', post);

// ...or add it to the parent `hasMany` array
post.get('comments').pushObject(comment);

As you’ll remember from Chapter 5, a template allows you to take a fragment of HTML annotated with template variables, combine it with a JavaScript object (called the template context), and produce a string of HTML where the template variables have been replaced with values from the object.

Ember.js uses Handlebars, a logicless JavaScript templating language. Logicless means that, unlike some other templating libraries, you cannot embed arbitrary JavaScript expressions in your template. Instead, you are only allowed to display the properties of the current template context.

While this may seem like a limitation, it is in fact what allows us to implement one of Ember’s coolest features: once you render a template, it automatically stays up-to-date as the underlying template context changes.

That means you never have to write custom render code or add model listeners in your views. In fact, you can usually skip creating views altogether. Just describe the HTML you want in a template, and it is Ember’s responsibility to set up bindings and update the DOM if the underlying object ever changes.

Here’s an example of a simple Handlebars template:

<div class="user-info">
Welcome back, {{firstName}} {{lastName}}!
</div>

Note that simple expressions are wrapped in double curly braces. In the above example, {{firstName}} means look up the firstName property from the current context and put it into the HTML.

There are also block helpers, which look similar to simple expressions but begin with a hash (#) in the opening expression and a slash (/) in the closing expression:

{{#if unreadPosts}}
  Unread Posts: {{unreadPosts.length}}
{{/if}}

Block helpers affect the content they enclose. In this example, information about the number of unread posts is only displayed if the template context’s unreadPosts property evaluates to a truthy value.

You can save your templates inside your application’s HTML file, by wrapping it in a <script> tag:

<script id="user-info-template" type="text/x-handlebars">
  <div class="user-info">
    Welcome back, {{firstName}} {{lastName}}!
  </div>
</script>

Note that the <script> tag includes an id attribute. You can use this identifier later to tell Ember.js which template to display. If you have a <script> tag without an id, Ember.js assumes that it is your main template and will render it immediately.

{{#if isLoaded}}
  <h1>{{title}}</h1>
{{else}}
  Loading…
{{/if}}

{{#unless isAdministrator}}
  Karma: {{karma}}
{{/unless}

<p>Name: {{firstName}} {{lastName}}</p>

{{#with profile}}
  <p>Bio: {{bio}}</p>
  <p>Address:  {{address}}</p>
{{/with}}

<h1>{{blogTitle}}</h1>
<ul class="posts">
{{#each posts}}
  <li>{{title}} by {{author}}</li>
{{/each}}

Remaining: {{pluralize remainingItems}}

Remaining: 1 item

Remaining: 16 items

Remaining: {{pluralize remainingItems word="post"}}

Remaining: 16 posts

Ember.Handlebars.registerBoundHelper('pluralize', function(value, options) {
  var word = options.hash.word || "item";
  if (value === 1) { return '1 ' + word; }
  return value + ' ' + word + 's';
});

In Ember, controllers have two responsibilities:

In many cases, you will not need a controller at all. Wait until you need to transform or augment the properties of a model, or respond to a user action, to start adding controllers to your application.

App.AuthenticationController = Ember.Controller.extend({
  logout: function() {
    // ...put logout code here...
  }
});

<button {{action "logout"}}>Log Out</button>

<button {{action "reload" on="doubleClick"}}>Double-click to reload</a>

<form {{action "submitForm" on="submit"}}>
  <label for="name">Name</label>
  {{view Ember.TextField valueBinding="name"}}
  <button type="submit">Submit</button>
</form>

// Model
App.Post = DS.Model.extend({
  title: DS.attr('string'),
  comments: DS.hasMany('App.Comment')
});

// Controller
App.PostController = Ember.ObjectController.extend();

<h2>{{title}}</h2>

var attr = DS.attr;

App.Item = DS.Model.extend({
  name: attr('string'),
  price: attr('number')
});

App.ItemController = Ember.ObjectController.extend({
  price: function() {
    var price = this.get('model.price');
    return "$" + parseFloat(price).toFixed(2);
  }.property('model.price')
});

<table>
  <tr><th>Item</th><td>{{name}}</td>
  <tr><th>Price</th><td>{{price}}</td>
</table>

App.PostsController = Ember.ArrayController.extend();

<h1>Posts</h1>
{{#each post in controller}}
  <h2>{{post.title}}</h2>
{{/each}}

App.PostsController = Ember.ArrayController.extend({
  unreadCount: function() {
    return this.filterProperty('isUnread').get('length');
  }.property('@each.isUnread')
});

<h1>My Cool Blog</h1>
{{#each post in controller}}
  <h2>{{post.title}}</h2>
{{/each}}

<p>Unread Posts: {{unreadCount}}</p>

In Ember, the router is responsible for figuring out what templates should currently be on screen, which controllers the templates should be connected to, and which models those controllers should represent. In many ways, it is responsible for tying together all of the concepts that you’ve learned about so far in this chapter, and telling them all how to work together. If your application were a NASA space project, you could perhaps think of the router as Mission Control.

As the user interacts with your app, the router updates the templates, controllers and models on screen in response to their actions. Because it’s important for users to be able to share what they’re seeing with friends, the router also updates the URL as the UI changes.

Additionally, if the user enters the application via an existing URL, the router is responsible for rebuilding the state of the application.

For example, imagine we’re writing an application for reading blog posts. If our user visits blog.example.com/, she should see the list of blog posts available. If she clicks one of the entries that interests her, two things should happen:

If our user takes that URL and tweets it to her followers, they should see the same blog post when they click the link.

App.Router.map(function() {
  this.route("about");
  this.route("favorites");
});

App.Router.map(function() {
  this.route("favorites", { path: '/favs' });
});

App.IndexRoute = Ember.Route.extend({
  model: function() {
    return App.Post.find();
  }
});

App.Router.map(function() {
  this.route("favorites");
  this.route("mostPopular");
});

App.Router.map(function() {
  this.resource('posts');
});

App.Router.map(function() {
  this.resource('posts', function() {
    this.route('unread');
    this.route('favorites');
  });
});

App.Router.map(function() {
  this.resource('post', { path: '/post/:post_id' });
});

App.Router.map(function() {
  this.route('about');
  this.route('contact');
  this.route('resume');
});

Welcome to my personal site!

Please {{#linkTo "resume"}}read my resume{{/linkTo}} or
{{#linkTo "contact"}}contact me!{{/linkTo}}

App.Router.map(function() {
  this.resource('posts');
  this.resource('post', { path: '/posts/:post_id' });
});

<h1>My Cool Blog</h1>
<ul>
{{#each post in controller}}
  <li>{{#linkTo "post" post}}{{post.title}}{{/linkTo}}</li>
{{/each}}
</ul>

Now that you’re familiar with the core concepts that make an Ember.js app tick, let’s put them all together to build a simple todo application.

Unlike the previous versions of this application that you’ve built, you won’t be writing a lot of JavaScript. Instead, you’ll describe what you want to happen using templates, and Ember will automatically keep them up-to-date for you.

Let’s start with the minimum needed to get a simple page that loads in all of our dependencies:

<html>
  <head>
    <title>Ember.js Todos</title>
    <link href="todos.css" media="all" rel="stylesheet" type="text/css"/>
    <script src="lib/handlebars-1.0.rc.2.js"></script>
    <script src="lib/jquery-1.8.3.js"></script>
    <script src="lib/ember.js"></script>
    <script src="lib/ember-data.js"></script>
    <script src="todos.js"></script>
  </head>
  <body>
  </body>
</html>

Now, let’s move on to todos.js, which contains all of the JavaScript necessary to run the application.

First, remember that every Ember application starts with an instance of Ember.Application. Let’s add it to the top of todos.js now:

App = Ember.Application.create();

This creates a namespace for all of the other classes we’ll define, as well as generating all of the infrastructure necessary to get the app to running.

Next, we’ll tell Ember that we’d like our application to have a data store by defining a subclass of DS.Store:

App.Store = DS.Store.extend({
  revision: 11,
  adapter: 'DS.FixtureAdapter'
});

The revision specifies the current Ember Data API revision, and the adapter tells the store where to go to load and save records. In this case, we’re using revision 11 of Ember Data, and we’re telling the store that it should try to fetch records from fixture data.

Because Ember Data is frequently being improved, specifying the revision number means that the library authors can alert you when the API changes. This makes it easy to stay up-to-date with improvements as they happen, without having to trudge through mysterious errors.

Now that we have a store, we can describe the models in our application. Because this is a simple application, we only have one: the Todo.

App.Todo = DS.Model.extend({
  isDone: DS.attr('boolean'),
  content: DS.attr('string')
});

This defines a model called App.Todo that has two attributes:

Now it’s time to tell Ember what template we want to display when our user loads the application. Using the built-in router, we’ll tell Ember that it should render the todos template when the user visits /.

App.Router.map(function() {
  this.route('todos', { path: '/' });
});

If we don’t do anything else, Ember will automatically render the contents of the todos template as soon as the user loads the page. However, this wouldn’t really qualify as an application — it’s just a static page.

In order to make the page dynamic, we need to tell Ember what models should be displayed by the template. We do that using route handlers. In this case, because we’re displaying the todos template, we can customize the App.TodosRoute handler to specify which model gets rendered:

App.TodosRoute = Ember.Route.extend({
  model: function() {
    return App.Todo.all();
  }
});

By returning App.Todo.all() from the route handler’s model hook, we’re telling Ember: When the user visits our web application at /, find all of the Todo models you know about and render them using the todos template.

Finally, we’ll define a controller that is responsible for:

Here’s the code for the controller:

App.TodosController = Ember.ArrayController.extend({
  newTodo: function(title, textField) {
    App.Todo.createRecord({
      content: title
    });

    textField.set('value', '');
  },

  destroyTodo: function(todo) {
    todo.deleteRecord();
  },

  destroyCompleted: function() {
    this.get('completed').invoke('deleteRecord');
  },

  remaining: function() {
    return this.get('length') - this.get('completedCount');
  }.property('length', 'completedCount'),

  completed: function() {
    return this.filterProperty('isDone');
  }.property('@each.isDone'),

  completedCount: function() {
    return this.get('completed.length');
  }.property('completed')
});

As you can see, there is not much JavaScript code here at all.

It implements three action handlers and three computed properties. In particular, it handles actions sent when:

It also implements three computed properties:

Lastly, let’s switch back to index.html and implement the template that will render the user interface for our app.

Remember that Handlebars templates that you keep in your HTML file need to be wrapped in <script> tags, to prevent the browser from trying to treat them as HTML. Our <script> tag will look like this:

<script type="text/x-handlebars" data-template-name="todos">

</script>

This todos template will be the template for the entire application. If we were to add features to the app, we would probably add more templates to go along with this one. But for now, you can put all of the Handlebars markup inside this one <script> tag.

Here’s what the entire template looks like, all together:

<div id="todoapp">
  <div class="title">
    <h1>Todos</h1>
  </div>

  <div class="content">
    <div id="create-todo">
      {{view Ember.TextField id="new-todo" action="newTodo" 
        placeholder="What needs to be done?"}}
    </div>

    <div id="todos">
      <ul id="todo-list">
        {{#each todo in controller}}
        <li>
          <div {{bindAttr class=":todo todo.isDone:done"}}>
            <div class="display" title="Double click to edit...">
              {{view Ember.Checkbox class="check" checkedBinding="todo.isDone"}}
              <div class="todo-content">{{todo.content}}</div>
              <span class="todo-destroy" {{action destroyTodo todo}}></span>
            </div>
            <div class="edit">
              <input class="todo-input" type="text" value="${content}" />
            </div>
          </div>
         </li>
        {{/each}}
      </ul>
    </div>

    <div id="todo-stats">
      {{#if length}}
        <span class="todo-count">
          <span class="number">{{pluralize remaining}}</span>
        </span>
      {{/if}}
      {{#if length}}
        <span class="todo-clear">
          <a href="#" {{action destroyCompleted}}>
            Clear {{pluralize completedCount word="completed item"}}</span>
          </a>
        </span>
      {{/if}}
    </div>
  </div>
</div>

There’s a lot going on here, so let’s break it into pieces.

First, we want to create a text field that, when the user hits the enter key, sends an action to the controller telling it to create a new todo:

<div id="create-todo">
  {{view Ember.TextField id="new-todo" action="newTodo" 
    placeholder="What needs to be done?"}}
</div>

Next, we loop over all of the todos that the application knows about and create an <li> for each:

<ul id="todo-list">
  {{#each todo in controller}}
  <li>
    <!-- todo template here -->
   </li>
  {{/each}}
</ul>

Inside the {{#each}} block, we put the template that should be rendered once per todo.

<li>
  <div {{bindAttr class=":todo todo.isDone:done"}}>
    <div class="display" title="Double click to edit...">
      {{view Ember.Checkbox class="check" checkedBinding="todo.isDone"}}
      <div class="todo-content">{{todo.content}}</div>
      <span class="todo-destroy" {{action destroyTodo todo}}></span>
    </div>
    <div class="edit">
      <input class="todo-input" type="text" value="${content}" />
    </div>
  </div>
 </li>

First, we bind the containing <div>’s class attribute to a static value, as well as to the Todo model’s isDone property. If the model’s isDone is true, the done class will be added to the HTML element. Otherwise, it will be removed.