backbone-fundamentals.db

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
                  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <articleinfo>
    <title></title>
  </articleinfo>
<sect1 id="prelude">
  <title>Prelude</title>
  <para>
    Welcome to my (in-progress) book about the
    <ulink url="http://documentcloud.github.com/backbone/">Backbone.js</ulink>
    framework for structuring JavaScript applications. It’s released
    under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0
    Unported
    <ulink url="http://creativecommons.org/licenses/by-nc-sa/3.0/">license</ulink>
    meaning you can both grab a copy of the book for free or help to
    further
    <ulink url="https://github.com/addyosmani/backbone-fundamentals/">improve</ulink>
    it.
  </para>
  <para>
    I’m very pleased to announce that this book will be out in physical
    form in a few months time via
    <ulink url="http://oreilly.com">O’Reilly Media</ulink>. Readers will
    have the option of purchasing the latest version in either print or
    a number of digital formats then or can grab a recent version from
    this repository.
  </para>
  <para>
    Corrections to existing material are always welcome and I hope that
    together we can provide the community with an up-to-date resource
    that is of help. My extended thanks go out to
    <ulink url="https://github.com/jashkenas">Jeremy Ashkenas</ulink>
    for creating Backbone.js and
    <ulink url="https://github.com/addyosmani/backbone-fundamentals/contributors">these</ulink>
    members of the community for their assistance tweaking this project.
  </para>
  <para>
    I hope you find this book helpful!
  </para>
</sect1>
<sect1 id="table-of-contents">
  <title>Table Of Contents</title>
  <itemizedlist>
    <listitem>
    </listitem>
    <listitem>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="mvc-mvp">MVC, MVP &amp; Backbone.js</link>
          </para>
        </listitem>
      </itemizedlist>
    </listitem>
    <listitem>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="models">Models</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="views">Views</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="collections">Collections</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="routers">Routers</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="namespacing">Namespacing</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="additional-tips">Additional tips</link>
          </para>
        </listitem>
      </itemizedlist>
    </listitem>
    <listitem>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="restful">Building RESTful applications with
            Backbone</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="stack1">Building Backbone apps with Node.js,
            Express, Mongoose and MongoDB</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="stack2">Building Backbone apps with Ruby,
            Sinatra, Haml and MongoDB</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="pagination">Paginating Backbone.js Requests
            &amp; Collections</link>
          </para>
        </listitem>
      </itemizedlist>
    </listitem>
    <listitem>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="modularjs">Modular JavaScript</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="organizingmodules">Organizing modules with
            RequireJS and AMD</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="externaltemplates">Keeping your templates
            external with the RequireJS text plugin</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="optimizingrequirejs">Optimizing Backbone apps
            for production with the RequireJS Optimizer</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="practicalrequirejs">Practical: Building a
            modular Backbone app with AMD &amp; RequireJS</link>
          </para>
        </listitem>
        <listitem>
          <para>
            <link linkend="decouplingbackbone">Decoupling Backbone with
            the Mediator and Facade patterns</link>
          </para>
        </listitem>
        <listitem>
          <para>
            Backbone &amp; jQuery Mobile
          </para>
        </listitem>
        <listitem>
          <para>
            Practical: Building A Modular Mobile App With Backbone &amp;
            jQuery Mobile
          </para>
        </listitem>
      </itemizedlist>
    </listitem>
    <listitem>
      <itemizedlist>
        <listitem>
          <para>
            <link linkend="unittestingjasmine">Unit Testing Backbone
            Applications With Jasmine</link>
          </para>
        </listitem>
        <listitem>
          <para>
            Introduction
          </para>
        </listitem>
        <listitem>
          <para>
            Jasmine
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Suites, Specs And Spies
              </para>
            </listitem>
            <listitem>
              <para>
                TDD With Backbone
              </para>
            </listitem>
            <listitem>
              <para>
                <link linkend="testing-jasmine-models">Testing
                Models</link>
              </para>
            </listitem>
            <listitem>
              <para>
                <link linkend="testing-jasmine-collections">Testing
                Collections</link>
              </para>
            </listitem>
            <listitem>
              <para>
                <link linkend="testing-jasmine-views">Testing
                Views</link>
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>
            <link linkend="unittestingqunit">Unit Testing Backbone
            Applications With QUnit And SinonJS</link>
          </para>
        </listitem>
        <listitem>
          <para>
            Introduction
          </para>
        </listitem>
        <listitem>
          <para>
            QUnit
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Assertions
              </para>
            </listitem>
            <listitem>
              <para>
                Adding structure to assertions
              </para>
            </listitem>
            <listitem>
              <para>
                Assertion examples
              </para>
            </listitem>
            <listitem>
              <para>
                Fixtures
              </para>
            </listitem>
            <listitem>
              <para>
                Asynchronous code
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>
            SinonJS
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Stubs
              </para>
            </listitem>
            <listitem>
              <para>
                Mocks
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
        <listitem>
          <para>
            Practical
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Testing Models
              </para>
            </listitem>
            <listitem>
              <para>
                Testing Collections
              </para>
            </listitem>
            <listitem>
              <para>
                Testing Views
              </para>
            </listitem>
            <listitem>
              <para>
                Testing Events
              </para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </listitem>
    <listitem>
    </listitem>
  </itemizedlist>
</sect1>
<sect1 id="introduction">
  <title><a name="introduction">Introduction</a></title>
  <para>
    As JavaScript developers, we are at an interesting point in time
    where not only do we have mature solutions to help organize the
    JavaScript powering our applications based on a separation of
    concerns, but developers looking to build non-trivial projects are
    almost spoiled for choice for frameworks that can help structure
    their applications.
  </para>
  <para>
    Maturity in software (framework) development isn’t simply about how
    long a framework has been around. It’s about how solid the framework
    is and more importantly how well it’s evolved to fill its role. Has
    it become more effective at solving common problems? Does it
    continue to improve as developers build larger and more complex
    applications with it?
  </para>
  <para>
    In this book, I will be covering the popular Backbone.js, which I
    consider the best of the current family of JavaScript architectural
    frameworks.
  </para>
  <para>
    Topics will include MVC theory and how to build applications using
    Backbone’s models, views, collections and routers. I’ll also be
    taking you through advanced topics like modular development with
    Backbone.js and AMD (via RequireJS), how to build applications using
    modern software stacks (like Node and Express), how to solve the
    routing problems with Backbone and jQuery Mobile, tips about
    scaffolding tools, and a lot more.
  </para>
  <para>
    If this is your first time looking at Backbone.js and you’re still
    unsure whether or not to give it a try, why not take a look at how
    <ulink url="http://github.com/addyosmani/todomvc">a Todo
    application</ulink> can be implemented in Backbone and several other
    popular Javascript frameworks before reading further?
  </para>
  <para>
    The goal of this book is to create an authoritative and centralized
    repository of information that can help those developing real-world
    apps with Backbone. If you come across a section or topic which you
    think could be improved or expanded on, please feel free to submit a
    pull-request. It won’t take long and you’ll be helping other
    developers avoid problems you’ve run into before.
  </para>
</sect1>
<sect1 id="fundamentals">
  <title><a name="fundamentals">Fundamentals</a></title>
  <para>
    In this section we are going to cover the context into which a
    framework like Backbone.js fits. Let’s begin our journey into
    understanding Backbone better with a look at code architecture.
  </para>
  <sect2 id="mvc-mvp-backbone.js">
    <title><a name="mvc-mvp">MVC, MVP &amp; Backbone.js</a></title>
    <para>
      Before exploring any JavaScript frameworks that assist in
      structuring applications, it can be useful to gain a basic
      understanding of architectural design patterns. Design patterns
      are proven solutions to common development problems and can
      suggest structural approaches to help guide developers in adding
      some organization to their applications.
    </para>
    <para>
      Patterns are useful because they’re a set of practices that build
      upon the collective experience of skilled developers who have
      repeatedly solved similar problems. Although developers 10 or 20
      years ago may not have been using the same programming languages
      when implementing patterns in their projects, there are many
      lessons we can learn from their efforts.
    </para>
    <para>
      In this section, we’re going to review two popular patterns - MVC
      and MVP. We’ll be exploring in greater detail how Backbone.js
      implements these patterns shortly to better appreciate where it
      fits in.
    </para>
  </sect2>
</sect1>
<sect1 id="mvc">
  <title>MVC</title>
  <para>
    MVC (Model-View-Controller) is an architectural design pattern that
    encourages improved application organization through a separation of
    concerns. It enforces the isolation of business data (Models) from
    user interfaces (Views), with a third component (Controllers)
    traditionally present to manage logic, user-input and the
    coordination of models and views. The pattern was originally
    designed by
    <ulink url="http://en.wikipedia.org/wiki/Trygve_Reenskaug">Trygve
    Reenskaug</ulink> while working on Smalltalk-80 (1979), where it was
    initially called Model-View-Controller-Editor. MVC was described in
    depth in
    <ulink url="http://www.amazon.co.uk/Design-patterns-elements-reusable-object-oriented/dp/0201633612"><quote>Design
    Patterns: Elements of Reusable Object-Oriented
    Software</quote></ulink> (The <quote>GoF</quote> or <quote>Gang of
    Four</quote> book) in 1994, which played a role in popularizing its
    use.
  </para>
  <sect2 id="smalltalk-80-mvc">
    <title>Smalltalk-80 MVC</title>
    <para>
      It’s important to understand what the original MVC pattern was
      aiming to solve as it has changed quite heavily since the days of
      its origin. Back in the 70’s, graphical user-interfaces were far
      and few between. An approach known as
      <ulink url="http://martinfowler.com/eaaDev/uiArchs.html">Separated
      Presentation</ulink> began to be used as a means to make a clear
      division between domain objects which modeled concepts in the real
      world (e.g a photo, a person) and the presentation objects which
      were rendered to the user’s screen.
    </para>
    <para>
      The Smalltalk-80 implementation of MVC took this concept further
      and had an objective of separating out the application logic from
      the user interface. The idea was that decoupling these parts of
      the application would also allow the reuse of models for other
      interfaces in the application. There are some interesting points
      worth noting about Smalltalk-80’s MVC architecture:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          A Domain element was known as a Model and were ignorant of the
          user-interface (Views and Controllers)
        </para>
      </listitem>
      <listitem>
        <para>
          Presentation was taken care of by the View and the Controller,
          but there wasn’t just a single view and controller. A
          View-Controller pair was required for each element being
          displayed on the screen and so there was no true separation
          between them
        </para>
      </listitem>
      <listitem>
        <para>
          The Controller’s role in this pair was handling user input
          (such as key-presses and click events), doing something
          sensible with them.
        </para>
      </listitem>
      <listitem>
        <para>
          The Observer pattern was relied upon for updating the View
          whenever the Model changed
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Developers are sometimes surprised when they learn that the
      Observer pattern (nowadays commonly implemented as a
      Publish/Subscribe system) was included as a part of MVC’s
      architecture decades ago. In Smalltalk-80’s MVC, the View and
      Controller both observe the Model: anytime the Model changes, the
      Views react. A simple example of this is an application backed by
      stock market data - for the application to show real-time
      information, any change to the data in its Models should result in
      the View being refreshed instantly.
    </para>
    <para>
      Martin Fowler has done an excellent job of writing about the
      <ulink url="http://martinfowler.com/eaaDev/uiArchs.html">origins</ulink>
      of MVC over the years and if you are interested in further
      historical information about Smalltalk-80’s MVC, I recommend
      reading his work.
    </para>
  </sect2>
</sect1>
<sect1 id="mvc-as-we-know-it">
  <title>MVC As We Know It</title>
  <para>
    We’ve reviewed the 70’s, but let us now return to the here and now.
    The MVC pattern has been applied to a diverse range of programming
    languages. For example, the popular Ruby on Rails is an
    implementation of a web application framework based on MVC for the
    Ruby language. JavaScript now has a number of MVC frameworks,
    including Ember.js, JavaScriptMVC, and of course Backbone.js. Given
    the importance of avoiding <quote>spaghetti</quote> code, a term
    which describes code that is very difficult to read or maintain due
    to its lack of structure, let’s look at what the MVC pattern enables
    the Javascript developer to do.
  </para>
  <para>
    MVC is composed of three core components:
  </para>
  <sect2 id="models">
    <title>Models</title>
    <para>
      Models manage the data for an application. They are concerned with
      neither the user-interface nor presentation layers, but instead
      represent structured data that an application may require. When a
      model changes (e.g when it is updated), it will typically notify
      its observers (e.g views, a concept we will cover shortly) that a
      change has occurred so that they may react accordingly.
    </para>
    <para>
      To understand models better, let us imagine we have a JavaScript
      photo gallery application. In a photo gallery, a photo would merit
      its own model, as it represents a unique kind of domain-specific
      data. The Photo model may represent attributes such as a caption,
      image source and additional meta-data. A specific photo would be
      stored in an instance of a model. Here’s an example of a simple
      Photo model implemented with Backbone.js:
    </para>
    <programlisting language="javascript">
var Photo = Backbone.Model.extend({

    // Default attributes for the photo
    defaults: {
      // Ensure that each photo created has an `src`.
      src: &quot;placeholder.jpg&quot;,
      caption: &quot;A default image&quot;,
      viewed: false
    },

    initialize: function() {
    }

});
</programlisting>
    <para>
      The built-in capabilities of models vary across frameworks,
      however it’s common for them to support validation of attributes,
      where attributes represent the properties of the model, such as a
      model identifier. When using models in real-world applications we
      generally also need a way of persisting models. Persistence allows
      us to edit and update models with the knowledge that their most
      recent states will be saved somewhere, for example in a web
      browser’s localStorage data-store or synchronized with a database.
    </para>
    <para>
      A model may also have multiple views observing it. Imagine our
      Photo model contained meta-data such as the longitude and latitude
      where the photo was taken, a list of people present in the photo,
      and a list of tags. A developer could create a single view that
      displayed all these attributes, or might create three separate
      views to display each attribute. The important detail is that the
      Photo model doesn’t care how these views are organized, it simply
      announces updates to its data as necessary. We’ll come back to
      Views in more detail later.
    </para>
    <para>
      It is not uncommon for modern MVC/MV* frameworks to provide a
      means to group models together. In Backbone, these groups are
      called <quote>Collections</quote>. Managing models in groups
      allows us to write application logic based on notifications from
      the group, should any model it contains change. This avoids the
      need to manually observe individual model instances.
    </para>
    <para>
      Here’s how we might group Photo models into a simplified Backbone
      Collection:
    </para>
    <programlisting language="javascript">
var PhotoGallery = Backbone.Collection.extend({

    // Reference to this collection's model.
    model: Photo,

    // Filter down the list of all photos that have been viewed
    viewed: function() {
      return this.filter(function(photo){ return photo.get('viewed'); });
    },

    // Filter down the list to only photos that have not yet been viewed
    unviewed: function() {
      return this.without.apply(this, this.viewed());
    }

});
</programlisting>
    <para>
      If you read older texts on MVC, you may come across a description
      of models as also managing application <quote>state</quote>. In
      JavaScript applications <quote>state</quote> has a specific
      meaning, typically referring to the current <quote>state</quote>
      of a view or sub-view on a user’s screen at a fixed time. State is
      a topic which is regularly discussed when looking at Single-page
      applications, where the concept of state needs to be simulated.
    </para>
  </sect2>
  <sect2 id="views">
    <title>Views</title>
    <para>
      Views are a visual representation of models that present a
      filtered view of their current state. A view typically observes a
      model and is notified when the model changes, allowing the view to
      update itself accordingly. Design pattern literature commonly
      refers to views as <quote>dumb</quote>, given that their knowledge
      of models and controllers in an application is limited.
    </para>
    <para>
      Users interact with views, which usually means reading and editing
      model data. For example, in our photo gallery application example,
      model viewing might happen in a user interface with a big image, a
      caption, and a list of tags. Model editing could be done through
      an <quote>edit</quote> view where a user who has selected a
      specific photo could edit its caption, tags, or other metadata in
      a form.
    </para>
    <para>
      In MVC, the actual task of updating the Model falls to
      Controllers, which we’ll be covering shortly.
    </para>
    <para>
      Let’s explore Views a little further using a simple JavaScript
      example. Below we can see a function that creates a single Photo
      view, consuming both a model instance and a controller instance.
    </para>
    <para>
      We define a <literal>render()</literal> utility within our view
      which is responsible for rendering the contents of the
      <literal>photoModel</literal> using a JavaScript templating engine
      (Underscore templating) and updating the contents of our view,
      referenced by <literal>photoEl</literal>.
    </para>
    <para>
      The <literal>photoModel</literal> then adds our
      <literal>render()</literal> callback as one of its subscribers, so
      that through the Observer pattern it can trigger the view to
      update when the model changes.
    </para>
    <para>
      You may wonder where user interaction comes into play here. When
      users click on any elements within the view, it’s not the view’s
      responsibility to know what to do next. A Controller makes this
      decision. In our sample implementation, this is achieved by adding
      an event listener to <literal>photoEl</literal> which will
      delegate handling the click behavior back to the controller,
      passing the model information along with it in case it’s needed.
    </para>
    <para>
      The benefit of this architecture is that each component plays its
      own separate role in making the application function as needed.
    </para>
    <programlisting language="javascript">
var buildPhotoView = function( photoModel, photoController ){

    var base        = document.createElement('div'),
        photoEl     = document.createElement('div');

     base.appendChild(photoEl);

     var render= function(){
        // We use a templating library such as Underscore
        // templating which generates the HTML for our 
        // photo entry
        photoEl.innerHTML = _.template('photoTemplate', {src: photoModel.getSrc()});
     }

     photoModel.addSubscriber( render );

     photoEl.addEventListener('click', function(){
        photoController.handleEvent('click', photoModel );
     });

     var show = function(){
        photoEl.style.display  = '';
     }

     var hide = function(){
        photoEl.style.display  = 'none';
     }


     return{
        showView: show,
        hideView: hide
     }

}
</programlisting>
    <para>
      <emphasis role="strong">Templating</emphasis>
    </para>
    <para>
      In the context of JavaScript frameworks that support MVC/MV*, it
      is worth looking more closely at JavaScript templating and its
      relationship to Views.
    </para>
    <para>
      It has long been considered bad practice (and computationally
      expensive) to manually create large blocks of HTML markup
      in-memory through string concatenation. Developers using this
      technique often find themselves iterating through their data,
      wrapping it in nested divs and using outdated techniques such as
      <literal>document.write</literal> to inject the
      <quote>template</quote> into the DOM. This approach often means
      keeping scripted markup inline with standard markup, which can
      quickly become difficult to read and maintain, especially when
      building large applications.
    </para>
    <para>
      JavaScript templating libraries (such as Handlebars.js or
      Mustache) are often used to define templates for views as HTML
      markup containing template variables. These template blocks can be
      either stored externally or within script tags with a custom type
      (e.g <quote>text/template</quote>). Variables are deliminated
      using a variable syntax (e.g {{name}}). Javascript template
      libraries typically accept data in JSON, and the grunt work of
      populating templates with data is taken care of by the framework
      itself. This has a several benefits, particularly when opting to
      store templates externally as this can let applications load
      templates dynamically on an as-needed basis.
    </para>
    <para>
      Let’s compare two examples of HTML templates. One is implemented
      using the popular Handlebars.js library, and the other uses
      Underscore’s <quote>microtemplates</quote>.
    </para>
    <para>
      <emphasis role="strong">Handlebars.js:</emphasis>
    </para>
    <programlisting language="html">
&lt;li class=&quot;photo&quot;&gt;
  &lt;h2&gt;{{caption}}&lt;/h2&gt;
  &lt;img class=&quot;source&quot; src=&quot;{{src}}&quot;/&gt;
  &lt;div class=&quot;meta-data&quot;&gt; 
    {{metadata}}
  &lt;/div&gt;
&lt;/li&gt;
</programlisting>
    <para>
      <emphasis role="strong">Underscore.js Microtemplates:</emphasis>
    </para>
    <programlisting language="html">
&lt;li class=&quot;photo&quot;&gt;
  &lt;h2&gt;&lt;%= caption %&gt;&lt;/h2&gt;
  &lt;img class=&quot;source&quot; src=&quot;&lt;%= src %&gt;&quot;/&gt;
  &lt;div class=&quot;meta-data&quot;&gt; 
    &lt;%= metadata %&gt;
  &lt;/div&gt;
&lt;/li&gt;
</programlisting>
    <para>
      You may also use double curly brackets (i.e
      <literal>{{}}</literal>) (or any other tag you feel comfortable
      with) in Microtemplates. In the case of curly brackets, this can
      be done by setting the Underscore
      <literal>templateSettings</literal> attribute as follows:
    </para>
    <programlisting language="javascript">
_.templateSettings = { interpolate : /\{\{(.+?)\}\}/g };
</programlisting>
    <para>
      <emphasis role="strong">A note on navigation and state</emphasis>
    </para>
    <para>
      It is also worth noting that in classical web development,
      navigating between independent views required the use of a page
      refresh. In single-page JavaScript applications, however, once
      data is fetched from a server via Ajax, it can be dynamically
      rendered in a new view within the same page. Since this doesn’t
      automatically update the URL, the role of navigation thus falls to
      a <quote>router</quote>, which assists in managing application
      state (e.g allowing users to bookmark a particular view they have
      navigated to). As routers are however neither a part of MVC nor
      present in every MVC-like framework, I will not be going into them
      in greater detail in this section.
    </para>
  </sect2>
  <sect2 id="controllers">
    <title>Controllers</title>
    <para>
      Controllers are an intermediary between models and views which are
      classically responsible for two tasks: they both update the view
      when the model changes and update the model when the user
      manipulates the view.
    </para>
    <para>
      In our photo gallery application, a controller would be
      responsible for handling changes the user made to the edit view
      for a particular photo, updating a specific photo model when a
      user has finished editing.
    </para>
    <para>
      It’s with controllers that most JavaScript MVC frameworks depart
      from this interpretation of the MVC pattern. The reasons for this
      vary, but in my opinion, Javascript framework authors likely
      initially looked at server-side interpretations of MVC (such as
      Ruby on Rails), realized that that approach didn’t translate 1:1
      on the client-side, and so re-interpreted the C in MVC to solve
      their state management problem. This was a clever approach, but it
      can make it hard for developers coming to MVC for the first time
      to understand both the classical MVC pattern and the
      <quote>proper</quote> role of controllers in other non-Javascript
      frameworks.
    </para>
    <para>
      So does Backbone.js have Controllers? Not really. Backbone’s Views
      typically contain <quote>controller</quote> logic, and Routers
      (discussed below) are used to help manage application state, but
      neither are true Controllers according to classical MVC.
    </para>
    <para>
      In this respect, contrary to what might be mentioned in the
      official documentation or in blog posts, Backbone is neither a
      truly MVC/MVP nor MVVM framework. It’s in fact better to see it a
      member of the MV* family which approaches architecture in its own
      way. There is of course nothing wrong with this, but it is
      important to distinguish between classical MVC and MV* should you
      be relying on discussions of MVC to help with your Backbone
      projects.
    </para>
  </sect2>
  <sect2 id="controllers-in-spine.js-vs-backbone.js">
    <title>Controllers in Spine.js vs Backbone.js</title>
    <para>
      <emphasis role="strong">Spine.js</emphasis>
    </para>
    <para>
      We now know that controllers are traditionally responsible for
      updating the view when the model changes (and similarly the model
      when the user updates the view). Since Backbone doesn’t have its
      <emphasis role="strong">own</emphasis> explicit controllers, it’s
      useful to review the controller from another MVC framework to
      appreciate the difference in implementations. Let’s take a look at
      <ulink url="http://spinejs.com/">Spine.js</ulink>:
    </para>
    <para>
      In this example, we’re going to have a controller called
      <literal>PhotosController</literal> which will be in charge of
      individual photos in the application. It will ensure that when the
      view updates (e.g a user edited the photo meta-data) the
      corresponding model does too.
    </para>
    <para>
      (Note: We won’t be delving heavily into Spine.js beyond this
      example, but it’s worth looking at it to learn more about
      Javascript frameworks in general.)
    </para>
    <programlisting language="javascript">
// Controllers in Spine are created by inheriting from Spine.Controller

var PhotosController = Spine.Controller.sub({      
  init: function(){
    this.item.bind(&quot;update&quot;, this.proxy(this.render));
    this.item.bind(&quot;destroy&quot;, this.proxy(this.remove));
  },

  render: function(){
    // Handle templating
    this.replace($(&quot;#photoTemplate&quot;).tmpl(this.item));
    return this;
  },

  remove: function(){
    this.el.remove();
    this.release();
  }
});
</programlisting>
    <para>
      In Spine, controllers are considered the glue for an application,
      adding and responding to DOM events, rendering templates and
      ensuring that views and models are kept in sync (which makes sense
      in the context of what we know to be a controller).
    </para>
    <para>
      What we’re doing in the above example is setting up listeners in
      the <literal>update</literal> and <literal>destroy</literal>
      events using <literal>render()</literal> and
      <literal>remove()</literal>. When a photo entry gets updated, we
      re-render the view to reflect the changes to the meta-data.
      Similarly, if the photo gets deleted from the gallery, we remove
      it from the view. In case you were wondering about the
      <literal>tmpl()</literal> function in the code snippet: in the
      <literal>render()</literal> function, we’re using this to render a
      JavaScript template called #photoTemplate which simply returns a
      HTML string used to replace the controller’s current element.
    </para>
    <para>
      What this provides us with is a very lightweight, simple way to
      manage changes between the model and the view.
    </para>
    <para>
      <emphasis role="strong">Backbone.js</emphasis>
    </para>
    <para>
      Later on in this section we’re going to revisit the differences
      between Backbone and traditional MVC, but for now let’s focus on
      controllers.
    </para>
    <para>
      In Backbone, controller logic is shared between Backbone.View and
      Backbone.Router. Earlier releases of Backbone contained something
      called Backbone.Controller, but it was renamed to Router to
      clarify its role.
    </para>
    <para>
      A Router’s main purpose is to translate URL requests into
      application states. When a user browses to the URL
      www.example.com/photos/42, a Router could be used to show the
      photo with that ID, and to define what application behavior should
      be run in response to that request. Routers
      <emphasis>can</emphasis> contain traditional controller
      responsibilities, such as binding the events between models and
      views, or rendering parts of the page. However, Backbone
      contributor Tim Branyen has pointed out that it’s possible to get
      away without needing Backbone.Router at all for this, so a way to
      think about it using the Router paradigm is probably:
    </para>
    <programlisting language="javascript">
var PhotoRouter = Backbone.Router.extend({
  routes: { &quot;photos/:id&quot;: &quot;route&quot; },

  route: function(id) {
    var item = photoCollection.get(id);
    var view = new PhotoView({ model: item });

    something.html( view.render().el );
  }
}):
</programlisting>
  </sect2>
</sect1>
<sect1 id="what-does-mvc-give-us">
  <title>What does MVC give us?</title>
  <para>
    To summarize, the separation of concerns in MVC facilitates
    modularization of an application’s functionality and enables:
  </para>
  <itemizedlist>
    <listitem>
      <para>
        Easier overall maintenance. When updates need to be made to the
        application it is clear whether the changes are data-centric,
        meaning changes to models and possibly controllers, or merely
        visual, meaning changes to views.<literallayout></literallayout>
      </para>
    </listitem>
    <listitem>
      <para>
        Decoupling models and views means that it’s straight-forward to
        write unit tests for business
        logic<literallayout></literallayout>
      </para>
    </listitem>
    <listitem>
      <para>
        Duplication of low-level model and controller code is eliminated
        across the application
      </para>
    </listitem>
    <listitem>
      <para>
        Depending on the size of the application and separation of
        roles, this modularity allows developers responsible for core
        logic and developers working on the user-interfaces to work
        simultaneously
      </para>
    </listitem>
  </itemizedlist>
  <sect2 id="delving-deeper">
    <title>Delving deeper</title>
    <para>
      Right now, you likely have a basic understanding of what the MVC
      pattern provides, but for the curious, we’ll explore it a little
      further.
    </para>
    <para>
      The GoF (Gang of Four) do not refer to MVC as a design pattern,
      but rather consider it a <quote>set of classes to build a user
      interface</quote>. In their view, it’s actually a variation of
      three other classical design patterns: the Observer (Pub/Sub),
      Strategy and Composite patterns. Depending on how MVC has been
      implemented in a framework, it may also use the Factory and
      Decorator patterns. I’ve covered some of these patterns in my
      other free book, JavaScript Design Patterns For Beginners if you
      would like to read into them further.
    </para>
    <para>
      As we’ve discussed, models represent application data, while views
      handle what the user is presented on screen. As such, MVC relies
      on Pub/Sub for some of its core communication (something that
      surprisingly isn’t covered in many articles about the MVC
      pattern). When a model is changed it <quote>publishes</quote> to
      the rest of the application that it has been updated. The
      <quote>subscriber</quote>–generally a Controller–then updates the
      view accordingly. The observer-viewer nature of this relationship
      is what facilitates multiple views being attached to the same
      model.
    </para>
    <para>
      For developers interested in knowing more about the decoupled
      nature of MVC (once again, depending on the implementation), one
      of the goals of the pattern is to help define one-to-many
      relationships between a topic and its observers. When a topic
      changes, its observers are updated. Views and controllers have a
      slightly different relationship. Controllers facilitate views to
      respond to different user input and are an example of the Strategy
      pattern.
    </para>
  </sect2>
  <sect2 id="summary">
    <title>Summary</title>
    <para>
      Having reviewed the classical MVC pattern, your should now
      understand how it allows developers to cleanly separate concerns
      in an application. You should also now appreciate how JavaScript
      MVC frameworks may differ in their interpretation of MVC, and how
      they share some of the fundamental concepts of the original
      pattern.
    </para>
    <para>
      When reviewing a new JavaScript MVC/MV* framework, remember - it
      can be useful to step back and consider how it’s opted to approach
      Models, Views, Controllers or other alternatives, as this can
      better help you grok how the framework expects to be used.
    </para>
  </sect2>
</sect1>
<sect1 id="mvp">
  <title>MVP</title>
  <para>
    Model-view-presenter (MVP) is a derivative of the MVC design pattern
    which focuses on improving presentation logic. It originated at a
    company named
    <ulink url="http://en.wikipedia.org/wiki/Taligent">Taligent</ulink>
    in the early 1990s while they were working on a model for a C++
    CommonPoint environment. Whilst both MVC and MVP target the
    separation of concerns across multiple components, there are some
    fundamental differences between them.
  </para>
  <para>
    For the purposes of this summary we will focus on the version of MVP
    most suitable for web-based architectures.
  </para>
  <sect2 id="models-views-presenters">
    <title>Models, Views &amp; Presenters</title>
    <para>
      The P in MVP stands for presenter. It’s a component which contains
      the user-interface business logic for the view. Unlike MVC,
      invocations from the view are delegated to the presenter, which
      are decoupled from the view and instead talk to it through an
      interface. This allows for all kinds of useful things such as
      being able to mock views in unit tests.
    </para>
    <para>
      The most common implementation of MVP is one which uses a Passive
      View (a view which is for all intents and purposes
      <quote>dumb</quote>), containing little to no logic. MVP models
      are almost identical to MVC models and handle application data.
      The presenter acts as a mediator which talks to both the view and
      model, however both of these are isolated from each other. They
      effectively bind models to views, a responsibility held by
      Controllers in MVC. Presenters are at the heart of the MVP pattern
      and as you can guess, incorporate the presentation logic behind
      views.
    </para>
    <para>
      Solicited by a view, presenters perform any work to do with user
      requests and pass data back to them. In this respect, they
      retrieve data, manipulate it and determine how the data should be
      displayed in the view. In some implementations, the presenter also
      interacts with a service layer to persist data (models). Models
      may trigger events but it’s the presenter’s role to subscribe to
      them so that it can update the view. In this passive architecture,
      we have no concept of direct data binding. Views expose setters
      which presenters can use to set data.
    </para>
    <para>
      The benefit of this change from MVC is that it increases the
      testability of your application and provides a more clean
      separation between the view and the model. This isn’t however
      without its costs as the lack of data binding support in the
      pattern can often mean having to take care of this task
      separately.
    </para>
    <para>
      Although a common implementation of a
      <ulink url="http://martinfowler.com/eaaDev/PassiveScreen.html">Passive
      View</ulink> is for the view to implement an interface, there are
      variations on it, including the use of events which can decouple
      the View from the Presenter a little more. As we don’t have the
      interface construct in JavaScript, we’re using it more as more a
      protocol than an explicit interface here. It’s technically still
      an API and it’s probably fair for us to refer to it as an
      interface from that perspective.
    </para>
    <para>
      There is also a
      <ulink url="http://martinfowler.com/eaaDev/SupervisingPresenter.html">Supervising
      Controller</ulink> variation of MVP, which is closer to the MVC
      and
      <ulink url="http://en.wikipedia.org/wiki/Model_View_ViewModel">MVVM</ulink>
      patterns as it provides data-binding from the Model directly from
      the View. Key-value observing (KVO) plugins (such as Derick
      Bailey’s Backbone.ModelBinding plugin) introduce this idea of a
      Supervising Controller to Backbone.
    </para>
  </sect2>
</sect1>
<sect1 id="mvp-or-mvc">
  <title>MVP or MVC?</title>
  <para>
    MVP is generally used most often in enterprise-level applications
    where it’s necessary to reuse as much presentation logic as
    possible. Applications with very complex views and a great deal of
    user interaction may find that MVC doesn’t quite fit the bill here
    as solving this problem may mean heavily relying on multiple
    controllers. In MVP, all of this complex logic can be encapsulated
    in a presenter, which can simplify maintenance greatly.
  </para>
  <para>
    As MVP views are defined through an interface and the interface is
    technically the only point of contact between the system and the
    view (other than a presenter), this pattern also allows developers
    to write presentation logic without needing to wait for designers to
    produce layouts and graphics for the application.
  </para>
  <para>
    Depending on the implementation, MVP may be more easy to
    automatically unit test than MVC. The reason often cited for this is
    that the presenter can be used as a complete mock of the
    user-interface and so it can be unit tested independent of other
    components. In my experience this really depends on the languages
    you are implementing MVP in (there’s quite a difference between
    opting for MVP for a JavaScript project over one for say, ASP.net).
  </para>
  <para>
    At the end of the day, the underlying concerns you may have with MVC
    will likely hold true for MVP given that the differences between
    them are mainly semantic. As long as you are cleanly separating
    concerns into models, views and controllers (or presenters) you
    should be achieving most of the same benefits regardless of the
    pattern you opt for.
  </para>
</sect1>
<sect1 id="mvc-mvp-and-backbone.js">
  <title>MVC, MVP and Backbone.js</title>
  <para>
    There are very few, if any architectural JavaScript frameworks that
    claim to implement the MVC or MVP patterns in their classical form
    as many JavaScript developers don’t view MVC and MVP as being
    mutually exclusive (we are actually more likely to see MVP strictly
    implemented when looking at web frameworks such as ASP.net or GWT).
    This is because it’s possible to have additional presenter/view
    logic in your application and yet still consider it a flavor of MVC.
  </para>
  <para>
    Backbone contributor <ulink url="http://ireneros.com/">Irene
    Ros</ulink> subscribes to this way of thinking as when she separates
    Backbone views out into their own distinct components, she needs
    something to actually assemble them for her. This could either be a
    controller route (such as a <literal>Backbone.Router</literal>,
    covered later in the book) or a callback in response to data being
    fetched.
  </para>
  <para>
    That said, some developers do however feel that Backbone.js better
    fits the description of MVP than it does MVC . Their view is that:
  </para>
  <itemizedlist>
    <listitem>
      <para>
        The presenter in MVP better describes the
        <literal>Backbone.View</literal> (the layer between View
        templates and the data bound to it) than a controller does
      </para>
    </listitem>
    <listitem>
      <para>
        The model fits <literal>Backbone.Model</literal> (it isn’t that
        different from the classical MVC
        <quote>Model</quote>)<literallayout></literallayout>
      </para>
    </listitem>
    <listitem>
      <para>
        The views best represent templates (e.g Handlebars/Mustache
        markup templates)
      </para>
    </listitem>
  </itemizedlist>
  <para>
    A response to this could be that the view can also just be a View
    (as per MVC) because Backbone is flexible enough to let it be used
    for multiple purposes. The V in MVC and the P in MVP can both be
    accomplished by <literal>Backbone.View</literal> because they’re
    able to achieve two purposes: both rendering atomic components and
    assembling those components rendered by other views.
  </para>
  <para>
    We’ve also seen that in Backbone the responsibility of a controller
    is shared with both the Backbone.View and Backbone.Router and in the
    following example we can actually see that aspects of that are
    certainly true.
  </para>
  <para>
    Here, our Backbone <literal>PhotoView</literal> uses the Observer
    pattern to <quote>subscribe</quote> to changes to a View’s model in
    the line <literal>this.model.bind('change',...)</literal>. It also
    handles templating in the <literal>render()</literal> method, but
    unlike some other implementations, user interaction is also handled
    in the View (see <literal>events</literal>).
  </para>
  <programlisting language="javascript">
var PhotoView = Backbone.View.extend({

    //... is a list tag.
    tagName:  &quot;li&quot;,

    // Pass the contents of the photo template through a templating
    // function, cache it for a single photo
    template: _.template($('#photo-template').html()),

    // The DOM events specific to an item.
    events: {
      &quot;click img&quot; : &quot;toggleViewed&quot;
    },

    // The PhotoView listens for changes to its model, re-rendering. Since there's
    // a one-to-one correspondence between a **Photo** and a **PhotoView** in this
    // app, we set a direct reference on the model for convenience.

    initialize: function() {
      _.bindAll(this, 'render');
      this.model.bind('change', this.render);
      this.model.bind('destroy', this.remove);
    },

    // Re-render the photo entry
    render: function() {
      $(this.el).html(this.template(this.model.toJSON()));
      return this;
    },

    // Toggle the `&quot;viewed&quot;` state of the model.
    toggleViewed: function() {
      this.model.viewed();
    }

});
</programlisting>
  <para>
    Another (quite different) opinion is that Backbone more closely
    resembles
    <ulink url="http://martinfowler.com/eaaDev/uiArchs.html#ModelViewController">Smalltalk-80
    MVC</ulink>, which we went through earlier.
  </para>
  <para>
    As regular Backbone user Derick Bailey has
    <ulink url="http://lostechies.com/derickbailey/2011/12/23/backbone-js-is-not-an-mvc-framework/">written</ulink>,
    it’s ultimately best not to force Backbone to fit any specific
    design patterns. Design patterns should be considered flexible
    guides to how applications may be structured and in this respect,
    Backbone doesn’t fit either MVC nor MVP perfectly. Instead, it
    borrows some of the best concepts from multiple architectural
    patterns and creates a flexible framework that just works well. Call
    it <emphasis role="strong">the Backbone way</emphasis>, MV* or
    whatever helps reference its flavor of application architecture.
  </para>
  <para>
    It <emphasis>is</emphasis> however worth understanding where and why
    these concepts originated, so I hope that my explanations of MVC and
    MVP have been of help. Most structural JavaScript frameworks will
    adopt their own take on classical patterns, either intentionally or
    by accident, but the important thing is that they help us develop
    applications which are organized, clean and can be easily
    maintained.
  </para>
</sect1>
<sect1 id="fast-facts">
  <title>Fast facts</title>
  <sect2 id="backbone.js">
    <title>Backbone.js</title>
    <itemizedlist>
      <listitem>
        <para>
          Core components: Model, View, Collection, Router. Enforces its
          own flavor of MV*
        </para>
      </listitem>
      <listitem>
        <para>
          Good documentation, with more improvements on the way
        </para>
      </listitem>
      <listitem>
        <para>
          Used by large companies such as SoundCloud and Foursquare to
          build non-trivial applications
        </para>
      </listitem>
      <listitem>
        <para>
          Event-driven communication between views and models. As we’ll
          see, it’s relatively straight-forward to add event listeners
          to any attribute in a model, giving developers fine-grained
          control over what changes in the view
        </para>
      </listitem>
      <listitem>
        <para>
          Supports data bindings through manual events or a separate
          Key-value observing (KVO) library
        </para>
      </listitem>
      <listitem>
        <para>
          Great support for RESTful interfaces out of the box, so models
          can be easily tied to a backend
        </para>
      </listitem>
      <listitem>
        <para>
          Extensive eventing system. It’s
          <ulink url="http://lostechies.com/derickbailey/2011/07/19/references-routing-and-the-event-aggregator-coordinating-views-in-backbone-js/">trivial</ulink>
          to add support for pub/sub in Backbone
        </para>
      </listitem>
      <listitem>
        <para>
          Prototypes are instantiated with the <literal>new</literal>
          keyword, which some developers prefer
        </para>
      </listitem>
      <listitem>
        <para>
          Agnostic about templating frameworks, however Underscore’s
          micro-templating is available by default. Backbone works well
          with libraries like Handlebars
        </para>
      </listitem>
      <listitem>
        <para>
          Doesn’t support deeply nested models, though there are
          Backbone plugins such as
          <ulink url="https://github.com/PaulUithol/Backbone-relational">this</ulink>
          which can help<literallayout></literallayout>
        </para>
      </listitem>
      <listitem>
        <para>
          Clear and flexible conventions for structuring applications.
          Backbone doesn’t force usage of all of its components and can
          work with only those needed.
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
</sect1>
<sect1 id="the-basics">
  <title>## <a name="thebasics">The Basics</a></title>
  <sect2 id="what-is-backbone">
    <title>What is Backbone?</title>
    <para>
      Backbone.js is one of a number of JavaScript frameworks for
      creating MVC-like web applications. On the front-end, it’s my
      architectural framework of choice as it’s both mature, relatively
      lightweight and can be easily tested using third-party toolkits
      such as Jasmine or QUnit. Other MVC frameworks you may be familiar
      with include Ember.js (SproutCore 2.0), Spine, YUILibrary and
      JavaScriptMVC.
    </para>
    <para>
      Backbone is maintained by a number of contributors, most notably:
      Jeremy Ashkenas, creator of CoffeeScript, Docco and Underscore.js.
      As Jeremy is a believer in detailed documentation, there’s a level
      of comfort in knowing you’re unlikely to run into issues which are
      either not explained in the official docs or which can’t be nailed
      down with some assistance from the #documentcloud IRC channel. I
      strongly recommend using the latter if you find yourself getting
      stuck.
    </para>
  </sect2>
  <sect2 id="why-should-you-consider-using-it">
    <title>Why should you consider using it?</title>
    <para>
      Backbone’s main benefits, regardless of your target platform or
      device, include helping:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Organize the structure to your application
        </para>
      </listitem>
      <listitem>
        <para>
          Simplify server-side persistence
        </para>
      </listitem>
      <listitem>
        <para>
          Decouple the DOM from your page’s data
        </para>
      </listitem>
      <listitem>
        <para>
          Model data, views and routers in a succinct manner
        </para>
      </listitem>
      <listitem>
        <para>
          Provide DOM, model and collection synchronization
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
</sect1>
<sect1 id="the-basics-1">
  <title>The Basics</title>
  <para>
    In this section, you’ll learn the essentials of Backbone’s models,
    views, collections and routers, as well as about using namespacing
    to organize your code. This isn’t meant as a replacement for the
    official documentation, but it will help you understand many of the
    core concepts behind Backbone before you start building applications
    with it.
  </para>
  <itemizedlist>
    <listitem>
      <para>
        Models
      </para>
    </listitem>
    <listitem>
      <para>
        Collections
      </para>
    </listitem>
    <listitem>
      <para>
        Routers
      </para>
    </listitem>
    <listitem>
      <para>
        Views
      </para>
    </listitem>
    <listitem>
      <para>
        Namespacing
      </para>
    </listitem>
  </itemizedlist>
  <sect2 id="models-1">
    <title><a name="models">Models</a></title>
    <para>
      Backbone models contain interactive data for an application as
      well as the logic around this data. For example, we can use a
      model to represent the concept of a photo object including its
      attributes like tags, titles and a location.
    </para>
    <para>
      Models can be created by extending
      <literal>Backbone.Model</literal> as follows:
    </para>
    <programlisting language="javascript">
var Photo = Backbone.Model.extend({
    defaults: {
        src: 'placeholder.jpg',
        title: 'an image placeholder',
        coordinates: [0,0]
    },
    initialize: function(){
        this.bind(&quot;change:src&quot;, function(){
            var src = this.get(&quot;src&quot;); 
            console.log('Image source updated to ' + src);
        });
    },
    changeSrc: function( source ){
        this.set({ src: source });
    }
});

var somePhoto = new Photo({ src: &quot;test.jpg&quot;, title:&quot;testing&quot;});
somePhoto.changeSrc(&quot;magic.jpg&quot;); // which triggers &quot;change:src&quot; and logs an update message to the console.
</programlisting>
    <sect3 id="initialization">
      <title>Initialization</title>
      <para>
        The <literal>initialize()</literal> method is called when a new
        instance of a model is created. Its use is optional, however
        you’ll see why it’s good practice to use it below.
      </para>
      <programlisting language="javascript">
var Photo = Backbone.Model.extend({
    initialize: function(){
        console.log('this model has been initialized');
    }
});

// We can then create our own instance of a photo as follows:
var myPhoto = new Photo();
</programlisting>
    </sect3>
    <sect3 id="getters-setters">
      <title>Getters &amp; Setters</title>
      <para>
        <emphasis role="strong">Model.get()</emphasis>
      </para>
      <para>
        <literal>Model.get()</literal> provides easy access to a model’s
        attributes. Attributes which are passed through to the model on
        instantiation are instantly available for retrieval.
      </para>
      <programlisting language="javascript">
var myPhoto = new Photo({ title: &quot;My awesome photo&quot;, 
                          src:&quot;boston.jpg&quot;, 
                          location: &quot;Boston&quot;, 
                          tags:['the big game', 'vacation']}),

    title = myPhoto.get(&quot;title&quot;), //My awesome photo
    location = myPhoto.get(&quot;location&quot;), //Boston
    tags = myPhoto.get(&quot;tags&quot;), // ['the big game','vacation']
    photoSrc = myPhoto.get(&quot;src&quot;); //boston.jpg
</programlisting>
      <para>
        Alternatively, if you wish to directly access all of the
        attributes in a model’s instance directly, you can achieve this
        as follows:
      </para>
      <programlisting language="javascript">
var myAttributes = myPhoto.attributes;
console.log(myAttributes);
</programlisting>
      <para>
        It is best practice to use <literal>Model.set()</literal> or
        direct instantiation to set the values of a model’s attributes.
      </para>
      <para>
        Accessing <literal>Model.attributes</literal> directly is
        generally discouraged. Instead, should you need to read or clone
        data, <literal>Model.toJSON()</literal> is recommended for this
        purpose. If you would like to access or copy a model’s
        attributes for purposes such as JSON stringification (e.g. for
        serialization prior to being passed to a view), this can be
        achieved using <literal>Model.toJSON()</literal>:
      </para>
      <programlisting language="javascript">
var myAttributes = myPhoto.toJSON();
console.log(myAttributes);
/* this returns { title: &quot;My awesome photo&quot;, 
             src:&quot;boston.jpg&quot;, 
             location: &quot;Boston&quot;, 
             tags:['the big game', 'vacation']}*/
</programlisting>
    </sect3>
    <sect3 id="model.set">
      <title>Model.set()</title>
      <para>
        <literal>Model.set()</literal> allows us to pass attributes into
        an instance of our model. Attributes can either be set during
        initialization or at any time afterwards. It’s important to
        avoid trying to set a Model’s attributes directly (for example
        Model.caption = <quote>A new caption</quote>). Backbone uses
        Model.set() to know when to broadcast that a model’s data has
        changed.
      </para>
      <programlisting language="javascript">
var Photo = Backbone.Model.extend({
    initialize: function(){
        console.log('this model has been initialized');
    }
});

// Setting the value of attributes via instantiation
var myPhoto = new Photo({ title: 'My awesome photo', location: 'Boston' });

var myPhoto2 = new Photo();

// Setting the value of attributes through Model.set()
myPhoto2.set({ title:'Vacation in Florida', location: 'Florida' });
</programlisting>
      <para>
        <emphasis role="strong">Default values</emphasis>
      </para>
      <para>
        There are times when you want your model to have a set of
        default values (e.g. in a scenario where a complete set of data
        isn’t provided by the user). This can be set using a property
        called <literal>defaults</literal> in your model.
      </para>
      <programlisting language="javascript">
var Photo = Backbone.Model.extend({
    defaults:{
        title: 'Another photo!',
        tags:  ['untagged'],
        location: 'home',
        src: 'placeholder.jpg'
    },
    initialize: function(){
    }
});

var myPhoto = new Photo({ location: &quot;Boston&quot;, 
                          tags:['the big game', 'vacation']}),
    title   = myPhoto.get(&quot;title&quot;), //Another photo!
    location = myPhoto.get(&quot;location&quot;), //Boston
    tags = myPhoto.get(&quot;tags&quot;), // ['the big game','vacation']
    photoSrc = myPhoto.get(&quot;src&quot;); //placeholder.jpg
</programlisting>
      <para>
        <emphasis role="strong">Listening for changes to your
        model</emphasis>
      </para>
      <para>
        Any and all of the attributes in a Backbone model can have
        listeners bound to them which detect when their values change.
        Listeners can be added to the <literal>initialize()</literal>
        function:
      </para>
      <programlisting language="javascript">
this.bind('change', function(){
    console.log('values for this model have changed');
});
</programlisting>
      <para>
        In the following example, we log a message whenever a specific
        attribute (the title of our Photo model) is altered.
      </para>
      <programlisting language="javascript">
var Photo = Backbone.Model.extend({
    defaults:{
        title: 'Another photo!',
        tags:  ['untagged'],
        location: 'home',
        src: 'placeholder.jpg'
    },
    initialize: function(){
        console.log('this model has been initialized');
        this.bind(&quot;change:title&quot;, function(){
            var title = this.get(&quot;title&quot;);
            console.log(&quot;My title has been changed to.. &quot; + title);
        });
    },

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

var myPhoto = new Photo({ title:&quot;Fishing at the lake&quot;, src:&quot;fishing.jpg&quot;});
myPhoto.setTitle('Fishing at sea'); 
//logs 'My title has been changed to.. Fishing at sea'
</programlisting>
      <para>
        <emphasis role="strong">Validation</emphasis>
      </para>
      <para>
        Backbone supports model validation through
        <literal>Model.validate()</literal>, which allows checking the
        attribute values for a model prior to them being set.
      </para>
      <para>
        Validation functions can be as simple or complex as necessary.
        If the attributes provided are valid, nothing should be returned
        from <literal>.validate()</literal>. If they are invalid, a
        custom error can be returned instead.
      </para>
      <para>
        A basic example for validation can be seen below:
      </para>
      <programlisting language="javascript">
var Photo = Backbone.Model.extend({
    validate: function(attribs){
        if(attribs.src === undefined){
            return &quot;Remember to set a source for your image!&quot;;
        }
    },

    initialize: function(){
        console.log('this model has been initialized');
        this.bind(&quot;error&quot;, function(model, error){
            console.log(error);
        });
    }
});

var myPhoto = new Photo();
myPhoto.set({ title: &quot;On the beach&quot; });
//logs Remember to set a source for your image!
</programlisting>
    </sect3>
  </sect2>
  <sect2 id="views-1">
    <title><a name="views">Views</a></title>
    <para>
      Views in Backbone don’t contain the markup for your application,
      but rather they are there to support models by defining the logic
      for how they should be represented to the user. This is usually
      achieved using JavaScript templating (e.g. Mustache, jQuery-tmpl,
      etc.). A view’s <literal>render()</literal> function can be bound
      to a model’s <literal>change()</literal> event, allowing the view
      to always be up to date without requiring a full page refresh.
    </para>
    <sect3 id="creating-new-views">
      <title>Creating new views</title>
      <para>
        Similar to the previous sections, creating a new view is
        relatively straight-forward. To create a new View, simply extend
        <literal>Backbone.View</literal>. I’ll explain this code in
        detail below:
      </para>
      <programlisting language="javascript">
var PhotoSearch = Backbone.View.extend({
    el: $('#results'),
    render: function( event ){
        var compiled_template = _.template( $(&quot;#results-template&quot;).html() );
        this.el.html( compiled_template(this.model.toJSON()) );
        return this; //recommended as this enables calls to be chained.
    },
    events: {
        &quot;submit #searchForm&quot;:  &quot;search&quot;,
        &quot;click .reset&quot;: &quot;reset&quot;,
        &quot;click .advanced&quot;: &quot;switchContext&quot;
    },
    search: function( event ){
        //executed when a form '#searchForm' has been submitted
    },
    reset: function( event ){
        //executed when an element with class &quot;reset&quot; has been clicked.
    },
    switchContext: function( event ){
        //executed when an element with class &quot;advanced&quot; has been clicked.
    }
});
</programlisting>
    </sect3>
    <sect3 id="what-is-el">
      <title>What is <literal>el</literal>?</title>
      <para>
        <literal>el</literal> is basically a reference to a DOM element
        and all views must have one. It allows for all of the contents
        of a view to be inserted into the DOM at once, which makes for
        faster rendering as browser performs the minimum required
        reflows and repaints.
      </para>
      <para>
        There are two ways to attach a DOM element to a view: the
        element already exists in the page or a new element is created
        for the view and added manually by the developer. If the element
        already exists in the page, you can set <literal>el</literal> as
        either a CSS selector that matches the element or a simple
        reference to the DOM element.
      </para>
      <programlisting language="javascript">
el: '#footer', 
// OR
el: document.getElementById( 'footer' )
</programlisting>
      <para>
        If you want to create a new element for you view, set any
        combination of the following view’s properties:
        <literal>tagName</literal>, <literal>id</literal> and
        <literal>className</literal>. A new element will be created for
        you by the framework and a reference to it will be available at
        the <literal>el</literal> property.
      </para>
      <programlisting>
tagName: 'p', // required, but defaults to 'div' if not set
className: 'container', // optional, you can assign multiple classes to this property like so 'container homepage'
id: 'header', // optional
</programlisting>
      <para>
        The above code creates the <literal>DOMElement</literal> below
        but doesn’t append it to the DOM.
      </para>
      <programlisting>
&lt;p id=&quot;header&quot; class=&quot;container&quot;&gt;&lt;/p&gt;
</programlisting>
      <para>
        <emphasis role="strong">Understanding
        <literal>render()</literal></emphasis>
      </para>
      <para>
        <literal>render()</literal> is an optional function that defines
        the logic for rendering a template. We’ll use Underscore’s
        micro-templating in these examples, but remember you can use
        other templating frameworks if you prefer.
      </para>
      <para>
        The <literal>_.template</literal> method in Underscore compiles
        JavaScript templates into functions which can be evaluated for
        rendering. In the above view, I’m passing the markup from a
        template with id <literal>results-template</literal> to
        <literal>_.template()</literal> to be compiled. Next, I set the
        html of the <literal>el</literal> DOM element to the output of
        processing a JSON version of the model associated with the view
        through the compiled template.
      </para>
      <para>
        Presto! This populates the template, giving you a data-complete
        set of markup in just a few short lines of code.
      </para>
      <para>
        <emphasis role="strong">The <literal>events</literal>
        attribute</emphasis>
      </para>
      <para>
        The Backbone <literal>events</literal> attribute allows us to
        attach event listeners to either custom selectors, or directly
        to <literal>el</literal> if no selector is provided. An event
        takes the form
        <literal>{&quot;eventName selector&quot;: &quot;callbackFunction&quot;}</literal>
        and a number of event-types are supported, including
        <literal>click</literal>, <literal>submit</literal>,
        <literal>mouseover</literal>, <literal>dblclick</literal> and
        more.
      </para>
      <para>
        What isn’t instantly obvious is that under the bonnet, Backbone
        uses jQuery’s <literal>.delegate()</literal> to provide instant
        support for event delegation but goes a little further,
        extending it so that <literal>this</literal> always refers to
        the current view object. The only thing to really keep in mind
        is that any string callback supplied to the events attribute
        must have a corresponding function with the same name within the
        scope of your view.
      </para>
    </sect3>
  </sect2>
  <sect2 id="collections">
    <title><a name="collections">Collections</a></title>
    <para>
      Collections are sets of Models and are created by extending
      <literal>Backbone.Collection</literal>.
    </para>
    <para>
      Normally, when creating a collection you’ll also want to pass
      through a property specifying the model that your collection will
      contain, as well as any instance properties required.
    </para>
    <para>
      In the following example, we create a PhotoCollection that will
      contain our Photo models:
    </para>
    <programlisting language="javascript">
var PhotoCollection = Backbone.Collection.extend({
    model: Photo
});
</programlisting>
    <para>
      <emphasis role="strong">Getters and Setters</emphasis>
    </para>
    <para>
      There are a few different ways to retrieve a model from a
      collection. The most straight-forward is to use
      <literal>Collection.get()</literal> which accepts a single id as
      follows:
    </para>
    <programlisting language="javascript">
var skiingEpicness = PhotoCollection.get(2);
</programlisting>
    <para>
      Sometimes you may also want to get a model based on its client id.
      The client id is a property that Backbone automatically assigns
      models that have not yet been saved. You can get a model’s client
      id from its <literal>.cid</literal> property.
    </para>
    <programlisting language="javascript">
var mySkiingCrash = PhotoCollection.getByCid(456);
</programlisting>
    <para>
      Backbone Collections don’t have setters as such, but do support
      adding new models via <literal>.add()</literal> and removing
      models via <literal>.remove()</literal>.
    </para>
    <programlisting language="javascript">
var a = new Backbone.Model({ title: 'my vacation'}),
    b = new Backbone.Model({ title: 'my holiday'});

var photoCollection = new PhotoCollection([a,b]);
photoCollection.remove([a,b]);
</programlisting>
    <para>
      <emphasis role="strong">Listening for events</emphasis>
    </para>
    <para>
      As collections represent a group of items, we’re also able to
      listen for <literal>add</literal> and <literal>remove</literal>
      events for when new models are added or removed from the
      collection. Here’s an example:
    </para>
    <programlisting language="javascript">
var PhotoCollection = new Backbone.Collection();
PhotoCollection.bind(&quot;add&quot;, function(photo) {
  console.log(&quot;I liked &quot; + photo.get(&quot;title&quot;) + ' its this one, right? '  + photo.get(&quot;src&quot;));
});

PhotoCollection.add([
  {title: &quot;My trip to Bali&quot;, src: &quot;bali-trip.jpg&quot;},
  {title: &quot;The flight home&quot;, src: &quot;long-flight-oofta.jpg&quot;},
  {title: &quot;Uploading pix&quot;, src: &quot;too-many-pics.jpg&quot;}
]);
</programlisting>
    <para>
      In addition, we’re able to bind a <literal>change</literal> event
      to listen for changes to models in the collection.
    </para>
    <programlisting language="javascript">
PhotoCollection.bind(&quot;change:title&quot;, function(){
    console.log('there have been updates made to this collections titles');    
});
</programlisting>
    <para>
      <emphasis role="strong">Fetching models from the server</emphasis>
    </para>
    <para>
      <literal>Collections.fetch()</literal> retrieves a default set of
      models from the server in the form of a JSON array. When this data
      returns, the current collection’s contents will be replaced with
      the contents of the array.
    </para>
    <programlisting language="javascript">
var PhotoCollection = new Backbone.Collection;
PhotoCollection.url = '/photos';
PhotoCollection.fetch();
</programlisting>
    <para>
      Under the covers, <literal>Backbone.sync</literal> is the function
      called every time Backbone tries to read or save models to the
      server. It uses jQuery or Zepto’s ajax implementations to make
      these RESTful requests, however this can be overridden as per your
      needs.
    </para>
    <para>
      In the above example if we wanted to log an event when
      <literal>.sync()</literal> was called, we could do this:
    </para>
    <programlisting language="javascript">
Backbone.sync = function(method, model) {
  console.log(&quot;I've been passed &quot; + method + &quot; with &quot; + JSON.stringify(model));
};
</programlisting>
    <para>
      <emphasis role="strong">Resetting/Refreshing
      Collections</emphasis>
    </para>
    <para>
      Rather than adding or removing models individually, you might
      occasionally wish to update an entire collection at once.
      <literal>Collection.reset()</literal> allows us to replace an
      entire collection with new models as follows:
    </para>
    <programlisting language="javascript">
PhotoCollection.reset([
  {title: &quot;My trip to Scotland&quot;, src: &quot;scotland-trip.jpg&quot;},
  {title: &quot;The flight from Scotland&quot;, src: &quot;long-flight.jpg&quot;},
  {title: &quot;Latest snap of lock-ness&quot;, src: &quot;lockness.jpg&quot;}]);
</programlisting>
  </sect2>
  <sect2 id="underscore-utility-functions">
    <title>Underscore utility functions</title>
    <para>
      As Backbone requires Underscore as a hard dependency, we’re able
      to use many of the utilities it has to offer to aid with our
      application development. Here’s an example of how Underscore’s
      <literal>sortBy()</literal> method can be used to sort a
      collection of photos based on a particular attribute.
    </para>
    <programlisting language="javascript">
var sortedByAlphabet = PhotoCollection.sortBy(function (photo) {
    return photo.get(&quot;title&quot;).toLowerCase();
});
</programlisting>
    <para>
      The complete list of what Underscore can do is beyond the scope of
      this guide, but can be found in its official
      <ulink url="http://documentcloud.github.com/underscore/">docs</ulink>.
    </para>
  </sect2>
  <sect2 id="routers">
    <title><a name="routers">Routers</a></title>
    <para>
      In Backbone, routers are used to help manage application state and
      for connecting URLs to application events. This is achieved using
      hash-tags with URL fragments, or using the browser’s pushState and
      History API. Some examples of routes may be seen below:
    </para>
    <programlisting language="javascript">
http://unicorns.com/#whatsup
http://unicorns.com/#search/seasonal-horns/page2
</programlisting>
    <para>
      Note: An application will usually have at least one route mapping
      a URL route to a function that determines what happens when a user
      reaches that particular route. This relationship is defined as
      follows:
    </para>
    <programlisting language="javascript">
&quot;route&quot; : &quot;mappedFunction&quot;
</programlisting>
    <para>
      Let us now define our first controller by extending
      <literal>Backbone.Router</literal>. For the purposes of this
      guide, we’re going to continue pretending we’re creating a photo
      gallery application that requires a GalleryRouter.
    </para>
    <para>
      Note the inline comments in the code example below as they
      continue the rest of the lesson on routers.
    </para>
    <programlisting language="javascript">
var GalleryRouter = Backbone.Router.extend({
    /* define the route and function maps for this router */
    routes: {
        &quot;about&quot; : &quot;showAbout&quot;,
        /*Sample usage: http://unicorns.com/#about*/

        &quot;photos/:id&quot; : &quot;getPhoto&quot;,
        /*This is an example of using a &quot;:param&quot; variable which allows us to match 
        any of the components between two URL slashes*/
        /*Sample usage: http://unicorns.com/#photos/5*/

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

        &quot;search/:query/p:page&quot; : &quot;searchPhotos&quot;,
        /*As we can see, URLs may contain as many &quot;:param&quot;s as we wish*/
        /*Sample usage: http://unicorns.com/#search/lolcats/p1*/

        &quot;photos/:id/download/*imagePath&quot; : &quot;downloadPhoto&quot;,
        /*This is an example of using a *splat. splats are able to match any number of 
        URL components and can be combined with &quot;:param&quot;s*/
        /*Sample usage: http://unicorns.com/#photos/5/download/files/lolcat-car.jpg*/

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

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

    },

    showAbout: function(){
    },

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

    searchPhotos: function(query, page){
        console.log(&quot;Page number: &quot; + page + &quot; of the results for &quot; + query);
    },

    downloadPhoto: function(id, path){
    },

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

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

var myGalleryRouter = new GalleryRouter();
</programlisting>
    <para>
      As of Backbone 0.5+, it’s possible to opt-in for HTML5 pushState
      support via <literal>window.history.pushState</literal>. This
      permits you to define routes such as
      http://www.scriptjunkie.com/just/an/example. This will be
      supported with automatic degradation when a user’s browser doesn’t
      support pushState. For the purposes of this tutorial, we’ll use
      the hashtag method.
    </para>
    <sect3 id="backbone.history">
      <title>Backbone.history</title>
      <para>
        Next, we need to initialize <literal>Backbone.history</literal>
        as it handles <literal>hashchange</literal> events in our
        application. This will automatically handle routes that have
        been defined and trigger callbacks when they’ve been accessed.
      </para>
      <para>
        The <literal>Backbone.history.start()</literal> method will
        simply tell Backbone that it’s OK to begin monitoring all
        <literal>hashchange</literal> events as follows:
      </para>
      <programlisting language="javascript">
Backbone.history.start();
Router.navigate();
</programlisting>
      <para>
        As an aside, if you would like to save application state to the
        URL at a particular point you can use the
        <literal>.navigate()</literal> method to achieve this. It simply
        updates your URL fragment without the need to trigger the
        <literal>hashchange</literal> event:
      </para>
      <programlisting language="javascript">
/*Lets imagine we would like a specific fragment for when a user zooms into a photo*/
zoomPhoto: function(factor){
    this.zoom(factor); //imagine this zooms into the image
    this.navigate(&quot;zoom/&quot; + factor); //updates the fragment for us, but doesn't trigger the route
}
</programlisting>
      <para>
        It is also possible for <literal>Router.navigate()</literal> to
        trigger the route as well as updating the URL fragment.
      </para>
      <programlisting language="javascript">
zoomPhoto: function(factor){
    this.zoom(factor); //imagine this zooms into the image
    this.navigate(&quot;zoom/&quot; + factor, true); //updates the fragment for us and triggers the route
}
</programlisting>
    </sect3>
  </sect2>
  <sect2 id="namespacing">
    <title><a name="namespacing">Namespacing</a></title>
    <para>
      When learning how to use Backbone, an important and commonly
      overlooked area by tutorials is namespacing. If you already have
      experience with namespacing in JavaScript, the following section
      will provide some advice on how to specifically apply concepts you
      know to Backbone, however I will also be covering explanations for
      beginners to ensure everyone is on the same page.
    </para>
    <sect3 id="what-is-namespacing">
      <title>What is namespacing?</title>
      <para>
        The basic idea around namespacing is to avoid collisions with
        other objects or variables in the global namespace. They’re
        important as it’s best to safeguard your code from breaking in
        the event of another script on the page using the same variable
        names as you are. As a good <quote>citizen</quote> of the global
        namespace, it’s also imperative that you do your best to
        similarly not prevent other developer’s scripts executing due to
        the same issues.
      </para>
      <para>
        JavaScript doesn’t really have built-in support for namespaces
        like other languages, however it does have closures which can be
        used to achieve a similar effect.
      </para>
      <para>
        In this section we’ll be taking a look shortly at some examples
        of how you can namespace your models, views, routers and other
        components specifically. The patterns we’ll be examining are:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            Single global variables
          </para>
        </listitem>
        <listitem>
          <para>
            Object Literals
          </para>
        </listitem>
        <listitem>
          <para>
            Nested namespacing
          </para>
        </listitem>
      </itemizedlist>
      <para>
        <emphasis role="strong">Single global variables</emphasis>
      </para>
      <para>
        One popular pattern for namespacing in JavaScript is opting for
        a single global variable as your primary object of reference. A
        skeleton implementation of this where we return an object with
        functions and properties can be found below:
      </para>
      <programlisting language="javascript">
var myApplication = (function(){
    function(){
      // ...
    },
    return {
      // ...
    }
})();
</programlisting>
      <para>
        You’ve probably seen this technique before. A Backbone-specific
        example might look like this:
      </para>
      <programlisting language="javascript">
var myViews = (function(){
    return {
        PhotoView: Backbone.View.extend({ .. }),
        GalleryView: Backbone.View.extend({ .. }),
        AboutView: Backbone.View.extend({ .. });
        //etc.
    };
})();
</programlisting>
      <para>
        Here we can return a set of views, but the same technique could
        return an entire collection of models, views and routers
        depending on how you decide to structure your application.
        Although this works for certain situations, the biggest
        challenge with the single global variable pattern is ensuring
        that no one else has used the same global variable name as you
        have in the page.
      </para>
      <para>
        One solution to this problem, as mentioned by Peter Michaux, is
        to use prefix namespacing. It’s a simple concept at heart, but
        the idea is you select a common prefix name (in this example,
        <literal>myApplication_</literal>) and then define any methods,
        variables or other objects after the prefix.
      </para>
      <programlisting language="javascript">
var myApplication_photoView = Backbone.View.extend({}),
myApplication_galleryView = Backbone.View.extend({});
</programlisting>
      <para>
        This is effective from the perspective of trying to lower the
        chances of a particular variable existing in the global scope,
        but remember that a uniquely named object can have the same
        effect. This aside, the biggest issue with the pattern is that
        it can result in a large number of global objects once your
        application starts to grow.
      </para>
      <para>
        For more on Peter’s views about the single global variable
        pattern, read his
        <ulink url="http://michaux.ca/articles/javascript-namespacing">excellent
        post on them</ulink>.
      </para>
      <para>
        Note: There are several other variations on the single global
        variable pattern out in the wild, however having reviewed quite
        a few, I felt the prefixing approach applied best to Backbone.
      </para>
      <para>
        <emphasis role="strong">Object Literals</emphasis>
      </para>
      <para>
        Object Literals have the advantage of not polluting the global
        namespace but assist in organizing code and parameters
        logically. They’re beneficial if you wish to create easily
        readable structures that can be expanded to support deep
        nesting. Unlike simple global variables, Object Literals often
        also take into account tests for the existence of a variable by
        the same name, which helps reduce the chances of collision.
      </para>
      <para>
        This example demonstrates two ways you can check to see if a
        namespace already exists before defining it. I commonly use
        Option 2.
      </para>
      <programlisting language="javascript">
/*Doesn't check for existence of myApplication*/
var myApplication = {};

/*
Does check for existence. If already defined, we use that instance.
Option 1:   if(!myApplication) myApplication = {};
Option 2:   var myApplication = myApplication || {};
We can then populate our object literal to support models, views and collections (or any data, really):
*/

var myApplication = {
    models : {},
    views : {
        pages : {}
    },
    collections : {}
};
</programlisting>
      <para>
        One can also opt for adding properties directly to the namespace
        (such as your views, in the following example):
      </para>
      <programlisting language="javascript">
var myGalleryViews = myGalleryViews || {};
myGalleryViews.photoView = Backbone.View.extend({});
myGalleryViews.galleryView = Backbone.View.extend({});
</programlisting>
      <para>
        The benefit of this pattern is that you’re able to easily
        encapsulate all of your models, views, routers etc. in a way
        that clearly separates them and provides a solid foundation for
        extending your code.
      </para>
      <para>
        This pattern has a number of benefits. It’s often a good idea to
        decouple the default configuration for your application into a
        single area that can be easily modified without the need to
        search through your entire codebase just to alter it. Here’s an
        example of a hypothetical object literal that stores application
        configuration settings:
      </para>
      <programlisting language="javascript">
var myConfig = {
    language: 'english',
    defaults: {
        enableGeolocation: true,
        enableSharing: false,
        maxPhotos: 20
    },
    theme: {
        skin: 'a',
        toolbars: {
            index: 'ui-navigation-toolbar',
            pages: 'ui-custom-toolbar'    
        }
    }
}
</programlisting>
      <para>
        Note that there are really only minor syntactical differences
        between the Object Literal pattern and a standard JSON data set.
        If for any reason you wish to use JSON for storing your
        configurations instead (e.g. for simpler storage when sending to
        the back-end), feel free to.
      </para>
      <para>
        For more on the Object Literal pattern, I recommend reading
        Rebecca Murphey’s
        <ulink url="http://blog.rebeccamurphey.com/2009/10/15/using-objects-to-organize-your-code">excellent
        article on the topic</ulink>.
      </para>
      <para>
        <emphasis role="strong">Nested namespacing</emphasis>
      </para>
      <para>
        An extension of the Object Literal pattern is nested
        namespacing. It’s another common pattern used that offers a
        lower risk of collision due to the fact that even if a top-level
        namespace already exists, it’s unlikely the same nested children
        do. For example, Yahoo’s YUI uses the nested object namespacing
        pattern extensively:
      </para>
      <programlisting language="javascript">
YAHOO.util.Dom.getElementsByClassName('test');
</programlisting>
      <para>
        Yahoo’s YUI uses the nested object namespacing pattern regularly
        and even DocumentCloud (the creators of Backbone) use the nested
        namespacing pattern in their main applications. A sample
        implementation of nested namespacing with Backbone may look like
        this:
      </para>
      <programlisting language="javascript">
var galleryApp =  galleryApp || {};

// perform similar check for nested children
galleryApp.routers = galleryApp.routers || {};
galleryApp.model = galleryApp.model || {};
galleryApp.model.special = galleryApp.model.special || {};

// routers
galleryApp.routers.Workspace   = Backbone.Router.extend({}); 
galleryApp.routers.PhotoSearch = Backbone.Router.extend({}); 

// models
galleryApp.model.Photo   = Backbone.Model.extend({});
galleryApp.model.Comment = Backbone.Model.extend({}); 

// special models
galleryApp.model.special.Admin = Backbone.Model.extend({});
</programlisting>
      <para>
        This is readable, clearly organized, and is a relatively safe
        way of namespacing your Backbone application. The only real
        caveat however is that it requires your browser’s JavaScript
        engine to first locate the galleryApp object, then dig down
        until it gets to the function you’re calling. However,
        developers such as Juriy Zaytsev (kangax) have tested and found
        the performance differences between single object namespacing vs
        the <quote>nested</quote> approach to be quite negligible.
      </para>
      <para>
        <emphasis role="strong">Recommendation</emphasis>
      </para>
      <para>
        Reviewing the namespace patterns above, the option that I prefer
        when writing Backbone applications is nested object namespacing
        with the object literal pattern.
      </para>
      <para>
        Single global variables may work fine for applications that are
        relatively trivial. However, larger codebases requiring both
        namespaces and deep sub-namespaces require a succinct solution
        that’s both readable and scalable. I feel this pattern achieves
        both of these objectives and is a good choice for most Backbone
        development.
      </para>
    </sect3>
  </sect2>
  <sect2 id="additional-tips">
    <title><a name="additional-tips">Additional Tips</a></title>
    <sect3 id="automated-backbone-scaffolding">
      <title>Automated Backbone Scaffolding</title>
      <para>
        Scaffolding can assist in expediting how quickly you can begin a
        new application by creating the basic files required for a
        project automatically. If you enjoy the idea of automated MVC
        scaffolding using Backbone, I’m happy to recommend checking out
        a tool called
        <ulink url="https://github.com/brunch/brunch">Brunch</ulink>.
      </para>
      <para>
        It works very well with Backbone, Underscore, jQuery and
        CoffeeScript and is even used by companies such as Red Bull and
        Jim Beam. You may have to update any third party dependencies
        (e.g. latest jQuery or Zepto) when using it, but other than that
        it should be fairly stable to use right out of the box.
      </para>
      <para>
        Brunch can be installed via the nodejs package manager and is
        easy to get started with. If you happen to use Vim or Textmate
        as your editor of choice, you’ll be happy to know that there are
        Brunch bundles available for both.
      </para>
    </sect3>
    <sect3 id="is-there-a-limit-to-the-number-of-routers-i-should-be-using">
      <title>Is there a limit to the number of routers I should be
      using?</title>
      <para>
        Andrew de Andrade has pointed out that DocumentCloud themselves
        usually only use a single router in most of their applications.
        You’re very likely to not require more than one or two routers
        in your own projects as the majority of your application routing
        can be kept organized in a single controller without it getting
        unwieldy.
      </para>
    </sect3>
    <sect3 id="is-backbone-too-small-for-my-applications-needs">
      <title>Is Backbone too small for my application’s needs?</title>
      <para>
        If you find yourself unsure of whether or not your application
        is too large to use Backbone, I recommend reading my post on
        building large-scale jQuery &amp; JavaScript applications or
        reviewing my slides on client-side MVC architecture options. In
        both, I cover alternative solutions and my thoughts on the
        suitability of current MVC solutions for scaled application
        development.
      </para>
      <para>
        Backbone can be used for building both trivial and complex
        applications as demonstrated by the many examples Ashkenas has
        been referencing in the Backbone documentation. As with any MVC
        framework however, it’s important to dedicate time towards
        planning out what models and views your application really
        needs. Diving straight into development without doing this can
        result in either spaghetti code or a large refactor later on and
        it’s best to avoid this where possible.
      </para>
      <para>
        At the end of the day, the key to building large applications is
        not to build large applications in the first place. If you
        however find Backbone doesn’t cut it for your requirements I
        strongly recommend checking out JavaScriptMVC or SproutCore as
        these both offer a little more than Backbone out of the box.
        Dojo and Dojo Mobile may also be of interest as these have also
        been used to build significantly complex apps by other
        developers.
      </para>
    </sect3>
  </sect2>
</sect1>
<sect1 id="restful-applications">
  <title>## <a name="restfulapps">RESTful Applications</a></title>
  <para>
  </para>
</sect1>
<sect1 id="building-restful-applications-with-backbone">
  <title><a name="restful">Building RESTful applications with
  Backbone</a></title>
  <para>
    In this section of the book, we’re going to take a look at
    developing RESTful applications using Backbone.js and modern
    technology stacks. When the data for your back-end is exposed
    through a purely RESTful API, tasks such as retrieving (GET),
    creating (POST), updating (PUT) and deleting (DELETE) models are
    made easy through Backbone’s Model API. This API is so intuitive in
    fact that switching from storing records in a local data-store (e.g
    localStorage) to a database/noSQL data-store is a lot simpler than
    you may think.
  </para>
</sect1>
<sect1 id="stack-1-building-a-backbone-app-with-node.js-express-mongoose-and-mongodb">
  <title><a name="stack1">Stack 1: Building A Backbone App With Node.js,
  Express, Mongoose and MongoDB</a></title>
  <para>
    The first stack we’ll be looking at is:
  </para>
  <itemizedlist>
    <listitem>
      <para>
        <ulink url="nodejs.org">Node.js</ulink>
      </para>
    </listitem>
    <listitem>
      <para>
        <ulink url="http://expressjs.com/">Express</ulink>
      </para>
    </listitem>
    <listitem>
      <para>
        <ulink url="http://mongoosejs.com/">Mongoose</ulink>
      </para>
    </listitem>
    <listitem>
      <para>
        and <ulink url="http://www.mongodb.org/">MongoDB</ulink>
      </para>
    </listitem>
  </itemizedlist>
  <para>
    with <ulink url="http://jade-lang.com/">Jade</ulink> used optionally
    as a view/templating engine.
  </para>
  <sect2 id="reviewing-the-stack">
    <title>Reviewing the stack</title>
    <para>
      As you may know, node.js is an event-driven platform (built on the
      <ulink url="http://code.google.com/apis/v8/design.html">V8</ulink>
      runtime), designed for writing fast, scalable network
      applications. It’s reasonably lightweight, efficient and great for
      real-time applications that are data-intensive.
    </para>
    <para>
      Express is a small web-development framework written with node.js,
      based on <ulink url="http://www.sinatrarb.com/">Sinatra</ulink>.
      It supports a number of useful features such as intuitive views,
      robust routing and a focus on high performance.
    </para>
    <para>
      Next on the list are MongoDB and Mongoose. MongoDB is an
      open-source, document-oriented database store designed with
      scalability and agility in mind. As a
      <ulink url="http://en.wikipedia.org/wiki/NoSQL">noSQL</ulink>
      database, rather than storing data in tables and rows (something
      we’re very used to doing with relational databases), with MongoDB
      we instead store JSON-like documents using dynamic schemas. One of
      the goals of Mongo is to try bridging the gap between key-value
      stores (speed, scalability) and
      <ulink url="http://en.wikipedia.org/wiki/Relational_database">relational</ulink>
      databases (rich functionality).
    </para>
    <para>
      Mongoose is a JavaScript library that simplifies how we interact
      with Mongo. Like Express, it’s designed to work within the node.js
      environment and tries to solve some of the complexities with
      asynchronous data storage by offering a more user-friendly API. It
      also adds chaining features into the mix, allowing for a slightly
      more expressive way of dealing with our data.
    </para>
    <para>
      Jade is a template engine influenced by Haml (which we’ll be
      looking at later). It’s implemented with JavaScript (and also runs
      under node). In addition to supporting Express out of the box, it
      boasts a number of useful features including support for mixins,
      includes, caching, template inheritance and much more. Whilst
      abstractions like Jade certainly aren’t for everyone, our
      practical will cover working both with and without it.
    </para>
  </sect2>
  <sect2 id="practical">
    <title>Practical</title>
    <para>
      For this practical, we’re going to once again look at extending
      the popular Backbone Todo application. Rather than relying on
      localStorage for data persistence, we’re going to switch to
      storing Todos in a MongoDB document-store instead. The code for
      this practical can be found in
      <literal>practicals\stacks\option2</literal>
    </para>
    <para>
      <emphasis role="strong">app.js</emphasis>
    </para>
    <para>
      (See
      <ulink url="https://github.com/addyosmani/backbone-boilerplates/blob/master/option2/app.js">here</ulink>
      for the source)
    </para>
    <para>
      We must first include the node dependencies required by our
      application. These are Express, Mongoose and Path (a module
      containing utilities for dealing with file paths.
    </para>
    <programlisting language="javascript">
var application_root = __dirname,
  express = require(&quot;express&quot;),
  path = require(&quot;path&quot;),
  mongoose = require('mongoose');
</programlisting>
    <para>
      Next, create a new Express server.
      <literal>express.createServer()</literal> is a simple way of
      creating an instance of express.HTTPServer, which we’ll be using
      to pass in our routes.
    </para>
    <programlisting language="javascript">
var app = express.createServer();
</programlisting>
    <para>
      After this, connect Mongoose up to a database (in our case,
      localhost should suffice). Should you require the ability to pass
      in authentication information, here’s a sample containing all of
      the supported URL parameters:
      <literal>mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]</literal>
    </para>
    <programlisting language="javascript">
mongoose.connect('mongodb://localhost/my_database');
</programlisting>
    <para>
      A Mongoose model for any Todo item can now be easily defined by
      passing a schema instance to <literal>mongoose.model</literal>. In
      our case the schema covers a Todo item’s <literal>text</literal>
      content, its <literal>done</literal> state and
      <literal>order</literal> position in the overall Todo list.
    </para>
    <programlisting language="javascript">
var Todo = mongoose.model('Todo', new mongoose.Schema({
  text: String,
  done: Boolean,
  order: Number
}));
</programlisting>
    <para>
      The <literal>configure()</literal> methods allows us to setup what
      we need for the current environment with our Express server. Note
      that lower down in the configuration are two view/view related
      lines. The last one explicitly sets the viewing/templating engine
      to be used as Jade
      <literal>app.set('view engine', 'jade')</literal>. We can avoid
      these if we wish to use plain HTML/JS for our templates instead.
    </para>
    <programlisting language="javascript">
app.configure(function(){
  // the bodyParser middleware parses JSON request bodies
  app.use(express.bodyParser());
  app.use(express.methodOverride());
  app.use(app.router);
  app.use(express.static(path.join(application_root, &quot;public&quot;)));
  app.use(express.errorHandler({ dumpExceptions: true, showStack: true }));
  app.set('views', path.join(application_root, &quot;views&quot;));
  app.set('view engine', 'jade')
});
</programlisting>
    <para>
      Should you prefer to switch out Jade for an alternative view
      engine, this can be done fairly trivially. See the section under
      <quote>Templating</quote> here:
      https://github.com/joyent/node/wiki/modules. For example, to
      switch to EJS, you would simply write
      <literal>app.set('view engine', 'ejs')</literal>
    </para>
    <para>
      Express makes use of common HTTP verbs (get, put, post etc.) to
      provide easy to use, expressive routing API based on CRUD (Create,
      Read, Update and Delete). Below for example, we can define what
      happens when the browser requests the root <quote>/</quote>. As a
      trivial route in this application, it doesn’t do anything
      particularly exciting, however getters typically read or retrieve
      data.
    </para>
    <programlisting language="javascript">
app.get('/', function(req, res){
  res.send('Hello World');
});
</programlisting>
    <para>
      Onto something a little more useful and in our next route,
      navigating to <quote>/todo</quote> will actually render our Jade
      view <quote>todo.jade</quote>, as seen in the callback. Additional
      configuration values can be passed as the second parameter, such
      as the custom title specified below.
    </para>
    <programlisting language="javascript">
app.get('/todo', function(req, res){
  res.render('todo', {title: &quot;Our sample application&quot;});
});
</programlisting>
    <para>
      Next, we can see the first of our <quote>/api/</quote> routes.
    </para>
    <programlisting language="javascript">
app.get('/api/todos', function(req, res){
  return Todo.find(function(err, todos) {
    return res.send(todos);
  });
});
</programlisting>
    <para>
      The callback to our next route supports querying for todos based
      on a specific ID. The route string itself (once compiled) will be
      converted from <quote>/api/todos/:id</quote> to a regular
      expression. As you might have guessed, this is a hint that routes
      can also be regular expression literals if we wished to do
      something more complex.
    </para>
    <programlisting language="javascript">
app.get('/api/todos/:id', function(req, res){
  return Todo.findById(req.params.id, function(err, todo) {
    if (!err) {
      return res.send(todo);
    }
  });
});
</programlisting>
    <para>
      Similarly, we want to support updating todos based on a specific
      ID as well. The following allows us to query a todo by ID and then
      update the values of it’s three attributes (text, done, order)
      easily.
    </para>
    <programlisting language="javascript">
app.put('/api/todos/:id', function(req, res){
  return Todo.findById(req.params.id, function(err, todo) {
    todo.text = req.body.text;
    todo.done = req.body.done;
    todo.order = req.body.order;
    return todo.save(function(err) {
      if (!err) {
        console.log(&quot;updated&quot;);
      }
      return res.send(todo);
    });
  });
});
</programlisting>
    <para>
      We’ve so far covered requesting todos and updating them, but a
      core part of the application requires us to insert (or add) new
      todos to our data-store. Below we can create new <code>Todo</code>
      models and simply save them.
    </para>
    <programlisting language="javascript">
app.post('/api/todos', function(req, res){
  var todo;
  todo = new Todo({
    text: req.body.text,
    done: req.body.done,
    order: req.body.order
  });
  todo.save(function(err) {
    if (!err) {
      return console.log(&quot;created&quot;);
    }
  });
  return res.send(todo);
});
</programlisting>
    <para>
      We of course also want to support deleting todos (e.g if a todo
      has been <quote>cleared</quote>, it should be deleted). This also
      works based on a specific todo ID.
    </para>
    <programlisting language="javascript">
app.delete('/api/todos/:id', function(req, res){
  return Todo.findById(req.params.id, function(err, todo) {
    return todo.remove(function(err) {
      if (!err) {
        console.log(&quot;removed&quot;);
        return res.send('')
      }
    });
  });
});
</programlisting>
    <para>
      Finally, this last line is to ensure we’re only listening on the
      port app.js is running.
    </para>
    <programlisting language="javascript">
app.listen(3000);
</programlisting>
    <para>
      <emphasis role="strong">script.js - updating our Backbone.js
      app</emphasis>
    </para>
    <para>
      In the <literal>/public/js</literal> folder of options 1 (HTML
      templates) and 2 (Jade) for the practical, you’ll find a version
      of the Backbone Todo app originally by Jerome Gravel-Niquet. Let’s
      pay attention to
      <ulink url="https://github.com/addyosmani/backbone-boilerplates/blob/master/option2/public/js/script.js">script.js</ulink>.
      In order to change the application to work with our new back-end,
      we’ll need to make some very minor changes to this.
    </para>
    <para>
      Reviewing <literal>window.TodoList</literal> (a Backbone
      Collection), you’ll notice that it has a property called
      <literal>localStorage</literal>, which uses the Backbone
      <ulink url="https://github.com/jeromegn/Backbone.localStorage">localStorage</ulink>
      adapter in order to facilitate storing data using the browser’s
      localStorage features.
    </para>
    <programlisting language="javascript">
window.TodoList = Backbone.Collection.extend({

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

    // Save all of the todo items under the `&quot;todos&quot;` namespace.
    // Typically, this should be a unique name within your application
    localStorage: new Store(&quot;todos&quot;),
</programlisting>
    <para>
      In order to switch it over to our RESTful backend, we’re going to
      make use of the <literal>url</literal> property or function on a
      collection to reference its location on the server. Models inside
      of a collection then use <literal>url</literal> to construct URLs
      of their own. As all of the CRUD for our RESTful API works on the
      base route <quote>/api/todos</quote>, this is the value we set
      <literal>url</literal> to.
    </para>
    <programlisting language="javascript">
    // localStorage: new Store(&quot;todos&quot;),
    url: '/api/todos',
</programlisting>
    <para>
      This is the only change necessary to our existing Backbone
      application in order to get things working. Pretty easy, right?
    </para>
    <para>
      <emphasis role="strong">todo.jade</emphasis>
    </para>
    <para>
      The Jade templates for our application cover declarative markup
      for both the index (layout.jade) of the application and the main
      Todo container (todo.jade). It also covers the script-tag
      templates used for rendering each new Todo item that’s added.
    </para>
    <programlisting language="html">
// Todo App Interface

#todoapp
  .title
    h1 Todos
  .content
    #create-todo
      input#new-todo(placeholder=&amp;quot;What needs to be done?&amp;quot;, type=&amp;quot;text&amp;quot;)
      span.ui-tooltip-top(style=&amp;quot;display:none;&amp;quot;) Press Enter to save this task
    #todos
      ul#todo-list
    #todo-stats


// Templates
script#item-template(type=&amp;quot;text/template&amp;quot;)
  &amp;lt;div class=&amp;quot;todo &amp;lt;%= done ? 'done' : '' %&amp;gt;&amp;quot;&amp;gt;
  .display
    &amp;lt;input class=&amp;quot;check&amp;quot; type=&amp;quot;checkbox&amp;quot; &amp;lt;%= done ? 'checked=&amp;quot;checked&amp;quot;' : '' %&amp;gt; /&amp;gt;
    .todo-text 
    span#todo-destroy
  .edit
    input.todo-input(type=&amp;quot;text&amp;quot;, &amp;quot;value&amp;quot;=&amp;quot;&amp;quot;)
  &amp;lt;/div&amp;gt;

script#stats-template(type=&amp;quot;text/template&amp;quot;)
  &amp;lt;% if (total) { %&amp;gt;
  span.todo-count
    span.number &amp;lt;%= remaining %&amp;gt; 
    span.word &amp;lt;%= remaining == 1 ? 'item' : 'items' %&amp;gt;
    |  left.
  &amp;lt;% } %&amp;gt;
  &amp;lt;% if (done) { %&amp;gt;
  span.todo-clear
    a(href=&amp;quot;#&amp;quot;)
      |  Clear
      span.number-done &amp;lt;%= done %&amp;gt;
      |  completed
      span.word-done &amp;lt;%= done == 1 ? 'item' : 'items' %&amp;gt;
  &amp;lt;% } %&amp;gt;
</programlisting>
    <para>
      <emphasis role="strong">layout.jade</emphasis>
    </para>
    <programlisting language="html">
!!! 5
//if lt IE 6
  &amp;lt;html class=&amp;quot;no-js ie6 oldie&amp;quot; lang=&amp;quot;en&amp;quot;&amp;gt; 
//if IE 7
  &amp;lt;html class=&amp;quot;no-js ie7 oldie&amp;quot; lang=&amp;quot;en&amp;quot;&amp;gt;
//if IE 8
  &amp;lt;html class=&amp;quot;no-js ie8 oldie&amp;quot; lang=&amp;quot;en&amp;quot;&amp;gt;
//if gt IE 8
  &amp;lt;!--&amp;gt; &amp;lt;html class=&amp;quot;no-js&amp;quot; lang=&amp;quot;en&amp;quot;&amp;gt; &amp;lt;!--
head
  meta(charset=&amp;quot;utf-8&amp;quot;)
  meta(http-equiv=&amp;quot;X-UA-Compatible&amp;quot;, content=&amp;quot;IE=edge,chrome=1&amp;quot;)

  title=title
  meta(name=&amp;quot;description&amp;quot;, content=&amp;quot;&amp;quot;)
  meta(name=&amp;quot;author&amp;quot;, content=&amp;quot;&amp;quot;)
  meta(name=&amp;quot;viewport&amp;quot;, content=&amp;quot;width=device-width,initial-scale=1&amp;quot;)

  // CSS concatenated and minified via ant build script
  link(rel=&amp;quot;stylesheet&amp;quot;, href=&amp;quot;css/style.css&amp;quot;)
  // end CSS

  script(src=&amp;quot;js/libs/modernizr-2.0.6.min.js&amp;quot;)
body

  #container
    header
    #main(role=&amp;quot;main&amp;quot;)!=body
    footer
  //! end of #container

  script(src=&amp;quot;//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js&amp;quot;)
  script
    window.jQuery || document.write('&amp;lt;script src=&amp;quot;js/libs/jquery-1.6.2.min.js&amp;quot;&amp;gt;&amp;lt;\\/script&amp;gt;')

  // scripts concatenated and minified via ant build script
  script(src=&amp;quot;js/mylibs/underscore.js&amp;quot;)
  script(src=&amp;quot;js/mylibs/backbone.js&amp;quot;)
  script(defer, src=&amp;quot;js/plugins.js&amp;quot;)
  script(defer, src=&amp;quot;js/script.js&amp;quot;)
  // end scripts

  // Change UA-XXXXX-X to be your site's ID
  script
    window._gaq = [['_setAccount','UAXXXXXXXX1'],['_trackPageview'],['_trackPageLoadTime']];
    Modernizr.load({load: ('https:' == location.protocol ? '//ssl' : '//www') + '.google-analytics.com/ga.js'});

  //if lt IE 7
    script(src=&amp;quot;//ajax.googleapis.com/ajax/libs/chrome-frame/1.0.3/CFInstall.min.js&amp;quot;)
    script
      window.attachEvent('onload',function(){CFInstall.check({mode:'overlay'})})
&amp;lt;/html&amp;gt;
</programlisting>
    <para>
      <emphasis role="strong">static.html</emphasis>
    </para>
    <para>
      Alternatively, a static version of our index which doesn’t rely on
      Jade can be put together as follows. See
      <ulink url="https://github.com/addyosmani/backbone-boilerplates/blob/master/option1/public/static.html">here</ulink>
      for the complete file or below for a sample.
    </para>
    <programlisting language="html">
 &amp;lt;div id=&amp;quot;container&amp;quot;&amp;gt;
    &amp;lt;div id=&amp;quot;main&amp;quot; role=&amp;quot;main&amp;quot;&amp;gt;

      &amp;lt;!-- Todo App Interface--&amp;gt;

      &amp;lt;div id=&amp;quot;todoapp&amp;quot;&amp;gt;
        &amp;lt;div class=&amp;quot;title&amp;quot;&amp;gt;
          &amp;lt;h1&amp;gt;Todos&amp;lt;/h1&amp;gt;
        &amp;lt;/div&amp;gt;

        &amp;lt;div class=&amp;quot;content&amp;quot;&amp;gt;
          &amp;lt;div id=&amp;quot;create-todo&amp;quot;&amp;gt;
            &amp;lt;input id=&amp;quot;new-todo&amp;quot; placeholder=&amp;quot;What needs to be done?&amp;quot; type=
            &amp;quot;text&amp;quot; /&amp;gt;&amp;lt;span style=&amp;quot;display:none;&amp;quot; class=&amp;quot;ui-tooltip-top&amp;quot;&amp;gt;Press Enter to
            save this task&amp;lt;/span&amp;gt;
          &amp;lt;/div&amp;gt;

          &amp;lt;div id=&amp;quot;todos&amp;quot;&amp;gt;
            &amp;lt;ul id=&amp;quot;todo-list&amp;quot;&amp;gt;&amp;lt;/ul&amp;gt;
          &amp;lt;/div&amp;gt;

          &amp;lt;div id=&amp;quot;todo-stats&amp;quot;&amp;gt;&amp;lt;/div&amp;gt;
        &amp;lt;/div&amp;gt;
      &amp;lt;/div&amp;gt;


    &amp;lt;!-- Templates--&amp;gt;

      &amp;lt;script id=&amp;quot;item-template&amp;quot; type=&amp;quot;text/template&amp;quot;&amp;gt;
      &amp;lt;div class=&amp;quot;todo &amp;lt;%= done ? 'done' : '' %&amp;gt;&amp;quot;&amp;gt;
      &amp;lt;div class=&amp;quot;display&amp;quot;&amp;gt;&amp;lt;input class=&amp;quot;check&amp;quot; type=&amp;quot;checkbox&amp;quot; &amp;lt;%= done ? 'checked=&amp;quot;checked&amp;quot;' : '' %&amp;gt; /&amp;gt;
      &amp;lt;div class=&amp;quot;todo-text&amp;quot;&amp;gt;&amp;lt;/div&amp;gt;&amp;lt;span id=&amp;quot;todo-destroy&amp;quot;&amp;gt;&amp;lt;/span&amp;gt;&amp;lt;/div&amp;gt;&amp;lt;div class=&amp;quot;edit&amp;quot;&amp;gt;&amp;lt;input type=&amp;quot;text&amp;quot; value=&amp;quot;&amp;quot; class=&amp;quot;todo-input&amp;quot;/&amp;gt;&amp;lt;/div&amp;gt;&amp;lt;/div&amp;gt;
      &amp;lt;/script&amp;gt;

      &amp;lt;script id=&amp;quot;stats-template&amp;quot; type=&amp;quot;text/template&amp;quot;&amp;gt;
      &amp;lt;% if (total) { %&amp;gt;
      &amp;lt;span class=&amp;quot;todo-count&amp;quot;&amp;gt;&amp;lt;span class=&amp;quot;number&amp;quot;&amp;gt;&amp;lt;%= remaining %&amp;gt; &amp;lt;/span&amp;gt;&amp;lt;span class=&amp;quot;word&amp;quot;&amp;gt;&amp;lt;%= remaining == 1 ? 'item' : 'items' %&amp;gt;&amp;lt;/span&amp;gt; left.
      &amp;lt;/span&amp;gt;&amp;lt;% } %&amp;gt;
      &amp;lt;% if (done) { %&amp;gt;
      &amp;lt;span class=&amp;quot;todo-clear&amp;quot;&amp;gt;&amp;lt;a href=&amp;quot;#&amp;quot;&amp;gt; Clear
      &amp;lt;span class=&amp;quot;number-done&amp;quot;&amp;gt;&amp;lt;%= done %&amp;gt;&amp;lt;/span&amp;gt; completed
      &amp;lt;span class=&amp;quot;word-done&amp;quot;&amp;gt;&amp;lt;%= done == 1 ? 'item' : 'items' %&amp;gt;&amp;lt;/span&amp;gt;&amp;lt;/a&amp;gt;&amp;lt;/span&amp;gt;&amp;lt;% } %&amp;gt;
      &amp;lt;/script&amp;gt;

    &amp;lt;/div&amp;gt;
  &amp;lt;/div&amp;gt;

  &amp;lt;!--! end of #container--&amp;gt;
</programlisting>
  </sect2>
  <sect2 id="practical-setup">
    <title>Practical Setup</title>
    <para>
      We’ve now gone through the major points of developing a RESTful
      backend using Node.js, Express and Mongoose. Next, let’s make sure
      you can get your environment setup to run the updated Todo app.
    </para>
    <sect3 id="mongodb">
      <title>MongoDB</title>
      <para>
        Once you’ve downloaded
        <ulink url="http://www.mongodb.org/downloads">MongoDB</ulink>,
        you’ll need to complete two steps to get it up and running.
      </para>
      <para>
        <emphasis role="strong">Data directories</emphasis>
      </para>
      <para>
        MongoDB stores data in the bin/data/db folder but won’t actually
        create this directory for you. Navigate to where you’ve
        downloaded and extracted MongoDB and run the following from
        terminal:
      </para>
      <programlisting language="html">
sudo mkdir -p /data/db/
sudo chown `id -u` /data/db
</programlisting>
      <para>
        <emphasis role="strong">Running and connecting to your
        server</emphasis>
      </para>
      <para>
        Once this is done, open up two terminal windows.
      </para>
      <para>
        In the first, <literal>cd</literal> to your MongoDB bin
        directory or type in the complete path to it. You’ll need to
        start <cpde>mongod`.
      </para>
      <programlisting language="html">
$ ./bin/mongod
</programlisting>
      <para>
        Next, in the second terminal, start the
        `mongo</code shell which will connect up to localhost by default.

        ```html
        $ ./bin/mongo
        ```

        That's it!.

        ####Express and Mongoose

        Option 1 (HTML) and Option 2 (Jade) of the practical download both come with an install.sh bash script. This allows you to easily install Express, Mongoose, Jade (and optionally MongoDB if you prefer to) through npm (the node package manager). 

        * Make sure you have Node.js installed. If not, you can grab it [here](http://nodejs.org/#download)
        * Next run `$ ./install.sh` at the terminal to install the rest of our dependencies. To see the exact contents of the install.sh file, see below:

        **install.sh**

        ```html
        #!/bin/bash
        npm install express
        npm install mongodb --mongodb:native
        npm install mongoose
        npm install jade
        ```


        * After you've installed all of the dependencies for the stack, we can get to cloning the repo containing our practicals and running them. Start by running the below lines:

        ```html
        git clone git://github.com/addyosmani/backbone-boilerplates.git
        cd option2
        node app.js
        ```

        For option1 (without Jade), simply cd into option1 and run `node app.js` from there.

        Finally, either of the example apps can now be accessed by navigating to:

        * Option 1: `http://localhost:3000/static.html`
        * Option 2: `http://localhost:3000/todo`

        That's it! Whilst there's a lot more than can be done to expand on the concepts covered so far, the base we're reviewed should be enough to get you up and running with this stack if you wish to use it with Backbone. 


        #<a name="stack2">Building Backbone.js Apps With Ruby, Sinatra,
        MongoDB and Haml</a>
      </para>
    </sect3>
  </sect2>
</sect1>
<sect1 id="introduction-1">
  <title>Introduction</title>
  <para>
    In this chapter we’re going to explore writing Backbone.js
    applications with a Ruby back-end. To assist with this, we’re going
    to use <ulink url="http://www.sinatrarb.com/">Sinatra</ulink> - a
    DSL (domain specific language) for rapidly creating web applications
    in Ruby. Similar to the
    <ulink url="https://github.com/addyosmani/backbone-fundamentals/#stack1">section</ulink>
    on writing an application with Node.js, our server-side language
    (Ruby) will be used to power an API whilst Backbone.js will be the
    client consuming it.
  </para>
</sect1>
<sect1 id="what-is-sinatra">
  <title>What Is Sinatra?</title>
  <para>
    In the past, you’ve likely come across or used
    <ulink url="http://rubyonrails.org">Ruby on Rails</ulink> (RoR) - a
    popular web application framework for the Ruby programming language
    that helps organize applications using the MVC pattern. Sinatra is a
    much smaller, more light-weight alternative to it.
  </para>
  <para>
    Whilst a very basic Rails application may require a more strict
    project structure (such as requiring the use of controllers, views
    and routing etc.), Sinatra doesn’t require as many of these
    dependencies, sacrificing the helpers needed to connect to
    databases, tools to create forms or any of the other utilities Rails
    comes with out of the box.
  </para>
  <para>
    What Sinatra does have is a
    <emphasis role="strong">minimal</emphasis> set of features most
    useful for tying specific URLs and RESTful HTTP actions to blocks of
    Ruby code and returning this code’s output as a response. Sinatra is
    particularly useful for getting projects up and running quickly
    where we don’t have a need for the extra pieces RoR provides.
  </para>
  <para>
    For those who are familiar with more Rails, you probably know that
    it requires a separate routes file to define how an application
    should be responding to requests. These are then piped into the
    relevant models and controllers as needed.
  </para>
  <para>
    Sinatra takes a more straight-forward approach, providing us with
    the most simple path to handling routing. By declaring
    <literal>get</literal>,<literal>post</literal>,
    <literal>put</literal> or <literal>delete</literal> actions, we can
    inform Sinatra to add a new route, which we can then have respond to
    requests.
  </para>
  <para>
    The framework is particularly useful for writing APIs, widgets and
    small-scale applications that can power the backend of a
    client-heavy application. As mentioned, we will be using it to power
    our API.
  </para>
</sect1>
<sect1 id="getting-started-with-sinatra">
  <title>Getting Started With Sinatra</title>
  <para>
    Let’s review how to write and run a very basic Sinatra application.
    As most programming languages and frameworks typically start with
    some variation of <quote>Hello World</quote>, we’ll start with a
    similar example.
  </para>
  <para>
    Note: Before beginning this section, I recommend installing Sinatra
    on your system. A guide to doing this can be found in the
    <link linkend="preq">prerequisites</link> section lower down in the
    article.
  </para>
  <sect2 id="routes">
    <title>Routes</title>
    <para>
      As mentioned, Sinatra allows us to define new routes using HTTP
      actions. Semantically, a route follows quite a simple structure:
    </para>
    <programlisting language="ruby">
&lt;a HTTP action&gt; &lt;the desired route&gt; do
   # some behaviour
end
</programlisting>
    <para>
      A tiny route that outputs a <quote>Hello World</quote>-like
      message when we attempt to <quote>get</quote> the root could thus
      be written as follows:
    </para>
    <programlisting language="ruby">
require 'sinatra'

get '/' do
   &quot;Hello World! Is it me you're looking for?&quot;
end
</programlisting>
    <para>
      To run this snippet, we can can simply save it to a local ’.rb’
      file and execute it as follows:
    </para>
    <programlisting language="ruby">
ruby -rubygems example.rb
</programlisting>
    <para>
      If we now navigated to http://localhost:4567 in our browser we
      could now see the application running successfully.
    </para>
    <para>
      The HTTP verbs we commonly work with when writing RESTful web
      services are: <literal>get</literal>, <literal>post</literal>,
      <literal>delete</literal> and <literal>put</literal>. As we now
      know, all Sinatra routes are basically HTTP actions
      (`<literal>get</literal> etc.) that are paired with a URL-matching
      pattern. We associate a pair of an action and route with code we
      would like sent back to the browser (executed)if the route is
      reached. Sinatra doesn’t enforce much in the way of architectural
      structure, instead relying on simplicity to supporting writing
      powerful APIs.
    </para>
    <para>
      Here’s an example of a skeleton service we could put together
      supporting four common HTTP actions: ruby ``` get
      <quote>/items</quote> do # list all items available end
    </para>
    <para>
      get <quote>/item/:id</quote> do # get a single item end
    </para>
    <para>
      post <quote>/item</quote> do # create a new item end
    </para>
    <para>
      put <quote>/item/:id</quote> do # update an existing item end
    </para>
    <para>
      delete <quote>/item/:id</quote> do # delete an item end ```
    </para>
    <para>
      Sinatra’s routing is both easy for beginners to get started with
      but is also flexible enough for those wishing to define more
      complex routes. As you probably noticed in the above example,
      routes can include named parameters (e.g
      <literal>/item/:id</literal>). We can actually access the content
      of these routes using the <literal>params</literal> hash as
      follows:
    </para>
    <programlisting language="ruby">
get '/item/:id' do
  # this matches &quot;GET /item/10&quot; and &quot;GET /item/11&quot;
  # params[:id] is &quot;10&quot; or &quot;11&quot;
  &quot;You reached #{params[:id]}&quot;
end
</programlisting>
    <para>
      Sinatra also supports route matching via splats, wildcards and
      regular expressions. For more information on this I recommend
      reading the official
      <ulink url="http://www.sinatrarb.com/documentation">docs</ulink>.
      Let’s now take a look at handlers.
    </para>
    <para>
      Sinatra includes convenient handler methods for tasks such as
      redirection, halting and passing.
    </para>
    <sect3 id="redirection">
      <title>Redirection</title>
      <para>
        A simple route supporting redirection which returns a 302
        response can be written as follows:
      </para>
      <programlisting language="ruby">
get '/items' do
      redirect '/items/welcome'
end
</programlisting>
      <para>
        And if we wish to pass additional parameters such as arguments
        we can do so like this: redirect
        <quote>http://site.com/</quote>, <quote>Oops! I think we have a
        problem!</quote>
      </para>
    </sect3>
    <sect3 id="halting">
      <title>Halting</title>
      <para>
        To immediately stop a request (halting) we can use
        <quote>halt</quote>. Heres an example of halting a request where
        we specify the message body:
      </para>
      <para>
        <literal>halt &quot;who goes there!?&quot;</literal>
      </para>
    </sect3>
    <sect3 id="passing">
      <title>Passing</title>
      <para>
        <quote>Passing</quote> is the concept of deferring processing of
        a block to the next matching route. We do this using
        <literal>pass</literal>. In the following example if a parameter
        isnt the username we expect (rick-astley) we simply pass it on:
      </para>
      <programlisting language="ruby">
get '/members/:username' do
 pass unless params[:username] == 'rick-astley'
 'Never gonna give you up, never gonna let you down'
end

get '/member/*' do
 'Welcome!'
end
</programlisting>
      <para>
        There are also handler methods that can assist with sessions
        (specifically, cookie-based session handling). To use Sinatra’s
        session handling, first enable it in your application with:
      </para>
      <programlisting language="ruby">
enable :sessions
</programlisting>
      <para>
        You can then use the session handling capabilities as follows:
      </para>
      <programlisting language="ruby">
get '/items' do
  session['visitCounter'] ||= 0;
  session['visitCounter'] += 1;
  &quot;This page has been accessed #{session['visitCounter']} times&quot;
end
</programlisting>
      <para>
        Note: By default enable:sessions will store all data in cookies.
        If this is not desired, you can not call this and instead use
        some Rack middleware instead. For more on this see
        <ulink url="http://www.sinatrarb.com/intro#Using%20Sessions">here</ulink>.
      </para>
      <para>
        This only touches the surface of what can be done using routes
        and handlers, but is sufficient for us to write the
        Sinatra-powered API service we require in the practical section
        of this chapter.
      </para>
    </sect3>
  </sect2>
</sect1>
<sect1 id="templating-and-haml">
  <title>Templating And HAML</title>
  <para>
    Let’s now discuss templating.Out of the box, we can begin using
    templates in our Sinatra applications with ERB. ERB is included with
    Ruby and allows Ruby code to be added to any plain text document for
    the purpose of generating information or flow control. In the
    following example using an ERB template, note that views are by
    default located in the <literal>views</literal> directory of our
    application.
  </para>
  <programlisting language="ruby">
get '/items' do
  erb :default
  # renders views/default.erb
end
</programlisting>
  <para>
    A useful Sinatra convention worth noting is how layouts are handled.
    Layouts automatically search for a views/layout template which is
    rendered before any other views are loaded. With ERB, our
    views/layout.erb file could look as follows:
  </para>
  <programlisting language="html">
&lt;html&gt;
  &lt;head&gt;&lt;/head&gt;
  &lt;body&gt;
    &lt;%= data %&gt;
  &lt;/body&gt;
&lt;/html&gt;
</programlisting>
  <para>
    Haml is a popular alternative to ERB which offers an abstract syntax
    for writing application templates. It has been said to be:
  </para>
  <itemizedlist>
    <listitem>
      <para>
        Straight-forward to learn
      </para>
    </listitem>
    <listitem>
      <para>
        Very easy to read and use for visually expressing a hierarchy of
        DOM elements
      </para>
    </listitem>
    <listitem>
      <para>
        Popular with web designers as it builds on top of CSS syntax
      </para>
    </listitem>
    <listitem>
      <para>
        Well documented with a large community backing it
      </para>
    </listitem>
    <listitem>
      <para>
        Almost as fast as ERB
      </para>
    </listitem>
  </itemizedlist>
  <para>
    For the purpose of comparison, below we can see an ERB template
    compared to it’s Haml equivalent.
  </para>
  <sect2 id="erb">
    <title>ERB</title>
    <programlisting language="html">
&lt;div class=&quot;todo&quot; id=&quot;content&quot;&gt;
  &lt;h2 class=&quot;entry_title&quot;&gt;&lt;%= h @todo.title %&gt;&lt;/h2&gt;
  &lt;div class=&quot;entry_link&quot;&gt;&lt;%= link_to('link', @todo.link) %&gt;&lt;/div&gt;
&lt;/div&gt;
</programlisting>
  </sect2>
  <sect2 id="haml">
    <title>Haml</title>
    <programlisting language="html">
.todo#content
  %h2.entry_title= @todo.title
  .entry_link= link_to('link', @todo.link)
</programlisting>
    <para>
      One of the first things we notice is that the Haml snippet looks
      significantly more like CSS than it does traditional markup. It’s
      much easier to read and we no longer need to be concerned with
      divs, spans, closing tags or other semantic rules that usually
      mean more keystrokes. The approach taken to making whitespace a
      part of the syntax also means it can be much easier to compare
      changes between multiple documents (especially if you’re doing a
      diff).
    </para>
    <para>
      In the list of Haml features, we briefly mentioned web designers.
      As developers, we regularly need to communicate and work with
      designers, but we always have to remember that at the end of the
      day, they are not programmers. They’re usually more concerned with
      the look and the feel of an application, but if we want them to
      write mark-up as a part of the templates or skins they create,
      Haml is a simpler option that has worked well for teams at a
      number of companies.
    </para>
    <programlisting language="ruby">
%h1 This is some h1 text
%h2 This is some h2 text.

%p Now we have a line containing a single instance variable: @content
%p= @content

%p Embedding Ruby code in the middle of a line can be done using ==.
%p== Here is an example: #{@foobar}

%p We can also add attributes using {}
%p{:style =&gt; &quot;color:green&quot;} We just made this paragraph green!

%p You'll want to apply classes and ids to your DOM, too.
%p.foo This has the foo class
%p.bar This has the bar class
%p#foobar This has the foobar id
%p.foo#foobar Or you can combine them!

%p Nesting can be done like this
%p
  Or even like this
</programlisting>
    <para>
      Note: Haml is whitespace sensitive and will not correctly work if
      it isn’t indented by an even number of spaces. This is due to
      whitespace being used for nesting in place of the classic HTML
      markup approach of closing tags.
    </para>
  </sect2>
</sect1>
<sect1 id="mongodb-ruby-driver">
  <title>MongoDB Ruby Driver</title>
  <sect2 id="getting-started">
    <title>Getting started</title>
    <para>
      Once the MongoDB Ruby driver is installed, we can begin to use it
      to connect to a Mongo database. To create a connection using
      localhost, we simply specify the driver as a dependency. Assuming
      we’re using the default port we can then connect as follows:
    </para>
    <programlisting language="ruby">
require 'mongo'

# where 'learning-mongo' is the name of our database:
db = Connection.new.db('learning-mongo');
</programlisting>
    <para>
      We probably also want to place some data into
      <quote>learning-mongo</quote>. It could be as simple as a note, so
      why don’t we go ahead and begin a notes collection?:
    </para>
    <para>
      <literal>ruby notes = db.collection('notes')</literal> Something
      interesting worth noting is that at this point, we haven’t
      actually created the database nor the collection we’re referencing
      above.
    </para>
    <para>
      Neither of these items exist in Mongo (just yet) but as we’re
      working with a new database but they will once we insert some real
      data.
    </para>
    <para>
      A new note could be defined using key/value pairs as follows and
      then inserted into <quote>learning-mongo</quote> using
      <literal>collection.insert()</literal>:
    </para>
    <programlisting language="ruby">
our_note = { :text =&gt; 'Remember the milk', :remindInterval =&gt; 'weekly'}
note_id = notes.insert(our_note)
</programlisting>
    <para>
      What is returned from inserting a note into the notes collection
      is an <literal>ObjectId</literal> reference for the note from
      Mongo. This is useful as we can re-use it to locate the same
      document in our database.
    </para>
    <programlisting language="ruby">
note = notes.find( :id =&gt; note_id ).first
</programlisting>
    <para>
      This can also be used in conjunction with Mongo’s
      <literal>collection.update()</literal> method and
      <ulink url="http://www.mongodb.org/display/DOCS/Updating">query</ulink>
      operators (i.e <literal>$set</literal>) to replace fields in an
      existing document.
    </para>
    <para>
      We might update an entire document as follows:
    </para>
    <programlisting language="ruby">
note = notes.find( :id =&gt; note_id ).first
note[:text] = 'Remember the bread'
notes.update({ :_id =&gt; note_id }, note)
</programlisting>
    <para>
      or using <literal>$set</literal>, update an existing document
      without overwriting the entire object as like this:
    </para>
    <programlisting language="ruby">
notes.update({ :_id =&gt; note_id }, '$set' =&gt; { :text = &gt; 'Remember the bread' })
</programlisting>
    <para>
      Useful to know: Almost each MongoDB document has an _id field as
      it’s first attribute. This can normally be of any type, however a
      special BSON datatype is provided for object ids. It’s a 12-byte
      binary value that has a high probability of being unique when
      allocated.
    </para>
    <para>
      Note: Whilst we opted for the MongoDB Ruby Driver for this stack,
      you may also be interested in
      <emphasis role="strong">DataMapper</emphasis> - a solution which
      allows us to use the same API to talk to a number of different
      datastores. This works well for both relational and non-relational
      databases and more information is available on the official
      <ulink url="http://datamapper.org/why.html">project page</ulink>.
      <ulink url="http://sinatra-book.gittr.com/#datamapper">Sinatra:
      The Book</ulink> also contains a brief tutorial on DataMapper for
      anyone interested in exploring it further.
    </para>
  </sect2>
</sect1>
<sect1 id="practical-1">
  <title>Practical</title>
  <para>
    We’re going to use Sinatra in a similar manner to how we used
    Express in the last chapter. It will power a RESTful API supporting
    CRUD operations. Together with a MongoDB data store, this will allow
    us to easily persist data (todo items) whilst ensuring they are
    stored in a database. If you’ve read the previous chapter or have
    gone through any of the Todo examples covered so far, you will find
    this surprisingly straight-forward.
  </para>
  <para>
    Remember that the default Todo example included with Backbone.js
    already persists data, although it does this via a localStorage
    adapter. Luckily there aren’t a great deal of changes needed to
    switch over to using our Sinatra-based API. Let’s briefly review the
    code that will be powering the CRUD operations for this sections
    practical, as we go course won’t be starting off with a
    near-complete base for most of our real world applications.
  </para>
  <sect2 id="installing-the-prerequisites">
    <title><a id="preq">Installing The Prerequisites</a></title>
    <sect3 id="ruby">
      <title>Ruby</title>
      <para>
        If using OSX or Linux, Ruby may be one of a number of
        open-source packages that come pre-installed and you can skip
        over to the next paragraph. In case you would like to check if
        check if you have Ruby installed, open up the terminal prompt
        and type:
      </para>
      <para>
        <literal>$ ruby -v</literal>
      </para>
      <para>
        The output of this will either be the version of Ruby installed
        or an error complaining that Ruby wasn’t found.
      </para>
      <para>
        Should you need to install Ruby manually (e.g for an operating
        system such as Windows), you can do so by downloading the latest
        version from http://www.ruby-lang.org/en/downloads/.
        Alternatively, (RVM)[http://beginrescueend.com/rvm/install/]
        (Ruby Version Manager) is a command-line tool that allows you to
        easily install and manage multiple ruby environments with ease.
      </para>
    </sect3>
    <sect3 id="ruby-gems">
      <title>Ruby Gems</title>
      <para>
        Next, we will need to install Ruby Gems. Gems are a standard way
        to package programs or libraries written in Ruby and with Ruby
        Gems it’s possible to install additional dependencies for Ruby
        applications very easily.
      </para>
      <para>
        On OSX, Linux or Windows go to
        <ulink url="http://rubyforge.org/projects/rubygems">http://rubyforge.org/projects/rubygems</ulink>
        and download the latest version of Ruby Gems. Once downloaded,
        open up a terminal, navigate to the folder where this resides
        and enter:
      </para>
      <programlisting>
$&gt; tar xzvf rubygems.tgz
$&gt; cd rubygems
$&gt; sudo ruby setup.rb
</programlisting>
      <para>
        There will likely be a version number included in your download
        and you should make sure to include this when tying the above.
        Finally, a symlink (symbolic link) to tie everything togther
        should be fun as follows:
      </para>
      <para>
        <literal>$ sudo ln -s /usr/bin/gem1.8.17 /usr/bin/gem</literal>
      </para>
      <para>
        To check that Ruby Gems has been correctly installed, type the
        following into your terminal:
      </para>
      <programlisting>
$ gem -v
</programlisting>
    </sect3>
    <sect3 id="sinatra">
      <title>Sinatra</title>
      <para>
        With Ruby Gems setup, we can now easily install Sinatra. For
        Linux or OSX type this in your terminal:
      </para>
      <para>
        <literal>$ sudo gem install sinatra</literal>
      </para>
      <para>
        and if you’re on Windows, enter the following at a command
        prompt:
      </para>
      <para>
        <literal>c:\\ &gt; gem install sinatra</literal>
      </para>
    </sect3>
    <sect3 id="haml-1">
      <title>Haml</title>
      <para>
        As with other DSLs and frameworks, Sinatra supports a wide range
        of different templating engines.
        <ulink url="http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/classes/ERB.html">ERB</ulink>
        is the one most often recommended by the Sinatra camp, however
        as a part of this chapter, we’re going to explore the use of
        <ulink url="http://haml.hamptoncatlin.com/">Haml</ulink> to
        define our application templates.
      </para>
      <para>
        Haml stands for HTML Abstractional Markup Language and is a
        lightweight markup language abstraction that can be used to
        describe HTML without the need to use traditional markup
        language semantics (such as opening and closing tags).
      </para>
      <para>
        Installing Haml can be done in just a line using Ruby Gems as
        follows:
      </para>
      <para>
        <literal>$ gem install haml</literal>
      </para>
    </sect3>
    <sect3 id="mongodb-1">
      <title>MongoDB</title>
      <para>
        If you haven’t already downloaded and installed MongoDB from an
        earlier chapter, please
        <ulink url="http://www.mongodb.org/downloads">do so</ulink> now.
        With Ruby Gems, Mongo can be installed in just one line:
      </para>
      <para>
        <literal>$ gem install mongodb</literal>
      </para>
      <para>
        We now require two further steps to get everything up and
        running.
      </para>
      <sect4 id="data-directories">
        <title>1.Data directories</title>
        <para>
          MongoDB stores data in the bin/data/db folder but won’t
          actually create this directory for you. Navigate to where
          you’ve downloaded and extracted Mongo and run the following
          from terminal:
        </para>
        <programlisting>
sudo mkdir -p /data/db/
sudo chown `id -u` /data/db
</programlisting>
      </sect4>
      <sect4 id="running-and-connecting-to-your-server">
        <title>2.Running and connecting to your server</title>
        <para>
          Once this is done, open up two terminal windows.
        </para>
        <para>
          In the first, cd to your MongoDB bin directory or type in the
          complete path to it. You’ll need to start mongod.
        </para>
        <programlisting>
$ ./bin/mongod
</programlisting>
        <para>
          Finally, in the second terminal, start the mongo shell which
          will connect up to localhost by default.
        </para>
        <programlisting>
$ ./bin/mongo
</programlisting>
      </sect4>
    </sect3>
    <sect3 id="mongodb-ruby-driver-1">
      <title>MongoDB Ruby Driver</title>
      <para>
        As we’ll be using the
        <ulink url="https://github.com/mongodb/mongo-ruby-driver">MongoDB
        Ruby Driver</ulink>, we’ll also require the following gems:
      </para>
      <para>
        The gem for the driver itself:
      </para>
      <programlisting>
$ gem install mongo
</programlisting>
      <para>
        and the driver’s other prerequisite, bson:
      </para>
      <programlisting>
$ gem install bson_ext
</programlisting>
      <para>
        This is basically a collection of extensions used to increase
        serialization speed.
      </para>
      <para>
        That’s it for our prerequisites!.
      </para>
    </sect3>
  </sect2>
  <sect2 id="tutorial">
    <title>Tutorial</title>
    <para>
      To get started, let’s get a local copy of the practical
      application working on our system.
    </para>
    <sect3 id="application-files">
      <title>Application Files</title>
      <para>
        Clone
        <ulink url="http://github.com/addyosmani/backbone-fundamentals">this</ulink>
        repository and navigate to
        <literal>/practicals/stacks/option3</literal>. Now run the
        following lines at the terminal:
      </para>
      <programlisting>
ruby app.rb
</programlisting>
      <para>
        Finally, navigate to <code>http://localhost:4567/todo</code> to
        see the application running successfully.
      </para>
      <para>
        <emphasis role="strong">Note:</emphasis> The Haml layout files
        for Option 3 can be found in the /views folder.
      </para>
      <para>
        The directory structure for our practical application is as
        follows:
      </para>
      <programlisting>
--public
----css
----img
----js
-----script.js
----test
--views
app.rb
</programlisting>
      <para>
        The <literal>public</literal> directory contains the scripts and
        stylesheets for our application and uses HTML5 Boilerplate as a
        base. You can find the Models, Views and Collections for this
        section within <literal>public/js/scripts.js</literal> (however,
        this can of course be expanded into sub-directories for each
        component if desired).
      </para>
      <para>
        <literal>scripts.js</literal> contains the following Backbone
        component definitions:
      </para>
      <programlisting>
--Models
----Todo

--Collections
----TodoList

--Views
---TodoView
---AppView
</programlisting>
      <para>
        <literal>app.rb</literal> is the small Sinatra application that
        powers our backend API.
      </para>
      <para>
        Lastly, the <literal>views</literal> directory hosts the Haml
        source files for our application’s index and templates, both of
        which are compiled to standard HTML markup at runtime.
      </para>
      <para>
        These can be viewed along with other note-worthy snippets of
        code from the application below.
      </para>
    </sect3>
    <sect3 id="backbone">
      <title>Backbone</title>
      <sect4 id="views-2">
        <title>Views</title>
        <para>
          In our main application view (AppView), we want to load any
          previously stored Todo items in our Mongo database when the
          view initializes. This is done below with the line
          <literal>Todos.fetch()</literal> in the
          <literal>initialize()</literal> method where we also bind to
          the relevant events on the <literal>Todos</literal> collection
          for when items are added or changed.
        </para>
        <programlisting language="javascript">
// Our overall **AppView** is the top-level piece of UI.
var AppView = Backbone.View.extend({

    // Instead of generating a new element, bind to the existing skeleton of
    // the App already present in the HTML.
    el: $(&quot;#todoapp&quot;),

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

    // Delegated events for creating new items, and clearing completed ones.
    events: {
      &quot;keypress #new-todo&quot;:  &quot;createOnEnter&quot;,
      &quot;keyup #new-todo&quot;:     &quot;showTooltip&quot;,
      &quot;click .todo-clear a&quot;: &quot;clearCompleted&quot;
    },

    // At initialization
    initialize: function() {
      this.input    = this.$(&quot;#new-todo&quot;);

      Todos.on('add',   this.addOne, this);
      Todos.on('reset', this.addAll, this);
      Todos.on('all',   this.render, this);

      Todos.fetch();
    },

    // Re-rendering the App just means refreshing the statistics -- the rest
    // of the app doesn't change.
    render: function() {
      this.$('#todo-stats').html(this.statsTemplate({
        total:      Todos.length,
        done:   
 ….
</programlisting>
      </sect4>
    </sect3>
    <sect3 id="collections-1">
      <title>Collections</title>
      <para>
        In the TodoList collection below, we’ve set the
        <literal>url</literal> property to point to
        <literal>/api/todos</literal> to reference the collection’s
        location on the server. When we attempt to access this from our
        Sinatra-backed API, it should return a list of all the Todo
        items that have been previously stored in Mongo.
      </para>
      <para>
        For the sake of thoroughness, our API will also support
        returning the data for a specific Todo item via
        <literal>/api/todos/itemID</literal>. We’ll take a look at this
        again when writing the Ruby code powering our backend.
      </para>
      <programlisting language="javascript">
 // Todo Collection

  var TodoList = Backbone.Collection.extend({

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

    // Save all of the todo items under the `&quot;todos&quot;` namespace.
    // localStorage: new Store(&quot;todos&quot;),
    url: '/api/todos',

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

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

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

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

  });
</programlisting>
    </sect3>
    <sect3 id="model">
      <title>Model</title>
      <para>
        The model for our Todo application remains largely unchanged
        from the versions previously covered in this book. It is however
        worth noting that calling the function
        <literal>model.url()</literal> within the below would return the
        relative URL where a specific Todo item could be located on the
        server.
      </para>
      <programlisting language="javascript">

  // Our basic **Todo** model has `text`, `order`, and `done` attributes.
  var Todo = Backbone.Model.extend({
    idAttribute: &quot;_id&quot;,

    // Default attributes for a todo item.
    defaults: function() {
      return {
        done:  false,
        order: Todos.nextOrder()
      };
    },

    // Toggle the `done` state of this todo item.
    toggle: function() {
      this.save({done: !this.get(&quot;done&quot;)});
    }
  });
</programlisting>
    </sect3>
    <sect3 id="rubysinatra">
      <title>Ruby/Sinatra</title>
      <para>
        Now that we’ve defined our main models, views and collections
        let’s get the CRUD operations required by our Backbone
        application supported in our Sinatra API.
      </para>
      <para>
        We want to make sure that for any operations changing underlying
        data (create, update, delete) that our Mongo data store
        correctly reflects these.
      </para>
    </sect3>
    <sect3 id="app.rb">
      <title>app.rb</title>
      <para>
        For <literal>app.rb</literal>, we first define the dependencies
        required by our application. These include Sinatra, Ruby Gems,
        the MongoDB Ruby driver and the JSON gem.
      </para>
      <programlisting language="ruby">
require 'rubygems'
require 'sinatra'
require 'mongo'
require 'json'
</programlisting>
      <para>
        Next, we create a new connection to Mongo, specifying any custom
        configuration desired. If running a multi-threaded application,
        setting the <quote>pool_size</quote> allows us to specify a
        maximum pool size and <quote>timeout</quote> a maximum timeout
        for waiting for old connections to be released to the pool.
      </para>
      <programlisting language="ruby">
DB = Mongo::Connection.new.db(&quot;mydb&quot;, :pool_size =&gt; 5, :timeout =&gt; 5)
</programlisting>
      <para>
        Finally we define the routes to be supported by our API. Note
        that in the first two blocks - one for our application root
        (<literal>/</literal>) and the other for our todo items route
        <literal>/todo</literal> - we’re using Haml for template
        rendering.
      </para>
      <programlisting language="ruby">
class TodoApp &lt; Sinatra::Base

    get '/' do
      haml :index, :attr_wrapper =&gt; '&quot;', :locals =&gt; {:title =&gt; 'hello'}
    end

    get '/todo' do
      haml :todo, :attr_wrapper =&gt; '&quot;', :locals =&gt; {:title =&gt; 'Our Sinatra Todo app'}
    end
</programlisting>
      <para>
        <literal>haml :index</literal> instructs Sinatra to use the
        <literal>views/index.haml</literal> for the application index,
        whilst `<literal>attr_wrapper</literal> is simply defining the
        values to be used for any local variables defined inside the
        template. This similarly applies Todo items with the template
        `views/todo.haml’.
      </para>
      <para>
        The rest of our routes make use of the <literal>params</literal>
        hash and a number of useful helper methods included with the
        MongoDB Ruby driver. For more details on these, please read the
        comments I’ve made inline below:
      </para>
      <programlisting language="ruby">
get '/api/:thing' do
  # query a collection :thing, convert the output to an array, map the _id 
  # to a string representation of the object's _id and finally output to JSON
  DB.collection(params[:thing]).find.to_a.map{|t| from_bson_id(t)}.to_json
end

get '/api/:thing/:id' do
  # get the first document with the id :id in the collection :thing as a single document (rather 
  # than a Cursor, the standard output) using find_one(). Our bson utilities assist with
  # ID conversion and the final output returned is also JSON
  from_bson_id(DB.collection(params[:thing]).find_one(to_bson_id(params[:id]))).to_json
end

post '/api/:thing' do
  # parse the post body of the content being posted, convert to a string, insert into
  # the collection #thing and return the ObjectId as a string for reference
  oid = DB.collection(params[:thing]).insert(JSON.parse(request.body.read.to_s))
  &quot;{\&quot;_id\&quot;: \&quot;#{oid.to_s}\&quot;}&quot;
end

delete '/api/:thing/:id' do
  # remove the item with id :id from the collection :thing, based on the bson
  # representation of the object id
  DB.collection(params[:thing]).remove('_id' =&gt; to_bson_id(params[:id]))
end

put '/api/:thing/:id' do
  # collection.update() when used with $set (as covered earlier) allows us to set single values
  # in this case, the put request body is converted to a string, rejecting keys with the name '_id' for security purposes
  DB.collection(params[:thing]).update({'_id' =&gt; to_bson_id(params[:id])}, {'$set' =&gt; JSON.parse(request.body.read.to_s).reject{|k,v| k == '_id'}})
end

# utilities for generating/converting MongoDB ObjectIds
def to_bson_id(id) BSON::ObjectId.from_string(id) end
def from_bson_id(obj) obj.merge({'_id' =&gt; obj['_id'].to_s}) end

end
</programlisting>
      <para>
        That’s it. The above is extremely lean for an entire API, but
        does allow us to read and write data to support the
        functionality required by our client-side application.
      </para>
      <para>
        For more on what MongoDB and the MongoDB Ruby driver are capable
        of, please do feel free to read their documentation for more
        information.
      </para>
      <para>
        If you’re a developer wishing to take this example further, why
        not try to add some additional capabilities to the service:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            Validation: improved validation of data in the API. What
            more could be done to ensure data sanitization?
          </para>
        </listitem>
        <listitem>
          <para>
            Search: search or filter down Todo items based on a set of
            keywords or within a certain date range
          </para>
        </listitem>
        <listitem>
          <para>
            Pagination: only return the Nth number of Todo items or
            items from a start and end-point
          </para>
        </listitem>
      </itemizedlist>
    </sect3>
    <sect3 id="hamltemplates">
      <title>Haml/Templates</title>
      <para>
        Finally, we move on to the Haml files that define our
        application index (layout.haml) and the template for a specific
        Todo item (todo.haml). Both of these are largely
        self-explanatory, but it’s useful to see the differences between
        the Jade approach we reviewed in the last chapter vs. using Haml
        for this implementation.
      </para>
      <para>
        Note: In our Haml snippets below, the forward slash character is
        used to indicate a comment. When this character is placed at the
        beginning of a line, it wraps all of the text after it into a
        HTML comment. e.g
      </para>
      <para>
        <literal>/ These are templates</literal>
      </para>
      <para>
        compiles to:
      </para>
      <para>
        <literal>&lt;!-- These are templates --&gt;</literal>
      </para>
    </sect3>
    <sect3 id="index.haml">
      <title>index.haml</title>
      <programlisting language="html">
%head
  %meta{'charset' =&gt; 'utf-8'}/
  %title=title
  %meta{'name' =&gt; 'description', 'content' =&gt; ''}/
  %meta{'name' =&gt; 'author', 'content' =&gt; ''}/
  %meta{'name' =&gt; 'viewport', 'content' =&gt; 'width=device-width,initial-scale=1'}/

  / CSS concatenated and minified via ant build script
  %link{'rel' =&gt; 'stylesheet', 'href' =&gt; 'css/style.css'}/
  / end CSS

  %script{'src' =&gt; 'js/libs/modernizr.min.js'}
%body
  %div#container
    %header
    %div#main
      = yield
    %footer
  /! end of #container

  %script{'src' =&gt; 'http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js'}

  / scripts concatenated and minified via ant build script
  %script{'src' =&gt; 'js/mylibs/underscore.js'}
  %script{'src' =&gt; 'js/mylibs/backbone.js'}
  %script{'defer' =&gt; true, 'src' =&gt; 'js/plugins.js'}
  %script{'defer' =&gt; true, 'src' =&gt; 'js/script.js'}
  / end scripts
</programlisting>
    </sect3>
    <sect3 id="todo.haml">
      <title>todo.haml</title>
      <programlisting language="html">
%div#todoapp
  %div.title
    %h1
      Todos
      %div.content
        %div#create-todo
          %input#new-todo{&quot;placeholder&quot; =&gt; &quot;What needs to be done?&quot;, &quot;type&quot; =&gt; &quot;text&quot;}/
          %span.ui-tooltip-top{&quot;style&quot; =&gt; &quot;display:none;&quot;} Press Enter to save this task
        %div#todos
          %ul#todo-list
        %div#todo-stats

/ Templates

%script#item-template{&quot;type&quot; =&gt; &quot;text/template&quot;}
  &lt;div class=&quot;todo &lt;%= done ? 'done' : '' %&gt;&quot;&gt;
  %div.display
    &lt;input class=&quot;check&quot; type=&quot;checkbox&quot; &lt;%= done ? 'checked=&quot;checked&quot;' : '' %&gt; /&gt;
    %div.todo-text 
    %span#todo-destroy
  %div.edit
    %input.todo-input{&quot;type&quot; =&gt; &quot;text&quot;, &quot;value&quot; =&gt;&quot;&quot;}/
  &lt;/div&gt;

%script#stats-template{&quot;type&quot; =&gt; &quot;text/template&quot;}
  &lt;% if (total) { %&gt;
  %span.todo-count
    %span.number &lt;%= remaining %&gt;
    %span.word &lt;%= remaining == 1 ? 'item' : 'items' %&gt;
    left.
  &lt;% } %&gt;
  &lt;% if (done) { %&gt;
  %span.todo-clear
    %a{&quot;href&quot; =&gt; &quot;#&quot;}
      Clear
      %span.number-done &lt;%= done %&gt;
      completed
      %span.word-done &lt;%= done == 1 ? 'item' : 'items' %&gt;
  &lt;% } %&gt;
</programlisting>
    </sect3>
  </sect2>
  <sect2 id="conclusions">
    <title>Conclusions</title>
    <para>
      In this chapter, we looked at creating a Backbone application
      backed by an API powered by Ruby, Sinatra, Haml, MongoDB and the
      MongoDB driver. I personally found developing APIs with Sinatra a
      relatively painless experience and one which I felt was on-par
      with the effort required for the Node/Express implementation of
      the same application.
    </para>
    <para>
      This section is by no means the most comprehensive guide on
      building complex apps using all of the items in this particular
      stack. I do however hope it was an introduction sufficient enough
      to help you decide on what stack to try out for your next project.
    </para>
  </sect2>
  <sect2 id="advanced">
    <title># <a name="advanced">Advanced</a></title>
    <para>
    </para>
  </sect2>
  <sect2 id="modular-javascript">
    <title><a name="modularjs">Modular JavaScript</a></title>
    <para>
      When we say an application is modular, we generally mean it’s
      composed of a set of highly decoupled, distinct pieces of
      functionality stored in modules. As you probably know, loose
      coupling facilitates easier maintainability of apps by removing
      dependencies where possible. When this is implemented efficiently,
      its quite easy to see how changes to one part of a system may
      affect another.
    </para>
    <para>
      Unlike some more traditional programming languages however, the
      current iteration of JavaScript (ECMA-262) doesn’t provide
      developers with the means to import such modules of code in a
      clean, organized manner. It’s one of the concerns with
      specifications that haven’t required great thought until more
      recent years where the need for more organized JavaScript
      applications became apparent.
    </para>
    <para>
      Instead, developers at present are left to fall back on variations
      of the module or object literal patterns. With many of these,
      module scripts are strung together in the DOM with namespaces
      being described by a single global object where it’s still
      possible to incur naming collisions in your architecture. There’s
      also no clean way to handle dependency management without some
      manual effort or third party tools.
    </para>
    <para>
      Whilst native solutions to these problems will be arriving in ES
      Harmony, the good news is that writing modular JavaScript has
      never been easier and you can start doing it today.
    </para>
    <para>
      In this next part of the book, we’re going to look at how to use
      AMD modules and RequireJS for cleanly wrapping units of code in
      your application into manageable modules.
    </para>
  </sect2>
  <sect2 id="organizing-modules-with-requirejs-and-amd">
    <title><a name="organizingmodules">Organizing modules with RequireJS
    and AMD</a></title>
    <para>
      In case you haven’t used it before,
      <ulink url="http://requirejs.org">RequireJS</ulink> is a popular
      script loader written by James Burke - a developer who has been
      quite instrumental in helping shape the AMD module format, which
      we’ll discuss more shortly. Some of RequireJS’s capabilities
      include helping to load multiple script files, helping define
      modules with or without dependencies and loading in non-script
      dependencies such as text files.
    </para>
    <para>
      So, why use RequireJS with Backbone? Although Backbone is
      excellent when it comes to providing a sanitary structure to your
      applications, there are a few key areas where some additional help
      could be used:
    </para>
    <orderedlist numeration="arabic">
      <listitem>
        <para>
          Backbone doesn’t endorse a particular approach to
          modular-development. Although this means it’s quite open-ended
          for developers to opt for classical patterns like the
          module-pattern or Object Literals for structuring their apps
          (which both work fine), it also means developers aren’t sure
          of what works best when other concerns come into play, such as
          dependency management.
        </para>
      </listitem>
    </orderedlist>
    <para>
      RequireJS is compatible with the AMD (Asynchronous Module
      Definition) format, a format which was born from a desire to write
      something better than the <quote>write lots of script tags with
      implicit dependencies and manage them manually</quote> approach to
      development. In addition to allowing you to clearly declare
      dependencies, AMD works well in the browser, supports string IDs
      for dependencies, declaring multiple modules in the same file and
      gives you easy-to-use tools to avoid polluting the global
      namespace.
    </para>
    <orderedlist numeration="arabic">
      <listitem override="2">
        <para>
          Let’s discuss dependency management a little more as it can
          actually be quite challenging to get right if you’re doing it
          by hand. When we write modules in JavaScript, we ideally want
          to be able to handle the reuse of code units intelligently and
          sometimes this will mean pulling in other modules at run-time
          whilst at other times you may want to do this dynamically to
          avoid a large pay-load when the user first hits your
          application.
        </para>
      </listitem>
    </orderedlist>
    <para>
      Think about the GMail web-client for a moment. When users
      initially load up the page on their first visit, Google can simply
      hide widgets such as the chat module until a user has indicated
      (by clicking <quote>expand</quote>) that they wish to use it.
      Through dynamic dependency loading, Google could load up the chat
      module only then, rather than forcing all users to load it when
      the page first initializes. This can improve performance and load
      times and can definitely prove useful when building larger
      applications.
    </para>
    <para>
      I’ve previously written
      <ulink url="http://addyosmani.com/writing-modular-js">a detailed
      article</ulink> covering both AMD and other module formats and
      script loaders in case you’d like to explore this topic further.
      The takeaway is that although it’s perfectly fine to develop
      applications without a script loader or clean module format in
      place, it can be of significant benefit to consider using these
      tools in your application development.
    </para>
    <sect3 id="writing-amd-modules-with-requirejs">
      <title>Writing AMD modules with RequireJS</title>
      <para>
        As discussed above, the overall goal for the AMD format is to
        provide a solution for modular JavaScript that developers can
        use today. The two key concepts you need to be aware of when
        using it with a script-loader are a <literal>define()</literal>
        method for facilitating module definition and a
        <literal>require()</literal> method for handling dependency
        loading. <literal>define()</literal> is used to define named or
        unnamed modules based on the proposal using the following
        signature:
      </para>
      <programlisting language="javascript">
define(
    module_id /*optional*/, 
    [dependencies] /*optional*/, 
    definition function /*function for instantiating the module or object*/
);
</programlisting>
      <para>
        As you can tell by the inline comments, the
        <literal>module_id</literal> is an optional argument which is
        typically only required when non-AMD concatenation tools are
        being used (there may be some other edge cases where it’s useful
        too). When this argument is left out, we call the module
        <quote>anonymous</quote>. When working with anonymous modules,
        the idea of a module’s identity is DRY, making it trivial to
        avoid duplication of filenames and code.
      </para>
      <para>
        Back to the define signature, the dependencies argument
        represents an array of dependencies which are required by the
        module you are defining and the third argument
        (<quote>definition function</quote>) is a function that’s
        executed to instantiate your module. A barebone module
        (compatible with RequireJS) could be defined using
        <literal>define()</literal> as follows:
      </para>
      <programlisting language="javascript">
// A module ID has been omitted here to make the module anonymous

define(['foo', 'bar'], 
    // module definition function
    // dependencies (foo and bar) are mapped to function parameters
    function ( foo, bar ) {
        // return a value that defines the module export
        // (i.e the functionality we want to expose for consumption)

        // create your module here
        var myModule = {
            doStuff:function(){
                console.log('Yay! Stuff');
            }
        }

        return myModule;
});
</programlisting>
      <sect4 id="alternate-syntax">
        <title>Alternate syntax</title>
        <para>
          There is also a
          <ulink url="http://requirejs.org/docs/whyamd.html#sugar">sugared
          version</ulink> of <literal>define()</literal> available that
          allows you to declare your dependencies as local variables
          using <literal>require()</literal>. This will feel familiar to
          anyone who’s used node, and can be easier to add or remove
          dependencies. Here is the previous snippet using the alternate
          syntax:
        </para>
        <programlisting language="javascript">
// A module ID has been omitted here to make the module anonymous

define(function(require){
        // module definition function
    // dependencies (foo and bar) are defined as local vars
    var foo = require('foo'),
        bar = require('bar');

        // return a value that defines the module export
        // (i.e the functionality we want to expose for consumption)

        // create your module here
        var myModule = {
            doStuff:function(){
                console.log('Yay! Stuff');
            }
        }

        return myModule;
});
</programlisting>
        <para>
          The <literal>require()</literal> method is typically used to
          load code in a top-level JavaScript file or within a module
          should you wish to dynamically fetch dependencies. An example
          of its usage is:
        </para>
        <programlisting language="javascript">
// Consider 'foo' and 'bar' are two external modules
// In this example, the 'exports' from the two modules loaded are passed as
// function arguments to the callback (foo and bar)
// so that they can similarly be accessed

require(['foo', 'bar'], function ( foo, bar ) {
        // rest of your code here
        foo.doSomething();
});
</programlisting>
        <para>
          <emphasis role="strong">Wrapping modules, views and other
          components with AMD</emphasis>
        </para>
        <para>
          Now that we’ve taken a look at how to define AMD modules,
          let’s review how to go about wrapping components like views
          and collections so that they can also be easily loaded as
          dependencies for any parts of your application that require
          them. At it’s simplest, a Backbone model may just require
          Backbone and Underscore.js. These are considered it’s
          dependencies and so, to write an AMD model module, we would
          simply do this:
        </para>
        <programlisting language="javascript">
define(['underscore', 'backbone'], function(_, Backbone) {
  var myModel = Backbone.Model.extend({

    // Default attributes 
    defaults: {
      content: &quot;hello world&quot;,
    },

    // A dummy initialization method
    initialize: function() {
    },

    clear: function() {
      this.destroy();
      this.view.remove();
    }

  });
  return myModel;
});
</programlisting>
        <para>
          Note how we alias Underscore.js’s instance to
          <literal>_</literal> and Backbone to just
          <literal>Backbone</literal>, making it very trivial to convert
          non-AMD code over to using this module format. For a view
          which might require other dependencies such as jQuery, this
          can similarly be done as follows:
        </para>
        <programlisting language="javascript">
define([
  'jquery',
  'underscore', 
  'backbone',
  'collections/mycollection',
  'views/myview'
  ], function($, _, Backbone, myCollection, myView){

  var AppView = Backbone.View.extend({
  ...
</programlisting>
        <para>
          Aliasing to the dollar-sign (<literal>$</literal>), once again
          makes it very easy to encapsulate any part of an application
          you wish using AMD.
        </para>
      </sect4>
    </sect3>
  </sect2>
  <sect2 id="keeping-your-templates-external-using-requirejs-and-the-text-plugin">
    <title><a name="externaltemplates">Keeping Your Templates External
    Using RequireJS And The Text Plugin</a></title>
    <para>
      Moving your [Underscore/Mustache/Handlebars] templates to external
      files is actually quite straight-forward. As this application
      makes use of RequireJS, I’ll discuss how to implement external
      templates using this specific script loader.
    </para>
    <para>
      RequireJS has a special plugin called text.js which is used to
      load in text file dependencies. To use the text plugin, simply
      follow these simple steps:
    </para>
    <orderedlist numeration="arabic">
      <listitem>
        <para>
          Download the plugin from
          http://requirejs.org/docs/download.html#text and place it in
          either the same directory as your application’s main JS file
          or a suitable sub-directory.
        </para>
      </listitem>
      <listitem>
        <para>
          Next, include the text.js plugin in your initial RequireJS
          configuration options. In the code snippet below, we assume
          that RequireJS is being included in our page prior to this
          code snippet being executed. Any of the other scripts being
          loaded are just there for the sake of example.
        </para>
      </listitem>
    </orderedlist>
    <programlisting language="javascript">
require.config( {
    paths: {
        'backbone':         'libs/AMDbackbone-0.5.3',
        'underscore':       'libs/underscore-1.2.2',
        'text':             'libs/require/text',
        'jquery':           'libs/jQuery-1.7.1',
        'json2':            'libs/json2',
        'datepicker':       'libs/jQuery.ui.datepicker',
        'datepickermobile': 'libs/jquery.ui.datepicker.mobile',
        'jquerymobile':     'libs/jquery.mobile-1.0'
    },
    baseUrl: 'app'
} );
</programlisting>
    <orderedlist numeration="arabic">
      <listitem override="3">
        <para>
          When the <literal>text!</literal> prefix is used for a
          dependency, RequireJS will automatically load the text plugin
          and treat the dependency as a text resource. A typical example
          of this in action may look like..
        </para>
      </listitem>
    </orderedlist>
    <programlisting language="javascript">
require(['js/app', 'text!templates/mainView.html'],
    function(app, mainView){
        // the contents of the mainView file will be
        // loaded into mainView for usage.
    }
);
</programlisting>
    <orderedlist numeration="arabic">
      <listitem override="4">
        <para>
          Finally we can use the text resource that’s been loaded for
          templating purposes. You’re probably used to storing your HTML
          templates inline using a script with a specific identifier.
        </para>
      </listitem>
    </orderedlist>
    <para>
      With Underscore.js’s micro-templating (and jQuery) this would
      typically be:
    </para>
    <para>
      HTML:
    </para>
    <programlisting>
&lt;script type=&quot;text/template&quot; id=&quot;mainViewTemplate&quot;&gt;
    &lt;% _.each( person, function( person_item ){ %&gt;
        &lt;li&gt;&lt;%= person_item.get(&quot;name&quot;) %&gt;&lt;/li&gt;  
    &lt;% }); %&gt;
&lt;/script&gt;
</programlisting>
    <para>
      JS:
    </para>
    <programlisting language="javascript">
var compiled_template = _.template( $('#mainViewTemplate').html() );
</programlisting>
    <para>
      With RequireJS and the text plugin however, it’s as simple as
      saving your template into an external text file (say,
      <literal>mainView.html</literal>) and doing the following:
    </para>
    <programlisting language="javascript">
require(['js/app', 'text!templates/mainView.html'],
    function(app, mainView){

        var compiled_template = _.template( mainView );
    }
);
</programlisting>
    <para>
      That’s it!. You can then go applying your template to a view in
      Backbone doing something like:
    </para>
    <programlisting language="javascript">
collection.someview.el.html( compiled_template( { results: collection.models } ) );
</programlisting>
    <para>
      All templating solutions will have their own custom methods for
      handling template compilation, but if you understand the above,
      substituting Underscore’s micro-templating for any other solution
      should be fairly trivial.
    </para>
    <para>
      <emphasis role="strong">Note:</emphasis> You may also be
      interested in looking at
      <ulink url="https://github.com/ZeeAgency/requirejs-tpl">Require.js
      tpl</ulink>. It’s an AMD-compatible version of the Underscore
      templating system that also includes support for optimization
      (pre-compiled templates) which can lead to better performance and
      no evals. I have yet to use it myself, but it comes as a
      recommended resource.
    </para>
  </sect2>
  <sect2 id="optimizing-backbone-apps-for-production-with-the-requirejs-optimizer">
    <title><a name="optimizingrequirejs">Optimizing Backbone apps for
    production with the RequireJS Optimizer</a></title>
    <para>
      As experienced developers may know, an essential final step when
      writing both small and large JavaScript web applications is the
      build process. The majority of non-trivial apps are likely to
      consist of more than one or two scripts and so optimizing,
      minimizing and concatenating your scripts prior to pushing them to
      production will require your users to download a reduced number
      (if not just one) script file.
    </para>
    <para>
      Note: If you haven’t looked at build processes before and this is
      your first time hearing about them, you might find
      <ulink url="http://addyosmani.com/blog/client-side-build-process/">my
      post and screencast on this topic</ulink> useful.
    </para>
    <para>
      With some other structural JavaScript frameworks, my
      recommendation would normally be to implicitly use YUI Compressor
      or Google’s closure compiler tools, but we have a slightly more
      elegant method available, when it comes to Backbone if you’re
      using RequireJS. RequireJS has a command line optimization tool
      called r.js which has a number of capabilities, including:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Concatenating specific scripts and minifying them using
          external tools such as UglifyJS (which is used by default) or
          Google’s Closure Compiler for optimal browser delivery, whilst
          preserving the ability to dynamically load modules
        </para>
      </listitem>
      <listitem>
        <para>
          Optimizing CSS and stylesheets by inlining CSS files imported
          using @import, stripping out comments etc.
        </para>
      </listitem>
      <listitem>
        <para>
          The ability to run AMD projects in both Node and Rhino (more
          on this later)
        </para>
      </listitem>
    </itemizedlist>
    <para>
      You’ll notice that I mentioned the word <quote>specific</quote> in
      the first bullet point. The RequireJS optimizer only concatenates
      module scripts that have been specified in arrays of string
      literals passed to top-level (i.e non-local) require and define
      calls. As clarified by the
      <ulink url="http://requirejs.org/docs/optimization.html">optimizer
      docs</ulink> this means that Backbone modules defined like this:
    </para>
    <programlisting language="javascript">
define(['jquery','backbone','underscore', 'collections/sample','views/test'], 
    function($,Backbone, _, Sample, Test){
        //...
    });
</programlisting>
    <para>
      will combine fine, however inline dependencies such as:
    </para>
    <programlisting language="javascript">
var models = someCondition ? ['models/ab','models/ac'] : ['models/ba','models/bc'];
</programlisting>
    <para>
      will be ignored. This is by design as it ensures that dynamic
      dependency/module loading can still take place even after
      optimization.
    </para>
    <para>
      Although the RequireJS optimizer works fine in both Node and Java
      environments, it’s strongly recommended to run it under Node as it
      executes significantly faster there. In my experience, it’s a
      piece of cake to get setup with either environment, so go for
      whichever you feel most comfortable with.
    </para>
    <para>
      To get started with r.js, grab it from the
      <ulink url="http://requirejs.org/docs/download.html#rjs">RequireJS
      download page</ulink> or
      <ulink url="http://requirejs.org/docs/optimization.html#download">through
      NPM</ulink>. Now, the RequireJS optimizer works absolutely fine
      for single script and CSS files, but for most cases you’ll want to
      actually optimize an entire Backbone project. You
      <emphasis>could</emphasis> do this completely from the
      command-line, but a cleaner option is using build profiles.
    </para>
    <para>
      Below is an example of a build file taken from the modular jQuery
      Mobile app referenced later in this book. A
      <emphasis role="strong">build profile</emphasis> (commonly named
      <literal>app.build.js</literal>) informs RequireJS to copy all of
      the content of <literal>appDir</literal> to a directory defined by
      <literal>dir</literal> (in this case
      <literal>../release</literal>). This will apply all of the
      necessary optimizations inside the release folder. The
      <literal>baseUrl</literal> is used to resolve the paths for your
      modules. It should ideally be relative to
      <literal>appDir</literal>.
    </para>
    <para>
      Near the bottom of this sample file, you’ll see an array called
      <literal>modules</literal>. This is where you specify the module
      names you wish to have optimized. In this case we’re optimizing
      the main application called <quote>app</quote>, which maps to
      <literal>appDir/app.js</literal>. If we had set the
      <literal>baseUrl</literal> to <quote>scripts</quote>, it would be
      mapped to <literal>appDir/scripts/app.js</literal>.
    </para>
    <programlisting language="javascript">
({
    appDir: &quot;./&quot;,
    baseUrl: &quot;./&quot;,
    dir: &quot;../release&quot;,
    paths: {
       'backbone':          'libs/AMDbackbone-0.5.3',
        'underscore':       'libs/underscore-1.2.2',
        'jquery':           'libs/jQuery-1.7.1',
        'json2':            'libs/json2',
        'datepicker':       'libs/jQuery.ui.datepicker',
        'datepickermobile': 'libs/jquery.ui.datepicker.mobile',
        'jquerymobile':     'libs/jquery.mobile-1.0'
    },
    optimize: &quot;uglify&quot;,
    modules: [
        {
            name: &quot;app&quot;,
            exclude: [
                // If you prefer not to include certain libs exclude them here
            ]
        }
    ]
})
</programlisting>
    <para>
      The way the build system in r.js works is that it traverses app.js
      (whatever modules you’ve passed) and resolved dependencies,
      concatenating them into the final <literal>release</literal>(dir)
      folder. CSS is treated the same way.
    </para>
    <para>
      The build profile is usually placed inside the
      <quote>scripts</quote> or <quote>js</quote> directory of your
      project. As per the docs, this file can however exist anywhere you
      wish, but you’ll need to edit the contents of your build profile
      accordingly.
    </para>
    <para>
      Finally, to run the build, execute the following command once
      inside your <literal>appDir</literal> or
      <literal>appDir/scripts</literal> directory:
    </para>
    <programlisting language="javascript">
node ../../r.js -o app.build.js
</programlisting>
    <para>
      That’s it. As long as you have UglifyJS/Closure tools setup
      correctly, r.js should be able to easily optimize your entire
      Backbone project in just a few key-strokes. If you would like to
      learn more about build profiles, James Burke has a
      <ulink url="https://github.com/jrburke/r.js/blob/master/build/example.build.js">heavily
      commented sample file</ulink> with all the possible options
      available.
    </para>
  </sect2>
  <sect2 id="practical-building-a-modular-backbone-app-with-amd-requirejs">
    <title><a name="practicalrequirejs">Practical: Building a modular
    Backbone app with AMD &amp; RequireJS</a></title>
    <para>
      In this chapter, we’ll look at our first practical Backbone &amp;
      RequireJS project - how to build a modular Todo application. The
      application will allow us to add new todos, edit new todos and
      clear todo items that have been marked as completed. For a more
      advanced practical, see the section on mobile Backbone
      development.
    </para>
    <para>
      The complete code for the application can can be found in the
      <literal>practicals/modular-todo-app</literal> folder of this repo
      (thanks to Thomas Davis and Jérôme Gravel-Niquet). Alternatively
      grab a copy of my side-project
      <ulink url="https://github.com/addyosmani/todomvc">TodoMVC</ulink>
      which contains the sources to both AMD and non-AMD versions.
    </para>
    <para>
      <emphasis role="strong">Note:</emphasis> Thomas may be covering a
      practical on this exercise in more detail on
      <ulink url="http://backbonetutorials.com">backbonetutorials.com</ulink>
      at some point soon, but for this section I’ll be covering what I
      consider the core concepts.
    </para>
    <sect3 id="overview">
      <title>Overview</title>
      <para>
        Writing a <quote>modular</quote> Backbone application can be a
        straight-forward process. There are however, some key conceptual
        differences to be aware of if opting to use AMD as your module
        format of choice:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            As AMD isn’t a standard native to JavaScript or the browser,
            it’s necessary to use a script loader (such as RequireJS or
            curl.js) in order to support defining components and modules
            using this module format. As we’ve already reviewed, there
            are a number of advantages to using the AMD as well as
            RequireJS to assist here.
          </para>
        </listitem>
        <listitem>
          <para>
            Models, views, controllers and routers need to be
            encapsulated <emphasis>using</emphasis> the AMD-format. This
            allows each component of our Backbone application to cleanly
            manage dependencies (e.g collections required by a view) in
            the same way that AMD allows non-Backbone modules to.
          </para>
        </listitem>
        <listitem>
          <para>
            Non-Backbone components/modules (such as utilities or
            application helpers) can also be encapsulated using AMD. I
            encourage you to try developing these modules in such a way
            that they can both be used and tested independent of your
            Backbone code as this will increase their ability to be
            re-used elsewhere.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        Now that we’ve reviewed the basics, let’s take a look at
        developing our application. For reference, the structure of our
        app is as follows:
      </para>
      <programlisting>
index.html
...js/
    main.js
    .../models
            todo.js
    .../views
            app.js
            todos.js
    .../collections
            todos.js
    .../templates
            stats.html
            todos.html
    ../libs
        .../backbone
        .../jquery
        .../underscore
        .../require
                require.js
                text.js
...css/
</programlisting>
    </sect3>
    <sect3 id="markup">
      <title>Markup</title>
      <para>
        The markup for the application is relatively simple and consists
        of three primary parts: an input section for entering new todo
        items (<literal>create-todo</literal>), a list section to
        display existing items (which can also be edited in-place)
        (<literal>todo-list</literal>) and finally a section summarizing
        how many items are left to be completed
        (<literal>todo-stats</literal>).
      </para>
      <programlisting>
&lt;div id=&quot;todoapp&quot;&gt;

      &lt;div class=&quot;content&quot;&gt;

        &lt;div id=&quot;create-todo&quot;&gt;
          &lt;input id=&quot;new-todo&quot; placeholder=&quot;What needs to be done?&quot; type=&quot;text&quot; /&gt;
          &lt;span class=&quot;ui-tooltip-top&quot;&gt;Press Enter to save this task&lt;/span&gt;
        &lt;/div&gt;

        &lt;div id=&quot;todos&quot;&gt;
          &lt;ul id=&quot;todo-list&quot;&gt;&lt;/ul&gt;
        &lt;/div&gt;

        &lt;div id=&quot;todo-stats&quot;&gt;&lt;/div&gt;

      &lt;/div&gt;

&lt;/div&gt;
</programlisting>
      <para>
        The rest of the tutorial will now focus on the JavaScript side
        of the practical.
      </para>
    </sect3>
    <sect3 id="configuration-options">
      <title>Configuration options</title>
      <para>
        If you’ve read the earlier chapter on AMD, you may have noticed
        that explicitly needing to define each dependency a Backbone
        module (view, collection or other module) may require with it
        can get a little tedious. This can however be improved.
      </para>
      <para>
        In order to simplify referencing common paths the modules in our
        application may use, we use a RequireJS
        <ulink url="http://requirejs.org/docs/api.html#config">configuration
        object</ulink>, which is typically defined as a top-level script
        file. Configuration objects have a number of useful
        capabilities, the most useful being mode name-mapping. Name-maps
        are basically a key:value pair, where the key defines the alias
        you wish to use for a path and the value represents the true
        location of the path.
      </para>
      <para>
        In the code-sample below, you can see some typical examples of
        common name-maps which include: <literal>backbone</literal>,
        <literal>underscore</literal>, <literal>jquery</literal> and
        depending on your choice, the RequireJS <literal>text</literal>
        plugin, which assists with loading text assets like templates.
      </para>
      <para>
        <emphasis role="strong">main.js</emphasis>
      </para>
      <programlisting language="javascript">
require.config({
  baseUrl:'../',
  paths: {
    jquery: 'libs/jquery/jquery-min',
    underscore: 'libs/underscore/underscore-min',
    backbone: 'libs/backbone/backbone-optamd3-min',
    text: 'libs/require/text'
  }
});

require(['views/app'], function(AppView){
  var app_view = new AppView;
});
</programlisting>
      <para>
        The <literal>require()</literal> at the end of our main.js file
        is simply there so we can load and instantiation the primary
        view for our application (<literal>views/app.js</literal>).
        You’ll commonly see both this and the configuration object
        included the most top-level script file for a project.
      </para>
      <para>
        In addition to offering name-mapping, the configuration object
        can be used to define additional properties such as
        <literal>waitSeconds</literal> - the number of seconds to wait
        before script loading times out and <literal>locale</literal>,
        should you wish to load up i18n bundles for custom languages.
        The <literal>baseUrl</literal> is simply the path to use for
        module lookups.
      </para>
      <para>
        For more information on configuration objects, please feel free
        to check out the excellent guide to them in the
        <ulink url="http://requirejs.org/docs/api.html#config">RequireJS
        docs</ulink>.
      </para>
    </sect3>
    <sect3 id="modularizing-our-models-views-and-collections">
      <title>Modularizing our models, views and collections</title>
      <para>
        Before we dive into AMD-wrapped versions of our Backbone
        components, let’s review a sample of a non-AMD view. The
        following view listens for changes to its model (a Todo item)
        and re-renders if a user edits the value of the item.
      </para>
      <programlisting language="javascript">
var TodoView = Backbone.View.extend({

    //... is a list tag.
    tagName:  &quot;li&quot;,

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

    // The DOM events specific to an item.
    events: {
      &quot;click .check&quot;              : &quot;toggleDone&quot;,
      &quot;dblclick div.todo-content&quot; : &quot;edit&quot;,
      &quot;click span.todo-destroy&quot;   : &quot;clear&quot;,
      &quot;keypress .todo-input&quot;      : &quot;updateOnEnter&quot;
    },

    // The TodoView listens for changes to its model, re-rendering. Since there's
    // a one-to-one correspondence between a **Todo** and a **TodoView** in this
    // app, we set a direct reference on the model for convenience.
    initialize: function() {      
      this.model.bind('change', this.render, this);
      this.model.view = this;
    },
    ...
</programlisting>
      <para>
        Note how for templating the common practice of referencing a
        script by an ID (or other selector) and obtaining its value is
        used. This of course requires that the template being accessed
        is implicitly defined in our markup. The following is the
        <quote>embedded</quote> version of our template being referenced
        above:
      </para>
      <programlisting>
&lt;script type=&quot;text/template&quot; id=&quot;item-template&quot;&gt;
      &lt;div class=&quot;todo &lt;%= done ? 'done' : '' %&gt;&quot;&gt;
        &lt;div class=&quot;display&quot;&gt;
          &lt;input class=&quot;check&quot; type=&quot;checkbox&quot; &lt;%= done ? 'checked=&quot;checked&quot;' : '' %&gt; /&gt;
          &lt;div class=&quot;todo-content&quot;&gt;&lt;/div&gt;
          &lt;span class=&quot;todo-destroy&quot;&gt;&lt;/span&gt;
        &lt;/div&gt;
        &lt;div class=&quot;edit&quot;&gt;
          &lt;input class=&quot;todo-input&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;
        &lt;/div&gt;
      &lt;/div&gt;
&lt;/script&gt;
</programlisting>
      <para>
        Whilst there is nothing wrong with the template itself, once we
        begin to develop larger applications requiring multiple
        templates, including them all in our markup on page-load can
        quickly become both unmanageable and come with performance
        costs. We’ll look at solving this problem in a minute.
      </para>
      <para>
        Let’s now take a look at the AMD-version of our view. As
        discussed earlier, the <quote>module</quote> is wrapped using
        AMD’s <literal>define()</literal> which allows us to specify the
        dependencies our view requires. Using the mapped paths to
        <quote>jquery</quote> etc. simplifies referencing common
        dependencies and instances of dependencies are themselves mapped
        to local variables that we can access (e.g <quote>jquery</quote>
        is mapped to <literal>$</literal>).
      </para>
      <para>
        <emphasis role="strong">views/todos.js</emphasis>
      </para>
      <programlisting language="javascript">
define([
  'jquery', 
  'underscore', 
  'backbone',
  'text!templates/todos.html'
  ], function($, _, Backbone, todosTemplate){
  var TodoView = Backbone.View.extend({

    //... is a list tag.
    tagName:  &quot;li&quot;,

    // Cache the template function for a single item.
    template: _.template(todosTemplate),

    // The DOM events specific to an item.
    events: {
      &quot;click .check&quot;              : &quot;toggleDone&quot;,
      &quot;dblclick div.todo-content&quot; : &quot;edit&quot;,
      &quot;click span.todo-destroy&quot;   : &quot;clear&quot;,
      &quot;keypress .todo-input&quot;      : &quot;updateOnEnter&quot;
    },

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

    // Re-render the contents of the todo item.
    render: function() {
      $(this.el).html(this.template(this.model.toJSON()));
      this.setContent();
      return this;
    },

    // Use `jQuery.text` to set the contents of the todo item.
    setContent: function() {
      var content = this.model.get('content');
      this.$('.todo-content').text(content);
      this.input = this.$('.todo-input');
      this.input.bind('blur', this.close);
      this.input.val(content);
    },
    ...
</programlisting>
      <para>
        From a maintenance perspective, there’s nothing logically
        different in this version of our view, except for how we
        approach templating.
      </para>
      <para>
        Using the RequireJS text plugin (the dependency marked
        <literal>text</literal>), we can actually store all of the
        contents for the template we looked at earlier in an external
        file (todos.html).
      </para>
      <para>
        <emphasis role="strong">templates/todos.html</emphasis>
      </para>
      <programlisting language="html">
&lt;div class=&quot;todo &lt;%= done ? 'done' : '' %&gt;&quot;&gt;
    &lt;div class=&quot;display&quot;&gt;
      &lt;input class=&quot;check&quot; type=&quot;checkbox&quot; &lt;%= done ? 'checked=&quot;checked&quot;' : '' %&gt; /&gt;
      &lt;div class=&quot;todo-content&quot;&gt;&lt;/div&gt;
      &lt;span class=&quot;todo-destroy&quot;&gt;&lt;/span&gt;
    &lt;/div&gt;
    &lt;div class=&quot;edit&quot;&gt;
      &lt;input class=&quot;todo-input&quot; type=&quot;text&quot; value=&quot;&quot; /&gt;
    &lt;/div&gt;
&lt;/div&gt;
</programlisting>
      <para>
        There’s no longer a need to be concerned with IDs for the
        template as we can map it’s contents to a local variable (in
        this case <literal>todosTemplate</literal>). We then simply pass
        this to the Underscore.js templating function
        <literal>_.template()</literal> the same way we normally would
        have the value of our template script.
      </para>
      <para>
        Next, let’s look at how to define models as dependencies which
        can be pulled into collections. Here’s an AMD-compatible model
        module, which has two default values: a
        <literal>content</literal> attribute for the content of a Todo
        item and a boolean <literal>done</literal> state, allowing us to
        trigger whether the item has been completed or not.
      </para>
      <para>
        <emphasis role="strong">models/todo.js</emphasis>
      </para>
      <programlisting language="javascript">
define(['underscore', 'backbone'], function(_, Backbone) {
  var TodoModel = Backbone.Model.extend({

    // Default attributes for the todo.
    defaults: {
      // Ensure that each todo created has `content`.
      content: &quot;empty todo...&quot;,
      done: false
    },

    initialize: function() {
    },

    // Toggle the `done` state of this todo item.
    toggle: function() {
      this.save({done: !this.get(&quot;done&quot;)});
    },

    // Remove this Todo from *localStorage* and delete its view.
    clear: function() {
      this.destroy();
      this.view.remove();
    }

  });
  return TodoModel;
});
</programlisting>
      <para>
        As per other types of dependencies, we can easily map our model
        module to a local variable (in this case
        <literal>Todo</literal>) so it can be referenced as the model to
        use for our <literal>TodosCollection</literal>. This collection
        also supports a simple <literal>done()</literal> filter for
        narrowing down Todo items that have been completed and a
        <literal>remaining()</literal> filter for those that are still
        outstanding.
      </para>
      <para>
        <emphasis role="strong">collections/todos.js</emphasis>
      </para>
      <programlisting language="javascript">
define([
  'underscore', 
  'backbone', 
  'libs/backbone/localstorage', 
  'models/todo'
  ], function(_, Backbone, Store, Todo){

    var TodosCollection = Backbone.Collection.extend({

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

    // Save all of the todo items under the `&quot;todos&quot;` namespace.
    localStorage: new Store(&quot;todos&quot;),

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

    // Filter down the list to only todo items that are still not finished.
    remaining: function() {
      return this.without.apply(this, this.done());
    },
    ...
</programlisting>
      <para>
        In addition to allowing users to add new Todo items from views
        (which we then insert as models in a collection), we ideally
        also want to be able to display how many items have been
        completed and how many are remaining. We’ve already defined
        filters that can provide us this information in the above
        collection, so let’s use them in our main application view.
      </para>
      <para>
        <emphasis role="strong">views/app.js</emphasis>
      </para>
      <programlisting language="javascript">
define([
  'jquery',
  'underscore', 
  'backbone',
  'collections/todos',
  'views/todos',
  'text!templates/stats.html'
  ], function($, _, Backbone, Todos, TodoView, statsTemplate){

  var AppView = Backbone.View.extend({

    // Instead of generating a new element, bind to the existing skeleton of
    // the App already present in the HTML.
    el: $(&quot;#todoapp&quot;),

    // Our template for the line of statistics at the bottom of the app.
    statsTemplate: _.template(statsTemplate),

    // ...events, initialize() etc. can be seen in the complete file

    // Re-rendering the App just means refreshing the statistics -- the rest
    // of the app doesn't change.
    render: function() {
      var done = Todos.done().length;
      this.$('#todo-stats').html(this.statsTemplate({
        total:      Todos.length,
        done:       Todos.done().length,
        remaining:  Todos.remaining().length
      }));
    },
    ...
</programlisting>
      <para>
        Above, we map the second template for this project,
        <literal>templates/stats.html</literal> to
        <literal>statsTemplate</literal> which is used for rendering the
        overall <literal>done</literal> and <literal>remaining</literal>
        states. This works by simply passing our template the length of
        our overall Todos collection (<literal>Todos.length</literal> -
        the number of Todo items created so far) and similarly the
        length (counts) for items that have been completed
        (<literal>Todos.done().length</literal>) or are remaining
        (<literal>Todos.remaining().length</literal>).
      </para>
      <para>
        The contents of our <literal>statsTemplate</literal> can be seen
        below. It’s nothing too complicated, but does use ternary
        conditions to evaluate whether we should state there’s <quote>1
        item</quote> or <quote>2 item<i>s</i></quote> in a particular
        state.
      </para>
      <programlisting>
&lt;% if (total) { %&gt;
        &lt;span class=&quot;todo-count&quot;&gt;
          &lt;span class=&quot;number&quot;&gt;&lt;%= remaining %&gt;&lt;/span&gt;
          &lt;span class=&quot;word&quot;&gt;&lt;%= remaining == 1 ? 'item' : 'items' %&gt;&lt;/span&gt; left.
        &lt;/span&gt;
      &lt;% } %&gt;
      &lt;% if (done) { %&gt;
        &lt;span class=&quot;todo-clear&quot;&gt;
          &lt;a href=&quot;#&quot;&gt;
            Clear &lt;span class=&quot;number-done&quot;&gt;&lt;%= done %&gt;&lt;/span&gt;
            completed &lt;span class=&quot;word-done&quot;&gt;&lt;%= done == 1 ? 'item' : 'items' %&gt;&lt;/span&gt;
          &lt;/a&gt;
        &lt;/span&gt;
      &lt;% } %&gt;
</programlisting>
      <para>
        The rest of the source for the Todo app mainly consists of code
        for handling user and application events, but that rounds up
        most of the core concepts for this practical.
      </para>
      <para>
        To see how everything ties together, feel free to grab the
        source by cloning this repo or browse it
        <ulink url="https://github.com/addyosmani/backbone-fundamentals/tree/master/practicals/modular-todo-app">online</ulink>
        to learn more. I hope you find it helpful!.
      </para>
      <para>
        <emphasis role="strong">Note:</emphasis> While this first
        practical doesn’t use a build profile as outlined in the chapter
        on using the RequireJS optimizer, we will be using one in the
        section on building mobile Backbone applications.
      </para>
    </sect3>
  </sect2>
  <sect2 id="decoupling-backbone-with-the-mediator-and-facade-patterns">
    <title><a name="decouplingbackbone">Decoupling Backbone with the
    Mediator and Facade patterns</a></title>
    <para>
      In this section we’ll discuss applying some of the concepts I
      cover in my article on
      <ulink url="http://addyosmani.com/largescalejavascript">Large-scale
      JavaScript Application development</ulink> to Backbone.
    </para>
    <sect3 id="summary-1">
      <title>Summary</title>
      <para>
        At a high-level, one architecture that works for such
        applications is something which is:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">Highly decoupled</emphasis>:
            encouraging modules to only publish and subscribe to events
            of interest rather than directly communicating with each
            other. This helps us to build applications who’s units of
            code aren’t highly tied (coupled) together and can thus be
            reused more easily.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Supports module-level
            security</emphasis>: whereby modules are only able to
            execute behavior they’ve been permitted to. Application
            security is an area which is often overlooked in JavaScript
            applications, but can be quite easily implemented in a
            flexible manner.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Supports failover</emphasis>:
            allowing an application continuing to function even if
            particular modules fail. The typical example I give of this
            is the GMail chat widget. Imagine being able to build
            applications in a way that if one widget on the page fails
            (e.g chat), the rest of your application (mail) can continue
            to function without being affected.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        This is an architecture which has been implemented by a number
        of different companies in the past, including Yahoo! (for their
        modularized homepage - which Nicholas Zakas has
        <ulink url="http://www.youtube.com/watch?v=vXjVFPosQHw">spoken</ulink>
        about) and AOL for some of our upcoming projects.
      </para>
      <para>
        The three design patterns that make this architecture possible
        are the:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">Module pattern</emphasis>: used for
            encapsulating unique blocks of code, where functions and
            variables can be kept either public or private.
            (<quote>private</quote> in the simulation of privacy sense,
            as of course don’t have true privacy in JavaScript)
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Mediator pattern</emphasis>: used
            when the communication between modules may be complex, but
            is still well defined. If it appears a system may have too
            many relationships between modules in your code, it may be
            time to have a central point of control, which is where the
            pattern fits in.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Facade pattern</emphasis>: used for
            providing a convenient higher-level interface to a larger
            body of code, hiding its true underlying complexity
          </para>
        </listitem>
      </itemizedlist>
      <para>
        Their specific roles in this architecture can be found below.
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">Modules</emphasis>: There are almost
            two concepts of what defines a module. As AMD is being used
            as a module wrapper, technically each model, view and
            collection can be considered a module. We then have the
            concept of modules being distinct blocks of code outside of
            just MVC/MV*. For the latter, these types of
            <quote>modules</quote> are primarily concerned with
            broadcasting and subscribing to events of interest rather
            than directly communicating with each other.They are made
            possible through the Mediator pattern.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Mediator</emphasis>: The mediator
            has a varying role depending on just how you wish to
            implement it. In my article, I mention using it as a module
            manager with the ability to start and stop modules at will,
            however when it comes to Backbone, I feel that simplifying
            it down to the role of a central <quote>controller</quote>
            that provides pub/sub capabilities should suffice. One can
            of course go all out in terms of building a module system
            that supports module starting, stopping, pausing etc,
            however the scope of this is outside of this chapter.
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Facade</emphasis>: This acts as a
            secure middle-layer that both abstracts an application core
            (Mediator) and relays messages from the modules back to the
            Mediator so they don’t touch it directly. The Facade also
            performs the duty of application security guard; it checks
            event notifications from modules against a configuration
            (permissions.js, which we will look at later) to ensure
            requests from modules are only processed if they are
            permitted to execute the behavior passed.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        For ease of reference, I sometimes refer to these three patterns
        grouped together as Aura (a word that means subtle, luminous
        light).
      </para>
    </sect3>
    <sect3 id="practical-2">
      <title>Practical</title>
      <para>
        For the practical section of this chapter, we’ll be extending
        the well-known Backbone Todo application using the three
        patterns mentioned above. The complete code for this section can
        be found here: https://github.com/addyosmani/backbone-aura and
        should ideally be run on at minimum, a local HTTP server.
      </para>
      <para>
        The application is broken down into AMD modules that cover
        everything from Backbone models through to application-level
        modules. The views publish events of interest to the rest of the
        application and modules can then subscribe to these event
        notifications.
      </para>
      <para>
        All subscriptions from modules go through a facade (or sandbox).
        What this does is check against the subscriber name and the
        <quote>channel/notification</quote> it’s attempting to subscribe
        to. If a channel <emphasis>doesn’t</emphasis> have permissions
        to be subscribed to (something established through
        permissions.js), the subscription isn’t permitted.
      </para>
      <para>
        <emphasis role="strong">Mediator</emphasis>
      </para>
      <para>
        Found in <literal>aura/mediator.js</literal>
      </para>
      <para>
        Below is a very simple AMD-wrapped implementation of the
        mediator pattern, based on prior work by Ryan Florence. It
        accepts as it’s input an object, to which it attaches
        <literal>publish()</literal> and <literal>subscribe()</literal>
        methods. In a larger application, the mediator can contain
        additional utilities, such as handlers for initializing,
        starting and stopping modules, but for demonstration purposes,
        these two methods should work fine for our needs.
      </para>
      <programlisting language="javascript">
define([], function(obj){

  var channels = {};
  if (!obj) obj = {};

  obj.subscribe = function (channel, subscription) {
    if (!channels[channel]) channels[channel] = [];
    channels[channel].push(subscription);
  };

  obj.publish = function (channel) {
    if (!channels[channel]) return;
    var args = [].slice.call(arguments, 1);
    for (var i = 0, l = channels[channel].length; i &lt; l; i++) {
      channels[channel][i].apply(this, args);
    }
  };

  return obj;

});
</programlisting>
      <para>
        <emphasis role="strong">Facade</emphasis>
      </para>
      <para>
        Found in <literal>aura/facade.js</literal>
      </para>
      <para>
        Next, we have an implementation of the facade pattern. Now the
        classical facade pattern applied to JavaScript would probably
        look a little like this:
      </para>
      <programlisting language="javascript">

var module = (function() {
    var _private = {
        i:5,
        get : function() {
            console.log('current value:' + this.i);
        },
        set : function( val ) {
            this.i = val;
        },
        run : function() {
            console.log('running');
        },
        jump: function(){
            console.log('jumping');
        }
    };
    return {
        facade : function( args ) {
            _private.set(args.val);
            _private.get();
            if ( args.run ) {
                _private.run();
            }
        }
    }
}());

module.facade({run: true, val:10});
//outputs current value: 10, running
</programlisting>
      <para>
        It’s effectively a variation of the module pattern, where
        instead of simply returning an interface of supported methods,
        your API can completely hide the true implementation powering
        it, returning something simpler. This allows the logic being
        performed in the background to be as complex as necessary,
        whilst all the end-user experiences is a simplified API they
        pass options to (note how in our case, a single method
        abstraction is exposed). This is a beautiful way of providing
        APIs that can be easily consumed.
      </para>
      <para>
        That said, to keep things simple, our implementation of an
        AMD-compatible facade will act a little more like a proxy.
        Modules will communicate directly through the facade to access
        the mediator’s <literal>publish()</literal> and
        <literal>subscribe()</literal> methods, however, they won’t as
        such touch the mediator directly.This enables the facade to
        provide application-level validation of any subscriptions and
        publications made.
      </para>
      <para>
        It also allows us to implement a simple, but flexible,
        permissions checker (as seen below) which will validate
        subscriptions made against a permissions configuration to see
        whether it’s permitted or not.
      </para>
      <programlisting language="javascript">
define([ &quot;../aura/mediator&quot; , &quot;../aura/permissions&quot; ], function (mediator, permissions) {

    var facade = facade || {};

    facade.subscribe = function(subscriber, channel, callback){

        // Note: Handling permissions/security is optional here
        // The permissions check can be removed 
        // to just use the mediator directly.

        if(permissions.validate(subscriber, channel)){
            mediator.subscribe( channel, callback );
        }
    }

    facade.publish = function(channel){
        mediator.publish( channel );
    }
    return facade;

});
</programlisting>
      <para>
        <emphasis role="strong">Permissions</emphasis>
      </para>
      <para>
        Found in <literal>aura/permissions.js</literal>
      </para>
      <para>
        In our simple permissions configuration, we support checking
        against subscription requests to establish whether they are
        allowed to clear. This enforces a flexible security layer for
        the application.
      </para>
      <para>
        To visually see how this works, consider changing say,
        permissions -&gt; renderDone -&gt; todoCounter to be false. This
        will completely disable the application from from rendering or
        displaying the counts component for Todo items left (because
        they aren’t allowed to subscribe to that event notification).
        The rest of the Todo app can still however be used without
        issue.
      </para>
      <para>
        It’s a very dumbed down example of the potential for application
        security, but imagine how powerful this might be in a large app
        with a significant number of visual widgets.
      </para>
      <programlisting language="javascript">
define([], function () {

    // Permissions

    // A permissions structure can support checking
    // against subscriptions prior to allowing them 
    // to clear. This enforces a flexible security 
    // layer for your application.

    var permissions = {

        newContentAvailable: {
            contentUpdater:true
        },

        endContentEditing:{
            todoSaver:true
        },

        beginContentEditing:{
            editFocus:true
        },

        addingNewTodo:{
            todoTooltip:true
        },

        clearContent:{
            garbageCollector:true
        },

        renderDone:{
            todoCounter:true //switch to false to see what happens :)
        },

        destroyContent:{
            todoRemover:true
        },

        createWhenEntered:{
            keyboardManager:true
        }

    };

    permissions.validate = function(subscriber, channel){
        var test = permissions[channel][subscriber];
        return test===undefined? false: test;
    };

    return permissions;

});
</programlisting>
      <para>
        <emphasis role="strong">Subscribers</emphasis>
      </para>
      <para>
        Found in <literal>subscribers.js</literal>
      </para>
      <para>
        Subscriber <quote>modules</quote> communicate through the facade
        back to the mediator and perform actions when a notification
        event of a particular name is published.
      </para>
      <para>
        For example, when a user enters in a new piece of text for a
        Todo item and hits <quote>enter</quote> the application
        publishes a notification saying two things: a) a new Todo item
        is available and b) the text content of the new item is X. It’s
        then left up to the rest of the application to do with this
        information whatever it wishes.
      </para>
      <para>
        In order to update your Backbone application to primarily use
        pub/sub, a lot of the work you may end up doing will be moving
        logic coupled inside of specific views to modules outside of it
        which are reactionary.
      </para>
      <para>
        Take the <literal>todoSaver</literal> for example - it’s
        responsibility is saving new Todo items to models once the a
        <literal>notificationName</literal> called
        <quote>newContentAvailable</quote> has fired. If you take a look
        at the permissions structure in the last code sample, you’ll
        notice that <quote>newContentAvailable</quote> is present there.
        If I wanted to prevent subscribers from being able to subscribe
        to this notification, I simply set it to a boolean value of
        <literal>false</literal>.
      </para>
      <para>
        Again, this is a massive oversimplification of how advanced your
        permissions structures could get, but it’s certainly one way of
        controlling what parts of your application can or can’t be
        accessed by specific modules at any time.
      </para>
      <programlisting language="javascript">
define([&quot;jquery&quot;, &quot;underscore&quot;, &quot;aura/facade&quot;], 
function ($, _, facade) {

    // Subscription 'modules' for our views. These take the 
    // the form facade.subscribe( subscriberName, notificationName , callBack )

    // Update view with latest todo content
    // Subscribes to: newContentAvailable

    facade.subscribe('contentUpdater', 'newContentAvailable', function (context) {
        var content = context.model.get('content');
        context.$('.todo-content').text(content);
        context.input = context.$('.todo-input');
        context.input.bind('blur', context.close);
        context.input.val(content);
    });


    // Save models when a user has finishes editing
    // Subscribes to: endContentEditing
    facade.subscribe('todoSaver','endContentEditing', function (context) {
        try {
            context.model.save({
                content: context.input.val()
            });
            $(context.el).removeClass(&quot;editing&quot;);
        } catch (e) {
            //console.log(e);
        }
    });


    // Delete a todo when the user no longer needs it
    // Subscribes to: destroyContent
    facade.subscribe('todoRemover','destroyContent', function (context) {
        try {
            context.model.clear();
        } catch (e) {
            //console.log(e);
        }
    });


    // When a user is adding a new entry, display a tooltip
    // Subscribes to: addingNewTodo
    facade.subscribe('todoTooltip','addingNewTodo', function (context, todo) {
        var tooltip = context.$(&quot;.ui-tooltip-top&quot;);
        var val = context.input.val();
        tooltip.fadeOut();
        if (context.tooltipTimeout) clearTimeout(context.tooltipTimeout);
        if (val == '' || val == context.input.attr('placeholder')) return;
        var show = function () {
                tooltip.show().fadeIn();
            };
        context.tooltipTimeout = _.delay(show, 1000);
    });


    // Update editing UI on switching mode to editing content
    // Subscribes to: beginContentEditing
    facade.subscribe('editFocus','beginContentEditing', function (context) {
        $(context.el).addClass(&quot;editing&quot;);
        context.input.focus();
    });


    // Create a new todo entry 
    // Subscribes to: createWhenEntered
    facade.subscribe('keyboardManager','createWhenEntered', function (context, e, todos) {
        if (e.keyCode != 13) return;
        todos.create(context.newAttributes());
        context.input.val('');
    });



    // A Todo and remaining entry counter
    // Subscribes to: renderDone
    facade.subscribe('todoCounter','renderDone', function (context, Todos) {
        var done = Todos.done().length;
        context.$('#todo-stats').html(context.statsTemplate({
            total: Todos.length,
            done: Todos.done().length,
            remaining: Todos.remaining().length
        }));
    });


    // Clear all completed todos when clearContent is dispatched
    // Subscribes to: clearContent
    facade.subscribe('garbageCollector','clearContent', function (Todos) {
        _.each(Todos.done(), function (todo) {
            todo.clear();
        });
    });


});
</programlisting>
      <para>
        That’s it for this section. If you’ve been intrigued by some of
        the concepts covered, I encourage you to consider taking a look
        at my
        <ulink url="http://addyosmani.com/blog/large-scale-javascript-application-architecture/">slides</ulink>
        on Large-scale JS from the jQuery Summit or my longer post on
        the topic
        <ulink url="http://addyosmani.com/largescalejavascript">here</ulink>
        for more information.
      </para>
    </sect3>
  </sect2>
  <sect2 id="paginating-backbone.js-requests-collections">
    <title><a name="pagination">Paginating Backbone.js Requests &amp;
    Collections</a></title>
    <para>
      Pagination is a ubiquitous problem we often find ourselves needing
      to solve on the web. Perhaps most predominantly when working with
      back-end APIs and JavaScript-heavy clients which consume them.
    </para>
    <para>
      On this topic, we’re going to go through a set of **pagination
      components ** I wrote for Backbone.js, which should hopefully come
      in useful if you’re working on applications which need to tackle
      this problem. They’re part of an extension called
      <ulink url="http://github.com/addyosmani/backbone.paginator">Backbone.Paginator</ulink>.
    </para>
    <para>
      When working with a structural framework like Backbone.js, the
      three types of pagination we are most likely to run into are:
    </para>
    <para>
      **Requests to a service layer (API) **- e.g query for results
      containing the term <quote>Brendan</quote> - if 5,000 results are
      available only display 20 results per page (leaving us with 250
      possible result pages that can be navigated to).
    </para>
    <para>
      This problem actually has quite a great deal more to it, such as
      maintaining persistence of other URL parameters (e.g sort, query,
      order) which can change based on a user’s search configuration in
      a UI. One also had to think of a clean way of hooking views up to
      this pagination so you can easily navigate between pages (e.g
      First, Last, Next, Previous, 1,2,3), manage the number of results
      displayed per page and so on.
    </para>
    <para>
      <emphasis role="strong">Further client-side pagination of data
      returned -</emphasis> e.g we’ve been returned a JSON esponse
      containing 100 results. Rather than displaying all 100 to the
      user, we only display 20 of these results within a navigatable UI
      in the browser.
    </para>
    <para>
      Similar to the request problem, client-pagination has its own
      challenges like navigation once again (Next, Previous, 1,2,3),
      sorting, order, switching the number of results to display per
      page and so on.
    </para>
    <para>
      <emphasis role="strong">Infinite results</emphasis> - with
      services such as Facebook, the concept of numeric pagination is
      instead replaced with a <quote>Load More</quote> or <quote>View
      More</quote> button. Triggering this normally fetches the next
      <quote>page</quote> of N results but rather than replacing the
      previous set of results loaded entirely, we simply append to them
      instead.
    </para>
    <para>
      A request pager which simply appends results in a view rather than
      replacing on each new fetch is effectively an
      <quote>infinite</quote> pager.
    </para>
    <para>
      <emphasis role="strong">Let’s now take a look at exactly what
      we’re getting out of the box:</emphasis>
    </para>
    <para>
      <emphasis><ulink url="http://addyosmani.github.com/backbone.paginator/">Backbone.Paginator</ulink>
      is a set of opinionated components for paginating collections of
      data using Backbone.js. It aims to provide both solutions for
      assisting with pagination of requests to a server (e.g an API) as
      well as pagination of single-loads of data, where we may wish to
      further paginate a collection of N results into M pages within a
      view.</emphasis>
    </para>
  </sect2>
  <sect2 id="paginators-pieces">
    <title>Paginator’s pieces</title>
    <para>
      Backbone.Paginator supports two main pagination components:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <emphasis role="strong">Backbone.Paginator.requestPager</emphasis>:
          For pagination of requests between a client and a server-side
          API
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong">Backbone.Paginator.clientPager</emphasis>:
          For pagination of data returned from a server which you would
          like to further paginate within the UI (e.g 60 results are
          returned, paginate into 3 pages of 20)
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
  <sect2 id="downloads-and-source-code">
    <title>Downloads And Source Code</title>
    <para>
      You can either download the raw source code for the project, fork
      the repository or use one of these links:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Production:
          <ulink url="https://raw.github.com/addyosmani/backbone.baginator/master/dist/backbone.paginator.min.js">production</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          Development:
          <ulink url="https://raw.github.com/addyosmani/backbone.baginator/master/dist/backbone.paginator.js">development
          version</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          Examples + Source :
          <ulink url="https://github.com/addyosmani/backbone.paginator/zipball/v0.153">zipball</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="">Repository</ulink>http://github.com/addyosmani/backbone.paginator)
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
  <sect2 id="live-examples">
    <title>Live Examples</title>
    <para>
      Live previews of both pagination components using the Netflix API
      can be found below. Download the tarball or fork the repository to
      experiment with these examples further.
    </para>
    <para>
      Demo 1:
      <ulink url="http://addyosmani.github.com/backbone.paginator/examples/netflix-request-paging/index.html">Backbone.Paginator.requestPager()</ulink>
    </para>
    <img alt="" class="aligncenter size-large wp-image-4578" height="451" src="img/requestPager.png" style="margin-left:-17px;"  width="600" />
    <para>
      Demo 2:
      <ulink url="http://addyosmani.github.com/backbone.paginator/examples/netflix-client-paging/index.html">Backbone.Paginator.clientPager()</ulink>
    </para>
    <img alt="" class="aligncenter size-full wp-image-4579" height="462" src="img/clientPager.png"  width="600" />
    <para>
      Demo 3:
      <ulink url="http://addyosmani.github.com/backbone.paginator/examples/netflix-infinite-paging/index.html">Infinite
      Pagination (Backbone.Paginator.requestPager())</ulink>
    </para>
    <img alt="" class="aligncenter size-large wp-image-4580" height="451" src="img/infinitepager.png"  width="600" />
  </sect2>
  <sect2 id="paginator.requestpager">
    <title>Paginator.requestPager</title>
    <para>
      In this section we’re going to walkthrough actually using the
      requestPager.
    </para>
    <sect3 id="create-a-new-paginated-collection">
      <title>1. Create a new Paginated collection</title>
      <para>
        First, we define a new Paginated collection using
        <literal>Backbone.Paginator.requestPager()</literal> as follows:
      </para>
      <pre class="javascript" name="code">var PaginatedCollection = Backbone.Paginator.requestPager.extend({
      </pre>
    </sect3>
    <sect3 id="set-the-model-and-base-url-for-the-collection-as-normal">
      <title>2: Set the model and base URL for the collection as
      normal</title>
      <para>
        Within our collection, we then (as normal) specify the model to
        be used with this collection followed by the URL (or base URL)
        for the service providing our data (e.g the Netflix API).
      </para>
      <programlisting language="javascript">
model: model,
        url: 'http://odata.netflix.com/v2/Catalog/Titles?&amp;',
</programlisting>
    </sect3>
    <sect3 id="map-the-attributes-supported-by-your-api-url">
      <title>3. Map the attributes supported by your API (URL)</title>
      <para>
        Next, we’re going to map the request (URL) parameters supported
        by your API or backend data service back to attributes that are
        internally used by Backbone.Paginator.
      </para>
      <para>
        For example: the NetFlix API refers to it’s parameter for
        stating how many results to skip ahead by as
        <literal>$skip</literal> and it’s number of items to return per
        page as <literal>$top</literal> (amongst others). We determine
        these by looking at a sample URL pointing at the service:
      </para>
      <programlisting language="javascript">
http://odata.netflix.com/v2/Catalog/Titles?&amp;callback=callback&amp;$top=30&amp;$skip=30&amp;orderBy=ReleaseYear&amp;$inlinecount=allpages&amp;$format=json&amp;$callback=callback&amp;$filter=substringof%28%27the%27,%20Name%29%20eq%20true&amp;_=1332702202090
</programlisting>
      <para>
        We then simply map these parameters to the relevant Paginator
        equivalents shown on the left hand side of the next snippets to
        get everything working:
      </para>
      <programlisting language="javascript">
        // @param-name for the query field in the 
        // request (e.g query/keywords/search)
        queryAttribute: '$filter',

        // @param-name for number of items to return per request/page
        perPageAttribute: '$top',

        // @param-name for how many results the request should skip ahead to
        skipAttribute: '$skip',

        // @param-name for the direction to sort in
        sortAttribute: '$sort',

        // @param-name for field to sort by
        orderAttribute: '$orderBy',

        // @param-name for the format of the request
        formatAttribute: '$format',

        // @param-name for a custom attribute 
        customAttribute1: '$inlinecount',

        // @param-name for another custom attribute
        customAttribute2: '$callback',
</programlisting>
      <para>
        <emphasis role="strong">Note</emphasis>: you can define support
        for new custom attributes in Backbone.Paginator if needed (e.g
        customAttribute1) for those that may be unique to your service.
      </para>
    </sect3>
    <sect3 id="configure-the-default-pagination-query-and-sort-details-for-the-paginator">
      <title>4. Configure the default pagination, query and sort details
      for the paginator</title>
      <para>
        Now, let’s configure the default values in our collection for
        these parameters so that as a user navigates through the
        paginated UI, requests are able to continue querying with the
        correct field to sort on, the right number of items to return
        per request etc.
      </para>
      <para>
        e.g: If we want to request the:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            1st page of results
          </para>
        </listitem>
        <listitem>
          <para>
            for the search query <quote>superman</quote>
          </para>
        </listitem>
        <listitem>
          <para>
            in JSON format
          </para>
        </listitem>
        <listitem>
          <para>
            sorted by release year
          </para>
        </listitem>
        <listitem>
          <para>
            in ascending order
          </para>
        </listitem>
        <listitem>
          <para>
            where only 30 results are returned per request
          </para>
        </listitem>
      </itemizedlist>
      <para>
        This would look as follows:
      </para>
      <programlisting language="javascript">
        // current page to query from the service
        page: 5,

        // The lowest page index your API allows to be accessed
        firstPage: 0, //some begin with 1

        // how many results to query from the service (i.e how many to return
        // per request)
        perPage: 30,

        // maximum number of pages that can be queried from 
        // the server (only here as a default in case your 
        // service doesn't return the total pages available)
        totalPages: 10,

        // what field should the results be sorted on?
        sortField: 'ReleaseYear',

        // what direction should the results be sorted in?
        sortDirection: 'asc',

        // what would you like to query (search) from the service?
        // as Netflix reqires additional parameters around the query
        // we simply fill these around our search term
        query: &quot;substringof('&quot; + escape('the') + &quot;',Name)&quot;,

        // what format would you like to request results in?
        format: 'json',

        // what other custom parameters for the request do 
        // you require
        // for your application?
        customParam1: 'allpages',

        customParam2: 'callback',
</programlisting>
      <para>
        As the particular API we’re using requires
        <literal>callback</literal> and <literal>allpages</literal>
        parameters to also be passed, we simply define the values for
        these as custom parameters which can be mapped back to
        requestPager as needed.
      </para>
    </sect3>
    <sect3 id="finally-configure-collection.parse-and-were-done">
      <title>5. Finally, configure Collection.parse() and we’re
      done</title>
      <para>
        The last thing we need to do is configure our collection’s
        <literal>parse()</literal> method. We want to ensure we’re
        returning the correct part of our JSON response containing the
        data our collection will be populated with, which below is
        <literal>response.d.results</literal> (for the Netflix API).
      </para>
      <para>
        You might also notice that we’re setting
        <literal>this.totalPages</literal> to the total page count
        returned by the API. This allows us to define the maximum number
        of (result) pages available for the current/last request so that
        we can clearly display this in the UI. It also allows us to
        infuence whether clicking say, a <quote>next</quote> button
        should proceed with a request or not.
      </para>
      <programlisting language="javascript">
parse: function (response) {
            // Be sure to change this based on how your results
            // are structured (e.g d.results is Netflix specific)
            var tags = response.d.results;
            //Normally this.totalPages would equal response.d.__count
            //but as this particular NetFlix request only returns a
            //total count of items for the search, we divide.
            this.totalPages = Math.floor(response.d.__count / this.perPage);
            return tags;
        }
    });

});
</programlisting>
    </sect3>
    <sect3 id="convenience-methods">
      <title>Convenience methods:</title>
      <para>
        For your convenience, the following methods are made available
        for use in your views to interact with the
        <literal>requestPager</literal>:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">Collection.goTo(n)</emphasis> - go
            to a specific page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.requestNextPage()</emphasis>
            - go to the next page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.requestPreviousPage()</emphasis>
            - go to the previous page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.howManyPer(n)</emphasis>
            - set the number of items to display per page
          </para>
        </listitem>
      </itemizedlist>
    </sect3>
  </sect2>
  <sect2 id="paginator.clientpager">
    <title>Paginator.clientPager</title>
    <para>
      The <literal>clientPager</literal> works similar to the
      <literal>requestPager</literal>, except that our configuration
      values influence the pagination of data already returned at a
      UI-level. Whilst not shown (yet) there is also a lot more UI logic
      that ties in with the <literal>clientPager</literal>. An example
      of this can be seen in ‘views/clientPagination.js.
    </para>
    <sect3 id="create-a-new-paginated-collection-with-a-model-and-url">
      <title>1. Create a new paginated collection with a model and
      URL</title>
      <para>
        As with <literal>requestPager</literal>, let’s first create a
        new Paginated <literal>Backbone.Paginator.clientPager</literal>
        collection, with a model and base URL:
      </para>
      <programlisting language="javascript">
var PaginatedCollection = Backbone.Paginator.clientPager.extend({

        model: model,

        url: 'http://odata.netflix.com/v2/Catalog/Titles?&amp;',
</programlisting>
    </sect3>
    <sect3 id="map-the-attributes-supported-by-your-api-url-1">
      <title>2. Map the attributes supported by your API (URL)</title>
      <para>
        We’re similarly going to map request parameter names for your
        API to those supported in the paginator:
      </para>
      <programlisting language="javascript">
        perPageAttribute: '$top',

        skipAttribute: '$skip',

        orderAttribute: '$orderBy',

        customAttribute1: '$inlinecount',

        queryAttribute: '$filter',

        formatAttribute: '$format',

        customAttribute2: '$callback',
</programlisting>
    </sect3>
    <sect3 id="configure-how-to-paginate-data-at-a-ui-level">
      <title>3. Configure how to paginate data at a UI-level</title>
      <para>
        We then get to configuration for the paginated data in the UI.
        <literal>perPage</literal> specifies how many results to return
        from the server whilst <literal>displayPerPage</literal>
        configures how many of the items in returned results to display
        per <quote>page</quote> in the UI. e.g If we request 100 results
        and only display 20 per page, we have 5 sub-pages of results
        that can be navigated through in the UI.
      </para>
      <programlisting language="javascript">
        // M: how many results to query from the service
        perPage: 40,

        // N: how many results to display per 'page' within the UI
        // Effectively M/N = the number of pages the data will be split into.
        displayPerPage: 20,
</programlisting>
    </sect3>
    <sect3 id="configure-the-rest-of-the-request-parameter-default-values">
      <title>4. Configure the rest of the request parameter default
      values</title>
      <para>
        We can then configure default values for the rest of our request
        parameters:
      </para>
      <programlisting language="javascript">
        // current page to query from the service
        page: 1,

        // a default. This should be overridden in the collection's parse()
        // sort direction
        sortDirection: 'asc',

        // sort field
        sortField: 'ReleaseYear',
        //or year(Instant/AvailableFrom)

        // query
        query: &quot;substringof('&quot; + escape('the') + &quot;',Name)&quot;,

        // request format
        format: 'json',

        // custom parameters for the request that may be specific to your
        // application
        customParam1: 'allpages',

        customParam2: 'callback',
</programlisting>
    </sect3>
    <sect3 id="finally-configure-collection.parse-and-were-done-1">
      <title>5. Finally, configure Collection.parse() and we’re
      done</title>
      <para>
        And finally we have our <literal>parse()</literal> method, which
        in this case isn’t concerned with the total number of result
        pages available on the server as we have our own total count of
        pages for the paginated data in the UI.
      </para>
      <programlisting language="javascript">
parse: function (response) {
            var tags = response.d.results;
            return tags;
        }

});
</programlisting>
    </sect3>
    <sect3 id="convenience-methods-1">
      <title>Convenience methods:</title>
      <para>
        As mentioned, your views can hook into a number of convenience
        methods to navigate around UI-paginated data. For
        <literal>clientPager</literal> these include:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">Collection.goTo(n)</emphasis> - go
            to a specific page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.previousPage()</emphasis>
            - go to the previous page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.nextPage()</emphasis> -
            go to the next page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.howManyPer(n)</emphasis>
            - set how many items to display per page
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">Collection.pager(sortBy,
            sortDirection)</emphasis> - update sort on the current view
          </para>
        </listitem>
      </itemizedlist>
    </sect3>
  </sect2>
  <sect2 id="viewstemplates">
    <title>Views/Templates</title>
    <para>
      Although the collection layer is perhaps the most important part
      of Backbone.Paginator, it would be of little use without views
      interacting with it. The project zipball comes with three complete
      examples of using the components with the Netflix API, but here’s
      a sample view and template from the
      <literal>requestPager()</literal> example for those interested in
      learning more:
    </para>
    <para>
      First, we have a view for a pagination bar in our UI that allows
      us to navigate around our paginated collection:
    </para>
    <programlisting language="javascript">
(function ( views ) {

    views.PaginatedView = Backbone.View.extend({

        events: {
            'click a.servernext': 'nextResultPage',
            'click a.serverprevious': 'previousResultPage',
            'click a.orderUpdate': 'updateSortBy',
            'click a.serverlast': 'gotoLast',
            'click a.page': 'gotoPage',
            'click a.serverfirst': 'gotoFirst',
            'click a.serverpage': 'gotoPage',
            'click .serverhowmany a': 'changeCount'

        },

        tagName: 'aside',

        template: _.template($('#tmpServerPagination').html()),

        initialize: function () {

            this.collection.on('reset', this.render, this);
            this.collection.on('change', this.render, this);
            this.$el.appendTo('#pagination');

        },

        render: function () {
            var html = this.template(this.collection.info());
            this.$el.html(html);
        },

        updateSortBy: function (e) {
            e.preventDefault();
            var currentSort = $('#sortByField').val();
            this.collection.updateOrder(currentSort);
        },

        nextResultPage: function (e) {
            e.preventDefault();
            this.collection.requestNextPage();
        },

        previousResultPage: function (e) {
            e.preventDefault();
            this.collection.requestPreviousPage();
        },

        gotoFirst: function (e) {
            e.preventDefault();
            this.collection.goTo(this.collection.information.firstPage);
        },

        gotoLast: function (e) {
            e.preventDefault();
            this.collection.goTo(this.collection.information.lastPage);
        },

        gotoPage: function (e) {
            e.preventDefault();
            var page = $(e.target).text();
            this.collection.goTo(page);
        },

        changeCount: function (e) {
            e.preventDefault();
            var per = $(e.target).text();
            this.collection.howManyPer(per);
        }

    });

})( app.views );
</programlisting>
    <para>
      which we use with a template like this to generate the necessary
      pagination links (more are shown in the full example):
    </para>
    <programlisting language="html">
&lt;span class=&quot;divider&quot;&gt;/&lt;/span&gt;  
        &lt;% if (page &gt; firstPage) { %&gt;  
            &lt;a href=&quot;#&quot; class=&quot;serverprevious&quot;&gt;Previous&lt;/a&gt;  
        &lt;% }else{ %&gt;  
            &lt;span&gt;Previous&lt;/span&gt;  
        &lt;% }%&gt;  
        &lt;% if (page &lt; totalPages) { %&gt;  
            &lt;a href=&quot;#&quot; class=&quot;servernext&quot;&gt;Next&lt;/a&gt;  
        &lt;% } %&gt;  
        &lt;% if (firstPage != page) { %&gt;  
            &lt;a href=&quot;#&quot; class=&quot;serverfirst&quot;&gt;First&lt;/a&gt;  
        &lt;% } %&gt;  
        &lt;% if (lastPage != page) { %&gt;  
            &lt;a href=&quot;#&quot; class=&quot;serverlast&quot;&gt;Last&lt;/a&gt;  
        &lt;% } %&gt;  
        &lt;span class=&quot;divider&quot;&gt;/&lt;/span&gt;  
        &lt;span class=&quot;cell serverhowmany&quot;&gt;  
            Show  
            &lt;a href=&quot;#&quot; class=&quot;selected&quot;&gt;3&lt;/a&gt;  
            |  
            &lt;a href=&quot;#&quot; class=&quot;&quot;&gt;9&lt;/a&gt;  
            |  
            &lt;a href=&quot;#&quot; class=&quot;&quot;&gt;12&lt;/a&gt;  
            per page  
        &lt;/span&gt;  
        &lt;span class=&quot;divider&quot;&gt;/&lt;/span&gt;  
        &lt;span class=&quot;cell first records&quot;&gt;  
            Page: &lt;span class=&quot;current&quot;&gt;&lt;%= page %&gt;&lt;/span&gt;  
            of  
            &lt;span class=&quot;total&quot;&gt;&lt;%= totalPages %&gt;&lt;/span&gt;  
                        shown  
        &lt;/span&gt;  
&lt;span class=&quot;divider&quot;&gt;/&lt;/span&gt;  
    &lt;span class=&quot;cell sort&quot;&gt;  
        &lt;a href=&quot;#&quot; class=&quot;orderUpdate btn small&quot;&gt;Sort by:&lt;/a&gt;  
    &lt;/span&gt;  
    &lt;select id=&quot;sortByField&quot;&gt;  
        &lt;option value=&quot;cid&quot;&gt;Select a field to sort on&lt;/option&gt;  
        &lt;option value=&quot;ReleaseYear&quot;&gt;Release year&lt;/option&gt;  
        &lt;option value=&quot;ShortName&quot;&gt;Alphabetical&lt;/option&gt;  
    &lt;/select&gt;  
&lt;/span&gt;  
</programlisting>
  </sect2>
  <sect2 id="license">
    <title>License</title>
    <para>
      Copyright © 2012 Addy Osmani. Licensed under the MIT license.
    </para>
  </sect2>
  <sect2 id="backbone-jquery-mobile">
    <title>Backbone &amp; jQuery Mobile</title>
    <sect3 id="resolving-the-routing-conflicts">
      <title>Resolving the routing conflicts</title>
      <para>
        The first major hurdle developers typically run into when
        building Backbone applications with jQuery Mobile is that both
        frameworks have their own opinions about how to handle
        application navigation.
      </para>
      <para>
        Backbone’s routers offer an explicit way to define custom
        navigation routes through <literal>Backbone.Router</literal>,
        whilst jQuery Mobile encourages the use of URL hash fragments to
        reference separate <quote>pages</quote> or views in the same
        document. jQuery Mobile also supports automatically pulling in
        external content for links through XHR calls meaning that there
        can be quite a lot of inter-framework confusion about what a
        link pointing at <quote>#photo/id</quote> should actually be
        doing.
      </para>
      <para>
        Some of the solutions that have been previously proposed to
        work-around this problem included manually patching Backbone or
        jQuery Mobile. I discourage opting for these techniques as it
        becomes necessary to manually patch your framework builds when
        new releases get made upstream.
      </para>
      <para>
        There’s also
        <ulink url="https://github.com/azicchetti/jquerymobile-router">jQueryMobile
        router</ulink>, which tries to solve this problem differently,
        however I think my proposed solution is both simpler and allows
        both frameworks to cohabit quite peacefully without the need to
        extend either. What we’re after is a way to prevent one
        framework from listening to hash changes so that we can fully
        rely on the other (e.g. <literal>Backbone.Router</literal>) to
        handle this for us exclusively.
      </para>
      <para>
        Using jQuery Mobile this can be done by setting:
      </para>
      <programlisting language="javascript">
$.mobile.hashListeningEnabled = false;
</programlisting>
      <para>
        prior to initializing any of your other code.
      </para>
      <para>
        I discovered this method looking through some jQuery Mobile
        commits that didn’t make their way into the official docs, but
        am happy to see that they are now covered here
        http://jquerymobile.com/test/docs/api/globalconfig.html in more
        detail.
      </para>
      <para>
        The next question that arises is, if we’re preventing jQuery
        Mobile from listening to URL hash changes, how can we still get
        the benefit of being able to navigate to other sections in a
        document using the built-in transitions and effects supported?
        Good question. This can now be solve by simply calling
        <literal>$.mobile.changePage()</literal> as follows:
      </para>
      <programlisting language="javascript">
var url = '#about',
    effect = 'slideup',
    reverse = false,
    changeHash = false;

$.mobile.changePage( url , { transition: effect}, reverse, changeHash );
</programlisting>
      <para>
        In the above sample, <literal>url</literal> can refer to a URL
        or a hash identifier to navigate to, <literal>effect</literal>
        is simply the transition effect to animate the page in with and
        the final two parameters decide the direction for the transition
        (<literal>reverse</literal>) and whether or not the hash in the
        address bar should be updated (<literal>changeHash</literal>).
        With respect to the latter, I typically set this to false to
        avoid managing two sources for hash updates, but feel free to
        set this to true if you’re comfortable doing so.
      </para>
      <para>
        <emphasis role="strong">Note:</emphasis> For some parallel work
        being done to explore how well the jQuery Mobile Router plugin
        works with Backbone, you may be interested in checking out
        https://github.com/Filirom1/jquery-mobile-backbone-requirejs.
      </para>
    </sect3>
    <sect3 id="practical-a-backbone-requirejsamd-app-with-jquery-mobile">
      <title>Practical: A Backbone, RequireJS/AMD app with jQuery
      Mobile</title>
      <para>
        <emphasis role="strong">Note:</emphasis> The code for this
        practical can be found in
        <literal>practicals/modular-mobile-app</literal>.
      </para>
    </sect3>
    <sect3 id="getting-started-1">
      <title>Getting started</title>
      <para>
        Once you feel comfortable with the
        <ulink url="http://msdn.microsoft.com/en-us/scriptjunkie/hh377172.aspx">Backbone
        fundamentals</ulink> and you’ve put together a rough wireframe
        of the app you may wish to build, start to think about your
        application architecture. Ideally, you’ll want to logically
        separate concerns so that it’s as easy as possible to maintain
        the app in the future.
      </para>
      <para>
        <emphasis role="strong">Namespacing</emphasis>
      </para>
      <para>
        For this application, I opted for the nested namespacing
        pattern. Implemented correctly, this enables you to clearly
        identify if items being referenced in your app are views, other
        modules and so on. This initial structure is a sane place to
        also include application defaults (unless you prefer maintaining
        those in a separate file).
      </para>
      <programlisting language="javascript">
window.mobileSearch = window.mobileSearch || {
    views: {
        appview: new AppView
    },
    routers:{
        workspace:new Workspace()
    },
    utils: utils,
    defaults:{
        resultsPerPage: 16,
        safeSearch: 2,
        maxDate:'',
        minDate:'01/01/1970'
    }
}
</programlisting>
      <para>
        <emphasis role="strong">Models</emphasis>
      </para>
      <para>
        In the Flickly application, there are at least two unique types
        of data that need to be modeled - search results and individual
        photos, both of which contain additional meta-data like photo
        titles. If you simplify this down, search results are actually
        groups of photos in their own right, so the application only
        requires:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            A single model (a photo or <quote>result</quote> entry)
          </para>
        </listitem>
        <listitem>
          <para>
            A result collection (containing a group of result entries)
            for search results
          </para>
        </listitem>
        <listitem>
          <para>
            A photo collection (containing one or more result entries)
            for individual photos or photos with more than one image
          </para>
        </listitem>
      </itemizedlist>
      <para>
        <emphasis role="strong">Views</emphasis>
      </para>
      <para>
        The views we’ll need include an application view, a search
        results view and a photo view. Static views or pages of the
        single-page application which do not require a dynamic element
        to them (e.g an <quote>about</quote> page) can be easily coded
        up in your document’s markup, independent of Backbone.
      </para>
      <para>
        <emphasis role="strong">Routers</emphasis>
      </para>
      <para>
        A number of possible routes need to be taken into consideration:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            Basic search queries <literal>#search/kiwis</literal>
          </para>
        </listitem>
        <listitem>
          <para>
            Search queries with additional parameters (e.g sort,
            pagination) <literal>#search/kiwis/srelevance/p7</literal>
          </para>
        </listitem>
        <listitem>
          <para>
            Queries for specific photos <literal>#photo/93839</literal>
          </para>
        </listitem>
        <listitem>
          <para>
            A default route (no parameters passed)
          </para>
        </listitem>
      </itemizedlist>
      <para>
        This tutorial will be expanded shortly to fully cover the demo
        application. In the mean time, please see the practicals folder
        for the completed application that demonstrates the router
        resolution discussed earlier between Backbone and jQuery Mobile.
      </para>
    </sect3>
    <sect3 id="jquery-mobile-going-beyond-mobile-application-development">
      <title>jQuery Mobile: Going beyond mobile application
      development</title>
      <para>
        The majority of jQM apps I’ve seen in production have been
        developed for the purpose of providing an optimal experience to
        users on mobile devices. Given that the framework was developed
        for this purpose, there’s nothing fundamentally wrong with this,
        but many developers forget that jQM is a UI framework not
        dissimilar to jQuery UI. It’s using the widget factory and is
        capable of being used for a lot more than we give it credit for.
      </para>
      <para>
        If you open up Flickly in a desktop browser, you’ll get an image
        search UI that’s modeled on Google.com, however, review the
        components (buttons, text inputs, tabs) on the page for a
        moment. The desktop UI doesn’t look anything like a mobile
        application yet I’m still using jQM for theming mobile
        components; the tabs, date-picker, sliders - everything in the
        desktop UI is re-using what jQM would be providing users on
        mobile devices. Thanks to some media queries, the desktop UI can
        make optimal use of whitespace, expanding component blocks out
        and providing alternative layouts whilst still making use of jQM
        as a component framework.
      </para>
      <para>
        The benefit of this is that I don’t need to go pulling in jQuery
        UI separately to be able to take advantage of these features.
        Thanks to the recent ThemeRoller my components can look pretty
        much exactly how I would like them to and users of the app can
        get a jQM UI for lower-resolutions and a jQM-ish UI for
        everything else.
      </para>
      <para>
        The takeaway here is just to remember that if you’re not
        (already) going through the hassle of conditional script/style
        loading based on screen-resolution (using matchMedia.js etc),
        there are simpler approaches that can be taken to cross-device
        component theming.
      </para>
    </sect3>
  </sect2>
  <sect2 id="unit-testing">
    <title># <a name="testing">Unit Testing</a></title>
    <para>
    </para>
  </sect2>
</sect1>
<sect1 id="unit-testing-backbone-applications-with-jasmine">
  <title><a name="unittestingjasmine">Unit Testing Backbone Applications
  With Jasmine</a></title>
  <sect2 id="introduction-2">
    <title>Introduction</title>
    <para>
      One definition of unit testing is the process of taking the
      smallest piece of testable code in an application, isolating it
      from the remainder of your codebase and determining if it behaves
      exactly as expected. In this section, we’ll be taking a look at
      how to unit test Backbone applications using a popular JavaScript
      testing framework called
      <ulink url="http://pivotal.github.com/jasmine/">Jasmine</ulink>
      from Pivotal Labs.
    </para>
    <para>
      For an application to be considered <quote>well</quote>-tested,
      distinct functionality should ideally have its own separate unit
      tests where it’s tested against the different conditions you
      expect it to work under. All tests must pass before functionality
      is considered <quote>complete</quote>. This allows developers to
      both modify a unit of code and it’s dependencies with a level of
      confidence about whether these changes have caused any breakage.
    </para>
    <para>
      As a basic example of unit testing is where a developer may wish
      to assert whether passing specific values through to a sum
      function results in the correct output being returned. For an
      example more relevant to this book, we may wish to assert whether
      a user adding a new Todo item to a list correctly adds a Model of
      a specific type to a Todos Collection.
    </para>
    <para>
      When building modern web-applications, it’s typically considered
      best-practice to include automated unit testing as a part of your
      development process. Whilst we’ll be focusing on Jasmine as a
      solution for this, there are a number of other alternatives worth
      considering, including QUnit.
    </para>
  </sect2>
  <sect2 id="jasmine">
    <title>Jasmine</title>
    <para>
      Jasmine describes itself as a behavior-driven development (BDD)
      framework for testing JavaScript code. Before we jump into how the
      framework works, it’s useful to understand exactly what
      <ulink url="http://en.wikipedia.org/wiki/Behavior_Driven_Development">BDD</ulink>
      is.
    </para>
    <para>
      BDD is a second-generation testing approach first described by
      <ulink url="http://dannorth.net/introducing-bdd/">Dan
      North</ulink> (the authority on BDD) which attempts to test the
      behavior of software. It’s considered second-generation as it came
      out of merging ideas from Domain driven design (DDD) and lean
      software development, helping teams to deliver high quality
      software by answering many of the more confusing questions early
      on in the agile process. Such questions commonly include those
      concerning documentation and testing.
    </para>
    <para>
      If you were to read a book on BDD, it’s likely to also be
      described as being <quote>outside-in and pull-based</quote>. The
      reason for this is that it borrows the idea of of pulling features
      from Lean manufacturing which effectively ensures that the right
      software solutions are being written by a) focusing on expected
      outputs of the system and b) ensuring these outputs are achieved.
    </para>
    <para>
      BDD recognizes that there are usually multiple stakeholders in a
      project and not a single amorphous user of the system. These
      different groups will be affected by the software being written in
      differing ways and will have a varying opinion of what quality in
      the system means to them. It’s for this reason that it’s important
      to understand who the software will be bringing value you and
      exactly what in it will be valuable to them.
    </para>
    <para>
      Finally, BDD relies on automation. Once you’ve defined the quality
      expected, your team will likely want to check on the functionality
      of the solution being built regularly and compare it to the
      results they expect. In order to facilitate this efficiently, the
      process has to be automated. BDD relies heavily on the automation
      of specification-testing and Jasmine is a tool which can assist
      with this.
    </para>
    <para>
      BDD helps both developers and non-technical stakeholders:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Better understand and represent the models of the problems
          being solved
        </para>
      </listitem>
      <listitem>
        <para>
          Explain supported tests cases in a language that
          non-developers can read
        </para>
      </listitem>
      <listitem>
        <para>
          Focus on minimizing translation of the technical code being
          written and the domain language spoken by the business
        </para>
      </listitem>
    </itemizedlist>
    <para>
      What this means is that developers should be able to show Jasmine
      unit tests to a project stakeholder and (at a high level, thanks
      to a common vocabulary being used) they’ll ideally be able to
      understand what the code supports.
    </para>
    <para>
      Developers often implement BDD in unison with another testing
      paradigm known as
      <ulink url="http://en.wikipedia.org/wiki/Test-driven_development">TDD</ulink>
      (test-driven development). The main idea behind TDD is:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Write unit tests which describe the functionality you would
          like your code to support
        </para>
      </listitem>
      <listitem>
        <para>
          Watch these tests fail (as the code to support them hasn’t yet
          been written)
        </para>
      </listitem>
      <listitem>
        <para>
          Write code to make the tests pass
        </para>
      </listitem>
      <listitem>
        <para>
          Rinse, repeat and refactor
        </para>
      </listitem>
    </itemizedlist>
    <para>
      In this chapter we’re going to use both BDD (with TDD) to write
      unit tests for a Backbone application.
    </para>
    <para>
      <emphasis role="strong"><emphasis>Note:</emphasis></emphasis> I’ve
      seen a lot of developers also opt for writing tests to validate
      behavior of their code after having written it. While this is
      fine, note that it can come with pitfalls such as only testing for
      behavior your code currently supports, rather than behavior the
      problem needs to be supported.
    </para>
  </sect2>
  <sect2 id="suites-specs-spies">
    <title>Suites, Specs &amp; Spies</title>
    <para>
      When using Jasmine, you’ll be writing suites and specifications
      (specs). Suites basically describe scenarios whilst specs describe
      what can be done in these scenarios.
    </para>
    <para>
      Each spec is a JavaScript function, described with a call to
      `<literal>it()</literal> using a description string and a
      function. The description should describe the behaviour the
      particular unit of code should exhibit and keeping in mind BDD, it
      should ideally be meaningful. Here’s an example of a basic spec:
    </para>
    <programlisting language="javascript">
it('should be incrementing in value', function(){
    var counter = 0;
    counter++;  
});
</programlisting>
    <para>
      On it’s own, a spec isn’t particularly useful until expectations
      are set about the behavior of the code. Expectations in specs are
      defined using the <literal>expect()</literal> function and an
      <ulink url="https://github.com/pivotal/jasmine/wiki/Matchers">expectation
      matcher</ulink> (e.g toEqual(), toBeTruthy(), toContain()). A
      revised example using an expectation matcher would look like:
    </para>
    <programlisting language="javascript">
it('should be incrementing in value', function(){
    var counter = 0;
    counter++;  
    expect(counter).toEqual(1);
});
</programlisting>
    <para>
      The above code passes our behavioral expectation as
      `<literal>counter</literal> equals 1. Notice how easy this was to
      read the expectation on the last line (you probably grokked it
      without any explanation).
    </para>
    <para>
      Specs are grouped into suites which we describe using Jasmine’s
      <literal>describe()</literal> function, again passing a string as
      a description and a function. The name/description for your suite
      is typically that of the component or module you’re testing.
    </para>
    <para>
      Jasmine will use it as the group name when it reports the results
      of the specs you’ve asked it to run. A simple suite containing our
      sample spec could look like:
    </para>
    <programlisting language="javascript">
describe('Stats', function(){
    it('can increment a number', function(){
        ...
    });

    it('can subtract a number', function(){
        ...
    });
});
</programlisting>
    <para>
      Suites also share a functional scope and so it’s possible to
      declare variables and functions inside a describe block which are
      accessible within specs:
    </para>
    <programlisting language="javascript">
describe('Stats', function(){
    var counter = 1;

    it('can increment a number', function(){
        // the counter was = 1
        counter = counter + 1;
        expect(counter).toEqual(2);
    });

    it('can subtract a number', function(){
        // the counter was = 2
        counter = counter - 1;
        expect(counter).toEqual(1);
    });
});
</programlisting>
    <para>
      <emphasis role="strong"><emphasis>Note:</emphasis></emphasis>
      Suites are executed in the order in which they are described,
      which can be useful to know if you would prefer to see test
      results for specific parts of your application reported first.
    </para>
    <para>
      Jasmine also supports <emphasis role="strong">spies</emphasis> - a
      way to mock, spy and fake behavior in our unit tests. Spies
      replace the function they’re spying on, allowing us to simulate
      behavior we would like to mock (i.e test free of the actual
      implementation).
    </para>
    <para>
      In the below example, we’re spying on the
      <literal>setComplete</literal> method of a dummy Todo function to
      test that arguments can be passed to it as expected.
    </para>
    <programlisting language="javascript">
var Todo = function(){
};

Todo.prototype.setComplete = function (arg){
    return arg;
}

describe('a simple spy', function(){
    it('should spy on an instance method of a Todo', function(){
        var myTodo = new Todo();
        spyOn(myTodo, 'setComplete');
        myTodo.setComplete('foo bar');

        expect(myTodo.setComplete).toHaveBeenCalledWith('foo bar');

        var myTodo2 = new Todo();
        spyOn(myTodo2, 'setComplete');

        expect(myTodo2.setComplete).not.toHaveBeenCalled();

    });
});
</programlisting>
    <para>
      What you’re more likely to use spies for is testing
      <ulink url="http://en.wikipedia.org/wiki/Asynchronous_communication">asynchronous</ulink>
      behavior in your application such as AJAX requests. Jasmine
      supports:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Writing tests which can mock AJAX requests using spies. This
          allows us to test code which runs before an AJAX request and
          right after. It’s also possible to mock/fake responses the
          server can return and the benefit of this type of testing is
          that it’s faster as no real calls are being made to a server
        </para>
      </listitem>
      <listitem>
        <para>
          Asynchronous tests which don’t rely on spies
        </para>
      </listitem>
    </itemizedlist>
    <para>
      For the first kind of test, it’s possible to both fake an AJAX
      request and verify that the request was both calling the correct
      URL and executed a callback where one was provided.
    </para>
    <programlisting language="javascript">
it(&quot;the callback should be executed on success&quot;, function () {
    spyOn($, &quot;ajax&quot;).andCallFake(function(options) {
        options.success();
    });

    var callback = jasmine.createSpy();
    getTodo(15, callback);

    expect($.ajax.mostRecentCall.args[0][&quot;url&quot;]).toEqual(&quot;/todos/15&quot;);
    expect(callback).toHaveBeenCalled();
});

function getTodo(id, callback) {
    $.ajax({
        type: &quot;GET&quot;,
        url: &quot;/todos/&quot; + id,
        dataType: &quot;json&quot;,
        success: callback
    });
}
</programlisting>
    <para>
      If you feel lost having seen matchers like
      <literal>andCallFake()</literal> and
      <literal>toHaveBeenCalled()</literal>, don’t worry. All of these
      are Spy-specific matchers and are documented on the Jasmine
      <ulink url="https://github.com/pivotal/jasmine/wiki/Spies">wiki</ulink>.
    </para>
    <para>
      For the second type of test (asynchronous tests), we can take the
      above further by taking advantage of three other methods Jasmine
      supports:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          runs(function) - a block which runs as if it was directly
          called
        </para>
      </listitem>
      <listitem>
        <para>
          waits(timeout) - a native timeout before the next block is run
        </para>
      </listitem>
      <listitem>
        <para>
          waitsFor(function, optional message, optional timeout) - a way
          to pause specs until some other work has completed. Jasmine
          waits until the supplied function returns true here before it
          moves on to the next block.
        </para>
      </listitem>
    </itemizedlist>
    <programlisting language="javascript">
it(&quot;should make an actual AJAX request to a server&quot;, function () {

    var callback = jasmine.createSpy();
    getTodo(16, callback);

    waitsFor(function() {
        return callback.callCount &gt; 0;
    });

    runs(function() {
        expect(callback).toHaveBeenCalled();
    });
});

function getTodo(id, callback) {
    $.ajax({
        type: &quot;GET&quot;,
        url: &quot;todos.json&quot;,
        dataType: &quot;json&quot;,
        success: callback
    });
}
</programlisting>
    <para>
      <emphasis role="strong"><emphasis>Note:</emphasis></emphasis> It’s
      useful to remember that when making real requests to a web server
      in your unit tests, this has the potential to massively slow down
      the speed at which tests run (due to many factors including server
      latency). As this also introduces an external dependency that can
      (and should) be minimized in your unit testing, it is strongly
      recommended that you opt for spies to remove the need for a web
      server to be used here.
    </para>
  </sect2>
  <sect2 id="beforeeach-and-aftereach">
    <title>beforeEach and afterEach()</title>
    <para>
      Jasmine also supports specifying code that can be run before each
      (<literal>beforeEach()</literal>) and after each
      (<literal>afterEach</literal>) test. This is useful for enforcing
      consistent conditions (such as resetting variables that may be
      required by specs). In the following example,
      <literal>beforeEach()</literal> is used to create a new sample
      Todo model specs can use for testing attributes.
    </para>
    <programlisting language="javascript">
beforeEach(function(){
   this.todo = new Backbone.Model({
      text: &quot;Buy some more groceries&quot;,
      done: false 
   });
});

it(&quot;should contain a text value if not the default value&quot;, function(){
   expect(this.todo.get('text')).toEqual(&quot;Buy some more groceries&quot;); 
});
</programlisting>
    <para>
      Each nested <literal>describe()</literal> in your tests can have
      their own <literal>beforeEach()</literal> and
      <literal>afterEach()</literal> methods which support including
      setup and teardown methods relevant to a particular suite. We’ll
      be using <literal>beforeEach()</literal> in practice a little
      later.
    </para>
  </sect2>
  <sect2 id="shared-scope">
    <title>Shared scope</title>
    <para>
      In the previous section you may have noticed that we initially
      declared a variable <literal>this.todo</literal> in our
      <literal>beforeEach()</literal> call and were then able to
      continue using this in <literal>afterEach()</literal>. This is
      thanks to a powerful feature of Jasmine known as shared functional
      scope. Shared scope allows <literal>this</literal> properties to
      be common to all blocks (including <literal>runs()</literal>), but
      not declared variables (i.e <literal>var</literal>s).
    </para>
  </sect2>
  <sect2 id="getting-setup">
    <title>Getting setup</title>
    <para>
      Now that we’ve reviewed some fundamentals, let’s go through
      downloading Jasmine and getting everything setup to write tests.
    </para>
    <para>
      A standalone release of Jasmine can be
      <ulink url="http://pivotal.github.com/jasmine/download.html">downloaded</ulink>
      from the official release page.
    </para>
    <para>
      You’ll need a file called SpecRunner.html in addition to the
      release. It can be downloaded from
      https://github.com/pivotal/jasmine/tree/master/lib/jasmine-core/example
      or as part of a download of the complete Jasmine
      <ulink url="https://github.com/pivotal/jasmine/zipball/master">repo</ulink>.Alternatively,
      you can <literal>git clone</literal> the main Jasmine repository
      from https://github.com/pivotal/jasmine.git.
    </para>
    <para>
      Let’s review
      <ulink url="https://github.com/pivotal/jasmine/blob/master/lib/jasmine-core/example/SpecRunner.html">SpecRunner.html</ulink>:
    </para>
    <para>
      It first includes both Jasmine and the necessary CSS required for
      reporting:
    </para>
    <programlisting>
&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;lib/jasmine-1.1.0.rc1/jasmine.css&quot;/&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;lib/jasmine-1.1.0.rc1/jasmine.js&quot;&gt;&lt;/script&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;lib/jasmine-1.1.0.rc1/jasmine-html.js&quot;&gt;&lt;/script&gt;
</programlisting>
    <para>
      Next, some sample tests are included:
    </para>
    <programlisting>
&lt;script type=&quot;text/javascript&quot; src=&quot;spec/SpecHelper.js&quot;&gt;&lt;/script&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;spec/PlayerSpec.js&quot;&gt;&lt;/script&gt;
</programlisting>
    <para>
      And finally the sources being tested:
    </para>
    <programlisting>
&lt;script type=&quot;text/javascript&quot; src=&quot;src/Player.js&quot;&gt;&lt;/script&gt;
&lt;script type=&quot;text/javascript&quot; src=&quot;src/Song.js&quot;&gt;&lt;/script&gt;
</programlisting>
    <para>
      <emphasis role="strong"><emphasis>Note:</emphasis></emphasis>
      Below this section of SpecRunner is code responsible for running
      the actual tests. Given that we won’t be covering modifying this
      code, I’m going to skip reviewing it. I do however encourage you
      to take a look through
      <ulink url="https://github.com/pivotal/jasmine/blob/master/lib/jasmine-core/example/spec/PlayerSpec.js">PlayerSpec.js</ulink>
      and
      <ulink url="https://github.com/pivotal/jasmine/blob/master/lib/jasmine-core/example/spec/SpecHelper.js">SpecHelper.js</ulink>.
      They’re a useful basic example to go through how a minimal set of
      tests might work.
    </para>
  </sect2>
  <sect2 id="tdd-with-backbone">
    <title>TDD With Backbone</title>
    <para>
      When developing applications with Backbone, it can be necessary to
      test both individual modules of code as well as modules, views,
      collections and routers. Taking a TDD approach to testing, let’s
      review some specs for testing these Backbone components using the
      popular Backbone
      <ulink url="https://github.com/addyosmani/todomvc/tree/master/todo-example/backbone">Todo</ulink>
      application. For this section we will be using a modified version
      of Larry Myers Backbone Koans project, which can be found in the
      <literal>practicals\jasmine-koans</literal> folder.
    </para>
  </sect2>
  <sect2 id="models-2">
    <title><a name="testing-jasmine-models">Models</a></title>
    <para>
      The complexity of Backbone models can vary greatly depending on
      what your application is trying to achieve. In the following
      example, we’re going to test default values, attributes, state
      changes and validation rules.
    </para>
    <para>
      First, we begin our suite for model testing using
      <literal>describe()</literal>:
    </para>
    <programlisting language="javascript">
describe('Tests for Todo', function() {
</programlisting>
    <para>
      Models should ideally have default values for attributes. This
      helps ensure that when creating instances without a value set for
      any specific attribute, a default one (e.g <quote></quote>) is
      used instead. The idea here is to allow your application to
      interact with models without any unexpected behavior.
    </para>
    <para>
      In the following spec, we create a new Todo without any attributes
      passed then check to find out what the value of the
      <literal>text</literal> attribute is. As no value has been set, we
      expect a default value of `<literal>&quot;&quot;</literal> to be
      returned.
    </para>
    <programlisting language="javascript">
it('Can be created with default values for its attributes.', function() {
    var todo = new Todo();
    expect(todo.get('text')).toBe(&quot;&quot;);
});
</programlisting>
    <para>
      If testing this spec before your models have been written, you’ll
      incur a failing test, as expected. What’s required for the spec to
      pass is a default value for the attribute <literal>text</literal>.
      We can implement this default value with some other useful
      defaults (which we’ll be using shortly) in our Todo model as
      follows:
    </para>
    <programlisting language="javascript">

window.Todo = Backbone.Model.extend({

    defaults: function() {
        return {
            text: &quot;&quot;,
            done:  false,
            order: 0
        };
    }
</programlisting>
    <para>
      Next, we want to test that our model will pass attributes that are
      set such that retrieving the value of these attributes after
      initialization will be what we expect. Notice that here, in
      addition to testing for an expected value for
      <literal>text</literal>, we’re also testing the other default
      values are what we expect them to be.
    </para>
    <programlisting language="javascript">
it('Will set passed attributes on the model instance when created.', function() {
    var todo = new Todo({ text: 'Get oil change for car.' });

    // what are the values expected here for each of the
    // attributes in our Todo?

    expect(todo.get('text')).toBe(&quot;Get oil change for car.&quot;);
    expect(todo.get('done')).toBe(false);
    expect(todo.get('order')).toBe(0);
});
</programlisting>
    <para>
      Backbone models support a model.change() event which is triggered
      when the state of a model changes. In the following example, by
      <quote>state</quote> I’m referring to the value of a Todo model’s
      attributes. The reason changes of state are important to test are
      that there may be state-dependent events in your application e.g
      you may wish to display a confirmation view once a Todo model has
      been updated.
    </para>
    <programlisting language="javascript">
it('Fires a custom event when the state changes.', function() {

    var spy = jasmine.createSpy('-change event callback-');

    var todo = new Todo();

    // how do we monitor changes of state?
    todo.bind('change', spy);

    // what would you need to do to force a change of state?
    todo.set({ text: 'Get oil change for car.' });

    expect(spy).toHaveBeenCalled();
});
</programlisting>
    <para>
      It’s common to include validation logic in your models to ensure
      both the input passed from users (and other modules) in the
      application are <quote>valid</quote>. A Todo app may wish to
      validate the text input supplied in case it contains rude words.
      Similarly if we’re storing the <literal>done</literal> state of a
      Todo item using booleans, we need to validate that truthy/falsy
      values are passed and not just any arbitrary string.
    </para>
    <para>
      In the following spec, we take advantage of the fact that
      validations which fail model.validate() trigger an
      <quote>error</quote> event. This allows us to test if validations
      are correctly failing when invalid input is supplied.
    </para>
    <para>
      We create an errorCallback spy using Jasmine’s built in
      <literal>createSpy()</literal> method which allows us to spy on
      the error event as follows:
    </para>
    <programlisting language="javascript">
it('Can contain custom validation rules, and will trigger an error event on failed validation.', function() {

    var errorCallback = jasmine.createSpy('-error event callback-');

    var todo = new Todo();

    todo.bind('error', errorCallback);

    // What would you need to set on the todo properties to 
    // cause validation to fail?

    todo.set({done:'a non-integer value'});

    var errorArgs = errorCallback.mostRecentCall.args;

    expect(errorArgs).toBeDefined();
    expect(errorArgs[0]).toBe(todo);
    expect(errorArgs[1]).toBe('Todo.done must be a boolean value.');
});
</programlisting>
    <para>
      The code to make the above failing test support validation is
      relatively simple. In our model, we override the validate() method
      (as recommended in the Backbone docs), checking to make sure a
      model both has a <quote>done</quote> property and is a valid
      boolean before allowing it to pass.
    </para>
    <programlisting language="javascript">
validate: function(attrs) {
    if (attrs.hasOwnProperty('done') &amp;&amp; !_.isBoolean(attrs.done)) {
        return 'Todo.done must be a boolean value.';
    }
}
</programlisting>
    <para>
      If you would like to review the final code for our Todo model, you
      can find it below:
    </para>
    <programlisting language="javascript">
var NAUGHTY_WORDS = /crap|poop|hell|frogs/gi;

function sanitize(str) {
    return str.replace(NAUGHTY_WORDS, 'rainbows');
}

window.Todo = Backbone.Model.extend({

    defaults: function() {
        return {
            text: '',
            done:  false,
            order: 0
        };
    },

    initialize: function() {
        this.set({text: sanitize(this.get('text'))}, {silent: true});
    },

    validate: function(attrs) {
        if (attrs.hasOwnProperty('done') &amp;&amp; !_.isBoolean(attrs.done)) {
            return 'Todo.done must be a boolean value.';
        }
    },

    toggle: function() {
        this.save({done: !this.get(&quot;done&quot;)});
    }

});
</programlisting>
  </sect2>
  <sect2 id="collections-2">
    <title><a name="testing-jasmine-collections">Collections</a></title>
    <para>
      We now need to define specs to tests a Backbone collection of Todo
      models (a TodoList). Collections are responsible for a number of
      list tasks including managing order and filtering.
    </para>
    <para>
      A few specific specs that come to mind when working with
      collections are:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Making sure we can add new Todo models as both objects and
          arrays
        </para>
      </listitem>
      <listitem>
        <para>
          Attribute testing to make sure attributes such as the base URL
          of the collection are values we expect
        </para>
      </listitem>
      <listitem>
        <para>
          Purposefully adding items with a status of
          <literal>done:true</literal> and checking against how many
          items the collection thinks have been completed vs. those that
          are remaining
        </para>
      </listitem>
    </itemizedlist>
    <para>
      In this section we’re going to cover the first two of these with
      the third left as an extended exercise I recommend trying out.
    </para>
    <para>
      Testing Todo models can be added to a collection as objects or
      arrays is relatively trivial. First, we initialize a new TodoList
      collection and check to make sure it’s length (i.e the number of
      Todo models it contains) is 0. Next, we add new Todos, both as
      objects and arrays, checking the length property of the collection
      at each stage to ensure the overall count is what we expect:
    </para>
    <programlisting language="javascript">
describe('Tests for TodoList', function() {

    it('Can add Model instances as objects and arrays.', function() {
        var todos = new TodoList();

        expect(todos.length).toBe(0);

        todos.add({ text: 'Clean the kitchen' });

        // how many todos have been added so far?
        expect(todos.length).toBe(1);

        todos.add([
            { text: 'Do the laundry', done: true }, 
            { text: 'Go to the gym'}
        ]);

        // how many are there in total now?
        expect(todos.length).toBe(3);
    });
...
</programlisting>
    <para>
      Similar to model attributes, it’s also quite straight-forward to
      test attributes in collections. Here we have a spec that ensures
      the collection.url (i.e the url reference to the collection’s
      location on the server) is what we expect it to be:
    </para>
    <programlisting language="javascript">
it('Can have a url property to define the basic url structure for all contained models.', function() {
        var todos = new TodoList();

        // what has been specified as the url base in our model?
        expect(todos.url).toBe('/todos/');
});
</programlisting>
    <para>
      For the third spec, it’s useful to remember that the
      implementation for our collection will have methods for filtering
      how many Todo items are done and how many are remaining - we can
      call these <literal>done()</literal> and
      <literal>remaining()</literal>. Consider writing a spec which
      creates a new collection and adds one new model that has a preset
      <literal>done</literal> state of <literal>true</literal> and two
      others that have the default <literal>done</literal> state of
      <literal>false</literal>. Testing the length of what’s returned
      using <literal>done()</literal> and <literal>remaining()</literal>
      should allow us to know whether the state management in our
      application is working or needs a little tweaking.
    </para>
    <para>
      The final implementation for our TodoList collection can be found
      below:
    </para>
    <programlisting language="javascript">
 window.TodoList = Backbone.Collection.extend({

        model: Todo,

        url: '/todos/',

        done: function() {
            return this.filter(function(todo) { return todo.get('done'); });
        },

        remaining: function() {
            return this.without.apply(this, this.done());
        },

        nextOrder: function() {
            if (!this.length) { 
                return 1; 
            }

            return this.last().get('order') + 1;
        },

        comparator: function(todo) {
            return todo.get('order');
        }

    });
</programlisting>
  </sect2>
  <sect2 id="views-3">
    <title><a name="testing-jasmine-views">Views</a></title>
    <para>
      Before we take a look at testing Backbone views, let’s briefly
      review a jQuery plugin that can assist with writing Jasmine specs
      for them.
    </para>
    <para>
      <emphasis role="strong">The Jasmine jQuery Plugin</emphasis>
    </para>
    <para>
      As we know our Todo application will be using jQuery for DOM
      manipulation, there’s a useful jQuery plugin called
      <ulink url="https://github.com/velesin/jasmine-jquery">jasmine-jquery</ulink>
      we can use to help simplify BDD testing rendered elements that our
      views may produce.
    </para>
    <para>
      The plugin provides a number of additional Jasmine
      <ulink url="https://github.com/pivotal/jasmine/wiki/Matchers">matchers</ulink>
      to help test jQuery wrapped sets such as:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <literal>toBe(jQuerySelector)</literal> e.g
          <literal>expect($('&lt;div id=&quot;some-id&quot;&gt;&lt;/div&gt;')).toBe('div#some-id')</literal>
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>toBeChecked()</literal> e.g
          <literal>expect($('&lt;input type=&quot;checkbox&quot; checked=&quot;checked&quot;/&gt;')).toBeChecked()</literal>
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>toBeSelected()</literal> e.g
          <literal>expect($('&lt;option selected=&quot;selected&quot;&gt;&lt;/option&gt;')).toBeSelected()</literal>
        </para>
      </listitem>
    </itemizedlist>
    <para>
      and <ulink url="https://github.com/velesin/jasmine-jquery">many
      others</ulink>. The complete list of matchers supported can be
      found on the project homepage. It’s useful to know that similar to
      the standard Jasmine matchers, the custom matchers above can be
      inverted using the .not prefix (i.e
      <literal>expect(x).not.toBe(y)</literal>):
    </para>
    <programlisting language="javascript">
expect($('&lt;div&gt;I am an example&lt;/div&gt;')).not.toHaveText(/other/)
</programlisting>
    <para>
      jasmine-jquery also includes a fixtures model, allowing us to load
      in arbitrary HTML content we may wish to use in our tests.
      Fixtures can be used as follows:
    </para>
    <para>
      Include some HTML in an external fixtures file:
    </para>
    <para>
      some.fixture.html:
      <literal>&lt;div id=&quot;sample-fixture&quot;&gt;some HTML content&lt;/div&gt;</literal>
    </para>
    <para>
      Next, inside our actual test we would load it as follows:
    </para>
    <programlisting language="javascript">
loadFixtures('some.fixture.html')
$('some-fixture').myTestedPlugin();
expect($('#some-fixture')).to&lt;the rest of your matcher would go here&gt;
</programlisting>
    <para>
      The jasmine-jquery plugin is by default setup to load fixtures
      from a specific directory: spec/javascripts/fixtures. If you wish
      to configure this path you can do so by initially setting
      <literal>jasmine.getFixtures().fixturesPath = 'your custom path'</literal>.
    </para>
    <para>
      Finally, jasmine-jquery includes support for spying on jQuery
      events without the need for any extra plumbing work. This can be
      done using the <literal>spyOnEvent()</literal> and
      <literal>assert(eventName).toHaveBeenTriggered(selector)</literal>
      functions. An example of usage may look as follows:
    </para>
    <programlisting language="javascript">
spyOnEvent($('#el'), 'click');
$('#el').click();
expect('click').toHaveBeenTriggeredOn($('#el'));
</programlisting>
    <para>
      <emphasis role="strong">View testing</emphasis>
    </para>
    <para>
      In this section we will review three dimensions to writing specs
      for Backbone Views: initial setup, view rendering and finally
      templating. The latter two of these are the most commonly tested,
      however we’ll review shortly why writing specs for the
      initialization of your views can also be of benefit.
    </para>
  </sect2>
  <sect2 id="initial-setup">
    <title>Initial setup</title>
    <para>
      At their most basic, specs for Backbone views should validate that
      they are being correctly tied to specific DOM elements and are
      backed by valid data models. The reason to consider doing this is
      that failures to such specs can trip up more complex tests later
      on and they’re fairly simple to write, given the overall value
      offered.
    </para>
    <para>
      To help ensure a consistent testing setup for our specs, we use
      <literal>beforeEach()</literal> to append both an empty
      <literal>UL</literal> (#todoList) to the DOM and initialize a new
      instance of a TodoView using an empty Todo model.
      <literal>afterEach()</literal> is used to remove the previous
      #todoList <literal>UL</literal> as well as the previous instance
      of the view.
    </para>
    <programlisting language="javascript">
describe('Tests for TodoView', function() {

    beforeEach(function() {
        $('body').append('&lt;ul id=&quot;todoList&quot;&gt;&lt;/ul&gt;');
        this.todoView = new TodoView({ model: new Todo() });
    });


    afterEach(function() {
        this.todoView.remove();
        $('#todoList').remove();
    });

...
</programlisting>
    <para>
      The first spec useful to write is a check that the TodoView we’ve
      created is using the correct <literal>tagName</literal> (element
      or className). The purpose of this test is to make sure it’s been
      correctly tied to a DOM element when it was created.
    </para>
    <para>
      Backbone views typically create empty DOM elements once
      initialized, however these elements are not attached to the
      visible DOM in order to allow them to be constructed without an
      impact on the performance of rendering.
    </para>
    <programlisting language="javascript">
it('Should be tied to a DOM element when created, based off the property provided.', function() {
    //what html element tag name represents this view?
    expect(todoView.el.tagName.toLowerCase()).toBe('li');
});
</programlisting>
    <para>
      Once again, if the TodoView has not already been written, we will
      experience failing specs. Thankfully, solving this is as simple as
      creating a new Backbone.View with a specific
      <literal>tagName</literal>.
    </para>
    <programlisting language="javascript">
var todoView = Backbone.View.extend({
    tagName:  &quot;li&quot;
});
</programlisting>
    <para>
      If instead of testing against the <literal>tagName</literal> you
      would prefer to use a className instead, we can take advantage of
      jasmine-jquery’s <literal>toHaveClass()</literal> matcher to cater
      for this.
    </para>
    <programlisting>
it('Should have a class of &quot;todos&quot;'), function(){
   expect($(this.view.el)).toHaveClass('todos');
});
</programlisting>
    <para>
      The <literal>toHaveClass()</literal> matcher operates on jQuery
      objects and if the plugin hadn’t been used, an exception would
      have been incurred (it is of course also possible to test for the
      className by accessing el.className if not opting to use
      jasmine-jquery).
    </para>
    <para>
      You may have noticed that in <literal>beforeEach()</literal>, we
      passed our view an initial (albeit unfilled) Todo model. Views
      should be backed by a model instance which provides data. As this
      is quite important to our view’s ability to function, we can write
      a spec to ensure a model is both defined (using the
      <literal>toBeDefined()</literal> matcher) and then test attributes
      of the model to ensure defaults both exist and are the value we
      expect them to be.
    </para>
    <programlisting language="javascript">
it('Is backed by a model instance, which provides the data.', function() {

    expect(todoView.model).toBeDefined();

    // what's the value for Todo.get('done') here?
    expect(todoView.model.get('done')).toBe(false); //or toBeFalsy()
});
</programlisting>
  </sect2>
  <sect2 id="view-rendering">
    <title>View rendering</title>
    <para>
      Next we’re going to take a look at writing specs for view
      rendering. Specifically, we want to test that our TodoView
      elements are actually rendering as expected.
    </para>
    <para>
      In smaller applications, those new to BDD might argue that visual
      confirmation of view rendering could replace unit testing of
      views. The reality is that when dealing with applications that
      might grow to multiple-views, it often makes sense to automate
      this process as much as possible from the get-go. There are also
      aspects of rendering that require verification beyond what is
      visually presented on-screen (which we’ll see very shortly).
    </para>
    <para>
      We’re going to begin testing views by writing two specs. The first
      spec will check that the view’s <literal>render()</literal> method
      is correctly returning the view instance, which is necessary for
      chaining. Our second spec will check that the HTML produced is
      exactly what we expect based on the properties of the model
      instance that’s been associated with our TodoView.
    </para>
    <para>
      Unlike some of the previous specs we’ve covered, this section will
      make greater use of <literal>beforeEach()</literal> to both
      demonstrate how to use nested suites and also ensure a consistent
      set of conditions for our specs. In our first view spec for
      TodoView, we’re simply going to create a sample model (based on
      Todo) and instantiate a TodoView which associates it with the
      model.
    </para>
    <programlisting language="javascript">
describe(&quot;TodoView&quot;, function() {

  beforeEach(function() {
    this.model = new Backbone.Model({
      text: &quot;My Todo&quot;,
      order: 1,
      done: false
    });
    this.view = new TodoView({model:this.model});
  });

  describe(&quot;Rendering&quot;, function() {

    it(&quot;returns the view object&quot;, function() {
      expect(this.view.render()).toEqual(this.view);
    });

    it(&quot;produces the correct HTML&quot;, function() {
      this.view.render();

      //let's use jasmine-jquery's toContain() to avoid
      //testing for the complete content of a todo's markup
      expect(this.view.el.innerHTML)
        .toContain('&lt;label class=&quot;todo-content&quot;&gt;My Todo&lt;/label&gt;');
    });

  });

});
</programlisting>
    <para>
      Once these specs are run, only the second one (<quote>produces the
      correct HTML</quote>) fails. Our first spec (<quote>returns the
      view object</quote>), which is testing that the TodoView instance
      is returned from <literal>render()</literal>, only passed as this
      is Backbone’s default behavior. We haven’t yet overwritten the
      <literal>render()</literal> method with our own version.
    </para>
    <para>
      <emphasis role="strong">Note:</emphasis> For the purposes of
      maintaining readability, all template examples in this section
      will use a minimal version of the following Todo view template. As
      it’s relatively trivial to expand this, please feel free to refer
      to this sample if needed:
    </para>
    <programlisting>
&lt;div class=&quot;todo &lt;%= done ? 'done' : '' %&gt;&quot;&gt;
        &lt;div class=&quot;display&quot;&gt;
          &lt;input class=&quot;check&quot; type=&quot;checkbox&quot; &lt;%= done ? 'checked=&quot;checked&quot;' : '' %&gt; /&gt;
          &lt;label class=&quot;todo-content&quot;&gt;&lt;%= text %&gt;&lt;/label&gt;
          &lt;span class=&quot;todo-destroy&quot;&gt;&lt;/span&gt;
        &lt;/div&gt;
        &lt;div class=&quot;edit&quot;&gt;
          &lt;input class=&quot;todo-input&quot; type=&quot;text&quot; value=&quot;&lt;%= content %&gt;&quot; /&gt;
        &lt;/div&gt;
&lt;/div&gt;
</programlisting>
    <para>
      The second spec fails with the following message:
    </para>
    <para>
      Expected ’’ to contain
      <literal>'&lt;label class=&quot;todo-content&quot;&gt;My Todo&lt;/label&gt;'</literal>.
    </para>
    <para>
      The reason for this is the default behavior for render() doesn’t
      create any markup. Let’s write a replacement for render() which
      fixes this:
    </para>
    <programlisting language="javascript">
render: function() {
  var template = '&lt;label class=&quot;todo-content&quot;&gt;&lt;%= text %&gt;&lt;/label&gt;';
  var output = template
    .replace(&quot;&lt;%= text %&gt;&quot;, this.model.get('text'));
  $(this.el).html(output);
  return this;
}
</programlisting>
    <para>
      The above specifies an inline string template and replaces fields
      found in the template within the <quote>&lt;% %&gt;</quote> blocks
      with their corresponding values from the associated model. As
      we’re now also returning the TodoView instance from the method,
      the first spec will also pass. It’s worth noting that there are
      serious drawbacks to using HTML strings in your specs to test
      against like this. Even minor changes to your template (a simple
      tab or whitespace) would cause your spec to fail, despite the
      rendered output being the same. It’s also more time consuming to
      maintain as most templates in real-world applications are
      significantly more complex. A better option for testing rendered
      output is using jQuery to both select and inspect values.
    </para>
    <para>
      With this in mind, let’s re-write the specs, this time using some
      of the custom matchers offered by jasmine-jquery:
    </para>
    <programlisting language="javascript">
describe(&quot;Template&quot;, function() {

  beforeEach(function() {
    this.view.render();
  });

  it(&quot;has the correct text content&quot;, function() {
    expect($(this.view.el).find('todo-content'))
      .toHaveText('My Todo');
  });

});
</programlisting>
    <para>
      It would be impossible to discuss unit testing without mentioning
      fixtures. Fixtures typically contain test data (e.g HTML) that is
      loaded in when needed (either locally or from an external file)
      for unit testing. So far we’ve been establishing jQuery
      expectations based on the view’s el property. This works for a
      number of cases, however, there are instances where it may be
      necessary to render markup into the document. The most optimal way
      to handle this within specs is through using fixtures (another
      feature brought to us by the jasmine-jquery plugin).
    </para>
    <para>
      Re-writing the last spec to use fixtures would look as follows:
    </para>
    <programlisting language="javascript">
describe(&quot;TodoView&quot;, function() {

  beforeEach(function() {
    ...
    setFixtures('&lt;ul class=&quot;todos&quot;&gt;&lt;/ul&gt;');
  });

  ...

  describe(&quot;Template&quot;, function() {

    beforeEach(function() {
      $('.todos').append(this.view.render().el);
    });

    it(&quot;has the correct text content&quot;, function() {
      expect($('.todos').find('.todo-content'))
        .toHaveText('My Todo');
    });

  });

});
</programlisting>
    <para>
      What we’re now doing in the above spec is appending the rendered
      todo item into the fixture. We then set expectations against the
      fixture, which may be something desirable when a view is setup
      against an element which already exists in the DOM. It would be
      necessary to provide both the fixture and test the
      <literal>el</literal> property correctly picking up the element
      expected when the view is instantiated.
    </para>
  </sect2>
  <sect2 id="rendering-with-a-templating-system">
    <title>Rendering with a templating system</title>
    <para>
      JavaScript templating systems (such as Handlebars, Mustache and
      even Underscore’s own Micro-templating) support conditional logic
      in template strings. What this effectively means is that we can
      add if/else/ternery expressions inline which can then be evaluated
      as needed, allowing us to build even more powerful templates.
    </para>
    <para>
      In our case, when a user sets a Todo item to be complete (done),
      we may wish to provide them with visual feedback (such as a
      striked line through the text) to differentiate the item from
      those that are remaining. This can be done by attaching a new
      class to the item. Let’s begin by writing a test we would ideally
      like to work:
    </para>
    <programlisting language="javascript">
describe(&quot;When a todo is done&quot;, function() {

  beforeEach(function() {
    this.model.set({done: true}, {silent: true});
    $('.todos').append(this.view.render().el);
  });

  it(&quot;has a done class&quot;, function() {
    expect($('.todos .todo-content:first-child'))
      .toHaveClass(&quot;done&quot;);
  });

});
</programlisting>
    <para>
      This will fail with the following message:
    </para>
    <para>
      Expected <quote><label class="todo-content">My
      Todo</label></quote> to have class <quote>done</quote>.
    </para>
    <para>
      which can be fixed in the existing render() method as follows:
    </para>
    <programlisting language="javascript">
render: function() {
  var template = '&lt;label class=&quot;todo-content&quot;&gt;' +
    '&lt;%= text %&gt;&lt;/label&gt;';
  var output = template
    .replace(&quot;&lt;%= text %&gt;&quot;, this.model.get('text'));
  $(this.el).html(output);
  if (this.model.get('done')) {
    this.$(&quot;.todo-content&quot;).addClass(&quot;done&quot;);
  }
  return this;
}
</programlisting>
    <para>
      This can however get unwieldily fairly quickly. As the logic in
      our templates increases, so does the complexity involved. This is
      where templates libraries can help. As mentioned earlier, there
      are a number of popular options available, but for the purposes of
      this chapter we’re going to stick to using Underscore’s built-in
      Microtemplating. Whilst there are more advanced options you’re
      free to explore, the benefit of this is that no additional files
      are required and we can easily change the existing Jasmine specs
      without too much adjustment.
    </para>
    <para>
      The TodoView object modified to use Underscore templating would
      look as follows:
    </para>
    <programlisting language="javascript">
var TodoView = Backbone.View.extend({

  tagName: &quot;li&quot;,

  initialize: function(options) {
    this.template = _.template(options.template || &quot;&quot;);
  },

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

  ...

});
</programlisting>
    <para>
      Above, the initialize() method compiles a supplied Underscore
      template (using the _.template() function) in the instantiation. A
      more common way of referencing templates is placing them in a
      script tag using a custom script type (e.g
      type=<quote>text/template</quote>). As this isn’t a script type
      any browser understands, it’s simply ignored, however referencing
      the script by an id attribute allows the template to be kept
      separate to other parts of the page which wish to use it. In real
      world applications, it’s preferable to either do this or load in
      templates stored in external files for testing.
    </para>
    <para>
      For testing purposes, we’re going to continue using the string
      injection approach to keep things simple. There is however a
      useful trick that can be applied to automatically create or extend
      templates in the Jasmine scope for each test. By creating a new
      directory (say, <quote>templates</quote>) in the
      <quote>spec</quote> folder and adding a new script file with the
      following contents, to jasmine.yml or SpecRunner.html, we can add
      a todo property which contains the Underscore template we wish to
      use:
    </para>
    <programlisting language="javascript">
beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '&lt;label class=&quot;todo-content&quot;&gt;' +
            '&lt;%= text %&gt;' +
          '&lt;/label&gt;'
  });
});
</programlisting>
    <para>
      To finish this off, we simply update our existing spec to
      reference the template when instantiating the TodoView object:
    </para>
    <programlisting language="javascript">
describe(&quot;TodoView&quot;, function() {

  beforeEach(function() {
    ...
    this.view = new TodoView({
      model: this.model,
      template: this.templates.todo
    });
  });

  ...

});
</programlisting>
    <para>
      The existing specs we’ve looked at would continue to pass using
      this approach, leaving us free to adjust the template with some
      additional conditional logic for Todos with a status of
      <quote>done</quote>:
    </para>
    <programlisting language="javascript">
beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '&lt;label class=&quot;todo-content &lt;%= done ? 'done' : '' %&gt;&quot;' +
            '&lt;%= text %&gt;' +
          '&lt;/label&gt;'
  });
});
</programlisting>
    <para>
      This will now also pass without any issues. Remember that
      jasmine-jquery also supports loading external fixtures into your
      specs easily using it’s build in <literal>loadFixtures()</literal>
      and <literal>readFixtures()</literal> methods. For more
      information, consider reading the official jasmine-jquery
      <ulink url="https://github.com/velesin/jasmine-jquery">docs</ulink>.
    </para>
  </sect2>
  <sect2 id="conclusions-1">
    <title>Conclusions</title>
    <para>
      We have now covered how to write Jasmine tests for models, views
      and collections with Backbone.js. Whilst testing routing can at
      times be desirable, some developers feel it can be more optimal to
      leave this to third-party tools such as Selenium, so do keep this
      in mind.
    </para>
    <para>
      James Newbery was kind enough to help me with writing the Views
      section above and his articles on
      <ulink url="http://tinnedfruit.com/2011/04/26/testing-backbone-apps-with-jasmine-sinon-3.html">Testing
      Backbone Apps With SinonJS</ulink> were of great inspiration
      (you’ll actually find some Handlebars examples of the view specs
      in part 3 of his article). If you would like to learn more about
      writing spies and mocks for Backbone using
      <ulink url="http://sinonjs.org">SinonJS</ulink> as well as how to
      test Backbone routers, do consider reading his series.
    </para>
  </sect2>
  <sect2 id="exercise">
    <title>Exercise</title>
    <para>
      As an exercise, I recommend now trying the Jasmine Koans in
      <literal>practicals\jasmine-joans</literal> and trying to fix some
      of the purposefully failing tests it has to offer. This is an
      excellent way of not just learning how Jasmine specs and suites
      work, but working through the examples (without peaking back) will
      also put your Backbone skills to test too.
    </para>
  </sect2>
  <sect2 id="further-reading">
    <title>Further reading</title>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="http://japhr.blogspot.com/2011/11/jasmine-backbonejs-revisited.html">Jasmine
          + Backbone Revisited</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="http://japhr.blogspot.com/2011/12/phantomjs-and-backbonejs-and-requirejs.html">Backbone,
          PhantomJS and Jasmine</ulink>
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
</sect1>
<sect1 id="unit-testing-backbone-applications-with-qunit-and-sinonjs">
  <title><a name="unittestingqunit">Unit Testing Backbone Applications
  With QUnit And SinonJS</a></title>
  <sect2 id="introduction-3">
    <title>Introduction</title>
    <para>
      QUnit is a powerful JavaScript test suite written by jQuery team
      member <ulink url="http://bassistance.de/">Jörn Zaefferer</ulink>
      and used by many large open-source projects (such as jQuery and
      Backbone.js) to test their code. It’s both capable of testing
      standard JavaScript code in the browser as well as code on the
      server-side (where environments supported include Rhino, V8 and
      SpiderMonkey). This makes it a robust solution for a large number
      of use-cases.
    </para>
    <para>
      Quite a few Backbone.js contributors feel that QUnit is a better
      introductory framework for testing if you don’t wish to start off
      with Jasmine and BDD right away. As we’ll see later on in this
      chapter, QUnit can also be combined with third-party solutions
      such as SinonJS to produce an even more powerful testing solution
      supporting spies and mocks, which some say is preferable over
      Jasmine.
    </para>
    <para>
      My personal recommendation is that it’s worth comparing both
      frameworks and opting for the solution that you feel the most
      comfortable with.
    </para>
  </sect2>
</sect1>
<sect1 id="qunit">
  <title>QUnit</title>
  <sect2 id="getting-setup-1">
    <title>Getting Setup</title>
    <para>
      Luckily, getting QUnit setup is a fairly straight-forward process
      that will take less than 5 minutes.
    </para>
    <para>
      We first setup a testing environment composed of three files:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          A HTML <emphasis role="strong">structure</emphasis> for
          displaying test results,
        </para>
      </listitem>
      <listitem>
        <para>
          The <emphasis role="strong">qunit.js</emphasis> file composing
          the testing framework and,
        </para>
      </listitem>
      <listitem>
        <para>
          The <emphasis role="strong">qunit.css</emphasis> file for
          styling test results.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      The latter two of these can be downloaded from the
      <ulink url="http://qunitjs.com">QUnit website</ulink>.
    </para>
    <para>
      If you would prefer, you can use a hosted version of the QUnit
      source files for testing purposes. The hosted URLs can be found at
      [http://github.com/jquery/qunit/raw/master/qunit/].
    </para>
    <sect3 id="sample-html-with-qunit-compatible-markup">
      <title>Sample HTML with QUnit-compatible markup:</title>
      <programlisting language="html">
&lt;!DOCTYPE html&gt;  
&lt;html&gt;  
&lt;head&gt;  
    &lt;title&gt;QUnit Test Suite&lt;/title&gt;  

     &lt;link rel=&quot;stylesheet&quot; href=&quot;qunit.css&quot;&gt;  
     &lt;script src=&quot;qunit.js&quot;&gt;&lt;/script&gt;  

     &lt;!-- Your application --&gt;  
     &lt;script src=&quot;app.js&quot;&gt;&lt;/script&gt;  

     &lt;!-- Your tests --&gt;  
     &lt;script src=&quot;tests.js&quot;&gt;&lt;/script&gt;   
&lt;/head&gt;  
&lt;body&gt;  
    &lt;h1 id=&quot;qunit-header&quot;&gt;QUnit Test Suite&lt;/h1&gt;  
    &lt;h2 id=&quot;qunit-banner&quot;&gt;&lt;/h2&gt;  
    &lt;div id=&quot;qunit-testrunner-toolbar&quot;&gt;&lt;/div&gt;  
    &lt;h2 id=&quot;qunit-userAgent&quot;&gt;&lt;/h2&gt;  
    &lt;ol id=&quot;qunit-tests&quot;&gt;test markup, hidden.&lt;/ol&gt;  
&lt;/body&gt;  
&lt;/html&gt;  
</programlisting>
      <para>
        Let’s go through the elements above with qunit mentioned in
        their ID. When QUnit is running:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">qunit-header</emphasis> shows the
            name of the test suite
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">qunit-banner</emphasis> shows up as
            red if a test fails and green if all tests pass
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">qunit-testrunner-toolbar</emphasis>
            contains additional options for configuring the display of
            tests
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">qunit-userAgent</emphasis> displays
            the navigator.userAgent property
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">qunit-tests</emphasis> is a
            container for our test results
          </para>
        </listitem>
      </itemizedlist>
      <para>
        When running correctly, the above test runner looks as follows:
      </para>
      <figure>
        <title>screenshot 1</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/7d4de12.png" />
          </imageobject>
          <textobject><phrase>screenshot 1</phrase></textobject>
        </mediaobject>
      </figure>
      <para>
        The numbers of the form (a, b, c) after each test name
        correspond to a) failed asserts, b) passed asserts and c) total
        asserts. Clicking on a test name expands it to display all of
        the assertions for that test case. Assertions in green have
        successfully passed.
      </para>
      <figure>
        <title>screenshot 2</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/9df4.png" />
          </imageobject>
          <textobject><phrase>screenshot 2</phrase></textobject>
        </mediaobject>
      </figure>
      <para>
        If however any tests fail, the test gets highlighted (and the
        qunit-banner at the top switches to red):
      </para>
      <figure>
        <title>screenshot 3</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/3e5545.png" />
          </imageobject>
          <textobject><phrase>screenshot 3</phrase></textobject>
        </mediaobject>
      </figure>
    </sect3>
  </sect2>
  <sect2 id="assertions">
    <title>Assertions</title>
    <para>
      QUnit supports a number of basic
      <emphasis role="strong">assertions</emphasis>, which are used in
      testing to verify that the result being returned by our code is
      what we expect. If an assertion fails, we know that a bug
      exists.Similar to Jasmine, QUnit can be used to easily test for
      regressions. Specifically, when a bug is found one can write an
      assertion to test the existence of the bug, write a patch and then
      commit both. If subsequent changes to the code break the test
      you’ll know what was responsible and be able to address it more
      easily.
    </para>
    <para>
      Some of the supported QUnit assertions we’re going to look at
      first are:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <literal>ok ( state, message )</literal> - passes if the first
          argument is truthy
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>equal ( actual, expected, message )</literal> - a
          simple comparison assertion with type coercion
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>notEqual ( actual, expected, message )</literal> -
          the opposite of the above
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>expect( amount )</literal> - the number of assertions
          expected to run within each test
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>strictEqual( actual, expected, message)</literal> -
          offers a much stricter comparison than
          <literal>equal()</literal> and is considered the preferred
          method of checking equality as it avoids stumbling on subtle
          coercion bugs
        </para>
      </listitem>
      <listitem>
        <para>
          <literal>deepEqual( actual, expected, message )</literal> -
          similar to <literal>strictEqual</literal>, comparing the
          contents (with <literal>===</literal>) of the given objects,
          arrays and primitives.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Creating new test cases with QUnit is relatively straight-forward
      and can be done using <literal>test()</literal>, which constructs
      a test where the first argument is the <literal>name</literal> of
      the test to be displayed in our results and the second is a
      <literal>callback</literal> function containing all of our
      assertions. This is called as soon as QUnit is running.
    </para>
    <sect3 id="basic-test-case-using-test-name-callback">
      <title>Basic test case using test( name, callback ):</title>
      <programlisting language="javascript">
var myString = 'Hello Backbone.js';

test( 'Our first QUnit test - asserting results', function(){

    // ok( boolean, message )
    ok( true, 'the test succeeds');
    ok( false, 'the test fails');

    // equal( actualValue, expectedValue, message )
    equal( myString, 'Hello Backbone.js', 'The value expected is Hello Backbone.js!');
});
</programlisting>
      <para>
        What we’re doing in the above is defining a variable with a
        specific value and then testing to ensure the value was what we
        expected it to be. This was done using the comparison assertion,
        <literal>equal()</literal>, which expects its first argument to
        be a value being tested and the second argument to be the
        expected value. We also used <literal>ok()</literal>, which
        allows us to easily test against functions or variables that
        evaluate to booleans.
      </para>
      <para>
        Note: Optionally in our test case, we could have passed an
        <quote>expected</quote> value to <literal>test()</literal>
        defining the number of assertions we expect to run. This takes
        the form: <literal>test( name, [expected], test );</literal> or
        by manually settings the expectation at the top of the test
        function, like so: <literal>expect( 1 )</literal>. I recommend
        you to make it a habit and always define how many assertions you
        expect. More on this later.
      </para>
      <para>
        As testing a simple static variable is fairly trivial, we can
        take this further to test actual functions. In the following
        example we test the output of a function that reverses a string
        to ensure that the output is correct using
        <literal>equal()</literal> and <literal>notEqual()</literal>:
      </para>
    </sect3>
    <sect3 id="comparing-the-actual-output-of-a-function-against-the-expected-output">
      <title>Comparing the actual output of a function against the
      expected output:</title>
      <programlisting language="javascript">
function reverseString( str ){
    return str.split(&quot;&quot;).reverse().join(&quot;&quot;);
}

test( 'reverseString()', function() { 
    expect( 5 );
    equal( reverseString('hello'), 'olleh', 'The value expected was olleh' ); 
    equal( reverseString('foobar'), 'raboof', 'The value expected was raboof' ); 
    equal( reverseString('world'), 'dlrow', 'The value expected was dlrow' ); 
    notEqual( reverseString('world'), 'dlroo', 'The value was expected to not be dlroo' ); 
    equal( reverseString('bubble'), 'double', 'The value expected was elbbub' ); 
})  
</programlisting>
      <para>
        Running these tests in the QUnit test runner (which you would
        see when your HTML test page was loaded) we would find that four
        of the assertions pass whilst the last one does not. The reason
        the test against <literal>'double'</literal> fails is because it
        was purposefully written incorrectly. In your own projects if a
        test fails to pass and your assertions are correct, you’ve
        probably just found a bug!
      </para>
    </sect3>
  </sect2>
  <sect2 id="adding-structure-to-assertions">
    <title>Adding structure to assertions</title>
    <para>
      Housing all of our assertions in one test case can quickly become
      difficult to maintain, but luckily QUnit supports structuring
      blocks of assertions more cleanly. This can be done using
      <literal>module()</literal> - a method that allows us to easily
      group tests together. A typical approach to grouping might be
      keeping multiple tests testing a specific method as part of the
      same group (module).
    </para>
    <sect3 id="basic-qunit-modules">
      <title>Basic QUnit Modules:</title>
      <programlisting language="javascript">
module( 'Module One' );  
test( 'first test', function() {} );  
test( 'another test', function() {} );  

module( 'Module Two' );  
test( 'second test', function() {} );  
test( 'another test', function() {} );  

module( 'Module Three' );  
test( 'third test', function() {} );  
test( 'another test', function() {} );  
</programlisting>
      <para>
        We can take this further by introducing
        <literal>setup()</literal> and <literal>teardown()</literal>
        callbacks to our modules, where <literal>setup()</literal> is
        run before each test whilst <literal>teardown()</literal> is run
        after each test.
      </para>
    </sect3>
    <sect3 id="using-setup-and-teardown">
      <title>Using setup() and teardown() :</title>
      <programlisting language="javascript">
module( &quot;Module One&quot;, {
    setup: function() {
        // run before
    },
    teardown: function() {
        // run after
    }
});

test(&quot;first test&quot;, function() {
    // run the first test
});
</programlisting>
      <para>
        These callbacks can be used to define (or clear) any components
        we wish to instantiate for use in one or more of our tests. As
        we’ll see shortly, this is ideal for defining new instances of
        views, collections, models or routers from a project that we can
        then reference across multiple tests.
      </para>
    </sect3>
    <sect3 id="using-setup-and-teardown-for-instantiation-and-clean-up">
      <title>Using setup() and teardown() for instantiation and
      clean-up:</title>
      <programlisting language="javascript">
// Define a simple model and collection modeling a store and
// list of stores

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

var StoreList = Backbone.Collection.extend({
    model: store,
    comparator: function( store ) { return store.get('name') }
});

// Define a group for our tests
module( &quot;StoreList sanity check&quot;, {
    setup: function() {
        this.list = new StoreList;
        this.list.add(new Store({ name: &quot;Costcutter&quot; }));
        this.list.add(new Store({ name: &quot;Target&quot; }));
        this.list.add(new Store({ name: &quot;Walmart&quot; }));
        this.list.add(new Store({ name: &quot;Barnes &amp; Noble&quot; });
    },
    teardown: function() {
        window.errors = null;
    }
});

// Test the order of items added
test( &quot;test ordering&quot;, function() {
    expect( 1 );
    var expected = [&quot;Barnes &amp; Noble&quot;, &quot;Costcutter&quot;, &quot;Target&quot;, &quot;Walmart&quot;];
    var actual = this.list.pluck(&quot;name&quot;);
    deepEqual( actual, expected, &quot;is maintained by comparator&quot; );
});
</programlisting>
      <para>
        Here, a list of stores is created and stored on
        <literal>setup()</literal>. A <literal>teardown()</literal>
        callback is used to simply clear our a list of errors we might
        be storing within the window scope, but is otherwise not needed.
      </para>
    </sect3>
  </sect2>
  <sect2 id="assertion-examples">
    <title>Assertion examples</title>
    <para>
      Before we continue any further, let’s review some more examples of
      how QUnits various assertions can be correctly used when writing
      tests:
    </para>
    <sect3 id="equal---a-comparison-assertion.-it-passes-if-actual-expected">
      <title>equal - a comparison assertion. It passes if actual ==
      expected</title>
      <programlisting language="javascript">
test( &quot;equal&quot;, 2, function() {
  var actual = 6 - 5;
  equal( actual, true,  &quot;passes as 1 == true&quot; );
  equal( actual, 1,     &quot;passes as 1 == 1&quot; );
});
</programlisting>
    </sect3>
    <sect3 id="notequal---a-comparison-assertion.-it-passes-if-actual-expected">
      <title>notEqual - a comparison assertion. It passes if actual !=
      expected</title>
      <programlisting language="javascript">
test( &quot;notEqual&quot;, 2, function() {
  var actual = 6 - 5;
  notEqual( actual, false, &quot;passes as 1 != false&quot; );
  notEqual( actual, 0,     &quot;passes as 1 != 0&quot; );
});
</programlisting>
    </sect3>
    <sect3 id="strictequal---a-comparison-assertion.-it-passes-if-actual-expected.">
      <title>strictEqual - a comparison assertion. It passes if actual
      === expected.</title>
      <programlisting language="javascript">
test( &quot;strictEqual&quot;, 2, function() {
  var actual = 6 - 5;
  strictEqual( actual, true,  &quot;fails as 1 !== true&quot; );
  strictEqual( actual, 1,     &quot;passes as 1 === 1&quot; );
});
</programlisting>
    </sect3>
    <sect3 id="notstrictequal---a-comparison-assertion.-it-passes-if-actual-expected.">
      <title>notStrictEqual - a comparison assertion. It passes if
      actual !== expected.</title>
      <programlisting language="javascript">
test(&quot;notStrictEqual&quot;, 2, function() {
  var actual = 6 - 5;
  notStrictEqual( actual, true,  &quot;passes as 1 !== true&quot; );
  notStrictEqual( actual, 1,     &quot;fails as 1 === 1&quot; );
});
</programlisting>
    </sect3>
    <sect3 id="deepequal---a-recursive-comparison-assertion.-unlike-strictequal-it-works-on-objects-arrays-and-primitives.">
      <title>deepEqual - a recursive comparison assertion. Unlike
      strictEqual(), it works on objects, arrays and primitives.</title>
      <programlisting language="javascript">
test(&quot;deepEqual&quot;, 4, function() {
  var actual = {q: 'foo', t: 'bar'};
  var el =  $('div');
  var children = $('div').children();

  equal( actual, {q: 'foo', t: 'bar'},   &quot;fails - objects are not equal using equal()&quot; );
  deepEqual( actual, {q: 'foo', t: 'bar'},   &quot;passes - objects are equal&quot; );
  equal( el, children, &quot;fails - jQuery objects are not the same&quot; );
  deepEqual(el, children, &quot;fails - objects not equivalent&quot; );

});
</programlisting>
    </sect3>
    <sect3 id="notdeepequal---a-comparison-assertion.-this-returns-the-opposite-of-deepequal">
      <title>notDeepEqual - a comparison assertion. This returns the
      opposite of deepEqual</title>
      <programlisting language="javascript">
test(&quot;notDeepEqual&quot;, 2, function() {
  var actual = {q: 'foo', t: 'bar'};
  notEqual( actual, {q: 'foo', t: 'bar'},   &quot;passes - objects are not equal&quot; );
  notDeepEqual( actual, {q: 'foo', t: 'bar'},   &quot;fails - objects are equivalent&quot; );
});
</programlisting>
    </sect3>
    <sect3 id="raises---an-assertion-which-tests-if-a-callback-throws-any-exceptions">
      <title>raises - an assertion which tests if a callback throws any
      exceptions</title>
      <programlisting language="javascript">
test(&quot;raises&quot;, 1, function() {
  raises(function() {
    throw new Error( &quot;Oh no! It's an error!&quot; );
  }, &quot;passes - an error was thrown inside our callback&quot;);
});
</programlisting>
    </sect3>
  </sect2>
  <sect2 id="fixtures">
    <title>Fixtures</title>
    <para>
      From time to time we may need to write tests that modify the DOM.
      Managing the clean-up of such operations between tests can be a
      genuine pain, but thankfully QUnit has a solution to this problem
      in the form of the <literal>#qunit-fixture</literal> element, seen
      below.
    </para>
    <sect3 id="fixture-markup">
      <title>Fixture markup:</title>
      <programlisting language="html">
&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
    &lt;title&gt;QUnit Test&lt;/title&gt;
    &lt;link rel=&quot;stylesheet&quot; href=&quot;qunit.css&quot;&gt;
    &lt;script src=&quot;qunit.js&quot;&gt;&lt;/script&gt;
    &lt;script src=&quot;app.js&quot;&gt;&lt;/script&gt;
    &lt;script src=&quot;tests.js&quot;&gt;&lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
    &lt;h1 id=&quot;qunit-header&quot;&gt;QUnit Test&lt;/h1&gt;
    &lt;h2 id=&quot;qunit-banner&quot;&gt;&lt;/h2&gt;
    &lt;div id=&quot;qunit-testrunner-toolbar&quot;&gt;&lt;/div&gt;
    &lt;h2 id=&quot;qunit-userAgent&quot;&gt;&lt;/h2&gt;
    &lt;ol id=&quot;qunit-tests&quot;&gt;&lt;/ol&gt;
    &lt;div id=&quot;qunit-fixture&quot;&gt;&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;
</programlisting>
      <para>
        We can either opt to place static markup in the fixture or just
        insert/append any DOM elements we may need to it. QUnit will
        automatically reset the <literal>innerHTML</literal> of the
        fixture after each test to its original value. In case you’re
        using jQuery, it’s useful to know that QUnit checks for its
        availability and will opt to use <literal>$(el).html()</literal>
        instead, which will cleanup any jQuery event handlers too.
      </para>
    </sect3>
    <sect3 id="fixtures-example">
      <title>Fixtures example:</title>
      <para>
        Let us now go through a more complete example of using fixtures.
        One thing that most of us are used to doing in jQuery is working
        with lists - they’re often used to define the markup for menus,
        grids and a number of other components. You may have used jQuery
        plugins before that manipulated a given list in a particular way
        and it can be useful to test that the final (manipulated) output
        of the plugin is what was expected.
      </para>
      <para>
        For the purposes of our next example, we’re going to use Ben
        Alman’s <literal>$.enumerate()</literal> plugin, which can
        prepend each item in a list by its index, optionally allowing us
        to set what the first number in the list is. The code snippet
        for the plugin can be found below, followed by an example of the
        output is generates:
      </para>
      <programlisting language="javascript">
$.fn.enumerate = function( start ) {
      if ( typeof start !== &quot;undefined&quot; ) {
        // Since `start` value was provided, enumerate and return
        // the initial jQuery object to allow chaining.

        return this.each(function(i){
          $(this).prepend( &quot;&lt;b&gt;&quot; + ( i + start ) + &quot;&lt;/b&gt; &quot; );
        });

      } else {
        // Since no `start` value was provided, function as a
        // getter, returing the appropriate value from the first
        // selected element.

        var val = this.eq( 0 ).children( &quot;b&quot; ).eq( 0 ).text();
        return Number( val );
      }
    };

/*
    &lt;ul&gt;
      &lt;li&gt;1. hello&lt;/li&gt;
      &lt;li&gt;2. world&lt;/li&gt;
      &lt;li&gt;3. i&lt;/li&gt;
      &lt;li&gt;4. am&lt;/li&gt;
      &lt;li&gt;5. foo&lt;/li&gt;
    &lt;/ul&gt;
*/
</programlisting>
      <para>
        Let’s now write some specs for the plugin. First, we define the
        markup for a list containing some sample items inside our
        <literal>qunit-fixture</literal> element:
      </para>
      <programlisting language="html">
&amp;lt;div id=&amp;quot;qunit-fixture&amp;quot;&amp;gt;
    &amp;lt;ul&amp;gt;
      &amp;lt;li&amp;gt;hello&amp;lt;/li&amp;gt;
      &amp;lt;li&amp;gt;world&amp;lt;/li&amp;gt;
      &amp;lt;li&amp;gt;i&amp;lt;/li&amp;gt;
      &amp;lt;li&amp;gt;am&amp;lt;/li&amp;gt;
      &amp;lt;li&amp;gt;foo&amp;lt;/li&amp;gt;
    &amp;lt;/ul&amp;gt;
  &amp;lt;/div&amp;gt;
</programlisting>
      <para>
        Next, we need to think about what should be tested.
        <literal>$.enumerate()</literal> supports a few different use
        cases, including:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="strong">No arguments passed</emphasis> - i.e
            <literal>$(el).enumerate()</literal>
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">0 passed as an argument</emphasis> -
            i.e <literal>$(el).enumerate(0)</literal>
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="strong">1 passed as an argument</emphasis> -
            i.e <literal>$(el).enumerate(1)</literal>
          </para>
        </listitem>
      </itemizedlist>
      <para>
        As the text value for each list item is of the form <quote>n.
        item-text</quote> and we only require this to test against the
        expected output, we can simply access the content using
        <literal>$(el).eq(index).text()</literal> (for more information
        on .eq() see
        <ulink url="http://api.jquery.com/eq/">here</ulink>).
      </para>
      <para>
        and finally, here are our test cases:
      </para>
      <programlisting language="javascript">
module(&quot;jQuery#enumerate&quot;);

test( &quot;No arguments passed&quot;, 5, function() {
  var items = $(&quot;#qunit-fixture li&quot;).enumerate();
  equal( items.eq(0).text(), &quot;1. hello&quot;, &quot;first item should have index 1&quot; );
  equal( items.eq(1).text(), &quot;2. world&quot;, &quot;second item should have index 2&quot; );
  equal( items.eq(2).text(), &quot;3. i&quot;, &quot;third item should have index 3&quot; );
  equal( items.eq(3).text(), &quot;4. am&quot;, &quot;fourth item should have index 4&quot; );
  equal( items.eq(4).text(), &quot;5. foo&quot;, &quot;fifth item should have index 5&quot; );
});

test( &quot;0 passed as an argument&quot;, 5, function() {
  var items = $(&quot;#qunit-fixture li&quot;).enumerate( 0 );
  equal( items.eq(0).text(), &quot;0. hello&quot;, &quot;first item should have index 0&quot; );
  equal( items.eq(1).text(), &quot;1. world&quot;, &quot;second item should have index 1&quot; );
  equal( items.eq(2).text(), &quot;2. i&quot;, &quot;third item should have index 2&quot; );
  equal( items.eq(3).text(), &quot;3. am&quot;, &quot;fourth item should have index 3&quot; );
  equal( items.eq(4).text(), &quot;4. foo&quot;, &quot;fifth item should have index 4&quot; );
});

test( &quot;1 passed as an argument&quot;, 3, function() {
  var items = $(&quot;#qunit-fixture li&quot;).enumerate( 1 );
  equal( items.eq(0).text(), &quot;1. hello&quot;, &quot;first item should have index 1&quot; );
  equal( items.eq(1).text(), &quot;2. world&quot;, &quot;second item should have index 2&quot; );
  equal( items.eq(2).text(), &quot;3. i&quot;, &quot;third item should have index 3&quot; );
  equal( items.eq(3).text(), &quot;4. am&quot;, &quot;fourth item should have index 4&quot; );
  equal( items.eq(4).text(), &quot;5. foo&quot;, &quot;fifth item should have index 5&quot; );
});
</programlisting>
    </sect3>
  </sect2>
  <sect2 id="asynchronous-code">
    <title>Asynchronous code</title>
    <para>
      As with Jasmine, the effort required to run synchronous tests with
      QUnit is fairly straight-forward. That said, what about tests that
      require asynchronous callbacks (such as expensive processes, Ajax
      requests and so on)? When we’re dealing with asynchronous code,
      rather than letting QUnit control when the next test runs, we can
      inform that we need it to stop running and wait until it’s okay to
      continue once again.
    </para>
    <para>
      Remember: running asynchronous code without any special
      considerations can cause incorrect assertions to appear in other
      tests, so we want to make sure we get it right.
    </para>
    <para>
      Writing QUnit tests for asynchronous code is made possible using
      the <literal>start()</literal> and `<literal>stop()</literal>
      methods, which programmatically set the start and stop points
      during such tests. Here’s a simple example:
    </para>
    <programlisting language="javascript">
test(&quot;An async test&quot;, function(){
   stop();
   expect( 1 );
   $.ajax({
        url: &quot;/test&quot;,
        dataType: 'json',
        success: function( data ){
            deepEqual(data, {
               topic: &quot;hello&quot;,
               message: &quot;hi there!&quot;
            });
            start();
        }
    }); 
});
</programlisting>
    <para>
      A jQuery <literal>$.ajax()</literal> request is used to connect to
      a test resource and assert that the data returned is correct.
      <literal>deepEqual()</literal> is used here as it allows us to
      compare different data types (e.g objects, arrays) and ensures
      that what is returned is exactly what we’re expecting. We know
      that our Ajax request is asynchronous and so we first call
      <literal>stop()</literal>, run the code making the request and
      finally at the very end of our callback, inform QUnit that it is
      okay to continue running other tests.
    </para>
    <para>
      Note: rather than including <literal>stop()</literal>, we can
      simply exclude it and substitute <literal>test()</literal> with
      <literal>asyncTest()</literal> if we prefer. This improves
      readability when dealing with a mixture of asynchronous and
      synchronous tests in your suite. Whilst this setup should work
      fine for many use-cases, there is no guarantee that the callback
      in our <literal>$.ajax()</literal> request will actually get
      called. To factor this into our tests, we can use
      <literal>expect()</literal> once again to define how many
      assertions we expect to see within our test. This is a healthy
      safety blanket as it ensures that if a test completes with an
      insufficient number of assertions, we know something went wrong
      and fix it.
    </para>
  </sect2>
</sect1>
<sect1 id="sinonjs">
  <title>SinonJS</title>
  <para>
    Similar to the section on testing Backbone.js apps using the Jasmine
    BDD framework, we’re nearly ready to take what we’ve learned and
    write a number of QUnit tests for our Todo application.
  </para>
  <para>
    Before we start though, you may have noticed that QUnit doesn’t
    support test spies. Test spies are functions which record arguments,
    exceptions and return values for any of their calls. They’re
    typically used to test callbacks and how functions may be used in
    the application being tested. In testing frameworks, spies can
    usually be either anonymous functions or wrap functions which
    already exist.
  </para>
  <sect2 id="what-is-sinonjs">
    <title>What is SinonJS?</title>
    <para>
      In order for us to substitute support for spies in QUnit, we will
      be taking advantage of a mocking framework called
      <ulink url="http://sinonjs.org/">SinonJS</ulink> by Christian
      Johansen. We will also be using the
      <ulink url="http://sinonjs.org/qunit/">SinonJS-QUnit
      adapter</ulink> which provides seamless integration with QUnit
      (meaning setup is minimal). Sinon.JS is completely test-framework
      agnostic and should be easy to use with any testing framework, so
      it’s ideal for our needs.
    </para>
    <para>
      The framework supports three features we’ll be taking advantage of
      for unit testing our application:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <emphasis role="strong">Anonymous spies</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong">Spying on existing methods</emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong">A rich inspection interface</emphasis>
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Using <literal>this.spy()</literal> without any arguments creates
      an anonymous spy. This is comparable to
      <literal>jasmine.createSpy()</literal> and we can observe basic
      usage of a SinonJS spy in the following example:
    </para>
    <sect3 id="basic-spies">
      <title>Basic Spies:</title>
      <programlisting language="javascript">
test(&quot;should call all subscribers for a message exactly once&quot;, function () {
    var message = getUniqueString();
    var spy = this.spy();

    PubSub.subscribe( message, spy );
    PubSub.publishSync( message, &quot;Hello World&quot; );

    ok( spy1.calledOnce, &quot;the subscriber was called once&quot; );
});
</programlisting>
      <para>
        We can also use <literal>this.spy()</literal> to spy on existing
        functions (like jQuery’s <literal>$.ajax</literal>) in the
        example below. When spying on a function which already exists,
        the function behaves normally but we get access to data about
        its calls which can be very useful for testing purposes.
      </para>
    </sect3>
    <sect3 id="spying-on-existing-functions">
      <title>Spying On Existing Functions:</title>
      <programlisting language="javascript">
test( &quot;should inspect jQuery.getJSON's usage of jQuery.ajax&quot;, function () {
    this.spy( jQuery, &quot;ajax&quot; );

    jQuery.getJSON( &quot;/todos/completed&quot; );

    ok( jQuery.ajax.calledOnce );
    equals( jQuery.ajax.getCall(0).args[0].url, &quot;/todos/completed&quot; );
    equals( jQuery.ajax.getCall(0).args[0].dataType, &quot;json&quot; );
});
</programlisting>
      <para>
        SinonJS comes with a rich spy interface which callows us to test
        whether a spy was called with a specific argument, if it was
        called a specific number of times and test against the values of
        arguments. A complete list of features supported in the
        interface can be found here (http://sinonjs.org/docs/), but
        let’s take a look at some examples demonstrating some of the
        most commonly used ones:
      </para>
    </sect3>
    <sect3 id="matching-arguments-test-a-spy-was-called-with-a-specific-set-of-arguments">
      <title>Matching arguments: test a spy was called with a specific
      set of arguments:</title>
      <programlisting language="javascript">
test( &quot;Should call a subscriber with standard matching&quot;: function () {
    var spy = sinon.spy();

    PubSub.subscribe( &quot;message&quot;, spy );
    PubSub.publishSync( &quot;message&quot;, { id: 45 } );

    assertTrue( spy.calledWith( { id: 45 } ) );
});
</programlisting>
    </sect3>
    <sect3 id="stricter-argument-matching-test-a-spy-was-called-at-least-once-with-specific-arguments-and-no-others">
      <title>Stricter argument matching: test a spy was called at least
      once with specific arguments and no others:</title>
      <programlisting language="javascript">
test( &quot;Should call a subscriber with strict matching&quot;: function () {
    var spy = sinon.spy();

    PubSub.subscribe( &quot;message&quot;, spy );
    PubSub.publishSync( &quot;message&quot;, &quot;many&quot;, &quot;arguments&quot; );
    PubSub.publishSync( &quot;message&quot;, 12, 34 );

    // This passes
    assertTrue( spy.calledWith(&quot;many&quot;) );     

    // This however, fails   
    assertTrue( spy.calledWithExactly( &quot;many&quot; ) ); 
});
</programlisting>
    </sect3>
    <sect3 id="testing-call-order-testing-if-a-spy-was-called-before-or-after-another-spy">
      <title>Testing call order: testing if a spy was called before or
      after another spy:</title>
      <programlisting language="javascript">
test( &quot;Should call a subscriber and maintain call order&quot;: function () {
    var a = sinon.spy();
    var b = sinon.spy();

    PubSub.subscribe( &quot;message&quot;, a );
    PubSub.subscribe( &quot;event&quot;, b );

    PubSub.publishSync( &quot;message&quot;, { id: 45 } );
    PubSub.publishSync( &quot;event&quot;, [1, 2, 3] );

    assertTrue( a.calledBefore(b) );
    assertTrue( b.calledAfter(a) );
});
</programlisting>
    </sect3>
    <sect3 id="match-execution-counts-test-a-spy-was-called-a-specific-number-of-times">
      <title>Match execution counts: test a spy was called a specific
      number of times:</title>
      <programlisting language="javascript">
test( &quot;Should call a subscriber and check call counts&quot;, function () {
    var message = getUniqueString();
    var spy = this.spy();

    PubSub.subscribe( message, spy );
    PubSub.publishSync( message, &quot;some payload&quot; );


    // Passes if spy was called once and only once.
    ok( spy.calledOnce ); // calledTwice and calledThrice are also supported

    // The number of recorded calls.
    equal( spy.callCount, 1 );

    // Directly checking the arguments of the call
    equals( spy.getCall(0).args[0], message );
});
</programlisting>
    </sect3>
  </sect2>
  <sect2 id="stubs-and-mocks">
    <title>Stubs and mocks</title>
    <para>
      SinonJS also supports two other powerful features which are useful
      to be aware of: stubs and mocks. Both stubs and mocks implement
      all of the features of the spy API, but have some added
      functionality.
    </para>
    <sect3 id="stubs">
      <title>Stubs</title>
      <para>
        A stub allows us to replace any existing behaviour for a
        specific method with something else. They can be very useful for
        simulating exceptions and are most often used to write test
        cases when certain dependencies of your code-base may not yet be
        written.
      </para>
      <para>
        Let us briefly re-explore our Backbone Todo application, which
        contained a Todo model and a TodoList collection. For the
        purpose of this walkthrough, we want to isolate our TodoList
        collection and fake the Todo model to test how adding new models
        might behave.
      </para>
      <para>
        We can pretend that the models have yet to be written just to
        demonstrate how stubbing might be carried out. A shell
        collection just containing a reference to the model to be used
        might look like this:
      </para>
      <programlisting language="javascript">
var TodoList = Backbone.Collection.extend({
    model: Todo
});

// Let's assume our instance of this collection is
this.todoList;
</programlisting>
      <para>
        Assuming our collection is instantiating new models itself, it’s
        necessary for us to stub the models constructor function for the
        the test. This can be done by creating a simple stub as follows:
      </para>
      <programlisting language="javascript">
this.todoStub = sinon.stub( window, &quot;Todo&quot; );
</programlisting>
      <para>
        The above creates a stub of the Todo method on the window
        object. When stubbing a persistent object, it’s necessary to
        restore it to its original state. This can be done in a
        <literal>teardown()</literal> as follows:
      </para>
      <programlisting language="javascript">
this.todoStub.restore();
</programlisting>
      <para>
        After this, we need to alter what the constructor returns, which
        can be efficiently done using a plain
        <literal>Backbone.Model</literal> constructor. Whilst this isn’t
        a Todo model, it does still provide us an actual Backbone model.
      </para>
      <programlisting language="javascript">
teardown: function() {
    this.todoStub = sinon.stub( window, &quot;Todo&quot; );
    this.model = new Backbone.Model({
      id: 2, 
      title: &quot;Hello world&quot;
    });
    this.todoStub.returns( this.model );
});
</programlisting>
      <para>
        The expectation here might be that this snippet would ensure our
        TodoList collection always instantiates a stubbed Todo model,
        but because a reference to the model in the collection is
        already present, we need to reset the model property of our
        collection as follows:
      </para>
      <programlisting language="javascript">
this.todoList.model = Todo;
</programlisting>
      <para>
        The result of this is that when our TodoList collection
        instantiates new Todo models, it will return our plain Backbone
        model instance as desired. This allows us to write a spec for
        testing the addition of new model literals as follows:
      </para>
      <programlisting language="javascript">
module( &quot;Should function when instantiated with model literals&quot;, {

  setup:function() {

    this.todoStub = sinon.stub(window, &quot;Todo&quot;);
    this.model = new Backbone.Model({
      id: 2, 
      title: &quot;Hello world&quot;
    });

    this.todoStub.returns(this.model);
    this.todos = new TodoList();

    // Let's reset the relationship to use a stub
    this.todos.model = Todo; 
    this.todos.add({
      id: 2, 
      title: &quot;Hello world&quot;
    });
  },

  teardown: function() {
    this.todoStub.restore();
  }

});

test(&quot;should add a model&quot;, function() {
    equal( this.todos.length, 1 );
});

test(&quot;should find a model by id&quot;, function() {
    equal( this.todos.get(5).get(&quot;id&quot;), 5 );
  });
});
</programlisting>
    </sect3>
    <sect3 id="mocks">
      <title>Mocks</title>
      <para>
        Mocks are effectively the same as stubs, however they mock a
        complete API out and have some built-in expectations for how
        they should be used. The difference between a mock and a spy is
        that as the expectations for their use are pre-defined, it will
        fail if any of these are not met.
      </para>
      <para>
        Here’s a snippet with sample usage of a mock based on PubSubJS.
        Here, we have a <literal>clearTodo()</literal> method as a
        callback and use mocks to verify its behavior.
      </para>
      <programlisting language="javascript">
test(&quot;should call all subscribers when exceptions&quot;, function () {
    var myAPI = { clearTodo: function () {} };

    var spy = this.spy();
    var mock = this.mock( myAPI );
    mock.expects( &quot;clearTodo&quot; ).once().throws();

    PubSub.subscribe( &quot;message&quot;, myAPI.clearTodo );
    PubSub.subscribe( &quot;message&quot;, spy );
    PubSub.publishSync( &quot;message&quot;, undefined );

    mock.verify();
    ok( spy.calledOnce );
});
</programlisting>
    </sect3>
  </sect2>
</sect1>
<sect1 id="practical-3">
  <title>Practical</title>
  <para>
    We can now begin writing test specs for our Todo application, which
    are listed and separated by component (e.g Models, Collections
    etc.). It’s useful to pay attention to the name of the test, the
    logic being tested and most importantly the assertions being made as
    this will give you some insight into how what we’ve learned can be
    applied to a complete application.
  </para>
  <para>
    To get the most out of this section, I recommend looking at the
    QUnit Koans included in the
    <literal>practicals\qunit-koans</literal> folder - this is a port of
    the Backbone.js Jasmine Koans over to QUnit that I converted for
    this post.
  </para>
  <para>
    <emphasis>In case you haven’t had a chance to try out one of the
    Koans kits as yet, they are a set of unit tests using a specific
    testing framework that both demonstrate how a set of specs for an
    application may be written, but also leave some tests unfilled so
    that you can complete them as an exercise.</emphasis>
  </para>
  <sect2 id="models-3">
    <title>Models</title>
    <para>
      For our models we want to at minimum test that:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          New instances can be created with the expected default values
        </para>
      </listitem>
      <listitem>
        <para>
          Attributes can be set and retrieved correctly
        </para>
      </listitem>
      <listitem>
        <para>
          Changes to state correctly fire off custom events where needed
        </para>
      </listitem>
      <listitem>
        <para>
          Validation rules are correctly enforced
        </para>
      </listitem>
    </itemizedlist>
    <programlisting language="javascript">
module( 'About Backbone.Model');

test('Can be created with default values for its attributes.', function() {
    expect( 1 );

    var todo = new Todo();

    equal( todo.get('text'), &quot;&quot; );
});

test('Will set attributes on the model instance when created.', function() {
    expect( 3 );

    var todo = new Todo( { text: 'Get oil change for car.' } );

    equal( todo.get('text'), &quot;Get oil change for car.&quot; );
    equal( todo.get('done'), false );
    equal( todo.get('order'), 0 );
});

test('Will call a custom initialize function on the model instance when created.', function() {
    expect( 1 );

    var toot = new Todo({ text: 'Stop monkeys from throwing their own crap!' });
    equal( toot.get('text'), 'Stop monkeys from throwing their own rainbows!' );
});

test('Fires a custom event when the state changes.', function() {
    expect( 1 );

    var spy = this.spy();
    var todo = new Todo();

    todo.bind( 'change', spy );
    // How would you update a property on the todo here?
    // Hint: http://documentcloud.github.com/backbone/#Model-set
    todo.set( { text: &quot;new text&quot; } );

    ok( spy.calledOnce, &quot;A change event callback was correctly triggered&quot; );
});


test('Can contain custom validation rules, and will trigger an error event on failed validation.', function() {
    expect( 3 );

    var errorCallback = this.spy();
    var todo = new Todo();

    todo.bind('error', errorCallback);
    // What would you need to set on the todo properties to cause validation to fail?
    todo.set( { done: &quot;not a boolean&quot; } );

    ok( errorCallback.called, 'A failed validation correctly triggered an error' );
    notEqual( errorCallback.getCall(0), undefined );
    equal( errorCallback.getCall(0).args[1], 'Todo.done must be a boolean value.' );

});
</programlisting>
  </sect2>
  <sect2 id="collections-3">
    <title>Collections</title>
    <para>
      For our collection we’ll want to test that:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          New model instances can be added as both objects and arrays
        </para>
      </listitem>
      <listitem>
        <para>
          Changes to models result in any necessary custom events being
          fired
        </para>
      </listitem>
      <listitem>
        <para>
          A <literal>url</literal> property for defining the URL
          structure for models is correctly defined
        </para>
      </listitem>
    </itemizedlist>
    <programlisting language="javascript">
module( 'About Backbone.Collection');

test( 'Can add Model instances as objects and arrays.', function() {
    expect( 3 );

    var todos = new TodoList();
    equal( todos.length, 0 );

    todos.add( { text: 'Clean the kitchen' } );
    equal( todos.length, 1 );

    todos.add([
        { text: 'Do the laundry', done: true }, 
        { text: 'Go to the gym' }
    ]);

    equal( todos.length, 3 );
});

test( 'Can have a url property to define the basic url structure for all contained models.', function() {
    expect( 1 );
    var todos = new TodoList();
    equal( todos.url, '/todos/' );
});

test('Fires custom named events when the models change.', function() {
    expect(2);

    var todos = new TodoList();
    var addModelCallback = this.spy();
    var removeModelCallback = this.spy();

    todos.bind( 'add', addModelCallback );
    todos.bind( 'remove', removeModelCallback );

    // How would you get the 'add' event to trigger?
    todos.add( {text:&quot;New todo&quot;} );

    ok( addModelCallback.called );

    // How would you get the 'remove' callback to trigger?
    todos.remove( todos.last() );

    ok( removeModelCallback.called );
});
</programlisting>
  </sect2>
  <sect2 id="views-4">
    <title>Views</title>
    <para>
      For our views we want to ensure:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          They are being correctly tied to a DOM element when created
        </para>
      </listitem>
      <listitem>
        <para>
          They can render, after which the DOM representation of the
          view should be visible
        </para>
      </listitem>
      <listitem>
        <para>
          They support wiring up view methods to DOM elements
        </para>
      </listitem>
    </itemizedlist>
    <para>
      One could also take this further and test that user interactions
      with the view correctly result in any models that need to be
      changed being updated correctly.
    </para>
    <programlisting language="javascript">
module( 'About Backbone.View', {
    setup: function() {
        $('body').append('&lt;ul id=&quot;todoList&quot;&gt;&lt;/ul&gt;');
        this.todoView = new TodoView({ model: new Todo() });
    },
    teardown: function() {
        this.todoView.remove();
        $('#todoList').remove();
    }
});

test('Should be tied to a DOM element when created, based off the property provided.', function() {
    expect( 1 );
    equal( this.todoView.el.tagName.toLowerCase(), 'li' );
});

test('Is backed by a model instance, which provides the data.', function() {
    expect( 2 );
    notEqual( this.todoView.model, undefined );
    equal( this.todoView.model.get('done'), false );
});

test('Can render, after which the DOM representation of the view will be visible.', function() {
   this.todoView.render();

    // Hint: render() just builds the DOM representation of the view, but doesn't insert it into the DOM.
    //       How would you append it to the ul#todoList? 
    //       How do you access the view's DOM representation?
    //
    // Hint: http://documentcloud.github.com/backbone/#View-el

    $('ul#todoList').append(this.todoView.el);
    equal($('#todoList').find('li').length, 1);
});

asyncTest('Can wire up view methods to DOM elements.', function() {
    expect( 2 );
    var viewElt;    

    $('#todoList').append( this.todoView.render().el );

    setTimeout(function() {
        viewElt = $('#todoList li input.check').filter(':first');

        equal(viewElt.length &gt; 0, true);

        // Make sure that QUnit knows we can continue
        start();
    }, 1000, 'Expected DOM Elt to exist');


    // Hint: How would you trigger the view, via a DOM Event, to toggle the 'done' status.
    //       (See todos.js line 70, where the events hash is defined.)
    //
    // Hint: http://api.jquery.com/click

    $('#todoList li input.check').click();
    expect( this.todoView.model.get('done'), true );
});
</programlisting>
  </sect2>
  <sect2 id="events">
    <title>Events</title>
    <para>
      For events, we may want to test a few different use cases:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Extending plain objects to support custom events
        </para>
      </listitem>
      <listitem>
        <para>
          Binding and triggering custom events on objects
        </para>
      </listitem>
      <listitem>
        <para>
          Passing along arguments to callbacks when events are triggered
        </para>
      </listitem>
      <listitem>
        <para>
          Binding a passed context to an event callback
        </para>
      </listitem>
      <listitem>
        <para>
          Removing custom events
        </para>
      </listitem>
    </itemizedlist>
    <para>
      and a few others that will be detailed in our module below:
    </para>
    <programlisting language="javascript">
module( 'About Backbone.Events', {
    setup: function() {
        this.obj = {};
        _.extend( this.obj, Backbone.Events );
        this.obj.unbind(); // remove all custom events before each spec is run.
    }
});

test('Can extend JavaScript objects to support custom events.', function() {
    expect(3);

    var basicObject = {};

    // How would you give basicObject these functions?
    // Hint: http://documentcloud.github.com/backbone/#Events
    _.extend( basicObject, Backbone.Events );

    equal( typeof basicObject.bind, 'function' );
    equal( typeof basicObject.unbind, 'function' );
    equal( typeof basicObject.trigger, 'function' );
});

test('Allows us to bind and trigger custom named events on an object.', function() {
    expect( 1 );

    var callback = this.spy();

    this.obj.bind( 'basic event', callback );
    this.obj.trigger( 'basic event' );

    // How would you cause the callback for this custom event to be called?
    ok( callback.called );
});

test('Also passes along any arguments to the callback when an event is triggered.', function() {
    expect( 1 );

    var passedArgs = [];

    this.obj.bind('some event', function() {
        for (var i = 0; i &lt; arguments.length; i++) {
            passedArgs.push( arguments[i] );
        }
    });

    this.obj.trigger( 'some event', 'arg1', 'arg2' );

    deepEqual( passedArgs, ['arg1', 'arg2'] );
});


test('Can also bind the passed context to the event callback.', function() {
    expect( 1 );

    var foo = { color: 'blue' };
    var changeColor = function() {
        this.color = 'red';
    };

    // How would you get 'this.color' to refer to 'foo' in the changeColor function?
    this.obj.bind( 'an event', changeColor, foo );
    this.obj.trigger( 'an event' );

    equal( foo.color, 'red' );
});

test( &quot;Uses 'all' as a special event name to capture all events bound to the object.&quot; , function() {
    expect( 2 );

    var callback = this.spy();

    this.obj.bind( 'all', callback );
    this.obj.trigger( &quot;custom event 1&quot; );
    this.obj.trigger( &quot;custom event 2&quot; );

    equal( callback.callCount, 2 );
    equal( callback.getCall(0).args[0], 'custom event 1' );
});

test('Also can remove custom events from objects.', function() {
    expect( 5 );

    var spy1 = this.spy();
    var spy2 = this.spy();
    var spy3 = this.spy();

    this.obj.bind( 'foo', spy1 );
    this.obj.bind( 'bar', spy1 );
    this.obj.bind( 'foo', spy2 );
    this.obj.bind( 'foo', spy3 );

    // How do you unbind just a single callback for the event?
    this.obj.unbind( 'foo', spy1 );
    this.obj.trigger( 'foo' );

    ok( spy2.called );

    // How do you unbind all callbacks tied to the event with a single method
    this.obj.unbind( 'foo' );
    this.obj.trigger( 'foo' );

    ok( spy2.callCount, 1 );
    ok( spy2.calledOnce, &quot;Spy 2 called once&quot; );
    ok( spy3.calledOnce, &quot;Spy 3 called once&quot; );

    // How do you unbind all callbacks and events tied to the object with a single method?
    this.obj.unbind( 'bar' );
    this.obj.trigger( 'bar' );

    equal( spy1.callCount, 0 );
});
</programlisting>
  </sect2>
  <sect2 id="app">
    <title>App</title>
    <para>
      It can also be useful to write specs for any application bootstrap
      you may have in place. For the following module, our setup
      initiates and appends a TodoApp view and we can test anything from
      local instances of views being correctly defined to application
      interactions correctly resulting in changes to instances of local
      collections.
    </para>
    <programlisting language="javascript">
module( 'About Backbone Applications' , {
    setup: function() {
        Backbone.localStorageDB = new Store('testTodos');
        $('#qunit-fixture').append('&lt;div id=&quot;app&quot;&gt;&lt;/div&gt;');   
        this.App = new TodoApp({ appendTo: $('#app') });
    },

    teardown: function() {
        this.App.todos.reset();
        $('#app').remove();
    }
});

test('Should bootstrap the application by initializing the Collection.', function() {
    expect( 2 );

    notEqual( this.App.todos, undefined );
    equal( this.App.todos.length, 0 );
});

test( 'Should bind Collection events to View creation.' , function() {
      $('#new-todo').val( 'Foo' );
      $('#new-todo').trigger(new $.Event( 'keypress', { keyCode: 13 } ));

      equal( this.App.todos.length, 1 );
 });
</programlisting>
  </sect2>
  <sect2 id="further-reading-resources">
    <title>Further Reading &amp; Resources</title>
    <para>
      That’s it for this section on testing applications with QUnit and
      SinonJS. I encourage you to try out the
      <ulink url="https://github.com/addyosmani/backbone-koans-qunit">QUnit
      Backbone.js Koans</ulink> and see if you can extend some of the
      examples. For further reading consider looking at some of the
      additional resources below:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="http://tddjs.com/">Test-driven
          JavaScript Development (book)</ulink></emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="http://sinonjs.org/qunit/">SinonJS/QUnit
          Adapter</ulink></emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="http://cjohansen.no/en/javascript/using_sinon_js_with_qunit">SinonJS
          and QUnit</ulink></emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="http://msdn.microsoft.com/en-us/scriptjunkie/gg749824">Automating
          JavaScript Testing With QUnit</ulink></emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="http://benalman.com/talks/unit-testing-qunit.html">Ben
          Alman’s Unit Testing With QUnit</ulink></emphasis>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="https://github.com/jc00ke/qunit-backbone">Another
          QUnit/Backbone.js demo
          project</ulink></emphasis><literallayout></literallayout>
        </para>
      </listitem>
      <listitem>
        <para>
          <emphasis role="strong"><ulink url="http://devblog.supportbee.com/2012/02/10/helpers-for-testing-backbone-js-apps-using-jasmine-and-sinon-js/">SinonJS
          helpers for Backbone</ulink></emphasis>
        </para>
      </listitem>
    </itemizedlist>
  </sect2>
  <sect2 id="resources">
    <title><a name="resources">Resources</a></title>
    <para>
      Whilst we get with Backbone out of the box can be terribly useful,
      there are some equally beneficial add-ons that can help simplify
      our development process. These include:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          <ulink url="https://github.com/tbranyen/backbone.layoutmanager">Backbone
          Layout Manager</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/tbranyen/backbone-boilerplate">Backbone
          Boilerplate</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/derickbailey/backbone.modelbinding">Backbone
          Model Binding</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/PaulUithol/Backbone-relational">Backbone
          Relational - for model relationships</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://gist.github.com/1271041">View and model
          inheritance</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/derickbailey/backbone.marionette">Backbone
          Marionette</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/janmonschke/backbone-couchdb">Backbone
          CouchDB</ulink>
        </para>
      </listitem>
      <listitem>
        <para>
          <ulink url="https://github.com/n-time/backbone.validations">Backbone
          Validations - HTML5 inspired validations</ulink>
        </para>
      </listitem>
    </itemizedlist>
    <para>
      In time, there will be tutorials in the book covering some of
      these resources but until then, please feel free to check them
      out.
    </para>
  </sect2>
  <sect2 id="conclusions-2">
    <title><a name="conclusions">Conclusions</a></title>
    <para>
      That’s it for <quote>Developing Backbone.js Applications</quote>.
      I hope you found this book both useful, enlightening and a good
      start for your journey into exploring Backbone.js.
    </para>
    <para>
      Remember, If there are other topics or areas of this book you feel
      could be expanded further, please feel free to let me know, or
      better yet, send a pull request upstream. I’m always interested in
      making this title as comprehensive as possible.
    </para>
    <para>
      Until next time, the very best of luck with the rest of your
      journey!
    </para>
    <para>
      Copyright Addy Osmani, 2012.
    </para>
  </sect2>
</sect1>
</article>