PageRenderTime 124ms CodeModel.GetById 5ms app.highlight 89ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

https://github.com/anushr/backbone
HTML | 3518 lines | 3044 code | 474 blank | 0 comment | 0 complexity | 392c4078188549fa6d0c2a674e0f5163 MD5 | raw file
   1<!DOCTYPE HTML>
   2<html>
   3<head>
   4  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
   5  <meta http-equiv="X-UA-Compatible" content="chrome=1" />
   6  <link rel="icon" href="docs/images/favicon.ico" />
   7  <title>Backbone.js</title>
   8  <style>
   9    body {
  10      font-size: 14px;
  11      line-height: 22px;
  12      font-family: Helvetica Neue, Helvetica, Arial;
  13      background: #f4f4f4 url(docs/images/background.png);
  14    }
  15    .interface {
  16      font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, sans-serif !important;
  17    }
  18    div#sidebar {
  19      background: #fff;
  20      position: fixed;
  21      top: 0; left: 0; bottom: 0;
  22      width: 200px;
  23      overflow-y: auto;
  24      overflow-x: hidden;
  25      padding: 15px 0 30px 30px;
  26      border-right: 1px solid #bbb;
  27      box-shadow: 0 0 20px #ccc; -webkit-box-shadow: 0 0 20px #ccc; -moz-box-shadow: 0 0 20px #ccc;
  28    }
  29      a.toc_title, a.toc_title:visited {
  30        display: block;
  31        color: black;
  32        font-weight: bold;
  33        margin-top: 15px;
  34      }
  35        a.toc_title:hover {
  36          text-decoration: underline;
  37        }
  38        #sidebar .version {
  39          font-size: 10px;
  40          font-weight: normal;
  41        }
  42      ul.toc_section {
  43        font-size: 11px;
  44        line-height: 14px;
  45        margin: 5px 0 0 0;
  46        padding-left: 0px;
  47        list-style-type: none;
  48        font-family: Lucida Grande;
  49      }
  50        .toc_section li {
  51          cursor: pointer;
  52          margin: 0 0 3px 0;
  53        }
  54          .toc_section li a {
  55            text-decoration: none;
  56            color: black;
  57          }
  58            .toc_section li a:hover {
  59              text-decoration: underline;
  60            }
  61    div.container {
  62      position: relative;
  63      width: 550px;
  64      margin: 40px 0 50px 260px;
  65    }
  66    div.run {
  67      position: absolute;
  68      right: 15px;
  69      width: 26px; height: 18px;
  70      background: url('docs/images/arrows.png') no-repeat -26px 0;
  71    }
  72      div.run:active {
  73        background-position: -51px 0;
  74      }
  75    p, div.container ul {
  76      margin: 25px 0;
  77      width: 550px;
  78    }
  79      p.warning {
  80        font-size: 12px;
  81        line-height: 18px;
  82        font-style: italic;
  83      }
  84      div.container ul {
  85        list-style: circle;
  86        padding-left: 15px;
  87        font-size: 13px;
  88        line-height: 18px;
  89      }
  90        div.container ul li {
  91          margin-bottom: 10px;
  92        }
  93        div.container ul.small {
  94          font-size: 12px;
  95        }
  96    a, a:visited {
  97      color: #444;
  98    }
  99    a:active, a:hover {
 100      color: #000;
 101    }
 102    a.punch {
 103      display: inline-block;
 104      background: #4162a8;
 105      border-top: 1px solid #38538c;
 106      border-right: 1px solid #1f2d4d;
 107      border-bottom: 1px solid #151e33;
 108      border-left: 1px solid #1f2d4d;
 109      -webkit-border-radius: 4px;
 110      -moz-border-radius: 4px;
 111      -ms-border-radius: 4px;
 112      -o-border-radius: 4px;
 113      border-radius: 4px;
 114      -webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 115      -moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 116      -ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 117      -o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 118      box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 119      color: #fff;
 120      font: bold 14px "helvetica neue", helvetica, arial, sans-serif;
 121      line-height: 1;
 122      margin-bottom: 15px;
 123      padding: 8px 0 10px 0;
 124      text-align: center;
 125      text-shadow: 0px -1px 1px #1e2d4d;
 126      text-decoration: none;
 127      width: 225px;
 128      -webkit-background-clip: padding-box; }
 129      a.punch:hover {
 130        -webkit-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 131        -moz-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 132        -ms-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 133        -o-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 134        box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 135        cursor: pointer; }
 136      a.punch:active {
 137        -webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 138        -moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 139        -ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 140        -o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 141        box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 142        margin-top: 5px; margin-bottom: 10px }
 143    a img {
 144      border: 0;
 145    }
 146    h1, h2, h3, h4, h5, h6 {
 147      padding-top: 20px;
 148    }
 149      h2 {
 150        font-size: 22px;
 151      }
 152    b.header {
 153      font-size: 18px;
 154      line-height: 35px;
 155    }
 156    span.alias {
 157      font-size: 14px;
 158      font-style: italic;
 159      margin-left: 20px;
 160    }
 161    table {
 162      margin: 15px 0 0; padding: 0;
 163    }
 164      tr, td {
 165        margin: 0; padding: 0;
 166      }
 167        td {
 168          padding: 0px 15px 5px 0;
 169        }
 170    code, pre, tt {
 171      font-family: Monaco, Consolas, "Lucida Console", monospace;
 172      font-size: 12px;
 173      line-height: 18px;
 174      font-style: normal;
 175    }
 176      tt {
 177        padding: 0px 3px;
 178        background: #fff;
 179        border: 1px solid #ddd;
 180        zoom: 1;
 181      }
 182      code {
 183        margin-left: 20px;
 184      }
 185      pre {
 186        font-size: 12px;
 187        padding: 2px 0 2px 15px;
 188        border: 4px solid #bbb; border-top: 0; border-bottom: 0;
 189        margin: 0px 0 25px;
 190      }
 191      img.example_image {
 192        margin: 0px auto;
 193      }
 194  </style>
 195</head>
 196<body>
 197
 198  <div id="sidebar" class="interface">
 199
 200    <a class="toc_title" href="#">
 201      Backbone.js <span class="version">(0.9.1)</span>
 202    </a>
 203    <ul class="toc_section">
 204      <li><a href="http://github.com/documentcloud/backbone">github repo</a></li>
 205      <li><a href="docs/backbone.html">annotated source</a></li>
 206    </ul>
 207
 208    <a class="toc_title" href="#introduction">
 209      Introduction
 210    </a>
 211
 212    <a class="toc_title" href="#upgrading">
 213      Upgrading
 214    </a>
 215
 216    <a class="toc_title" href="#Events">
 217      Events
 218    </a>
 219    <ul class="toc_section">
 220      <li><a href="#Events-on">on</a></li>
 221      <li><a href="#Events-off">off</a></li>
 222      <li><a href="#Events-trigger">trigger</a></li>
 223    </ul>
 224
 225    <a class="toc_title" href="#Model">
 226      Model
 227    </a>
 228    <ul class="toc_section">
 229      <li><a href="#Model-extend">extend</a></li>
 230      <li><a href="#Model-constructor">constructor / initialize</a></li>
 231      <li><a href="#Model-get">get</a></li>
 232      <li><a href="#Model-set">set</a></li>
 233      <li><a href="#Model-escape">escape</a></li>
 234      <li><a href="#Model-has">has</a></li>
 235      <li><a href="#Model-unset">unset</a></li>
 236      <li><a href="#Model-clear">clear</a></li>
 237      <li><a href="#Model-id">id</a></li>
 238      <li><a href="#Model-idAttribute">idAttribute</a></li>
 239      <li><a href="#Model-cid">cid</a></li>
 240      <li><a href="#Model-attributes">attributes</a></li>
 241      <li><a href="#Model-changed">changed</a></li>
 242      <li><a href="#Model-defaults">defaults</a></li>
 243      <li><a href="#Model-toJSON">toJSON</a></li>
 244      <li><a href="#Model-fetch">fetch</a></li>
 245      <li><a href="#Model-save">save</a></li>
 246      <li><a href="#Model-destroy">destroy</a></li>
 247      <li><a href="#Model-validate">validate</a></li>
 248      <li><a href="#Model-isValid">isValid</a></li>
 249      <li><a href="#Model-url">url</a></li>
 250      <li><a href="#Model-urlRoot">urlRoot</a></li>
 251      <li><a href="#Model-parse">parse</a></li>
 252      <li><a href="#Model-clone">clone</a></li>
 253      <li><a href="#Model-isNew">isNew</a></li>
 254      <li><a href="#Model-change">change</a></li>
 255      <li><a href="#Model-hasChanged">hasChanged</a></li>
 256      <li><a href="#Model-changedAttributes">changedAttributes</a></li>
 257      <li><a href="#Model-previous">previous</a></li>
 258      <li><a href="#Model-previousAttributes">previousAttributes</a></li>
 259    </ul>
 260
 261    <a class="toc_title" href="#Collection">
 262      Collection
 263    </a>
 264    <ul class="toc_section">
 265      <li><a href="#Collection-extend">extend</a></li>
 266      <li><a href="#Collection-model">model</a></li>
 267      <li><a href="#Collection-constructor">constructor / initialize</a></li>
 268      <li><a href="#Collection-models">models</a></li>
 269      <li><a href="#Collection-toJSON">toJSON</a></li>
 270      <li><a href="#Collection-Underscore-Methods"><b>Underscore Methods (28)</b></a></li>
 271      <li><a href="#Collection-add">add</a></li>
 272      <li><a href="#Collection-remove">remove</a></li>
 273      <li><a href="#Collection-get">get</a></li>
 274      <li><a href="#Collection-getByCid">getByCid</a></li>
 275      <li><a href="#Collection-at">at</a></li>
 276      <li><a href="#Collection-length">length</a></li>
 277      <li><a href="#Collection-comparator">comparator</a></li>
 278      <li><a href="#Collection-sort">sort</a></li>
 279      <li><a href="#Collection-pluck">pluck</a></li>
 280      <li><a href="#Collection-url">url</a></li>
 281      <li><a href="#Collection-parse">parse</a></li>
 282      <li><a href="#Collection-fetch">fetch</a></li>
 283      <li><a href="#Collection-reset">reset</a></li>
 284      <li><a href="#Collection-create">create</a></li>
 285    </ul>
 286
 287    <a class="toc_title" href="#Router">
 288      Router
 289    </a>
 290    <ul class="toc_section">
 291      <li><a href="#Router-extend">extend</a></li>
 292      <li><a href="#Router-routes">routes</a></li>
 293      <li><a href="#Router-constructor">constructor / initialize</a></li>
 294      <li><a href="#Router-route">route</a></li>
 295      <li><a href="#Router-navigate">navigate</a></li>
 296    </ul>
 297
 298    <a class="toc_title" href="#History">
 299      History
 300    </a>
 301    <ul class="toc_section">
 302      <li><a href="#History-start">start</a></li>
 303    </ul>
 304
 305    <a class="toc_title" href="#Sync">
 306      Sync
 307    </a>
 308    <ul class="toc_section">
 309      <li><a href="#Sync">Backbone.sync</a></li>
 310      <li><a href="#Sync-emulateHTTP">Backbone.emulateHTTP</a></li>
 311      <li><a href="#Sync-emulateJSON">Backbone.emulateJSON</a></li>
 312    </ul>
 313
 314    <a class="toc_title" href="#View">
 315      View
 316    </a>
 317    <ul class="toc_section">
 318      <li><a href="#View-extend">extend</a></li>
 319      <li><a href="#View-constructor">constructor / initialize</a></li>
 320      <li><a href="#View-el">el</a></li>
 321      <li><a href="#View-$el">$el</a></li>
 322      <li><a href="#View-setElement">setElement</a></li>
 323      <li><a href="#View-attributes">attributes</a></li>
 324      <li><a href="#View-dollar">$ (jQuery or Zepto)</a></li>
 325      <li><a href="#View-render">render</a></li>
 326      <li><a href="#View-remove">remove</a></li>
 327      <li><a href="#View-make">make</a></li>
 328      <li><a href="#View-delegateEvents">delegateEvents</a></li>
 329      <li><a href="#View-undelegateEvents">undelegateEvents</a></li>
 330    </ul>
 331
 332    <a class="toc_title" href="#Utility">
 333      Utility
 334    </a>
 335    <ul class="toc_section">
 336      <li><a href="#Utility-noConflict">noConflict</a></li>
 337      <li><a href="#Utility-setDomLibrary">setDomLibrary</a></li>
 338    </ul>
 339
 340    <a class="toc_title" href="#examples">
 341      Examples
 342    </a>
 343    <ul class="toc_section">
 344      <li><a href="#examples-todos">Todos</a></li>
 345      <li><a href="#examples-documentcloud">DocumentCloud</a></li>
 346      <li><a href="#examples-linkedin">LinkedIn Mobile</a></li>
 347      <li><a href="#examples-flow">Flow</a></li>
 348      <li><a href="#examples-audiovroom">AudioVroom</a></li>
 349      <li><a href="#examples-foursquare">Foursquare</a></li>
 350      <li><a href="#examples-wunderkit">Wunderkit</a></li>
 351      <li><a href="#examples-khan-academy">Khan Academy</a></li>
 352      <li><a href="#examples-do">Do</a></li>
 353      <li><a href="#examples-posterous">Posterous Spaces</a></li>
 354      <li><a href="#examples-groupon">Groupon Now!</a></li>
 355      <li><a href="#examples-basecamp">Basecamp Mobile</a></li>
 356      <li><a href="#examples-slavery-footprint">Slavery Footprint</a></li>
 357      <li><a href="#examples-stripe">Stripe</a></li>
 358      <li><a href="#examples-diaspora">Diaspora</a></li>
 359      <li><a href="#examples-soundcloud">SoundCloud Mobile</a></li>
 360      <li><a href="#examples-pandora">Pandora</a></li>
 361      <li><a href="#examples-code-school">Code School</a></li>
 362      <li><a href="#examples-cloudapp">CloudApp</a></li>
 363      <li><a href="#examples-seatgeek">SeatGeek</a></li>
 364      <li><a href="#examples-grove">Grove.io</a></li>
 365      <li><a href="#examples-kicksend">Kicksend</a></li>
 366      <li><a href="#examples-shortmail">Shortmail</a></li>
 367      <li><a href="#examples-battlefield">Battlefield Play4Free</a></li>
 368      <li><a href="#examples-salon">Salon.io</a></li>
 369      <li><a href="#examples-tilemill">TileMill</a></li>
 370      <li><a href="#examples-blossom">Blossom</a></li>
 371      <li><a href="#examples-animoto">Animoto</a></li>
 372      <li><a href="#examples-codiqa">Codiqa</a></li>
 373      <li><a href="#examples-attictv">AtticTV</a></li>
 374      <li><a href="#examples-decide">Decide</a></li>
 375      <li><a href="#examples-trello">Trello</a></li>
 376      <li><a href="#examples-ducksboard">Ducksboard</a></li>
 377      <li><a href="#examples-picklive">Picklive</a></li>
 378      <li><a href="#examples-quietwrite">QuietWrite</a></li>
 379      <li><a href="#examples-tzigla">Tzigla</a></li>
 380    </ul>
 381
 382    <a class="toc_title" href="#faq">
 383      F.A.Q.
 384    </a>
 385    <ul class="toc_section">
 386      <li><a href="#FAQ-events">Catalog of Events</a></li>
 387      <li><a href="#FAQ-tim-toady">More Than One Way To Do It</a></li>
 388      <li><a href="#FAQ-nested">Nested Models &amp; Collections</a></li>
 389      <li><a href="#FAQ-bootstrap">Loading Bootstrapped Models</a></li>
 390      <li><a href="#FAQ-extending">Extending Backbone</a></li>
 391      <li><a href="#FAQ-mvc">Traditional MVC</a></li>
 392      <li><a href="#FAQ-this">Binding "this"</a></li>
 393      <li><a href="#FAQ-rails">Working with Rails</a></li>
 394    </ul>
 395
 396    <a class="toc_title" href="#changelog">
 397      Change Log
 398    </a>
 399
 400  </div>
 401
 402  <div class="container">
 403
 404    <p>
 405      <img style="width: 451px; height: 80px;" src="docs/images/backbone.png" alt="Backbone.js" />
 406    </p>
 407
 408    <p>
 409      Backbone.js gives structure to web applications
 410      by providing <b>models</b> with key-value binding and custom events,
 411      <b>collections</b> with a rich API of enumerable functions,
 412      <b>views</b> with declarative event handling, and connects it all to your
 413      existing API over a RESTful JSON interface.
 414    </p>
 415
 416    <p>
 417      The project is <a href="http://github.com/documentcloud/backbone/">hosted on GitHub</a>,
 418      and the <a href="docs/backbone.html">annotated source code</a> is available,
 419      as well as an online <a href="test/test.html">test suite</a>,
 420      an <a href="examples/todos/index.html">example application</a>,
 421      a <a href="https://github.com/documentcloud/backbone/wiki/Tutorials%2C-blog-posts-and-example-sites">list of tutorials</a>
 422      and a <a href="#examples">long list of real-world projects</a> that use Backbone.
 423      Backbone is available for use under the <a href="http://github.com/documentcloud/backbone/blob/master/LICENSE">MIT software license</a>.
 424    </p>
 425
 426    <p>
 427      You can report bugs and discuss features on the
 428      <a href="http://github.com/documentcloud/backbone/issues">GitHub issues page</a>,
 429      on Freenode IRC in the <tt>#documentcloud</tt> channel, post questions to the
 430      <a href="https://groups.google.com/forum/#!forum/backbonejs">Google Group</a>,
 431      add pages to the <a href="https://github.com/documentcloud/backbone/wiki">wiki</a>
 432      or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>.
 433    </p>
 434
 435    <p>
 436      <i>
 437        Backbone is an open-source component of
 438        <a href="http://documentcloud.org/">DocumentCloud</a>.
 439      </i>
 440    </p>
 441
 442    <h2 id="downloads">
 443      Downloads &amp; Dependencies
 444      <span style="padding-left: 7px; font-size:11px; font-weight: normal;" class="interface">(Right-click, and use "Save As")</span>
 445    </h2>
 446
 447    <table>
 448      <tr>
 449        <td><a class="punch" href="backbone.js">Development Version (0.9.1)</a></td>
 450        <td><i>47kb, Full source, lots of comments</i></td>
 451      </tr>
 452      <tr>
 453        <td><a class="punch" href="backbone-min.js">Production Version (0.9.1)</a></td>
 454        <td><i>5.3kb, Packed and gzipped</i></td>
 455      </tr>
 456    </table>
 457
 458    <p>
 459      Backbone's only hard dependency is
 460      <a href="http://documentcloud.github.com/underscore/">Underscore.js</a> <small>( > 1.3.1)</small>.
 461      For RESTful persistence, history support via <a href="#Router">Backbone.Router</a>
 462      and DOM manipulation with <a href="#View">Backbone.View</a>, include
 463      <a href="https://github.com/douglascrockford/JSON-js">json2.js</a>, and either
 464      <a href="http://jquery.com">jQuery</a> <small>( > 1.4.2)</small> or
 465      <a href="http://zeptojs.com/">Zepto</a>.
 466    </p>
 467
 468    <h2 id="introduction">Introduction</h2>
 469
 470    <p>
 471      When working on a web application that involves a lot of JavaScript, one
 472      of the first things you learn is to stop tying your data to the DOM. It's all
 473      too easy to create JavaScript applications that end up as tangled piles of
 474      jQuery selectors and callbacks, all trying frantically to keep data in
 475      sync between the HTML UI, your JavaScript logic, and the database on your
 476      server. For rich client-side applications, a more structured approach
 477      is often helpful.
 478    </p>
 479
 480    <p>
 481      With Backbone, you represent your data as
 482      <a href="#Model">Models</a>, which can be created, validated, destroyed,
 483      and saved to the server. Whenever a UI action causes an attribute of
 484      a model to change, the model triggers a <i>"change"</i> event; all
 485      the <a href="#View">Views</a> that display the model's state can be notified of the
 486      change, so that they are able to respond accordingly, re-rendering themselves with
 487      the new information. In a finished Backbone app, you don't have to write the glue
 488      code that looks into the DOM to find an element with a specific <i>id</i>,
 489      and update the HTML manually
 490      &mdash; when the model changes, the views simply update themselves.
 491    </p>
 492
 493    <p>
 494      If you're new here, and aren't yet quite sure what Backbone is for, start by
 495      browsing the <a href="#examples">list of Backbone-based projects</a>.
 496    </p>
 497
 498    <p>
 499      Many of the examples that follow are runnable. Click the <i>play</i> button
 500      to execute them.
 501    </p>
 502
 503    <h2 id="upgrading">Upgrading to 0.9</h2>
 504
 505    <p>
 506      Backbone's <b>0.9</b> series should be considered as a release candidate
 507      for an upcoming <b>1.0</b>. Some APIs have changed, and while there is a
 508      <a href="#changelog">change log</a> available, and many new features to
 509      take advantage of, there are a few specific changes where you'll need
 510      to take care:
 511    </p>
 512
 513    <ul>
 514      <li>
 515        If you've ever manually set <tt>this.el</tt> in a Backbone View to be a
 516        particular DOM element, you'll want to use
 517        <a href="#View-setElement">setElement</a> instead.
 518      </li>
 519      <li>
 520        Creating and destroying models is now optimistic. Pass <tt>{wait: true}</tt>
 521        if you need the previous behavior of waiting for the server to acknowledge
 522        success. You can now also pass <tt>{wait: true}</tt> to <a href="#Model-save">save</a> calls.
 523      </li>
 524      <li>
 525        If you have been writing a fair amount of <tt>$(view.el)</tt>, there's now
 526        a cached reference for that jQuery object: <a href="#View-$el">$el</a>.
 527      </li>
 528      <li>
 529        If you're upgrading, make sure you also upgrade your version of Underscore.js
 530        to the latest &mdash; 1.3.1 or greater.
 531      </li>
 532      <li>
 533        <tt>model.set</tt> will no longer trigger change events when setting a value
 534        with <tt>{silent: true}</tt> then setting it back to its original value.
 535        Similarly, after changing an attribute silently, that <tt>change:attribute</tt>
 536        event <i>will</i> fire during the next change.
 537      </li>
 538      <li>
 539        Since <tt>view.$(selector)</tt> is now equivalent to <tt>view.$el.find(selector)</tt>
 540        rather than <tt>$(selector, view.el)</tt> it can no longer be used when
 541        <tt>selector</tt> is an HTML string or DOM element.
 542      </li>
 543    </ul>
 544
 545    <h2 id="Events">Backbone.Events</h2>
 546
 547    <p>
 548      <b>Events</b> is a module that can be mixed in to any object, giving the
 549      object the ability to bind and trigger custom named events. Events do not
 550      have to be declared before they are bound, and may take passed arguments.
 551      For example:
 552    </p>
 553
 554<pre class="runnable">
 555var object = {};
 556
 557_.extend(object, Backbone.Events);
 558
 559object.on("alert", function(msg) {
 560  alert("Triggered " + msg);
 561});
 562
 563object.trigger("alert", "an event");
 564</pre>
 565
 566    <p>
 567      For example, to make a handy event dispatcher that can coordinate events
 568      among different areas of your application: <tt>var dispatcher = _.clone(Backbone.Events)</tt>
 569    </p>
 570
 571    <p id="Events-on">
 572      <b class="header">on</b><code>object.on(event, callback, [context])</code><span class="alias">Alias: bind</span>
 573      <br />
 574      Bind a <b>callback</b> function to an object. The callback will be invoked
 575      whenever the <b>event</b> is fired.
 576      If you have a large number of different events on a page, the convention is to use colons to
 577      namespace them: <tt>"poll:start"</tt>, or <tt>"change:selection"</tt>.
 578      The event string may also be a space-delimited list of several events...
 579    </p>
 580
 581<pre>
 582book.on("change:title change:author", ...);
 583</pre>
 584
 585    <p>
 586      To supply a <b>context</b> value for <tt>this</tt> when the callback is invoked,
 587      pass the optional third argument: <tt>model.on('change', this.render, this)</tt>
 588    </p>
 589
 590    <p>
 591      Callbacks bound to the special
 592      <tt>"all"</tt> event will be triggered when any event occurs, and are passed
 593      the name of the event as the first argument. For example, to proxy all events
 594      from one object to another:
 595    </p>
 596
 597<pre>
 598proxy.on("all", function(eventName) {
 599  object.trigger(eventName);
 600});
 601</pre>
 602
 603    <p id="Events-off">
 604      <b class="header">off</b><code>object.off([event], [callback], [context])</code><span class="alias">Alias: unbind</span>
 605      <br />
 606      Remove a previously-bound <b>callback</b> function from an object. If no
 607      <b>context</b> is specified, all of the versions of the callback with
 608      different contexts will be removed. If no
 609      callback is specified, all callbacks for the <b>event</b> will be
 610      removed. If no event is specified, <i>all</i> event callbacks on the object
 611      will be removed.
 612    </p>
 613
 614<pre>
 615object.off("change", onChange);  // Removes just the onChange callback.
 616
 617object.off("change");            // Removes all "change" callbacks.
 618
 619object.off();                    // Removes all callbacks on object.
 620</pre>
 621
 622    <p id="Events-trigger">
 623      <b class="header">trigger</b><code>object.trigger(event, [*args])</code>
 624      <br />
 625      Trigger callbacks for the given <b>event</b>, or space-delimited list of events.
 626      Subsequent arguments to <b>trigger</b> will be passed along to the
 627      event callbacks.
 628    </p>
 629
 630    <h2 id="Model">Backbone.Model</h2>
 631
 632    <p>
 633      <b>Models</b> are the heart of any JavaScript application, containing
 634      the interactive data as well as a large part of the logic surrounding it:
 635      conversions, validations, computed properties, and access control. You
 636      extend <b>Backbone.Model</b> with your domain-specific methods, and
 637      <b>Model</b> provides a basic set of functionality for managing changes.
 638    </p>
 639
 640    <p>
 641      The following is a contrived example, but it demonstrates defining a model
 642      with a custom method, setting an attribute, and firing an event keyed
 643      to changes in that specific attribute.
 644      After running this code once, <tt>sidebar</tt> will be
 645      available in your browser's console, so you can play around with it.
 646    </p>
 647
 648<pre class="runnable">
 649var Sidebar = Backbone.Model.extend({
 650  promptColor: function() {
 651    var cssColor = prompt("Please enter a CSS color:");
 652    this.set({color: cssColor});
 653  }
 654});
 655
 656window.sidebar = new Sidebar;
 657
 658sidebar.on('change:color', function(model, color) {
 659  $('#sidebar').css({background: color});
 660});
 661
 662sidebar.set({color: 'white'});
 663
 664sidebar.promptColor();
 665</pre>
 666
 667    <p id="Model-extend">
 668      <b class="header">extend</b><code>Backbone.Model.extend(properties, [classProperties])</code>
 669      <br />
 670      To create a <b>Model</b> class of your own, you extend <b>Backbone.Model</b>
 671      and provide instance <b>properties</b>, as well as optional
 672      <b>classProperties</b> to be attached directly to the constructor function.
 673    </p>
 674
 675    <p>
 676      <b>extend</b> correctly sets up the prototype chain, so subclasses created
 677      with <b>extend</b> can be further extended and subclassed as far as you like.
 678    </p>
 679
 680<pre>
 681var Note = Backbone.Model.extend({
 682
 683  initialize: function() { ... },
 684
 685  author: function() { ... },
 686
 687  coordinates: function() { ... },
 688
 689  allowedToEdit: function(account) {
 690    return true;
 691  }
 692
 693});
 694
 695var PrivateNote = Note.extend({
 696
 697  allowedToEdit: function(account) {
 698    return account.owns(this);
 699  }
 700
 701});
 702</pre>
 703
 704    <p class="warning">
 705        Brief aside on <tt>super</tt>: JavaScript does not provide
 706        a simple way to call super &mdash; the function of the same name defined
 707        higher on the prototype chain. If you override a core function like
 708        <tt>set</tt>, or <tt>save</tt>, and you want to invoke the
 709        parent object's implementation, you'll have to explicitly call it, along these lines:
 710    </p>
 711
 712<pre>
 713var Note = Backbone.Model.extend({
 714  set: function(attributes, options) {
 715    Backbone.Model.prototype.set.call(this, attributes, options);
 716    ...
 717  }
 718});
 719</pre>
 720
 721    <p id="Model-constructor">
 722      <b class="header">constructor / initialize</b><code>new Model([attributes])</code>
 723      <br />
 724      When creating an instance of a model, you can pass in the initial values
 725      of the <b>attributes</b>, which will be <a href="#Model-set">set</a> on the
 726      model. If you define an <b>initialize</b> function, it will be invoked when
 727      the model is created.
 728    </p>
 729
 730<pre>
 731new Book({
 732  title: "One Thousand and One Nights",
 733  author: "Scheherazade"
 734});
 735</pre>
 736
 737    <p>
 738      In rare cases, if you're looking to get fancy,
 739      you may want to override <b>constructor</b>, which allows
 740      you to replace the actual constructor function for your model.
 741    </p>
 742
 743    <p id="Model-get">
 744      <b class="header">get</b><code>model.get(attribute)</code>
 745      <br />
 746      Get the current value of an attribute from the model. For example:
 747      <tt>note.get("title")</tt>
 748    </p>
 749
 750    <p id="Model-set">
 751      <b class="header">set</b><code>model.set(attributes, [options])</code>
 752      <br />
 753      Set a hash of attributes (one or many) on the model. If any of the attributes
 754      change the models state, a <tt>"change"</tt> event will be triggered, unless
 755      <tt>{silent: true}</tt> is passed as an option. Change events for specific
 756      attributes are also triggered, and you can bind to those as well, for example:
 757      <tt>change:title</tt>, and <tt>change:content</tt>. You may also pass
 758      individual keys and values.
 759    </p>
 760
 761<pre>
 762note.set({title: "March 20", content: "In his eyes she eclipses..."});
 763
 764book.set("title", "A Scandal in Bohemia");
 765</pre>
 766
 767    <p>
 768      If the model has a <a href="#Model-validate">validate</a> method,
 769      it will be validated before the attributes are set, no changes will
 770      occur if the validation fails, and <b>set</b> will return <tt>false</tt>.
 771      Otherwise, <b>set</b> returns a reference to the model.
 772      You may also pass an <tt>error</tt>
 773      callback in the options, which will be invoked instead of triggering an
 774      <tt>"error"</tt> event, should validation fail.
 775    </p>
 776
 777    <p id="Model-escape">
 778      <b class="header">escape</b><code>model.escape(attribute)</code>
 779      <br />
 780      Similar to <a href="#Model-get">get</a>, but returns the HTML-escaped version
 781      of a model's attribute. If you're interpolating data from the model into
 782      HTML, using <b>escape</b> to retrieve attributes will prevent
 783      <a href="http://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a> attacks.
 784    </p>
 785
 786<pre class="runnable">
 787var hacker = new Backbone.Model({
 788  name: "&lt;script&gt;alert('xss')&lt;/script&gt;"
 789});
 790
 791alert(hacker.escape('name'));
 792</pre>
 793
 794    <p id="Model-has">
 795      <b class="header">has</b><code>model.has(attribute)</code>
 796      <br />
 797      Returns <tt>true</tt> if the attribute is set to a non-null or non-undefined
 798      value.
 799    </p>
 800
 801<pre>
 802if (note.has("title")) {
 803  ...
 804}
 805</pre>
 806
 807    <p id="Model-unset">
 808      <b class="header">unset</b><code>model.unset(attribute, [options])</code>
 809      <br />
 810      Remove an attribute by deleting it from the internal attributes hash.
 811      Fires a <tt>"change"</tt> event unless <tt>silent</tt> is passed as an option.
 812    </p>
 813
 814    <p id="Model-clear">
 815      <b class="header">clear</b><code>model.clear([options])</code>
 816      <br />
 817      Removes all attributes from the model. Fires a <tt>"change"</tt> event unless
 818      <tt>silent</tt> is passed as an option.
 819    </p>
 820
 821    <p id="Model-id">
 822      <b class="header">id</b><code>model.id</code>
 823      <br />
 824      A special property of models, the <b>id</b> is an arbitrary string
 825      (integer id or UUID). If you set the <b>id</b> in the
 826      attributes hash, it will be copied onto the model as a direct property.
 827      Models can be retrieved by id from collections, and the id is used to generate
 828      model URLs by default.
 829    </p>
 830
 831    <p id="Model-idAttribute">
 832      <b class="header">idAttribute</b><code>model.idAttribute</code>
 833      <br />
 834      A model's unique identifier is stored under the <tt>id</tt> attribute.
 835      If you're directly communicating with a backend (CouchDB, MongoDB) that uses
 836      a different unique key, you may set a Model's <tt>idAttribute</tt> to
 837      transparently map from that key to <tt>id</tt>.
 838
 839<pre class="runnable">
 840var Meal = Backbone.Model.extend({
 841  idAttribute: "_id"
 842});
 843
 844var cake = new Meal({ _id: 1, name: "Cake" });
 845alert("Cake id: " + cake.id);
 846</pre>
 847    </p>
 848
 849    <p id="Model-cid">
 850      <b class="header">cid</b><code>model.cid</code>
 851      <br />
 852      A special property of models, the <b>cid</b> or client id is a unique identifier
 853      automatically assigned to all models when they're first created. Client ids
 854      are handy when the model has not yet been saved to the server, and does not
 855      yet have its eventual true <b>id</b>, but already needs to be visible in the UI.
 856      Client ids take the form: <tt>c1, c2, c3 ...</tt>
 857    </p>
 858
 859    <p id="Model-attributes">
 860      <b class="header">attributes</b><code>model.attributes</code>
 861      <br />
 862      The <b>attributes</b> property is the internal hash containing the model's
 863      state. Please use <a href="#Model-set">set</a> to update the attributes instead of modifying
 864      them directly. If you'd like to retrieve and munge a copy of the model's
 865      attributes, use <a href="#Model-toJSON">toJSON</a> instead.
 866    </p>
 867
 868    <p id="Model-changed">
 869      <b class="header">changed</b><code>model.changed</code>
 870      <br />
 871      The <b>changed</b> property is the internal hash containing all the attributes
 872      that have changed since the last <tt>"change"</tt> event was triggered.
 873      Please do not update <b>changed</b> directly.  Its state is maintained internally
 874      by <a href="#Model-set">set</a> and <a href="#Model-change">change</a>.
 875      A copy of <b>changed</b> can be acquired from
 876      <a href="#Model-changedAttributes">changedAttributes</a>.
 877    </p>
 878
 879    <p id="Model-defaults">
 880      <b class="header">defaults</b><code>model.defaults or model.defaults()</code>
 881      <br />
 882      The <b>defaults</b> hash (or function) can be used to specify the default
 883      attributes for your model. When creating an instance of the model,
 884      any unspecified attributes will be set to their default value.
 885    </p>
 886
 887<pre class="runnable">
 888var Meal = Backbone.Model.extend({
 889  defaults: {
 890    "appetizer":  "caesar salad",
 891    "entree":     "ravioli",
 892    "dessert":    "cheesecake"
 893  }
 894});
 895
 896alert("Dessert will be " + (new Meal).get('dessert'));
 897</pre>
 898
 899    <p class="warning">
 900      Remember that in JavaScript, objects are passed by reference, so if you
 901      include an object as a default value, it will be shared among all instances.
 902    </p>
 903
 904    <p id="Model-toJSON">
 905      <b class="header">toJSON</b><code>model.toJSON()</code>
 906      <br />
 907      Return a copy of the model's <a href="#Model-attributes">attributes</a> for JSON stringification.
 908      This can be used for persistence, serialization, or for augmentation before
 909      being handed off to a view. The name of this method is a bit confusing, as
 910      it doesn't actually return a JSON string &mdash; but I'm afraid that it's
 911      the way that the <a href="https://developer.mozilla.org/en/JSON#toJSON()_method">JavaScript API for <b>JSON.stringify</b> works</a>.
 912    </p>
 913
 914<pre class="runnable">
 915var artist = new Backbone.Model({
 916  firstName: "Wassily",
 917  lastName: "Kandinsky"
 918});
 919
 920artist.set({birthday: "December 16, 1866"});
 921
 922alert(JSON.stringify(artist));
 923</pre>
 924
 925    <p id="Model-fetch">
 926      <b class="header">fetch</b><code>model.fetch([options])</code>
 927      <br />
 928      Resets the model's state from the server. Useful if the model has never
 929      been populated with data, or if you'd like to ensure that you have the
 930      latest server state. A <tt>"change"</tt> event will be triggered if the
 931      server's state differs from the current attributes. Accepts
 932      <tt>success</tt> and <tt>error</tt> callbacks in the options hash, which
 933      are passed <tt>(model, response)</tt> as arguments.
 934    </p>
 935
 936<pre>
 937// Poll every 10 seconds to keep the channel model up-to-date.
 938setInterval(function() {
 939  channel.fetch();
 940}, 10000);
 941</pre>
 942
 943    <p id="Model-save">
 944      <b class="header">save</b><code>model.save([attributes], [options])</code>
 945      <br />
 946      Save a model to your database (or alternative persistence layer),
 947      by delegating to <a href="#Sync">Backbone.sync</a>. The <b>attributes</b>
 948      hash (as in <a href="#Model-set">set</a>) should contain the attributes
 949      you'd like to change &mdash; keys that aren't mentioned won't be altered &mdash; but,
 950      a <i>complete representation</i> of the resource will be sent to the server.
 951      As with <tt>set</tt>, you may pass individual keys and values instead of a hash.
 952      If the model has a <a href="#Model-validate">validate</a>
 953      method, and validation fails, the model will not be saved. If the model
 954      <a href="#Model-isNew">isNew</a>, the save will be a <tt>"create"</tt>
 955      (HTTP <tt>POST</tt>), if the model already
 956      exists on the server, the save will be an <tt>"update"</tt> (HTTP <tt>PUT</tt>).
 957    </p>
 958
 959    <p>
 960      Calling <tt>save</tt> with new attributes will cause a <tt>"change"</tt>
 961      event immediately, and a <tt>"sync"</tt> event after the server has acknowledged
 962      the successful change. Pass <tt>{wait: true}</tt> if you'd like to wait
 963      for the server before setting the new attributes on the model.
 964    </p>
 965
 966    <p>
 967      In the following example, notice how our overridden version
 968      of <tt>Backbone.sync</tt> receives a <tt>"create"</tt> request
 969      the first time the model is saved and an <tt>"update"</tt>
 970      request the second time.
 971    </p>
 972
 973<pre class="runnable">
 974Backbone.sync = function(method, model) {
 975  alert(method + ": " + JSON.stringify(model));
 976  model.id = 1;
 977};
 978
 979var book = new Backbone.Model({
 980  title: "The Rough Riders",
 981  author: "Theodore Roosevelt"
 982});
 983
 984book.save();
 985
 986book.save({author: "Teddy"});
 987</pre>
 988
 989    <p>
 990      <b>save</b> accepts <tt>success</tt> and <tt>error</tt> callbacks in the
 991      options hash, which are passed <tt>(model, response)</tt> as arguments.
 992      The <tt>error</tt> callback will also be invoked if the model has a
 993      <tt>validate</tt> method, and validation fails. If a server-side
 994      validation fails, return a non-<tt>200</tt> HTTP response code, along with
 995      an error response in text or JSON.
 996    </p>
 997
 998<pre>
 999book.save("author", "F.D.R.", {error: function(){ ... }});
