PageRenderTime 37ms CodeModel.GetById 4ms app.highlight 103ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

Relevant Search: With Applications for Solr and Elasticsearch

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