1000</pre>
1001
1002    <p id="Model-destroy">
1003      <b class="header">destroy</b><code>model.destroy([options])</code>
1004      <br />
1005      Destroys the model on the server by delegating an HTTP <tt>DELETE</tt>
1006      request to <a href="#Sync">Backbone.sync</a>. Accepts
1007      <tt>success</tt> and <tt>error</tt> callbacks in the options hash.
1008      Triggers a <tt>"destroy"</tt> event on the model, which will bubble up
1009      through any collections that contain it, and a <tt>"sync"</tt> event, after
1010      the server has successfully acknowledged the model's deletion. Pass
1011      <tt>{wait: true}</tt> if you'd like to wait for the server to respond
1012      before removing the model from the collection.
1013    </p>
1014
1015<pre>
1016book.destroy({success: function(model, response) {
1017  ...
1018}});
1019</pre>
1020
1021    <p id="Model-validate">
1022      <b class="header">validate</b><code>model.validate(attributes)</code>
1023      <br />
1024      This method is left undefined, and you're encouraged to override it with
1025      your custom validation logic, if you have any that can be performed
1026      in JavaScript. <b>validate</b> is called before <tt>set</tt> and
1027      <tt>save</tt>, and is passed the attributes that are about to be updated.
1028      If the model and attributes are valid, don't return anything from <b>validate</b>;
1029      if the attributes are invalid, return an error of your choosing. It
1030      can be as simple as a string error message to be displayed, or a complete
1031      error object that describes the error programmatically. <tt>set</tt> and
1032      <tt>save</tt> will not continue if <b>validate</b> returns an error.
1033      Failed validations trigger an <tt>"error"</tt> event.
1034    </p>
1035
1036<pre class="runnable">
1037var Chapter = Backbone.Model.extend({
1038  validate: function(attrs) {
1039    if (attrs.end < attrs.start) {
1040      return "can't end before it starts";
1041    }
1042  }
1043});
1044
1045var one = new Chapter({
1046  title : "Chapter One: The Beginning"
1047});
1048
1049one.on("error", function(model, error) {
1050  alert(model.get("title") + " " + error);
1051});
1052
1053one.set({
1054  start: 15,
1055  end:   10
1056});
1057</pre>
1058
1059    <p>
1060      <tt>"error"</tt> events are useful for providing coarse-grained error
1061      messages at the model or collection level, but if you have a specific view
1062      that can better handle the error, you may override and suppress the event
1063      by passing an <tt>error</tt> callback directly:
1064    </p>
1065
1066<pre>
1067account.set({access: "unlimited"}, {
1068  error: function(model, error) {
1069    alert(error);
1070  }
1071});
1072</pre>
1073
1074    <p id="Model-isValid">
1075      <b class="header">isValid</b><code>model.isValid()</code>
1076      <br />
1077      Models may enter an invalid state if you make changes to them silently
1078      ... useful when dealing with form input. Call <tt>model.isValid()</tt>
1079      to check if the model is currently in a valid state, according to your
1080      <tt>validate</tt> function.
1081    </p>
1082
1083    <p id="Model-url">
1084      <b class="header">url</b><code>model.url()</code>
1085      <br />
1086      Returns the relative URL where the model's resource would be located on
1087      the server. If your models are located somewhere else, override this method
1088      with the correct logic. Generates URLs of the form: <tt>"/[collection.url]/[id]"</tt>,
1089      falling back to <tt>"/[urlRoot]/id"</tt> if the model is not part of a collection.
1090    </p>
1091
1092    <p>
1093      Delegates to <a href="#Collection-url">Collection#url</a> to generate the
1094      URL, so make sure that you have it defined, or a <a href="#Model-urlRoot">urlRoot</a>
1095      property, if all models of this class share a common root URL.
1096      A model with an id of <tt>101</tt>, stored in a
1097      <a href="#Collection">Backbone.Collection</a> with a <tt>url</tt> of <tt>"/documents/7/notes"</tt>,
1098      would have this URL: <tt>"/documents/7/notes/101"</tt>
1099    </p>
1100
1101    <p id="Model-urlRoot">
1102      <b class="header">urlRoot</b><code>model.urlRoot or model.urlRoot()</code>
1103      <br />
1104      Specify a <tt>urlRoot</tt> if you're using a model outside of a collection,
1105      to enable the default <a href="#Model-url">url</a> function to generate
1106      URLs based on the model id. <tt>"/[urlRoot]/id"</tt><br />
1107      Note that <tt>urlRoot</tt> may also be defined as a function.
1108    </p>
1109
1110<pre class="runnable">
1111var Book = Backbone.Model.extend({urlRoot : '/books'});
1112
1113var solaris = new Book({id: "1083-lem-solaris"});
1114
1115alert(solaris.url());
1116</pre>
1117
1118    <p id="Model-parse">
1119      <b class="header">parse</b><code>model.parse(response)</code>
1120      <br />
1121      <b>parse</b> is called whenever a model's data is returned by the
1122      server, in <a href="#Model-fetch">fetch</a>, and <a href="#Model-save">save</a>.
1123      The function is passed the raw <tt>response</tt> object, and should return
1124      the attributes hash to be <a href="#Model-set">set</a> on the model. The
1125      default implementation is a no-op, simply passing through the JSON response.
1126      Override this if you need to work with a preexisting API, or better namespace
1127      your responses.
1128    </p>
1129
1130    <p>
1131      If you're working with a Rails backend, you'll notice that Rails' default
1132      <tt>to_json</tt> implementation includes a model's attributes under a
1133      namespace. To disable this behavior for seamless Backbone integration, set:
1134    </p>
1135
1136<pre>
1137ActiveRecord::Base.include_root_in_json = false
1138</pre>
1139
1140    <p id="Model-clone">
1141      <b class="header">clone</b><code>model.clone()</code>
1142      <br />
1143      Returns a new instance of the model with identical attributes.
1144    </p>
1145
1146    <p id="Model-isNew">
1147      <b class="header">isNew</b><code>model.isNew()</code>
1148      <br />
1149      Has this model been saved to the server yet? If the model does not yet have
1150      an <tt>id</tt>, it is considered to be new.
1151    </p>
1152
1153    <p id="Model-change">
1154      <b class="header">change</b><code>model.change()</code>
1155      <br />
1156      Manually trigger the <tt>"change"</tt> event and a <tt>"change:attribute"</tt>
1157      event for each attribute that has changed. If you've been passing
1158      <tt>{silent: true}</tt> to the <a href="#Model-set">set</a> function in order to
1159      aggregate rapid changes to a model, you'll want to call <tt>model.change()</tt>
1160      when you're all finished.
1161    </p>
1162
1163    <p id="Model-hasChanged">
1164      <b class="header">hasChanged</b><code>model.hasChanged([attribute])</code>
1165      <br />
1166      Has the model changed since the last <tt>"change"</tt> event? If an <b>attribute</b>
1167      is passed, returns <tt>true</tt> if that specific attribute has changed.
1168    </p>
1169
1170    <p class="warning">
1171      Note that this method, and the following change-related ones,
1172      are only useful during the course of a <tt>"change"</tt> event.
1173    </p>
1174
1175<pre>
1176book.on("change", function() {
1177  if (book.hasChanged("title")) {
1178    ...
1179  }
1180});
1181</pre>
1182
1183    <p id="Model-changedAttributes">
1184      <b class="header">changedAttributes</b><code>model.changedAttributes([attributes])</code>
1185      <br />
1186      Retrieve a hash of only the model's attributes that have changed. Optionally,
1187      an external <b>attributes</b> hash can be passed in, returning
1188      the attributes in that hash which differ from the model. This can be used
1189      to figure out which portions of a view should be updated, or what calls
1190      need to be made to sync the changes to the server.
1191    </p>
1192
1193    <p id="Model-previous">
1194      <b class="header">previous</b><code>model.previous(attribute)</code>
1195      <br />
1196      During a <tt>"change"</tt> event, this method can be used to get the
1197      previous value of a changed attribute.
1198    </p>
1199
1200<pre class="runnable">
1201var bill = new Backbone.Model({
1202  name: "Bill Smith"
1203});
1204
1205bill.on("change:name", function(model, name) {
1206  alert("Changed name from " + bill.previous("name") + " to " + name);
1207});
1208
1209bill.set({name : "Bill Jones"});
1210</pre>
1211
1212    <p id="Model-previousAttributes">
1213      <b class="header">previousAttributes</b><code>model.previousAttributes()</code>
1214      <br />
1215      Return a copy of the model's previous attributes. Useful for getting a
1216      diff between versions of a model, or getting back to a valid state after
1217      an error occurs.
1218    </p>
1219
1220    <h2 id="Collection">Backbone.Collection</h2>
1221
1222    <p>
1223      Collections are ordered sets of models. You can bind <tt>"change"</tt> events
1224      to be notified when any model in the collection has been modified,
1225      listen for <tt>"add"</tt> and <tt>"remove"</tt> events, <tt>fetch</tt>
1226      the collection from the server, and use a full suite of
1227      <a href="#Collection-Underscore-Methods">Underscore.js methods</a>.
1228    </p>
1229
1230    <p>
1231      Any event that is triggered on a model in a collection will also be
1232      triggered on the collection directly, for convenience.
1233      This allows you to listen for changes to specific attributes in any
1234      model in a collection, for example:
1235      <tt>Documents.on("change:selected", ...)</tt>
1236    </p>
1237
1238    <p id="Collection-extend">
1239      <b class="header">extend</b><code>Backbone.Collection.extend(properties, [classProperties])</code>
1240      <br />
1241      To create a <b>Collection</b> class of your own, extend <b>Backbone.Collection</b>,
1242      providing instance <b>properties</b>, as well as optional <b>classProperties</b> to be attached
1243      directly to the collection's constructor function.
1244    </p>
1245
1246    <p id="Collection-model">
1247      <b class="header">model</b><code>collection.model</code>
1248      <br />
1249      Override this property to specify the model class that the collection
1250      contains. If defined, you can pass raw attributes objects (and arrays) to
1251      <a href="#Collection-add">add</a>, <a href="#Collection-create">create</a>,
1252      and <a href="#Collection-reset">reset</a>, and the attributes will be
1253      converted into a model of the proper type.
1254    </p>
1255
1256<pre>
1257var Library = Backbone.Collection.extend({
1258  model: Book
1259});
1260</pre>
1261
1262    <p id="Collection-constructor">
1263      <b class="header">constructor / initialize</b><code>new Collection([models], [options])</code>
1264      <br />
1265      When creating a Collection, you may choose to pass in the initial array of <b>models</b>.
1266      The collection's <a href="#Collection-comparator">comparator</a> function
1267      may be included as an option. If you define an <b>initialize</b> function, it will be
1268      invoked when the collection is created.
1269    </p>
1270
1271<pre>
1272var tabs = new TabSet([tab1, tab2, tab3]);
1273</pre>
1274
1275    <p id="Collection-models">
1276      <b class="header">models</b><code>collection.models</code>
1277      <br />
1278      Raw access to the JavaScript array of models inside of the collection. Usually you'll
1279      want to use <tt>get</tt>, <tt>at</tt>, or the <b>Underscore methods</b>
1280      to access model objects, but occasionally a direct reference to the array
1281      is desired.
1282    </p>
1283
1284    <p id="Collection-toJSON">
1285      <b class="header">toJSON</b><code>collection.toJSON()</code>
1286      <br />
1287      Return an array containing the attributes hash of each model in the
1288      collection. This can be used to serialize and persist the
1289      collection as a whole. The name of this method is a bit confusing, because
1290      it conforms to
1291      <a href="https://developer.mozilla.org/en/JSON#toJSON()_method">JavaScript's JSON API</a>.
1292    </p>
1293
1294<pre class="runnable">
1295var collection = new Backbone.Collection([
1296  {name: "Tim", age: 5},
1297  {name: "Ida", age: 26},
1298  {name: "Rob", age: 55}
1299]);
1300
1301alert(JSON.stringify(collection));
1302</pre>
1303
1304    <p id="Collection-Underscore-Methods">
1305      <b class="header">Underscore Methods (28)</b>
1306      <br />
1307      Backbone proxies to <b>Underscore.js</b> to provide 28 iteration functions
1308      on <b>Backbone.Collection</b>. They aren't all documented here, but
1309      you can take a look at the Underscore documentation for the full details&hellip;
1310    </p>
1311
1312    <ul class="small">
1313      <li><a href="http://documentcloud.github.com/underscore/#each">forEach (each)</a></li>
1314      <li><a href="http://documentcloud.github.com/underscore/#map">map</a></li>
1315      <li><a href="http://documentcloud.github.com/underscore/#reduce">reduce (foldl, inject)</a></li>
1316      <li><a href="http://documentcloud.github.com/underscore/#reduceRight">reduceRight (foldr)</a></li>
1317      <li><a href="http://documentcloud.github.com/underscore/#detect">find (detect)</a></li>
1318      <li><a href="http://documentcloud.github.com/underscore/#select">filter (select)</a></li>
1319      <li><a href="http://documentcloud.github.com/underscore/#reject">reject</a></li>
1320      <li><a href="http://documentcloud.github.com/underscore/#all">every (all)</a></li>
1321      <li><a href="http://documentcloud.github.com/underscore/#any">some (any)</a></li>
1322      <li><a href="http://documentcloud.github.com/underscore/#include">include</a></li>
1323      <li><a href="http://documentcloud.github.com/underscore/#invoke">invoke</a></li>
1324      <li><a href="http://documentcloud.github.com/underscore/#max">max</a></li>
1325      <li><a href="http://documentcloud.github.com/underscore/#min">min</a></li>
1326      <li><a href="http://documentcloud.github.com/underscore/#sortBy">sortBy</a></li>
1327      <li><a href="http://documentcloud.github.com/underscore/#groupBy">groupBy</a></li>
1328      <li><a href="http://documentcloud.github.com/underscore/#sortedIndex">sortedIndex</a></li>
1329      <li><a href="http://documentcloud.github.com/underscore/#shuffle">shuffle</a></li>
1330      <li><a href="http://documentcloud.github.com/underscore/#toArray">toArray</a></li>
1331      <li><a href="http://documentcloud.github.com/underscore/#size">size</a></li>
1332      <li><a href="http://documentcloud.github.com/underscore/#first">first</a></li>
1333      <li><a href="http://documentcloud.github.com/underscore/#initial">initial</a></li>
1334      <li><a href="http://documentcloud.github.com/underscore/#rest">rest</a></li>
1335      <li><a href="http://documentcloud.github.com/underscore/#last">last</a></li>
1336      <li><a href="http://documentcloud.github.com/underscore/#without">without</a></li>
1337      <li><a href="http://documentcloud.github.com/underscore/#indexOf">indexOf</a></li>
1338      <li><a href="http://documentcloud.github.com/underscore/#lastIndexOf">lastIndexOf</a></li>
1339      <li><a href="http://documentcloud.github.com/underscore/#isEmpty">isEmpty</a></li>
1340      <li><a href="http://documentcloud.github.com/underscore/#chain">chain</a></li>
1341    </ul>
1342
1343<pre>
1344Books.each(function(book) {
1345  book.publish();
1346});
1347
1348var titles = Books.map(function(book) {
1349  return book.get("title");
1350});
1351
1352var publishedBooks = Books.filter(function(book) {
1353  return book.get("published") === true;
1354});
1355
1356var alphabetical = Books.sortBy(function(book) {
1357  return book.author.get("name").toLowerCase();
1358});
1359</pre>
1360
1361    <p id="Collection-add">
1362      <b class="header">add</b><code>collection.add(models, [options])</code>
1363      <br />
1364      Add a model (or an array of models) to the collection. Fires an <tt>"add"</tt>
1365      event, which you can pass <tt>{silent: true}</tt> to suppress. If a
1366      <a href="#Collection-model">model</a> property is defined, you may also pass
1367      raw attributes objects, and have them be vivified as instances of the model.
1368      Pass <tt>{at: index}</tt> to splice the model into the collection at the
1369      specified <tt>index</tt>. Likewise, if you're a callback listening to a
1370      collection's <tt>"add"</tt> event, <tt>options.index</tt> will tell you the
1371      index at which the model is being added to the collection.
1372    </p>
1373
1374<pre class="runnable">
1375var ships = new Backbone.Collection;
1376
1377ships.on("add", function(ship) {
1378  alert("Ahoy " + ship.get("name") + "!");
1379});
1380
1381ships.add([
1382  {name: "Flying Dutchman"},
1383  {name: "Black Pearl"}
1384]);
1385</pre>
1386
1387    <p id="Collection-remove">
1388      <b class="header">remove</b><code>collection.remove(models, [options])</code>
1389      <br />
1390      Remove a model (or an array of models) from the collection. Fires a
1391      <tt>"remove"</tt> event, which you can use <tt>silent</tt>
1392      to suppress. If you're a callback listening to the <tt>"remove"</tt> event,
1393      the index at which the model is being removed from the collection is available
1394      as <tt>options.index</tt>.
1395    </p>
1396
1397    <p id="Collection-get">
1398      <b class="header">get</b><code>collection.get(id)</code>
1399      <br />
1400      Get a model from a collection, specified by <b>id</b>.
1401    </p>
1402
1403<pre>
1404var book = Library.get(110);
1405</pre>
1406
1407    <p id="Collection-getByCid">
1408      <b class="header">getByCid</b><code>collection.getByCid(cid)</code>
1409      <br />
1410      Get a model from a collection, specified by client id. The client id
1411      is the <tt>.cid</tt> property of the model, automatically assigned whenever
1412      a model is created. Useful for models which have not yet been saved to
1413      the server, and do not yet have true ids.
1414    </p>
1415
1416    <p id="Collection-at">
1417      <b class="header">at</b><code>collection.at(index)</code>
1418      <br />
1419      Get a model from a collection, specified by index. Useful if your collection
1420      is sorted, and if your collection isn't sorted, <b>at</b> will still
1421      retrieve models in insertion order.
1422    </p>
1423
1424    <p id="Collection-length">
1425      <b class="header">length</b><code>collection.length</code>
1426      <br />
1427      Like an array, a Collection maintains a <tt>length</tt> property, counting
1428      the number of models it contains.
1429    </p>
1430
1431    <p id="Collection-comparator">
1432      <b class="header">comparator</b><code>collection.comparator</code>
1433      <br />
1434      By default there is no <b>comparator</b> function on a collection.
1435      If you define a comparator, it will be used to maintain
1436      the collection in sorted order. This means that as models are added,
1437      they are inserted at the correct index in <tt>collection.models</tt>.
1438      Comparator function can be defined as either a
1439      <a href="http://underscorejs.org/#sortBy">sortBy</a>
1440      (pass a function that takes a single argument),
1441      or as a
1442      <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
1443      (pass a comparator function that expects two arguments).
1444    </p>
1445
1446    <p>
1447      "sortBy" comparator functions take a model and return a numeric or string
1448      value by which the model should be ordered relative to others.
1449      "sort" comparator functions take two models, and return <tt>-1</tt> if
1450      the first model should come before the second, <tt>0</tt> if they are of
1451      the same rank and <tt>1</tt> if the first model should come after.
1452    </p>
1453
1454    <p>
1455      Note how even though all of the chapters in this example are added backwards,
1456      they come out in the proper order:
1457    </p>
1458
1459<pre class="runnable">
1460var Chapter  = Backbone.Model;
1461var chapters = new Backbone.Collection;
1462
1463chapters.comparator = function(chapter) {
1464  return chapter.get("page");
1465};
1466
1467chapters.add(new Chapter({page: 9, title: "The End"}));
1468chapters.add(new Chapter({page: 5, title: "The Middle"}));
1469chapters.add(new Chapter({page: 1, title: "The Beginning"}));
1470
1471alert(chapters.pluck('title'));
1472</pre>
1473
1474    <p class="warning">
1475      Collections with comparator functions will not automatically re-sort if you
1476      later change model attributes, so you may wish to call <tt>sort</tt> after
1477      changing model attributes that would affect the order.
1478    </p>
1479
1480    <p id="Collection-sort">
1481      <b class="header">sort</b><code>collection.sort([options])</code>
1482      <br />
1483      Force a collection to re-sort itself. You don't need to call this under
1484      normal circumstances, as a collection with a <a href="#Collection-comparator">comparator</a> function
1485      will maintain itself in proper sort order at all times. Calling <b>sort</b>
1486      triggers the collection's <tt>"reset"</tt> event, unless silenced by passing
1487      <tt>{silent: true}</tt>
1488    </p>
1489
1490    <p id="Collection-pluck">
1491      <b class="header">pluck</b><code>collection.pluck(attribute)</code>
1492      <br />
1493      Pluck an attribute from each model in the collection. Equivalent to calling
1494      <tt>map</tt>, and returning a single attribute from the iterator.
1495    </p>
1496
1497<pre class="runnable">
1498var stooges = new Backbone.Collection([
1499  new Backbone.Model({name: "Curly"}),
1500  new Backbone.Model({name: "Larry"}),
1501  new Backbone.Model({name: "Moe"})
1502]);
1503
1504var names = stooges.pluck("name");
1505
1506alert(JSON.stringify(names));
1507</pre>
1508
1509    <p id="Collection-url">
1510      <b class="header">url</b><code>collection.url or collection.url()</code>
1511      <br />
1512      Set the <b>url</b> property (or function) on a collection to reference
1513      its location on the server. Models within the collection will use <b>url</b>
1514      to construct URLs of their own.
1515    </p>
1516
1517<pre>
1518var Notes = Backbone.Collection.extend({
1519  url: '/notes'
1520});
1521
1522// Or, something more sophisticated:
1523
1524var Notes = Backbone.Collection.extend({
1525  url: function() {
1526    return this.document.url() + '/notes';
1527  }
1528});
1529</pre>
1530
1531    <p id="Collection-parse">
1532      <b class="header">parse</b><code>collection.parse(response)</code>
1533      <br />
1534      <b>parse</b> is called by Backbone whenever a collection's models are
1535      returned by the server, in <a href="#Collection-fetch">fetch</a>.
1536      The function is passed the raw <tt>response</tt> object, and should return
1537      the array of model attributes to be <a href="#Collection-add">added</a>
1538      to the collection. The default implementation is a no-op, simply passing
1539      through the JSON response. Override this if you need to work with a
1540      preexisting API, or better namespace your responses. Note that afterwards,
1541      if your model class already has a <tt>parse</tt> function, it will be
1542      run against each fetched model.
1543    </p>
1544
1545<pre>
1546var Tweets = Backbone.Collection.extend({
1547  // The Twitter Search API returns tweets under "results".
1548  parse: function(response) {
1549    return response.results;
1550  }
1551});
1552</pre>
1553
1554    <p id="Collection-fetch">
1555      <b class="header">fetch</b><code>collection.fetch([options])</code>
1556      <br />
1557      Fetch the default set of models for this collection from the server,
1558      resetting the collection when they arrive. The <b>options</b> hash takes
1559      <tt>success</tt> and <tt>error</tt>
1560      callbacks which will be passed <tt>(collection, response)</tt> as arguments.
1561      When the model data returns from the server, the collection will
1562      <a href="#Collection-reset">reset</a>.
1563      Delegates to <a href="#Sync">Backbone.sync</a>
1564      under the covers, for custom persistence strategies.
1565      The server handler for <b>fetch</b> requests should return a JSON array of
1566      models.
1567    </p>
1568
1569<pre class="runnable">
1570Backbone.sync = function(method, model) {
1571  alert(method + ": " + model.url);
1572};
1573
1574var Accounts = new Backbone.Collection;
1575Accounts.url = '/accounts';
1576
1577Accounts.fetch();
1578</pre>
1579
1580    <p>
1581      If you'd like to add the incoming models to the current collection, instead
1582      of replacing the collection's contents, pass <tt>{add: true}</tt> as an
1583      option to <b>fetch</b>.
1584    </p>
1585
1586    <p>
1587      <b>jQuery.ajax</b> options can also be passed directly as <b>fetch</b> options,
1588      so to fetch a specific page of a paginated collection:
1589      <tt>Documents.fetch({data: {page: 3}})</tt>
1590    </p>
1591
1592    <p>
1593      Note that <b>fetch</b> should not be used to populate collections on
1594      page load &mdash; all models needed at load time should already be
1595      <a href="#FAQ-bootstrap">bootstrapped</a> in to place. <b>fetch</b> is
1596      intended for lazily-loading models for interfaces that are not needed
1597      immediately: for example, documents with collections of notes that may be
1598      toggled open and closed.
1599    </p>
1600
1601    <p id="Collection-reset">
1602      <b class="header">reset</b><code>collection.reset(models, [options])</code>
1603      <br />
1604      Adding and removing models one at a time is all well and good, but sometimes
1605      you have so many models to change that you'd rather just update the collection
1606      in bulk. Use <b>reset</b> to replace a collection with a new list
1607      of models (or attribute hashes), triggering a single <tt>"reset"</tt> event
1608      at the end. Pass <tt>{silent: true}</tt> to suppress the <tt>"reset"</tt> event.
1609      Using reset with no arguments is useful as a way to empty the collection.
1610    </p>
1611
1612    <p>
1613      Here's an example using <b>reset</b> to bootstrap a collection during initial page load,
1614      in a Rails application.
1615    </p>
1616
1617<pre>
1618&lt;script&gt;
1619  var Accounts = new Backbone.Collection;
1620  Accounts.reset(&lt;%= @accounts.to_json %&gt;);
1621&lt;/script&gt;
1622</pre>
1623
1624    <p>
1625      Calling <tt>collection.reset()</tt> without passing any models as arguments
1626      will empty the entire collection.
1627    </p>
1628
1629    <p id="Collection-create">
1630      <b class="header">create</b><code>collection.create(attributes, [options])</code>
1631      <br />
1632      Convenience to create a new instance of a model within a collection.
1633      Equivalent to instantiating a model with a hash of attributes,
1634      saving the model to the server, and adding the model to the set after being
1635      successfully created. Returns
1636      the model, or <tt>false</tt> if a validation error prevented the
1637      model from being created. In order for this to work, you should set the
1638      <a href="#Collection-model">model</a> property of the collection.
1639      The <b>create</b> method can accept either an attributes hash or an
1640      existing, unsaved model object.
1641    </p>
1642
1643    <p>
1644      Creating a model will cause an immediate <tt>"add"</tt> event to be
1645      triggered on the collection, as well as a <tt>"sync"</tt> event, once the
1646      model has been successfully created on the server. Pass <tt>{wait: true}</tt>
1647      if you'd like to wait for the server before adding the new model to the collection.
1648    </p>
1649
1650<pre>
1651var Library = Backbone.Collection.extend({
1652  model: Book
1653});
1654
1655var NYPL = new Library;
1656
1657var othello = NYPL.create({
1658  title: "Othello",
1659  author: "William Shakespeare"
1660});
1661</pre>
1662
1663    <h2 id="Router">Backbone.Router</h2>
1664
1665    <p>
1666      Web applications often provide linkable, bookmarkable, shareable URLs for
1667      important locations in the app. Until recently, hash fragments
1668      (<tt>#page</tt>) were used to provide these permalinks, but with the
1669      arrival of the History API, it's now possible to use standard URLs (<tt>/page</tt>).
1670      <b>Backbone.Router</b> provides methods for routing client-side pages, and
1671      connecting them to actions and events. For browsers which don't yet support
1672      the History API, the Router handles graceful fallback and transparent
1673      translation to the fragment version of the URL.
1674    </p>
1675
1676    <p>
1677      During page load, after your application has finished creating all of its routers,
1678      be sure to call <tt>Backbone.history.start()</tt>, or
1679      <tt>Backbone.history.start({pushState: true})</tt> to route the initial URL.
1680    </p>
1681
1682    <p id="Router-extend">
1683      <b class="header">extend</b><code>Backbone.Router.extend(properties, [classProperties])</code>
1684      <br />
1685      Get started by creating a custom router class. Define actions that are
1686      triggered when certain URL fragments are
1687      matched, and provide a <a href="#Router-routes">routes</a> hash
1688      that pairs routes to actions. Note that you'll want to avoid using a
1689      leading slash in your route definitions:
1690    </p>
1691
1692<pre>
1693var Workspace = Backbone.Router.extend({
1694
1695  routes: {
1696    "help":                 "help",    // #help
1697    "search/:query":        "search",  // #search/kiwis
1698    "search/:query/p:page": "search"   // #search/kiwis/p7
1699  },
1700
1701  help: function() {
1702    ...
1703  },
1704
1705  search: function(query, page) {
1706    ...
1707  }
1708
1709});
1710</pre>
1711
1712    <p id="Router-routes">
1713      <b class="header">routes</b><code>router.routes</code>
1714      <br />
1715      The routes hash maps URLs with parameters to functions on your router,
1716      similar to the <a href="#View">View</a>'s <a href="#View-delegateEvents">events hash</a>.
1717      Routes can contain parameter parts, <tt>:param</tt>, which match a single URL
1718      component between slashes; and splat parts <tt>*splat</tt>, which can match
1719      any number of URL components.
1720    </p>
1721
1722    <p>
1723      For example, a route of <tt>"search/:query/p:page"</tt> will match
1724      a fragment of <tt>#search/obama/p2</tt>, passing <tt>"obama"</tt>
1725      and <tt>"2"</tt> to the action. A route of <tt>"file/*path"</tt> will
1726      match <tt>#file/nested/folder/file.txt</tt>,
1727      passing <tt>"nested/folder/file.txt"</tt> to the action.
1728    </p>
1729
1730    <p>
1731      When the visitor presses the back button, or enters a URL, and a particular
1732      route is matched, the name of the action will be fired as an
1733      <a href="#Events">event</a>, so that other objects can listen to the router,
1734      and be notified. In the following example, visiting <tt>#help/uploading</tt>
1735      will fire a <tt>route:help</tt> event from the router.
1736    </p>
1737
1738<pre>
1739routes: {
1740  "help/:page":         "help",
1741  "download/*path":     "download",
1742  "folder/:name":       "openFolder",
1743  "folder/:name-:mode": "openFolder"
1744}
1745</pre>
1746
1747<pre>
1748router.on("route:help", function(page) {
1749  ...
1750});
1751</pre>
1752
1753    <p id="Router-constructor">
1754      <b class="header">constructor / initialize</b><code>new Router([options])</code>
1755      <br />
1756      When creating a new router, you may pass its
1757      <a href="#Router-routes">routes</a> hash directly as an option, if you
1758      choose. All <tt>options</tt> will also be passed to your <tt>initialize</tt>
1759      function, if defined.
1760    </p>
1761
1762    <p id="Router-route">
1763      <b class="header">route</b><code>router.route(route, name, [callback])</code>
1764      <br />
1765      Manually create a route for the router, The <tt>route</tt> argument may
1766      be a <a href="#Router-routes">routing string</a> or regular expression.
1767      Each matching capture from the route or regular expression will be passed as
1768      an argument to the callback. The <tt>name</tt> argument will be triggered as
1769      a <tt>"route:name"</tt> event whenever the route is matched.  If the
1770      <tt>callback</tt> argument is omitted <tt>router[name]</tt> will be used
1771      instead.
1772    </p>
1773
1774<pre>
1775initialize: function(options) {
1776
1777  // Matches #page/10, passing "10"
1778  this.route("page/:number", "page", function(number){ ... });
1779
1780  // Matches /117-a/b/c/open, passing "117-a/b/c" to this.open
1781  this.route(/^(.*?)\/open$/, "open");
1782
1783},
1784
1785open: function(id) { ... }
1786</pre>
1787
1788    <p id="Router-navigate">
1789      <b class="header">navigate</b><code>router.navigate(fragment, [options])</code>
1790      <br />
1791      Whenever you reach a point in your application that you'd like to save
1792      as a URL, call <b>navigate</b> in order to update the URL.
1793      If you wish to also call the route function, set the <b>trigger</b>
1794      option to <tt>true</tt>.
1795      To update the URL without creating an entry in the browser's history,
1796      set the <b>replace</b> option to <tt>true</tt>.
1797    </p>
1798
1799<pre>
1800openPage: function(pageNumber) {
1801  this.document.pages.at(pageNumber).open();
1802  this.navigate("page/" + pageNumber);
1803}
1804
1805# Or ...
1806
1807app.navigate("help/troubleshooting", {trigger: true});
1808
1809# Or ...
1810
1811app.navigate("help/troubleshooting", {trigger: true, replace: true});
1812</pre>
1813
1814    <h2 id="History">Backbone.history</h2>
1815
1816    <p>
1817      <b>History</b> serves as a global router (per frame) to handle <tt>hashchange</tt>
1818      events or <tt>pushState</tt>, match the appropriate route, and trigger callbacks. You shouldn't
1819      ever have to create one of these yourself &mdash; you should use the reference
1820      to <tt>Backbone.history</tt> that will be created for you automatically if you make use
1821      of <a href="#Router">Routers</a> with <a href="#Router-routes">routes</a>.
1822    </p>
1823
1824    <p>
1825      <b>pushState</b> support exists on a purely opt-in basis in Backbone.
1826      Older browsers that don't support <tt>pushState</tt> will continue to use
1827      hash-based URL fragments, and if a hash URL is visited by a
1828      <tt>pushState</tt>-capable browser, it will be transparently upgraded to
1829      the true URL. Note that using real URLs requires your web server to be
1830      able to correctly render those pages, so back-end changes are required
1831      as well. For example, if you have a route of <tt>/documents/100</tt>,
1832      your web server must be able to serve that page, if the browser
1833      visits that URL directly. For full search-engine crawlability, it's best to
1834      have the server generate the complete HTML for the page ... but if it's a web
1835      application, just rendering the same content you would have for the root URL,
1836      and filling in the rest with Backbone Views and JavaScript works fine.
1837    </p>
1838
1839    <p id="History-start">
1840      <b class="header">start</b><code>Backbone.history.start([options])</code>
1841      <br />
1842      When all of your <a href="#Router">Routers</a> have been created,
1843      and all of the routes are set up properly, call <tt>Backbone.history.start()</tt>
1844      to begin monitoring <tt>hashchange</tt> events, and dispatching routes.
1845    </p>
1846
1847    <p>
1848      To indicate that you'd like to use HTML5 <tt>pushState</tt> support in
1849      your application, use <tt>Backbone.history.start({pushState: true})</tt>.
1850    </p>
1851
1852    <p>
1853      If your application is not being served from the root url <tt>/</tt> of your
1854      domain, be sure to tell History where the root really is, as an option:
1855      <tt>Backbone.history.start({pushState: true, root: "/public/search/"})</tt>
1856    </p>
1857
1858    <p>
1859      When called, if a route succeeds with a match for the current URL,
1860      <tt>Backbone.history.start()</tt> returns <tt>true</tt>. If no defined
1861      route matches the current URL, it returns <tt>false</tt>.
1862    </p>
1863
1864    <p>
1865      If the server has already rendered the entire page, and you don't want the
1866      initial route to trigger when starting History, pass <tt>silent: true</tt>.
1867    </p>
1868
1869    <p>
1870      Because hash-based history in Internet Explorer relies on an
1871      <tt>&lt;iframe&gt;</tt>, be sure to only call <tt>start()</tt> after the DOM
1872      is ready.
1873    </p>
1874
1875<pre>
1876$(function(){
1877  new WorkspaceRouter();
1878  new HelpPaneRouter();
1879  Backbone.history.start({pushState: true});
1880});
1881</pre>
1882
1883    <h2 id="Sync">Backbone.sync</h2>
1884
1885    <p>
1886      <b>Backbone.sync</b> is the function that Backbone calls every time it
1887      attempts to read or save a model to the server. By default, it uses
1888      <tt>(jQuery/Zepto).ajax</tt> to make a RESTful JSON request. You can override
1889      it in order to use a different persistence strategy, such as WebSockets,
1890      XML transport, or Local Storage.
1891    </p>
1892
1893    <p>
1894      The method signature of <b>Backbone.sync</b> is <tt>sync(method, model, [options])</tt>
1895    </p>
1896
1897    <ul>
1898      <li><b>method</b> – the CRUD method (<tt>"create"</tt>, <tt>"read"</tt>, <tt>"update"</tt>, or <tt>"delete"</tt>)</li>
1899      <li><b>model</b> – the model to be saved (or collection to be read)</li>
1900      <li><b>options</b> – success and error callbacks, and all other jQuery request options</li>
1901    </ul>
1902
1903    <p>
1904      With the default implementation, when <b>Backbone.sync</b> sends up a request to save
1905      a model, its attributes will be passed, serialized as JSON, and sent in the HTTP body
1906      with content-type <tt>application/json</tt>. When returning a JSON response,
1907      send down the attributes of the  model that have been changed by the server, and need
1908      to be updated on the client. When responding to a <tt>"read"</tt> request from a collection
1909      (<a href="#Collection#fetch">Collection#fetch</a>), send down an array
1910      of model attribute objects.
1911    </p>
1912
1913    <p>
1914      The default <b>sync</b> handler maps CRUD to REST like so:
1915    </p>
1916
1917    <ul>
1918      <li><b>create &rarr; POST &nbsp; </b><tt>/collection</tt></li>
1919      <li><b>read &rarr; GET &nbsp; </b><tt>/collection[/id]</tt></li>
1920      <li><b>update &rarr; PUT &nbsp; </b><tt>/collection/id</tt></li>
1921      <li><b>delete &rarr; DELETE &nbsp; </b><tt>/collection/id</tt></li>
1922    </ul>
1923
1924    <p>
1925      As an example, a Rails handler responding to an <tt>"update"</tt> call from
1926      <tt>Backbone</tt> might look like this: <i>(In real code, never use
1927      </i><tt>update_attributes</tt><i> blindly, and always whitelist the attributes
1928      you allow to be changed.)</i>
1929    </p>
1930
1931<pre>
1932def update
1933  account = Account.find params[:id]
1934  account.update_attributes params
1935  render :json => account
1936end
1937</pre>
1938
1939    <p>
1940      One more tip for Rails integration is to disable the default namespacing for
1941      <tt>to_json</tt> calls on models by setting <tt>ActiveRecord::Base.include_root_in_json = false</tt>
1942    </p>
1943
1944    <p id="Sync-emulateHTTP">
1945      <b class="header">emulateHTTP</b><code>Backbone.emulateHTTP = true</code>
1946      <br />
1947      If you want to work with a legacy web server that doesn't support Backbones's
1948      default REST/HTTP approach, you may choose to turn on <tt>Backbone.emulateHTTP</tt>.
1949      Setting this option will fake <tt>PUT</tt> and <tt>DELETE</tt> requests with
1950      a HTTP <tt>POST</tt>, setting the <tt>X-HTTP-Method-Override</tt> header
1951      with the true method. If <tt>emulateJSON</tt> is also on, the true method
1952      will be passed as an additional <tt>_method</tt> parameter.
1953    </p>
1954
1955<pre>
1956Backbone.emulateHTTP = true;
1957
1958model.save();  // POST to "/collection/id", with "_method=PUT" + header.
1959</pre>
1960
1961    <p id="Sync-emulateJSON">
1962      <b class="header">emulateJSON</b><code>Backbone.emulateJSON = true</code>
1963      <br />
1964      If you're working with a legacy web server that can't handle requests
1965      encoded as <tt>application/json</tt>, setting <tt>Backbone.emulateJSON = true;</tt>
1966      will cause the JSON to be serialized under a <tt>model</tt> parameter, and
1967      the request to be made with a <tt>application/x-www-form-urlencoded</tt>
1968      mime type, as if from an HTML form.
1969    </p>
1970
1971    <h2 id="View">Backbone.View</h2>
1972
1973    <p>
1974      Backbone views are almost more convention than they are code &mdash; they
1975      don't determine anything about your HTML or CSS for you, and can be used
1976      with any JavaScript templating library.
1977      The general idea is to organize your interface into logical views,
1978      backed by models, each of which can be updated independently when the
1979      model changes, without having to redraw the page. Instead of digging into
1980      a JSON object, looking up an element in the DOM, and updating the HTML by hand,
1981      you can bind your view's <tt>render</tt> function to the model's <tt>"change"</tt>
1982      event &mdash; and now everywhere that
1983      model data is displayed in the UI, it is always immediately up to date.
1984    </p>
1985
1986    <p id="View-extend">
1987      <b class="header">extend</b><code>Backbone.View.extend(properties, [classProperties])</code>
1988      <br />
1989      Get started with views by creating a custom view class. You'll want to
1990      override the <a href="#View-render">render</a> function, specify your
1991      declarative <a href="#View-delegateEvents">events</a>, and perhaps the
1992      <tt>tagName</tt>, <tt>className</tt>, or <tt>id</tt> of the View's root
1993      element.
1994    </p>
1995
1996<pre>
1997var DocumentRow = Backbone.View.extend({
1998
1999  tagName: "li",
2000
2001  className: "document-row",
2002
2003  events: {
2004    "click .icon":          "open",
2005    "click .button.edit":   "openEditDialog",
2006    "click .button.delete": "destroy"
2007  },
2008
2009  render: function() {
2010    ...
2011  }
2012
2013});
2014</pre>
2015
2016    <p id="View-constructor">
2017      <b class="header">constructor / initialize</b><code>new View([options])</code>
2018      <br />
2019      When creating a new View, the options you pass are attached to the view
2020      as <tt>this.options</tt>, for future reference. There are several special
2021      options that, if passed, will be attached directly to the view:
2022      <tt>model</tt>, <tt>collection</tt>,
2023      <tt>el</tt>, <tt>id</tt>, <tt>className</tt>, <tt>tagName</tt> and <tt>attributes</tt>.
2024      If the view defines an <b>initialize</b> function, it will be called when
2025      the view is first created. If you'd like to create a view that references
2026      an element <i>already</i> in the DOM, pass in the element as an option:
2027      <tt>new View({el: existingElement})</tt>
2028    </p>
2029
2030<pre>
2031var doc = Documents.first();
2032
2033new DocumentRow({
2034  model: doc,
2035  id: "document-row-" + doc.id
2036});
2037</pre>
2038
2039    <p id="View-el">
2040      <b class="header">el</b><code>view.el</code>
2041      <br />
2042      All views have a DOM element at all times (the <b>el</b> property),
2043      whether they've already been inserted into the page or not. In this
2044      fashion, views can be rendered at any time, and inserted into the DOM all
2045      at once, in order to get high-performance UI rendering with as few
2046      reflows and repaints as possible. <tt>this.el</tt> is created from the
2047      view's <tt>tagName</tt>, <tt>className</tt>, <tt>id</tt> and <tt>attributes</tt> properties,
2048      if specified. If not, <b>el</b> is an empty <tt>div</tt>.
2049    </p>
2050
2051<pre class="runnable">
2052var ItemView = Backbone.View.extend({
2053  tagName: 'li'
2054});
2055
2056var BodyView = Backbone.View.extend({
2057  el: 'body'
2058});
2059
2060var item = new ItemView();
2061var body = new BodyView();
2062
2063alert(item.el + ' ' + body.el);
2064</pre>
2065
2066    <p id="View-$el">
2067      <b class="header">$el</b><code>view.$el</code>
2068      <br />
2069      A cached jQuery (or Zepto) object for the view's element. A handy
2070      reference instead of re-wrapping the DOM element all the time.
2071    </p>
2072
2073<pre>
2074view.$el.show();
2075
2076listView.$el.append(itemView.el);
2077</pre>
2078
2079    <p id="View-setElement">
2080      <b class="header">setElement</b><code>view.setElement(element)</code>
2081      <br />
2082      If you'd like to apply a Backbone view to a different DOM element, use
2083      <b>setElement</b>, which will also create the cached <tt>$el</tt> reference
2084      and move the view's delegated events from the old element to the new one.
2085    </p>
2086
2087    <p id="View-attributes">
2088      <b class="header">attributes</b><code>view.attributes</code>
2089      <br />
2090      A hash of attributes that will be set as HTML DOM element attributes on the
2091      view's <tt>el</tt> (id, class, data-properties, etc.), or a function that
2092      returns such a hash.
2093    </p>
2094
2095    <p id="View-dollar">
2096      <b class="header">$ (jQuery or Zepto)</b><code>view.$(selector)</code>
2097      <br />
2098      If jQuery or Zepto is included on the page, each view has a
2099      <b>$</b> function that runs queries scoped within the view's element. If you use this
2100      scoped jQuery function, you don't have to use model ids as part of your query
2101      to pull out specific elements in a list, and can rely much more on HTML class
2102      attributes. It's equivalent to running: <tt>view.$el.find(selector)</tt>
2103    </p>
2104
2105<pre>
2106ui.Chapter = Backbone.View.extend({
2107  serialize : function() {
2108    return {
2109      title: this.$(".title").text(),
2110      start: this.$(".start-page").text(),
2111      end:   this.$(".end-page").text()
2112    };
2113  }
2114});
2115</pre>
2116
2117    <p id="View-render">
2118      <b class="header">render</b><code>view.render()</code>
2119      <br />
2120      The default implementation of <b>render</b> is a no-op. Override this
2121      function with your code that renders the view template from model data,
2122      and updates <tt>this.el</tt> with the new HTML. A good
2123      convention is to <tt>return this</tt> at the end of <b>render</b> to
2124      enable chained calls.
2125    </p>
2126
2127<pre>
2128var Bookmark = Backbone.View.extend({
2129  render: function() {
2130    $(this.el).html(this.template(this.model.toJSON()));
2131    return this;
2132  }
2133});
2134</pre>
2135
2136    <p>
2137      Backbone is agnostic with respect to your preferred method of HTML templating.
2138      Your <b>render</b> function could even munge together an HTML string, or use
2139      <tt>document.createElement</tt> to generate a DOM tree. However, we suggest
2140      choosing a nice JavaScript templating library.
2141      <a href="http://github.com/janl/mustache.js">Mustache.js</a>,
2142      <a href="http://github.com/creationix/haml-js">Haml-js</a>, and
2143      <a href="http://github.com/sstephenson/eco">Eco</a> are all fine alternatives.
2144      Because <a href="http://documentcloud.github.com/underscore/">Underscore.js</a> is already on the page,
2145      <a href="http://documentcloud.github.com/underscore/#template">_.template</a>
2146      is available, and is an excellent choice if you've already XSS-sanitized
2147      your interpolated data.
2148    </p>
2149
2150    <p>
2151      Whatever templating strategy you end up with, it's nice if you <i>never</i>
2152      have to put strings of HTML in your JavaScript. At DocumentCloud, we
2153      use <a href="http://documentcloud.github.com/jammit/">Jammit</a> in order
2154      to package up JavaScript templates stored in <tt>/app/views</tt> as part
2155      of our main <tt>core.js</tt> asset package.
2156    </p>
2157
2158    <p id="View-remove">
2159      <b class="header">remove</b><code>view.remove()</code>
2160      <br />
2161      Convenience function for removing the view from the DOM. Equivalent to calling
2162      <tt>$(view.el).remove();</tt>
2163    </p>
2164
2165    <p id="View-make">
2166      <b class="header">make</b><code>view.make(tagName, [attributes], [content])</code>
2167      <br />
2168      Convenience function for creating a DOM element of the given type (<b>tagName</b>),
2169      with optional attributes and HTML content. Used internally to create the
2170      initial <tt>view.el</tt>.
2171    </p>
2172
2173<pre class="runnable">
2174var view = new Backbone.View;
2175
2176var el = view.make("b", {"class": "bold"}, "Bold! ");
2177
2178$("#make-demo").append(el);
2179</pre>
2180
2181<div id="make-demo"></div>
2182
2183    <p id="View-delegateEvents">
2184      <b class="header">delegateEvents</b><code>delegateEvents([events])</code>
2185      <br />
2186      Uses jQuery's <tt>delegate</tt> function to provide declarative callbacks
2187      for DOM events within a view.
2188      If an <b>events</b> hash is not passed directly, uses <tt>this.events</tt>
2189      as the source. Events are written in the format <tt>{"event selector": "callback"}</tt>.
2190      The callback may be either the name of a method on the view, or a direct
2191      function body.
2192      Omitting the <tt>selector</tt> causes the event to be bound to the view's
2193      root element (<tt>this.el</tt>). By default, <tt>delegateEvents</tt> is called
2194      within the View's constructor for you, so if you have a simple <tt>events</tt>
2195      hash, all of your DOM events will always already be connected, and you will
2196      never have to call this function yourself.
2197    </p>
2198
2199    <p>
2200      The <tt>events</tt> property may also be defined as a function that returns
2201      an <b>events</b> hash, to make it easier to programmatically define your
2202      events, as well as inherit them from parent views.
2203    </p>
2204
2205    <p>
2206      Using <b>delegateEvents</b> provides a number of advantages over manually
2207      using jQuery to bind events to child elements during <a href="#View-render">render</a>. All attached
2208      callbacks are bound to the view before being handed off to jQuery, so when
2209      the callbacks are invoked, <tt>this</tt> continues to refer to the view object. When
2210      <b>delegateEvents</b> is run again, perhaps with a different <tt>events</tt>
2211      hash, all callbacks are removed and delegated afresh &mdash; useful for
2212      views which need to behave differently when in different modes.
2213    </p>
2214
2215    <p>
2216      A view that displays a document in a search result might look
2217      something like this:
2218    </p>
2219
2220<pre>
2221var DocumentView = Backbone.View.extend({
2222
2223  events: {
2224    "dblclick"                : "open",
2225    "click .icon.doc"         : "select",
2226    "contextmenu .icon.doc"   : "showMenu",
2227    "click .show_notes"       : "toggleNotes",
2228    "click .title .lock"      : "editAccessLevel",
2229    "mouseover .title .date"  : "showTooltip"
2230  },
2231
2232  render: function() {
2233    $(this.el).html(this.template(this.model.toJSON()));
2234    return this;
2235  },
2236
2237  open: function() {
2238    window.open(this.model.get("viewer_url"));
2239  },
2240
2241  select: function() {
2242    this.model.set({selected: true});
2243  },
2244
2245  ...
2246
2247});
2248</pre>
2249
2250    <p id="View-undelegateEvents">
2251      <b class="header">undelegateEvents</b><code>undelegateEvents()</code>
2252      <br />
2253      Removes all of the view's delegated events. Useful if you want to disable
2254      or remove a view from the DOM temporarily.
2255    </p>
2256
2257    <h2 id="Utility">Utility Functions</h2>
2258
2259    <p id="Utility-noConflict">
2260      <b class="header">noConflict</b><code>var backbone = Backbone.noConflict();</code>
2261      <br />
2262      Returns the <tt>Backbone</tt> object back to its original value. You can
2263      use the return value of <tt>Backbone.noConflict()</tt> to keep a local
2264      reference to Backbone. Useful for embedding Backbone on third-party
2265      websites, where you don't want to clobber the existing Backbone.
2266    </p>
2267
2268<pre>
2269var localBackbone = Backbone.noConflict();
2270var model = localBackbone.Model.extend(...);
2271</pre>
2272
2273    <p id="Utility-setDomLibrary">
2274      <b class="header">setDomLibrary</b><code>Backbone.setDomLibrary(jQueryNew);</code>
2275      <br />
2276      If you have multiple copies of <tt>jQuery</tt> on the page, or simply want
2277      to tell Backbone to use a particular object as its DOM / Ajax library,
2278      this is the function for you.
2279    </p>
2280
2281    <h2 id="examples">Examples</h2>
2282
2283    <p>
2284      The list of examples that follows, while long, is not exhaustive. If you've
2285      worked on an app that uses Backbone, please add it to the
2286      <a href="https://github.com/documentcloud/backbone/wiki/Projects-and-Companies-using-Backbone">wiki page of Backbone apps</a>.
2287    </p>
2288
2289    <p id="examples-todos">
2290      <a href="http://jgn.me/">Jérôme Gravel-Niquet</a> has contributed a
2291      <a href="examples/todos/index.html">Todo List application</a>
2292      that is bundled in the repository as Backbone example. If you're wondering
2293      where to get started with Backbone in general, take a moment to
2294      <a href="docs/todos.html">read through the annotated source</a>. The app uses a
2295      <a href="docs/backbone-localstorage.html">LocalStorage adapter</a>
2296      to transparently save all of your todos within your browser, instead of
2297      sending them to a server. Jérôme also has a version hosted at
2298      <a href="http://localtodos.com/">localtodos.com</a> that uses a
2299      <a href="http://github.com/jeromegn/backbone-mootools">MooTools-backed version of Backbone</a>
2300      instead of jQuery.
2301    </p>
2302
2303    <div style="text-align: center;">
2304      <a href="examples/todos/index.html">
2305        <img src="docs/images/todos.png" alt="Todos" class="example_image" />
2306      </a>
2307    </div>
2308
2309    <h2 id="examples-documentcloud">DocumentCloud</h2>
2310
2311    <p>
2312      The <a href="http://www.documentcloud.org/public/#search/">DocumentCloud workspace</a>
2313      is built on Backbone.js, with <i>Documents</i>, <i>Projects</i>,
2314      <i>Notes</i>, and <i>Accounts</i> all as Backbone models and collections.
2315      If you're interested in history &mdash; both Underscore.js and Backbone.js
2316      were originally extracted from the DocumentCloud codebase, and packaged
2317      into standalone JS libraries.
2318    </p>
2319
2320    <div style="text-align: center;">
2321      <a href="http://www.documentcloud.org/public/#search/">
2322        <img src="docs/images/dc-workspace.png" alt="DocumentCloud Workspace" class="example_image" />
2323      </a>
2324    </div>
2325
2326    <h2 id="examples-linkedin">LinkedIn Mobile</h2>
2327
2328    <p>
2329      <a href="http://www.linkedin.com/">LinkedIn</a> used Backbone.js to create
2330      its <a href="http://www.linkedin.com/static?key=mobile">next-generation HTML5 mobile web app</a>.
2331      Backbone made it easy to keep the app modular, organized and extensible so
2332      that it was possible to program the complexities of LinkedIn's user experience.
2333      The app also uses <a href="http://zeptojs.com/">Zepto</a>,
2334      <a href="http://documentcloud.github.com/underscore/">Underscore.js</a>,
2335      <a href="http://sass-lang.com/">SASS</a>, <a href="http://cubiq.org/iscroll">iScroll</a>,
2336      HTML5 LocalStorage and Canvas.
2337    </p>
2338
2339    <div style="text-align: center;">
2340      <a href="http://www.linkedin.com/static?key=mobile">
2341        <img src="docs/images/linkedin-mobile.png" alt="LinkedIn Mobile" class="example_image" />
2342      </a>
2343    </div>
2344
2345    <h2 id="examples-flow">Flow</h2>
2346
2347    <p>
2348      <a href="http://www.metalabdesign.com/">MetaLab</a> used Backbone.js to create
2349      <a href="http://www.getflow.com/">Flow</a>, a task management app for teams. The
2350      workspace relies on Backbone.js to construct task views, activities, accounts,
2351      folders, projects, and tags. You can see the internals under <tt>window.Flow</tt>.
2352    </p>
2353
2354    <div style="text-align: center;">
2355      <a href="http://www.getflow.com/">
2356        <img src="docs/images/flow.png" alt="Flow" class="example_image" />
2357      </a>
2358    </div>
2359
2360    <h2 id="examples-audiovroom">AudioVroom</h2>
2361
2362    <p>
2363      <a href="http://www.audiovroom.com/">AudioVroom</a> is a free music
2364      streaming app that allows you to listen to your Facebook friends like
2365      radio stations. It relies heavily on Backbone (views and song management)
2366      and also features a responsive grid-based design (using CSS3 media-queries)
2367      to deliver a unified user experience on desktops, mobiles, and tablets alike.
2368      Being a pure Backbone app, AudioVroom is only 60kb compressed, and can be
2369      entirely hosted on the CDN.
2370    </p>
2371
2372    <div style="text-align: center;">
2373      <a href="http://www.audiovroom.com/">
2374        <img src="docs/images/audiovroom.png" alt="AudioVroom" class="example_image" />
2375      </a>
2376    </div>
2377
2378    <h2 id="examples-foursquare">Foursquare</h2>
2379
2380    <p>
2381      Foursquare is a fun little startup that helps you meet up with friends,
2382      discover new places, and save money. Backbone Models are heavily used in
2383      the core JavaScript API layer and Views power many popular features like
2384      the <a href="https://foursquare.com">homepage map</a> and
2385      <a href="https://foursquare.com/seriouseats/list/the-best-doughnuts-in-ny">lists</a>.
2386    </p>
2387
2388    <div style="text-align: center;">
2389      <a href="http://foursquare.com">
2390        <img src="docs/images/foursquare.png" alt="Foursquare" class="example_image" />
2391      </a>
2392    </div>
2393
2394    <h2 id="examples-wunderkit">Wunderkit</h2>
2395
2396    <p>
2397      <a href="http://get.wunderkit.com/">Wunderkit</a> is a productivity and
2398      social collaboration platform. It
2399      uses Backbone.js as the foundation for the single-page application,
2400      which is backed by a RESTful Rails API.
2401      The freedom and agility that Backbone gives to developers
2402      made it possible to build Wunderkit in a very short time and
2403      extend it with custom features: a write-through cache using HTML5
2404      localStorage, and a view hierarchy extension to easily manage trees of
2405      sub-views. Aside from Backbone, Wunderkit also
2406      depends on jQuery, Underscore, Require.js, LESS and doT.js templates.
2407    </p>
2408
2409    <div style="text-align: center;">
2410      <a href="http://get.wunderkit.com/">
2411        <img src="docs/images/wunderkit.png" alt="Wunderkit" class="example_image" />
2412      </a>
2413    </div>
2414
2415    <h2 id="examples-khan-academy">Khan Academy</h2>
2416
2417    <p>
2418      <a href="http://www.khanacademy.org">Khan Academy</a> is on a mission to
2419      provide a free world-class education to anyone anywhere. With thousands of
2420      videos, hundreds of JavaScript-driven exercises, and big plans for the
2421      future, Khan Academy uses Backbone to keep frontend code modular and organized.
2422      <a href="https://khanacademy.kilnhg.com/Code/Website/Group/stable/Files/javascript/profile-package?rev=tip">User profiles</a>
2423      and <a href="https://khanacademy.kilnhg.com/Code/Website/Group/stable/File/javascript/shared-package/goals.js?rev=tip">goal setting</a>
2424      are implemented with Backbone, jQuery and Handlebars, and most new feature
2425      work is being pushed to the client side, greatly increasing the quality of
2426      <a href="https://github.com/Khan/khan-api/">the API</a>.
2427    </p>
2428
2429    <div style="text-align: center;">
2430      <a href="http://www.khanacademy.org">
2431        <img src="docs/images/khan-academy.png" alt="Khan Academy" class="example_image" />
2432      </a>
2433    </div>
2434
2435    <h2 id="examples-do">Do</h2>
2436
2437    <p>
2438      <a href="http://do.com">Do</a> is a social productivity app that makes it
2439      easy to work on tasks, track projects, and take notes with your team.
2440      The <a href="http://do.com">Do.com</a> web application was built from the
2441      ground up to work seamlessly on your smartphone, tablet and computer. The
2442      team used Backbone, CoffeeScript and Handlebars to build a full-featured
2443      app in record time and rolled their own extensions for complex navigation
2444      and model sync support.
2445    </p>
2446
2447    <div style="text-align: center;">
2448      <a href="http://do.com">
2449        <img src="docs/images/do.png" alt="Do" class="example_image" />
2450      </a>
2451    </div>
2452
2453    <h2 id="examples-posterous">Posterous</h2>
2454
2455    <p>
2456      <a href="https://posterous.com/">Posterous Spaces</a> is
2457      <a href="http://technology.posterous.com/posterous-spaces-is-built-on-backbonejs">built on Backbone</a>.
2458      The models and collections mirror the public
2459      <a href="http://posterous.com/api">Posterous API</a>. Backbone made it easy
2460      for the team to create a JavaScript-heavy application with complex
2461      interactions and state maintenance. Spaces also uses CoffeeScript,
2462      Underscore.js, Haml.js, Sass, Compass, and of course jQuery.
2463    </p>
2464
2465    <div style="text-align: center;">
2466      <a href="https://posterous.com/">
2467        <img src="docs/images/posterous-spaces.png" alt="Posterous Spaces" class="example_image" />
2468      </a>
2469    </div>
2470
2471    <h2 id="examples-groupon">Groupon Now!</h2>
2472
2473    <p>
2474      <a href="http://www.groupon.com/now">Groupon Now!</a> helps you find
2475      local deals that you can buy and use right now. When first developing
2476      the product, the team decided it would be AJAX heavy with smooth transitions
2477      between sections instead of full refreshes, but still needed to be fully
2478      linkable and shareable. Despite never having used Backbone before, the
2479      learning curve was incredibly quick &mdash; a prototype was hacked out in an
2480      afternoon, and the team was able to ship the product in two weeks.
2481      Because the source is minimal and understandable, it was easy to
2482      add several Backbone extensions for Groupon Now!: changing the router
2483      to handle URLs with querystring parameters, and adding a simple
2484      in-memory store for caching repeated requests for the same data.
2485    </p>
2486
2487    <div style="text-align: center;">
2488      <a href="http://www.groupon.com/now">
2489        <img src="docs/images/groupon.png" alt="Groupon Now!" class="example_image" />
2490      </a>
2491    </div>
2492
2493    <h2 id="examples-basecamp">Basecamp Mobile</h2>
2494
2495    <p>
2496      <a href="http://37signals.com/">37Signals</a> used Backbone.js to create
2497      <a href="http://basecamphq.com/mobile">Basecamp Mobile</a>, the mobile version
2498      of their popular project management software. You can access all your Basecamp
2499      projects, post new messages, and comment on milestones (all represented
2500      internally as Backbone.js models).
2501    </p>
2502
2503    <div style="text-align: center;">
2504      <a href="http://basecamphq.com/mobile">
2505        <img src="docs/images/basecamp-mobile.png" alt="Basecamp Mobile" class="example_image" />
2506      </a>
2507    </div>
2508
2509    <h2 id="examples-slavery-footprint">Slavery Footprint</h2>
2510
2511    <p>
2512      <a href="http://slaveryfootprint.org/survey">Slavery Footprint</a>
2513      allows consumers to visualize how their consumption habits are
2514      connected to modern-day slavery and provides them with an opportunity
2515      to have a deeper conversation with the companies that manufacture the
2516      goods they purchased.
2517      Based in Oakland, California, the Slavery Footprint team works to engage
2518      individuals, groups, and businesses to build awareness for and create
2519      deployable action against forced labor, human trafficking, and modern-day
2520      slavery through online tools, as well as off-line community education and
2521      mobilization programs.
2522    </p>
2523
2524    <div style="text-align: center;">
2525      <a href="http://slaveryfootprint.org/survey">
2526        <img src="docs/images/slavery-footprint.png" alt="Slavery Footprint" class="example_image" />
2527      </a>
2528    </div>
2529
2530    <h2 id="examples-stripe">Stripe</h2>
2531
2532    <p>
2533      <a href="https://stripe.com">Stripe</a> provides an API for accepting
2534      credit cards on the web. Stripe's
2535      <a href="https://manage.stripe.com">management interface</a> was recently
2536      rewritten from scratch in Coffeescript using Backbone.js as the primary
2537      framework, Eco for templates, Sass for stylesheets, and Stitch to package
2538      everything together as CommonJS modules. The new app uses
2539      <a href="https://stripe.com/docs/api">Stripe's API</a> directly for the
2540      majority of its actions; Backbone.js models made it simple to map
2541      client-side models to their corresponding RESTful resources.
2542    </p>
2543
2544    <div style="text-align: center;">
2545      <a href="https://stripe.com">
2546        <img src="docs/images/stripe.png" alt="Stripe" class="example_image" />
2547      </a>
2548    </div>
2549
2550    <h2 id="examples-diaspora">Diaspora</h2>
2551
2552    <p>
2553      <a href="http://www.joindiaspora.com/">Diaspora</a> is a distributed social
2554      network, formed from a number of independently operated <i>pods</i>.
2555      You own your personal data, and control with whom you share.
2556      All of Diaspora is <a href="https://github.com/diaspora/diaspora">open-source</a>
2557      code, built with Rails and Backbone.js.
2558    </p>
2559
2560    <div style="text-align: center;">
2561      <a href="http://www.joindiaspora.com/">
2562        <img src="docs/images/diaspora.png" alt="Diaspora" class="example_image" />
2563      </a>
2564    </div>
2565
2566    <h2 id="examples-soundcloud">SoundCloud Mobile</h2>
2567
2568    <p>
2569      <a href="http://soundcloud.com">SoundCloud</a> is the leading sound sharing
2570      platform on the internet, and Backbone.js provides the foundation for
2571      <a href="http://m.soundcloud.com">SoundCloud Mobile</a>. The project uses
2572      the public SoundCloud <a href="http://soundcloud.com/developers">API</a>
2573      as a data source (channeled through a nginx proxy),
2574      <a href="http://api.jquery.com/category/plugins/templates/">jQuery templates</a>
2575      for the rendering, <a href="http://docs.jquery.com/Qunit">Qunit
2576      </a> and <a href="http://www.phantomjs.org/">PhantomJS</a> for
2577      the testing suite. The JS code, templates and CSS are built for the
2578      production deployment with various Node.js tools like
2579      <a href="https://github.com/dsimard/ready.js">ready.js</a>,
2580      <a href="https://github.com/mde/jake">Jake</a>,
2581      <a href="https://github.com/tmpvar/jsdom">jsdom</a>.
2582      The <b>Backbone.History</b> was modified to support the HTML5 <tt>history.pushState</tt>.
2583      <b>Backbone.sync</b> was extended with an additional SessionStorage based cache
2584      layer.
2585    </p>
2586
2587    <div style="text-align: center;">
2588      <a href="http://m.soundcloud.com">
2589        <img src="docs/images/soundcloud.png" alt="SoundCloud" class="example_image" />
2590      </a>
2591    </div>
2592
2593    <h2 id="examples-pandora">Pandora</h2>
2594
2595    <p>
2596      When <a href="http://www.pandora.com/newpandora">Pandora</a> redesigned
2597      their site in HTML5, they chose Backbone.js to help
2598      manage the user interface and interactions. For example, there's a model
2599      that represents the "currently playing track", and multiple views that
2600      automatically update when the current track changes. The station list is a
2601      collection, so that when stations are added or changed, the UI stays up to date.
2602    </p>
2603
2604    <div style="text-align: center;">
2605      <a href="http://www.pandora.com/newpandora">
2606        <img src="docs/images/pandora.png" alt="Pandora" class="example_image" />
2607      </a>
2608    </div>
2609
2610    <h2 id="examples-code-school">Code School</h2>
2611
2612    <p>
2613      <a href="http://www.codeschool.com">Code School</a> courses teach people
2614      about various programming topics like CoffeeScript, CSS, Ruby on Rails,
2615      and more. The new Code School course
2616      <a href="http://coffeescript.codeschool.com/levels/1/challenges/1">challenge page</a>
2617      is built from the ground up on Backbone.js, using
2618      everything it has to offer: the router, collections, models, and complex
2619      event handling. Before, the page was a mess of jQuery DOM manipulation
2620      and manual Ajax calls. Backbone.js helped introduce a new way to
2621      think about developing an organized front-end application in Javascript.
2622    </p>
2623
2624    <div style="text-align: center;">
2625      <a href="http://www.codeschool.com">
2626        <img src="docs/images/code-school.png" alt="Code School" class="example_image" />
2627      </a>
2628    </div>
2629
2630    <h2 id="examples-cloudapp">CloudApp</h2>
2631
2632    <p>
2633      <a href="http://getcloudapp.com">CloudApp</a> is simple file and link
2634      sharing for the Mac. Backbone.js powers the web tools
2635      which consume the <a href="http://developer.getcloudapp.com">documented API</a>
2636      to manage Drops. Data is either pulled manually or pushed by
2637      <a href="http://pusher.com">Pusher</a> and fed to
2638      <a href="http://github.com/janl/mustache.js">Mustache</a> templates for
2639      rendering. Check out the <a href="http://cloudapp.github.com/engine">annotated source code</a>
2640      to see the magic.
2641    </p>
2642
2643    <div style="text-align: center;">
2644      <a href="http://getcloudapp.com">
2645        <img src="docs/images/cloudapp.png" alt="CloudApp" class="example_image" />
2646      </a>
2647    </div>
2648
2649    <h2 id="examples-seatgeek">SeatGeek</h2>
2650
2651    <p>
2652      <a href="http://seatgeek.com">SeatGeek</a>'s stadium ticket maps were originally
2653      developed with Prototype.js. Moving to Backbone.js and jQuery helped organize
2654      a lot of the UI code, and the increased structure has made adding features
2655      a lot easier. SeatGeek is also in the process of building a mobile
2656      interface that will be Backbone.js from top to bottom.
2657    </p>
2658
2659    <div style="text-align: center;">
2660      <a href="http://seatgeek.com">
2661        <img src="docs/images/seatgeek.png" alt="SeatGeek" class="example_image" />
2662      </a>
2663    </div>
2664
2665    <h2 id="examples-grove">Grove.io</h2>
2666
2667    <p>
2668      <a href="http://grove.io">Grove.io</a> provides hosted IRC for teams.
2669      Backbone.js powers Grove's web client together with Handlebars.js templating.
2670      Updates to chat stream are pulled in realtime using long-polling.
2671    </p>
2672
2673    <div style="text-align: center;">
2674      <a href="http://grove.io">
2675        <img src="docs/images/grove.png" alt="Grove.io" class="example_image" />
2676      </a>
2677    </div>
2678
2679    <h2 id="examples-kicksend">Kicksend</h2>
2680
2681    <p>
2682      <a href="http://kicksend.com">Kicksend</a> is a real-time file sharing
2683      platform that helps everyday people send and receive files of any size
2684      with their friends and family. Kicksend's web application makes extensive
2685      use of Backbone.js to model files, friends, lists and activity streams.
2686    </p>
2687
2688    <div style="text-align: center;">
2689      <a href="http://kicksend.com">
2690        <img src="docs/images/kicksend.png" alt="Kicksend" class="example_image" />
2691      </a>
2692    </div>
2693
2694    <h2 id="examples-shortmail">Shortmail</h2>
2695
2696    <p>
2697      <a href="http://410labs.com/">410 Labs</a> uses Backbone.js at
2698      <a href="http://shortmail.com/">Shortmail.com</a> to build a
2699      fast and responsive inbox, driven by the <a href="#Router">Router</a>.
2700      Backbone works with a Rails backend to provide inbox rendering, archiving,
2701      replying, composing, and even a changes feed. Using Backbone's event-driven
2702      model and pushing the rendering and interaction logic to the front-end
2703      has not only simplified the view code, it has also drastically reduced the
2704      load on Shortmail's servers.
2705    </p>
2706
2707    <div style="text-align: center;">
2708      <a href="http://shortmail.com">
2709        <img src="docs/images/shortmail.png" alt="Shortmail" class="example_image" />
2710      </a>
2711    </div>
2712
2713    <h2 id="examples-battlefield">Battlefield Play4Free</h2>
2714
2715    <p>
2716      <a href="http://battlefield.play4free.com/">Battlefield Play4Free</a> is
2717      the latest free-to-play first person shooter from the same team that
2718      created Battlefield Heroes. The in-game HTML5 front-end for makes heavy use of
2719      Backbone's views, models and collections to help keep the code modular
2720      and structured.
2721    </p>
2722
2723    <div style="text-align: center;">
2724      <a href="http://battlefield.play4free.com/">
2725        <img src="docs/images/battlefield.png" alt="Battlefield Play4Free" class="example_image" />
2726      </a>
2727    </div>
2728
2729    <h2 id="examples-salon">Salon.io</h2>
2730
2731    <p>
2732      <a href="http://salon.io">Salon.io</a> provides a space where photographers,
2733      artists and designers freely arrange their visual art on virtual walls.
2734      <a href="http://salon.io">Salon.io</a> runs on Rails, but does not use
2735      much of the traditional stack, as the entire frontend is designed as a
2736      single page web app, using Backbone.js and
2737      <a href="http://coffeescript.org">CoffeeScript</a>.
2738    </p>
2739
2740    <div style="text-align: center;">
2741      <a href="http://salon.io">
2742        <img src="docs/images/salon.png" alt="Salon.io" class="example_image" />
2743      </a>
2744    </div>
2745
2746    <h2 id="examples-tilemill">TileMill</h2>
2747
2748    <p>
2749      Our fellow
2750      <a href="http://www.newschallenge.org/">Knight Foundation News Challenge</a>
2751      winners, <a href="http://mapbox.com/">MapBox</a>, created an open-source
2752      map design studio with Backbone.js:
2753      <a href="http://mapbox.github.com/tilemill/">TileMill</a>.
2754      TileMill lets you manage map layers based on shapefiles and rasters, and
2755      edit their appearance directly in the browser with the
2756      <a href="https://github.com/mapbox/carto">Carto styling language</a>.
2757      Note that the gorgeous <a href="http://mapbox.com/">MapBox</a> homepage
2758      is also a Backbone.js app.
2759    </p>
2760
2761    <div style="text-align: center;">
2762      <a href="http://mapbox.github.com/tilemill/">
2763        <img src="docs/images/tilemill.png" alt="TileMill" class="example_image" />
2764      </a>
2765    </div>
2766
2767    <h2 id="examples-blossom">Blossom</h2>
2768
2769    <p>
2770      <a href="http://blossom.io">Blossom</a> is a lightweight project management
2771      tool for lean teams. Backbone.js is heavily used in combination with
2772      <a href="http://coffeescript.org">CoffeeScript</a> to provide a smooth
2773      interaction experience. The RESTful backend is built
2774      with <a href="http://flask.pocoo.org/">Flask</a> on Google App Engine.
2775    </p>
2776
2777    <div style="text-align: center;">
2778      <a href="http://blossom.io">
2779        <img src="docs/images/blossom.png" alt="Blossom" class="example_image" />
2780      </a>
2781    </div>
2782
2783    <h2 id="examples-animoto">Animoto</h2>
2784
2785    <p>
2786      <a href="http://animoto.com">Animoto</a> is a web-based video creation
2787      platform, where users can upload their own photos, video clips and music
2788      and create beautifully orchestrated slideshows. The video editor app is
2789      built with Backbone.js and jQuery and interfaces with a Ruby on Rails
2790      backend. Backbone has provided structure which helps the Animoto team
2791      iterate quickly on the codebase while reducing the risk of regressions.
2792    </p>
2793
2794    <div style="text-align: center;">
2795      <a href="http://www.animoto.com/">
2796        <img src="docs/images/animoto.png" alt="Tzigla" class="Animoto Video Editor" />
2797      </a>
2798    </div>
2799    
2800    <h2 id="examples-codiqa">Codiqa</h2>
2801
2802    <p>
2803      <a href="http://codiqa.com/">Codiqa</a> is a drag-and-drop prototyping tool 
2804      for jQuery Mobile. Core features include saving apps online, sharing them 
2805      with teammates and stakeholders, previewing directly on a mobile device, 
2806      and theming with the jQuery Mobile ThemeRoller. Codiqa uses Backbone.js 
2807      to model all draggable components and interface views, backed by the API,
2808      which allowed the team to iterate quickly on features, and easily model complex 
2809      component interactions and hierarchy.
2810    </p>
2811
2812    <div style="text-align: center;">
2813      <a href="http://codiqa.com/">
2814        <img src="docs/images/codiqa.png" alt="Codiqa" class="example_image" />
2815      </a>
2816    </div>
2817    
2818    <h2 id="examples-attictv">AtticTV</h2>
2819
2820    <p>
2821      <a href="http://attictv.com/">AtticTV</a> is MTV for the Youtube Generation: 
2822      kick back and relax while watching the best 
2823      music videos of your favorite genre. The videos are synced across the 
2824      world, so, you're never watching alone on AtticTV. AtticTV is served by 
2825      NodeJS written in CoffeeScript with Socket.IO as data transport. The 
2826      frontend is built with Backbone.js with pushstate support, jQuery, and 
2827      Jade templates.
2828    </p>
2829
2830    <div style="text-align: center;">
2831      <a href="http://attictv.com/">
2832        <img src="docs/images/attictv.png" alt="AtticTV" class="example_image" />
2833      </a>
2834    </div>
2835
2836    <h2 id="examples-decide">Decide</h2>
2837
2838    <p>
2839      <a href="http://decide.com">Decide.com</a> helps people decide when to buy
2840      consumer electronics. It relies heavily on Backbone.js to render and
2841      update its Search Results Page. An "infinite scroll" feature takes
2842      advantage of a SearchResults model containing a collection of
2843      Product models to fetch more results and render them on the fly
2844      with Mustache. A SearchController keeps everything in sync and
2845      maintains page state in the URL. Backbone also powers the user
2846      accounts and settings management.
2847    </p>
2848
2849    <div style="text-align: center;">
2850      <a href="http://decide.com">
2851        <img src="docs/images/decide.png" alt="Decide" class="example_image" />
2852      </a>
2853    </div>
2854
2855    <h2 id="examples-trello">Trello</h2>
2856
2857    <p>
2858      <a href="http://trello.com">Trello</a> is a collaboration tool that
2859      organizes your projects into boards. A Trello board holds many lists of
2860      cards, which can contain checklists, files and conversations, and may be
2861      voted on and organized with labels. Updates on the board happen in
2862      real time. The site was built ground up using Backbone.js for all the
2863      models, views, and routes.
2864    </p>
2865
2866    <div style="text-align: center;">
2867      <a href="http://trello.com">
2868        <img src="docs/images/trello.png" alt="Trello" class="example_image" />
2869      </a>
2870    </div>
2871
2872    <h2 id="examples-ducksboard">Ducksboard</h2>
2873
2874    <p>
2875    <a href="http://ducksboard.com/">Ducksboard</a> is an online dashboard
2876      for your SaaS and business metrics, built with
2877      <a href="http://twistedmatrix.com/">Twisted</a> and
2878      <a href="http://www.djangoproject.com/">Django</a> and using WebSockets.
2879      It can fetch data from popular providers or accept input through
2880      a simple API.
2881      Backbone is used throughout Ducksboard's interface, every widget,
2882      dashboard and SaaS account is a Backbone model with several views
2883      (data display, configuration view). A
2884      <a href="https://public.ducksboard.com/BFVzKVPeOoWRsL0VZ8MZ/">live demo</a>
2885      is available.
2886    </p>
2887
2888    <div style="text-align: center;">
2889      <a href="http://ducksboard.com/">
2890        <img src="docs/images/ducksboard.png" alt="Ducksboard" class="example_image" />
2891      </a>
2892    </div>
2893
2894    <h2 id="examples-picklive">Picklive</h2>
2895
2896    <p>
2897      <a href="http://twitter.com/timruffles">Tim Ruffles</a> and <a href="http://twitter.com/timparker">Tim Parker</a>
2898      created the game client for <a href="https://free.picklive.com">Picklive</a>, a real-time fantasy-soccer game.
2899      The client is written in <a href="http://coffeescript.org">CoffeeScript</a>, organised into
2900      modules via <a href="http://requirejs.org">require.js</a>, tested with
2901      <a href="http://code.google.com/p/js-test-driver">jsTestDriver</a> and uses
2902      <a href="http://mustache.github.com">Mustache.js</a> for templating. Backbone's model and sync layer separation
2903      manages the complexity of mixed polling and web-sockets based synchronisation.
2904    </p>
2905
2906    <div style="text-align: center;">
2907      <a href="https://free.picklive.com/">
2908        <img src="docs/images/picklive.png" alt="picklive" class="example_image" />
2909      </a>
2910    </div>
2911
2912    <h2 id="examples-quietwrite">QuietWrite</h2>
2913
2914    <p>
2915      <a href="http://www.twitter.com/jamesjyu">James Yu</a> used Backbone.js to
2916      create <a href="http://www.quietwrite.com/">QuietWrite</a>, an app
2917      that gives writers a clean and quiet interface to concentrate on the text itself.
2918      The editor relies on Backbone to persist document data to the server. He
2919      followed up with a Backbone.js + Rails tutorial that describes how to implement
2920      <a href="http://www.jamesyu.org/2011/01/27/cloudedit-a-backbone-js-tutorial-by-example/">CloudEdit, a simple document editing app</a>.
2921    </p>
2922
2923    <div style="text-align: center;">
2924      <a href="http://www.quietwrite.com/">
2925        <img src="docs/images/quietwrite.png" alt="QuietWrite" class="example_image" />
2926      </a>
2927    </div>
2928
2929    <h2 id="examples-tzigla">Tzigla</h2>
2930
2931    <p>
2932      <a href="http://twitter.com/evilchelu">Cristi Balan</a> and
2933      <a href="http://dira.ro">Irina Dumitrascu</a> created
2934      <a href="http://tzigla.com">Tzigla</a>, a collaborative drawing
2935      application where artists make tiles that connect to each other to
2936      create <a href="http://tzigla.com/boards/1">surreal drawings</a>.
2937      Backbone models help organize the code, routers provide
2938      <a href="http://tzigla.com/boards/1#!/tiles/2-2">bookmarkable deep links</a>,
2939      and the views are rendered with
2940      <a href="https://github.com/creationix/haml-js">haml.js</a> and
2941      <a href="http://zeptojs.com/">Zepto</a>.
2942      Tzigla is written in Ruby (Rails) on the backend, and
2943      <a href="http://coffeescript.org">CoffeeScript</a> on the frontend, with
2944      <a href="http://documentcloud.github.com/jammit/">Jammit</a>
2945      prepackaging the static assets.
2946    </p>
2947
2948    <div style="text-align: center;">
2949      <a href="http://www.tzigla.com/">
2950        <img src="docs/images/tzigla.png" alt="Tzigla" class="example_image" />
2951      </a>
2952    </div>
2953
2954    <h2 id="faq">F.A.Q.</h2>
2955
2956    <p id="FAQ-events">
2957      <b class="header">Catalog of Events</b>
2958      <br />
2959      Here's a list of all of the built-in events that Backbone.js can fire.
2960      You're also free to trigger your own events on Models and Views as you
2961      see fit.
2962    </p>
2963
2964    <ul class="small">
2965      <li><b>"add"</b> (model, collection) &mdash; when a model is added to a collection. </li>
2966      <li><b>"remove"</b> (model, collection) &mdash; when a model is removed from a collection. </li>
2967      <li><b>"reset"</b> (collection) &mdash; when the collection's entire contents have been replaced. </li>
2968      <li><b>"change"</b> (model, options) &mdash; when a model's attributes have changed. </li>
2969      <li><b>"change:[attribute]"</b> (model, value, options) &mdash; when a specific attribute has been updated. </li>
2970      <li><b>"destroy"</b> (model, collection) &mdash; when a model is <a href="#Model-destroy">destroyed</a>. </li>
2971      <li><b>"sync"</b> (model, collection) &mdash; triggers whenever a model has been successfully synced to the server. </li>
2972      <li><b>"error"</b> (model, collection) &mdash; when a model's validation fails, or a <a href="#Model-save">save</a> call fails on the server. </li>
2973      <li><b>"route:[name]"</b> (router) &mdash; when one of a router's routes has matched. </li>
2974      <li><b>"all"</b> &mdash; this special event fires for <i>any</i> triggered event, passing the event name as the first argument. </li>
2975    </ul>
2976
2977    <p id="FAQ-tim-toady">
2978      <b class="header">There's More Than One Way To Do It</b>
2979      <br />
2980      It's common for folks just getting started to treat the examples listed
2981      on this page as some sort of gospel truth. In fact, Backbone.js is intended
2982      to be fairly agnostic about many common patterns in client-side code.
2983      For example...
2984    </p>
2985
2986    <p>
2987      <b>References between Models and Views</b> can be handled several ways.
2988      Some people like to have direct pointers, where views correspond 1:1 with
2989      models (<tt>model.view</tt> and <tt>view.model</tt>). Others prefer to have intermediate
2990      "controller" objects that orchestrate the creation and organization of
2991      views into a hierarchy. Others still prefer the evented approach, and always
2992      fire events instead of calling methods directly. All of these styles work well.
2993    </p>
2994
2995    <p>
2996      <b>Batch operations</b> on Models are common, but often best handled differently
2997      depending on your server-side setup. Some folks don't mind making individual
2998      Ajax requests. Others create explicit resources for RESTful batch operations:
2999      <tt>/notes/batch/destroy?ids=1,2,3,4</tt>. Others tunnel REST over JSON, with the
3000      creation of "changeset" requests:
3001    </p>
3002
3003<pre>
3004  {
3005    "create":  [array of models to create]
3006    "update":  [array of models to update]
3007    "destroy": [array of model ids to destroy]
3008  }
3009</pre>
3010
3011    <p>
3012      <b>Feel free to define your own events.</b> <a href="#Events">Backbone.Events</a>
3013      is designed so that you can mix it in to any JavaScript object or prototype.
3014      Since you can use any string as an event, it's often handy to bind
3015      and trigger your own custom events: <tt>model.on("selected:true")</tt> or
3016      <tt>model.on("editing")</tt>
3017    </p>
3018
3019    <p>
3020      <b>Render the UI</b> as you see fit. Backbone is agnostic as to whether you
3021      use <a href="http://documentcloud.github.com/underscore/#template">Underscore templates</a>,
3022      <a href="https://github.com/janl/mustache.js">Mustache.js</a>, direct DOM
3023      manipulation, server-side rendered snippets of HTML, or
3024      <a href="http://jqueryui.com/">jQuery UI</a> in your <tt>render</tt> function.
3025      Sometimes you'll create a view for each model ... sometimes you'll have a
3026      view that renders thousands of models at once, in a tight loop. Both can be
3027      appropriate in the same app, depending on the quantity of data involved,
3028      and the complexity of the UI.
3029    </p>
3030
3031    <p id="FAQ-nested">
3032      <b class="header">Nested Models &amp; Collections</b>
3033      <br />
3034      It's common to nest collections inside of models with Backbone. For example,
3035      consider a <tt>Mailbox</tt> model that contains many <tt>Message</tt> models.
3036      One nice pattern for handling this is have a <tt>this.messages</tt> collection
3037      for each mailbox, enabling the lazy-loading of messages, when the mailbox
3038      is first opened ... perhaps with <tt>MessageList</tt> views listening for
3039      <tt>"add"</tt> and <tt>"remove"</tt> events.
3040    </p>
3041
3042<pre>
3043var Mailbox = Backbone.Model.extend({
3044
3045  initialize: function() {
3046    this.messages = new Messages;
3047    this.messages.url = '/mailbox/' + this.id + '/messages';
3048    this.messages.on("reset", this.updateCounts);
3049  },
3050
3051  ...
3052
3053});
3054
3055var Inbox = new Mailbox;
3056
3057// And then, when the Inbox is opened:
3058
3059Inbox.messages.fetch();
3060</pre>
3061
3062    <p>
3063      If you're looking for something more opinionated, there are a number of
3064      Backbone plugins that add sophisticated associations among models,
3065      <a href="https://github.com/documentcloud/backbone/wiki/Extensions%2C-Plugins%2C-Resources">available on the wiki</a>.
3066    </p>
3067
3068    <p>
3069      Backbone doesn't include direct support for nested models and collections
3070      or "has many" associations because there are a number
3071      of good patterns for modeling structured data on the client side, and
3072      <i>Backbone should provide the foundation for implementing any of them.</i>
3073      You may want to&hellip;
3074    </p>
3075
3076    <ul>
3077      <li>
3078        Mirror an SQL database's structure, or the structure of a NoSQL database.
3079      </li>
3080      <li>
3081        Use models with arrays of "foreign key" ids, and join to top level
3082        collections (a-la tables).
3083      </li>
3084      <li>
3085        For associations that are numerous, use a range of ids instead of an
3086        explicit list.
3087      </li>
3088      <li>
3089        Avoid ids, and use direct references, creating a partial object graph
3090        representing your data set.
3091      </li>
3092      <li>
3093        Lazily load joined models from the server, or lazily deserialize nested
3094        models from JSON documents.
3095      </li>
3096    </ul>
3097
3098    <p id="FAQ-bootstrap">
3099      <b class="header">Loading Bootstrapped Models</b>
3100      <br />
3101      When your app first loads, it's common to have a set of initial models that
3102      you know you're going to need, in order to render the page. Instead of
3103      firing an extra AJAX request to <a href="#Collection-fetch">fetch</a> them,
3104      a nicer pattern is to have their data already bootstrapped into the page.
3105      You can then use <a href="#Collection-reset">reset</a> to populate your
3106      collections with the initial data. At DocumentCloud, in the
3107      <a href="http://en.wikipedia.org/wiki/ERuby">ERB</a> template for the
3108      workspace, we do something along these lines:
3109    </p>
3110
3111<pre>
3112&lt;script&gt;
3113  var Accounts = new Backbone.Collection;
3114  Accounts.reset(&lt;%= @accounts.to_json %&gt;);
3115  var Projects = new Backbone.Collection;
3116  Projects.reset(&lt;%= @projects.to_json(:collaborators => true) %&gt;);
3117&lt;/script&gt;
3118</pre>
3119
3120    <p id="FAQ-extending">
3121      <b class="header">Extending Backbone</b>
3122      <br />
3123      Many JavaScript libraries are meant to be insular and self-enclosed,
3124      where you interact with them by calling their public API, but never peek
3125      inside at the guts. Backbone.js is <i>not</i> that kind of library.
3126    </p>
3127
3128    <p>
3129      Because it serves as a foundation for your application, you're meant to
3130      extend and enhance it in the ways you see fit &mdash; the entire source
3131      code is <a href="docs/backbone.html">annotated</a> to make this easier
3132      for you. You'll find that there's very little there apart from core
3133      functions, and most of those can be overriden or augmented should you find
3134      the need. If you catch yourself adding methods to <tt>Backbone.Model.prototype</tt>,
3135      or creating your own base subclass, don't worry &mdash; that's how things are
3136      supposed to work.
3137    </p>
3138
3139    <p id="FAQ-mvc">
3140      <b class="header">How does Backbone relate to "traditional" MVC?</b>
3141      <br />
3142      Different implementations of the
3143      <a href="http://en.wikipedia.org/wiki/Model–View–Controller">Model-View-Controller</a>
3144      pattern tend to disagree about the definition of a controller. If it helps any, in
3145      Backbone, the <a href="#View">View</a> class can also be thought of as a
3146      kind of controller, dispatching events that originate from the UI, with
3147      the HTML template serving as the true view. We call it a View because it
3148      represents a logical chunk of UI, responsible for the contents of a single
3149      DOM element.
3150    </p>
3151
3152    <p>
3153      Comparing the overall structure of Backbone to a server-side MVC framework
3154      like <b>Rails</b>, the pieces line up like so:
3155    </p>
3156
3157    <ul>
3158      <li>
3159        <b>Backbone.Model</b> &ndash; Like a Rails model minus the class
3160        methods. Wraps a row of data in business logic.
3161      </li>
3162      <li>
3163        <b>Backbone.Collection</b> &ndash; A group of models on the client-side,
3164        with sorting/filtering/aggregation logic.
3165      </li>
3166      <li>
3167        <b>Backbone.Router</b> &ndash; Rails <tt>routes.rb</tt> + Rails controller
3168        actions. Maps URLs to functions.
3169      </li>
3170      <li>
3171        <b>Backbone.View</b> &ndash; A logical, re-usable piece of UI. Often,
3172        but not always, associated with a model.
3173      </li>
3174      <li>
3175        <b>Client-side Templates</b> &ndash; Rails <tt>.html.erb</tt> views,
3176        rendering a chunk of HTML.
3177      </li>
3178    </ul>
3179
3180    <p id="FAQ-this">
3181      <b class="header">Binding "this"</b>
3182      <br />
3183      Perhaps the single most common JavaScript "gotcha" is the fact that when
3184      you pass a function as a callback, its value for <tt>this</tt> is lost. With
3185      Backbone, when dealing with <a href="#Events">events</a> and callbacks,
3186      you'll often find it useful to rely on
3187      <a href="http://documentcloud.github.com/underscore/#bind">_.bind</a> and
3188      <a href="http://documentcloud.github.com/underscore/#bindAll">_.bindAll</a>
3189      from Underscore.js.
3190    </p>
3191
3192    <p>
3193      When binding callbacks to Backbone events, you can choose to pass an optional
3194      third argument to specify the <tt>this</tt> that will be used when the
3195      callback is later invoked:
3196    </p>
3197
3198<pre>
3199var MessageList = Backbone.View.extend({
3200
3201  initialize: function() {
3202    var messages = this.collection;
3203    messages.on("reset", this.render, this);
3204    messages.on("add", this.addMessage, this);
3205    messages.on("remove", this.removeMessage, this);
3206  }
3207
3208});
3209
3210// Later, in the app...
3211
3212Inbox.messages.add(newMessage);
3213</pre>
3214
3215    <p id="FAQ-rails">
3216      <b class="header">Working with Rails</b>
3217      <br />
3218      Backbone.js was originally extracted from
3219      <a href="http://www.documentcloud.org">a Rails application</a>; getting
3220      your client-side (Backbone) Models to sync correctly with your server-side
3221      (Rails) Models is painless, but there are still a few things to be aware of.
3222    </p>
3223
3224    <p>
3225      By default, Rails adds an extra layer of wrapping around the JSON representation
3226      of models. You can disable this wrapping by setting:
3227    </p>
3228
3229<pre>
3230ActiveRecord::Base.include_root_in_json = false
3231</pre>
3232
3233    <p>
3234      ... in your configuration. Otherwise, override
3235      <a href="#Model-parse">parse</a> to pull model attributes out of the
3236      wrapper. Similarly, Backbone PUTs and POSTs direct JSON representations
3237      of models, where by default Rails expcects namespaced attributes. You can
3238      have your controllers filter attributes directly from <tt>params</tt>, or
3239      you can override <a href="#Model-toJSON">toJSON</a> in Backbone to add
3240      the extra wrapping Rails expects.
3241    </p>
3242
3243    <h2 id="changelog">Change Log</h2>
3244
3245    <b class="header">0.9.1</b> &mdash; <small><i>Feb. 2, 2012</i></small> &mdash; <a href="https://github.com/documentcloud/backbone/compare/0.9.0...0.9.1">Diff</a><br />
3246    <ul style="margin-top: 5px;">
3247      <li>
3248        Reverted to 0.5.3-esque behavior for validating models. Silent changes
3249        no longer trigger validation (making it easier to work with forms).
3250        Added an <tt>isValid</tt> function that you can use to check if a model
3251        is currently in a valid state.
3252      </li>
3253      <li>
3254        If you have multiple versions of jQuery on the page, you can now tell
3255        Backbone which one to use with <tt>Backbone.setDomLibrary</tt>.
3256      </li>
3257      <li>
3258        Fixes regressions in <b>0.9.0</b> for routing with "root", saving with
3259        both "wait" and "validate", and the order of nested "change" events.
3260      </li>
3261    </ul>
3262
3263    <b class="header">0.9.0</b> &mdash; <small><i>Jan. 30, 2012</i></small> &mdash; <a href="https://github.com/documentcloud/backbone/compare/0.5.3...0.9.0">Diff</a><br />
3264    <ul style="margin-top: 5px;">
3265      <li>
3266        Creating and destroying models with <tt>create</tt> and <tt>destroy</tt>
3267        are now optimistic by default. Pass <tt>{wait: true}</tt> as an option
3268        if you'd like them to wait for a successful server response to proceed.
3269      </li>
3270      <li>
3271        Two new properties on views: <tt>$el</tt> &mdash; a cached jQuery (or Zepto)
3272        reference to the view's element, and <tt>setElement</tt>, which should
3273        be used instead of manually setting a view's <tt>el</tt>. It will
3274        both set <tt>view.el</tt> and <tt>view.$el</tt> correctly, as well as
3275        re-delegating events on the new DOM element.
3276      </li>
3277      <li>
3278        You can now bind and trigger multiple spaced-delimited events at once.
3279        For example: <tt>model.on("change:name change:age", ...)</tt>
3280      </li>
3281      <li>
3282        When you don't know the key in advance, you may now call
3283        <tt>model.set(key, value)</tt> as well as <tt>save</tt>.
3284      </li>
3285      <li>
3286        Multiple models with the same <tt>id</tt> are no longer allowed in a
3287        single collection.
3288      </li>
3289      <li>
3290        Added a <tt>"sync"</tt> event, which triggers whenever a model's state
3291        has been successfully synced with the server (create, save, destroy).
3292      </li>
3293      <li>
3294        <tt>bind</tt> and <tt>unbind</tt> have been renamed to <tt>on</tt>
3295        and <tt>off</tt> for clarity, following jQuery's lead.
3296        The old names are also still supported.
3297      </li>
3298      <li>
3299        A Backbone collection's <tt>comparator</tt> function may now behave
3300        either like a <a href="http://underscorejs.org/#sortBy">sortBy</a>
3301        (pass a function that takes a single argument),
3302        or like a <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
3303        (pass a comparator function that expects two arguments). The comparator
3304        function is also now bound by default to the collection &mdash; so you
3305        can refer to <tt>this</tt> within it.
3306      </li>
3307      <li>
3308        A view's <tt>events</tt> hash may now also contain direct function
3309        values as well as the string names of existing view methods.
3310      </li>
3311      <li>
3312        Validation has gotten an overhaul &mdash; a model's <tt>validate</tt> function
3313        will now be run even for silent changes, and you can no longer create
3314        a model in an initially invalid state.
3315      </li>
3316      <li>
3317        Added <tt>shuffle</tt> and <tt>initial</tt> to collections, proxied
3318        from Underscore.
3319      </li>
3320      <li>
3321        <tt>Model#urlRoot</tt> may now be defined as a function as well as a
3322        value.
3323      </li>
3324      <li>
3325        <tt>View#attributes</tt> may now be defined as a function as well as a
3326        value.
3327      </li>
3328      <li>
3329        Calling <tt>fetch</tt> on a collection will now cause all fetched JSON
3330        to be run through the collection's model's <tt>parse</tt> function, if
3331        one is defined.
3332      </li>
3333      <li>
3334        You may now tell a router to <tt>navigate(fragment, {replace: true})</tt>,
3335        which will either use <tt>history.replaceState</tt> or
3336        <tt>location.hash.replace</tt>, in order to change the URL without adding
3337        a history entry.
3338      </li>
3339      <li>
3340        Within a collection's <tt>add</tt> and <tt>remove</tt> events, the index
3341        of the model being added or removed is now available as <tt>options.index</tt>.
3342      </li>
3343      <li>
3344        Added an <tt>undelegateEvents</tt> to views, allowing you to manually
3345        remove all configured event delegations.
3346      </li>
3347      <li>
3348        Although you shouldn't be writing your routes with them in any case &mdash;
3349        leading slashes (<tt>/</tt>) are now stripped from routes.
3350      </li>
3351      <li>
3352        Calling <tt>clone</tt> on a model now only passes the attributes
3353        for duplication, not a reference to the model itself.
3354      </li>
3355    </ul>
3356
3357    <p>
3358      <b class="header">0.5.3</b> &mdash; <small><i>August 9, 2011</i></small><br />
3359      A View's <tt>events</tt> property may now be defined as a function, as well
3360      as an object literal, making it easier to programmatically define and inherit
3361      events. <tt>groupBy</tt> is now proxied from Underscore as a method on Collections.
3362      If the server has already rendered everything on page load, pass
3363      <tt>Backbone.history.start({silent: true})</tt> to prevent the initial route
3364      from triggering. Bugfix for pushState with encoded URLs.
3365    </p>
3366
3367    <p>
3368      <b class="header">0.5.2</b> &mdash; <small><i>July 26, 2011</i></small><br />
3369      The <tt>bind</tt> function, can now take an optional third argument, to specify
3370      the <tt>this</tt> of the callback function.
3371      Multiple models with the same <tt>id</tt> are now allowed in a collection.
3372      Fixed a bug where calling <tt>.fetch(jQueryOptions)</tt> could cause an
3373      incorrect URL to be serialized.
3374      Fixed a brief extra route fire before redirect, when degrading from
3375      <tt>pushState</tt>.
3376    </p>
3377
3378    <p>
3379      <b class="header">0.5.1</b> &mdash; <small><i>July 5, 2011</i></small><br />
3380      Cleanups from the 0.5.0 release, to wit: improved transparent upgrades from
3381      hash-based URLs to pushState, and vice-versa. Fixed inconsistency with
3382      non-modified attributes being passed to <tt>Model#initialize</tt>. Reverted
3383      a <b>0.5.0</b> change that would strip leading hashbangs from routes.
3384      Added <tt>contains</tt> as an alias for <tt>includes</tt>.
3385    </p>
3386
3387    <p>
3388      <b class="header">0.5.0</b> &mdash; <small><i>July 1, 2011</i></small><br />
3389      A large number of tiny tweaks and micro bugfixes, best viewed by looking
3390      at <a href="https://github.com/documentcloud/backbone/compare/0.3.3...0.5.0">the commit diff</a>.
3391      HTML5 <tt>pushState</tt> support, enabled by opting-in with:
3392      <tt>Backbone.history.start({pushState: true})</tt>.
3393      <tt>Controller</tt> was renamed to <tt>Router</tt>, for clarity.
3394      <tt>Collection#refresh</tt> was renamed to <tt>Collection#reset</tt> to emphasize
3395      its ability to both reset the collection with new models, as well as empty
3396      out the collection when used with no parameters.
3397      <tt>saveLocation</tt> was replaced with <tt>navigate</tt>.
3398      RESTful persistence methods (save, fetch, etc.) now return the jQuery deferred
3399      object for further success/error chaining and general convenience.
3400      Improved XSS escaping for <tt>Model#escape</tt>.
3401      Added a <tt>urlRoot</tt> option to allow specifying RESTful urls without
3402      the use of a collection.
3403      An error is thrown if <tt>Backbone.history.start</tt> is called multiple times.
3404      <tt>Collection#create</tt> now validates before initializing the new model.
3405      <tt>view.el</tt> can now be a jQuery string lookup.
3406      Backbone Views can now also take an <tt>attributes</tt> parameter.
3407      <tt>Model#defaults</tt> can now be a function as well as a literal attributes
3408      object.
3409    </p>
3410
3411    <p>
3412      <b class="header">0.3.3</b> &mdash; <small><i>Dec 1, 2010</i></small><br />
3413      Backbone.js now supports <a href="http://zeptojs.com">Zepto</a>, alongside
3414      jQuery, as a framework for DOM manipulation and Ajax support.
3415      Implemented <a href="#Model-escape">Model#escape</a>, to efficiently handle
3416      attributes intended for HTML interpolation. When trying to persist a model,
3417      failed requests will now trigger an <tt>"error"</tt> event. The
3418      ubiquitous <tt>options</tt> argument is now passed as the final argument
3419      to all <tt>"change"</tt> events.
3420    </p>
3421
3422    <p>
3423      <b class="header">0.3.2</b> &mdash; <small><i>Nov 23, 2010</i></small><br />
3424      Bugfix for IE7 + iframe-based "hashchange" events. <tt>sync</tt> may now be
3425      overridden on a per-model, or per-collection basis. Fixed recursion error
3426      when calling <tt>save</tt> with no changed attributes, within a
3427      <tt>"change"</tt> event.
3428    </p>
3429
3430    <p>
3431      <b class="header">0.3.1</b> &mdash; <small><i>Nov 15, 2010</i></small><br />
3432      All <tt>"add"</tt> and <tt>"remove"</tt> events are now sent through the
3433      model, so that views can listen for them without having to know about the
3434      collection. Added a <tt>remove</tt> method to <a href="#View">Backbone.View</a>.
3435      <tt>toJSON</tt> is no longer called at all for <tt>'read'</tt> and <tt>'delete'</tt> requests.
3436      Backbone routes are now able to load empty URL fragments.
3437    </p>
3438
3439    <p>
3440      <b class="header">0.3.0</b> &mdash; <small><i>Nov 9, 2010</i></small><br />
3441      Backbone now has <a href="#Controller">Controllers</a> and
3442      <a href="#History">History</a>, for doing client-side routing based on
3443      URL fragments.
3444      Added <tt>emulateHTTP</tt> to provide support for legacy servers that don't
3445      do <tt>PUT</tt> and <tt>DELETE</tt>.
3446      Added <tt>emulateJSON</tt> for servers that can't accept <tt>application/json</tt>
3447      encoded requests.
3448      Added <a href="#Model-clear">Model#clear</a>, which removes all attributes
3449      from a model.
3450      All Backbone classes may now be seamlessly inherited by CoffeeScript classes.
3451    </p>
3452
3453    <p>
3454      <b class="header">0.2.0</b> &mdash; <small><i>Oct 25, 2010</i></small><br />
3455      Instead of requiring server responses to be namespaced under a <tt>model</tt>
3456      key, now you can define your own <a href="#Model-parse">parse</a> method
3457      to convert responses into attributes for Models and Collections.
3458      The old <tt>handleEvents</tt> function is now named
3459      <a href="#View-delegateEvents">delegateEvents</a>, and is automatically
3460      called as part of the View's constructor.
3461      Added a <a href="#Collection-toJSON">toJSON</a> function to Collections.
3462      Added <a href="#Collection-chain">Underscore's chain</a> to Collections.
3463    </p>
3464
3465    <p>
3466      <b class="header">0.1.2</b> &mdash; <small><i>Oct 19, 2010</i></small><br />
3467      Added a <a href="#Model-fetch">Model#fetch</a> method for refreshing the
3468      attributes of single model from the server.
3469      An <tt>error</tt> callback may now be passed to <tt>set</tt> and <tt>save</tt>
3470      as an option, which will be invoked if validation fails, overriding the
3471      <tt>"error"</tt> event.
3472      You can now tell backbone to use the <tt>_method</tt> hack instead of HTTP
3473      methods by setting <tt>Backbone.emulateHTTP = true</tt>.
3474      Existing Model and Collection data is no longer sent up unnecessarily with
3475      <tt>GET</tt> and <tt>DELETE</tt> requests. Added a <tt>rake lint</tt> task.
3476      Backbone is now published as an <a href="http://npmjs.org">NPM</a> module.
3477    </p>
3478
3479    <p>
3480      <b class="header">0.1.1</b> &mdash; <small><i>Oct 14, 2010</i></small><br />
3481      Added a convention for <tt>initialize</tt> functions to be called
3482      upon instance construction, if defined. Documentation tweaks.
3483    </p>
3484
3485    <p>
3486      <b class="header">0.1.0</b> &mdash; <small><i>Oct 13, 2010</i></small><br />
3487      Initial Backbone release.
3488    </p>
3489
3490    <p>
3491      <br />
3492      <a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;">
3493        <img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" style="position:relative;left:-10px;" />
3494      </a>
3495    </p>
3496
3497  </div>
3498
3499  <script src="test/vendor/underscore-1.3.1.js"></script>
3500  <script src="test/vendor/jquery-1.7.1.js"></script>
3501  <script src="test/vendor/json2.js"></script>
3502  <script src="backbone.js"></script>
3503
3504  <script>
3505    // Set up the "play" buttons for each runnable code example.
3506    $(function() {
3507      $('.runnable').each(function() {
3508        var code = this;
3509        var button = '<div class="run" title="Run"></div>';
3510        $(button).insertBefore(code).bind('click', function(){
3511          eval($(code).text());
3512        });
3513      });
3514    });
3515  </script>
3516
3517</body>
3518</html>