PageRenderTime 154ms CodeModel.GetById 7ms app.highlight 107ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

https://gitlab.com/JJVV27/backbone
HTML | 4878 lines | 4294 code | 584 blank | 0 comment | 0 complexity | 41a36c312559ec3f0f3e76d2dc9504fb 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  <meta name="viewport" content="width=device-width">
   7  <link rel="canonical" href="http://backbonejs.org" />
   8  <title>Backbone.js</title>
   9  <style>
  10    body {
  11      font-size: 14px;
  12      line-height: 22px;
  13      font-family: Helvetica Neue, Helvetica, Arial;
  14      background: #f4f4f4 url(docs/images/background.png);
  15    }
  16    .interface {
  17      font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, sans-serif !important;
  18    }
  19    div#sidebar {
  20      background: #fff;
  21      position: fixed;
  22      z-index: 10;
  23      top: 0; left: 0; bottom: 0;
  24      width: 200px;
  25      overflow-y: auto;
  26      overflow-x: hidden;
  27      -webkit-overflow-scrolling: touch;
  28      padding: 15px 0 30px 30px;
  29      border-right: 1px solid #bbb;
  30      box-shadow: 0 0 20px #ccc; -webkit-box-shadow: 0 0 20px #ccc; -moz-box-shadow: 0 0 20px #ccc;
  31    }
  32      a.toc_title, a.toc_title:visited {
  33        display: block;
  34        color: black;
  35        font-weight: bold;
  36        margin-top: 15px;
  37      }
  38        a.toc_title:hover {
  39          text-decoration: underline;
  40        }
  41        #sidebar .version {
  42          font-size: 10px;
  43          font-weight: normal;
  44        }
  45      ul.toc_section {
  46        font-size: 11px;
  47        line-height: 14px;
  48        margin: 5px 0 0 0;
  49        padding-left: 0px;
  50        list-style-type: none;
  51        font-family: Lucida Grande;
  52      }
  53        .toc_section li {
  54          cursor: pointer;
  55          margin: 0 0 3px 0;
  56        }
  57          .toc_section li a {
  58            text-decoration: none;
  59            color: black;
  60          }
  61            .toc_section li a:hover {
  62              text-decoration: underline;
  63            }
  64    div.container {
  65      position: relative;
  66      width: 550px;
  67      margin: 40px 0 50px 260px;
  68    }
  69    img#logo {
  70      width: 450px;
  71      height: 80px;
  72    }
  73    div.run {
  74      position: absolute;
  75      right: 15px;
  76      width: 26px; height: 18px;
  77      background: url('docs/images/arrows.png') no-repeat -26px 0;
  78    }
  79      div.run:active {
  80        background-position: -51px 0;
  81      }
  82    p, div.container ul {
  83      margin: 25px 0;
  84      width: 550px;
  85    }
  86      p.warning {
  87        font-size: 12px;
  88        line-height: 18px;
  89        font-style: italic;
  90      }
  91      div.container ul {
  92        list-style: circle;
  93        padding-left: 15px;
  94        font-size: 13px;
  95        line-height: 18px;
  96      }
  97        div.container ul li {
  98          margin-bottom: 10px;
  99        }
 100        div.container ul.small {
 101          font-size: 12px;
 102        }
 103    a, a:visited {
 104      color: #444;
 105    }
 106    a:active, a:hover {
 107      color: #000;
 108    }
 109    a.punch {
 110      display: inline-block;
 111      background: #4162a8;
 112      border-top: 1px solid #38538c;
 113      border-right: 1px solid #1f2d4d;
 114      border-bottom: 1px solid #151e33;
 115      border-left: 1px solid #1f2d4d;
 116      -webkit-border-radius: 4px;
 117      -moz-border-radius: 4px;
 118      -ms-border-radius: 4px;
 119      -o-border-radius: 4px;
 120      border-radius: 4px;
 121      -webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 122      -moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 123      -ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 124      -o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 125      box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 126      color: #fff;
 127      font: bold 14px "helvetica neue", helvetica, arial, sans-serif;
 128      line-height: 1;
 129      margin-bottom: 15px;
 130      padding: 8px 0 10px 0;
 131      text-align: center;
 132      text-shadow: 0px -1px 1px #1e2d4d;
 133      text-decoration: none;
 134      width: 225px;
 135      -webkit-background-clip: padding-box; }
 136      a.punch:hover {
 137        -webkit-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 138        -moz-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 139        -ms-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 140        -o-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 141        box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 142        cursor: pointer; }
 143      a.punch:active {
 144        -webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 145        -moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 146        -ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 147        -o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 148        box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 149        margin-top: 5px; margin-bottom: 10px; }
 150    a img {
 151      border: 0;
 152    }
 153    a.travis-badge {
 154      display: block;
 155    }
 156    h1, h2, h3, h4, h5, h6 {
 157      padding-top: 20px;
 158    }
 159      h2 {
 160        font-size: 22px;
 161      }
 162    b.header {
 163      font-size: 18px;
 164      line-height: 35px;
 165    }
 166    span.alias {
 167      font-size: 14px;
 168      font-style: italic;
 169      margin-left: 20px;
 170    }
 171    table {
 172      margin: 15px 0 0; padding: 0;
 173    }
 174      tr, td {
 175        margin: 0; padding: 0;
 176      }
 177        td {
 178          padding: 0px 15px 5px 0;
 179        }
 180        table .rule {
 181          height: 1px;
 182          background: #ccc;
 183          margin: 5px 0;
 184        }
 185    code, pre, tt {
 186      font-family: Monaco, Consolas, "Lucida Console", monospace;
 187      font-size: 12px;
 188      line-height: 18px;
 189      font-style: normal;
 190    }
 191      tt {
 192        padding: 0px 3px;
 193        background: #fff;
 194        border: 1px solid #ddd;
 195        zoom: 1;
 196      }
 197      code {
 198        margin-left: 20px;
 199      }
 200      pre {
 201        font-size: 12px;
 202        padding: 2px 0 2px 15px;
 203        border: 4px solid #bbb; border-top: 0; border-bottom: 0;
 204        margin: 0px 0 25px;
 205      }
 206      img.example_image {
 207        margin: 0px auto;
 208      }
 209        img.example_retina {
 210          margin: 20px;
 211          box-shadow: 0 8px 15px rgba(0,0,0,0.4);
 212        }
 213    @media only screen and (-webkit-max-device-pixel-ratio: 1) and (max-width: 600px),
 214           only screen and (max--moz-device-pixel-ratio: 1) and (max-width: 600px) {
 215      div#sidebar {
 216        display: none;
 217      }
 218      img#logo {
 219        max-width: 450px;
 220        width: 100%;
 221        height: auto;
 222      }
 223      div.container {
 224        width: auto;
 225        margin-left: 15px;
 226        margin-right: 15px;
 227      }
 228        p, div.container ul {
 229          width: auto;
 230        }
 231    }
 232    @media only screen and (-webkit-min-device-pixel-ratio: 1.5) and (max-width: 640px),
 233          only screen and (-o-min-device-pixel-ratio: 3/2) and (max-width: 640px),
 234          only screen and (min-device-pixel-ratio: 1.5) and (max-width: 640px) {
 235      img {
 236        max-width: 100%;
 237        height: auto;
 238      }
 239      div#sidebar {
 240        -webkit-overflow-scrolling: initial;
 241        position: relative;
 242        width: 90%;
 243        height: 120px;
 244        left: 0;
 245        top: -7px;
 246        padding: 10px 0 10px 30px;
 247        border: 0;
 248      }
 249      img#logo {
 250        width: auto;
 251        height: auto;
 252      }
 253      div.container {
 254        margin: 0;
 255        width: 100%;
 256      }
 257      p, div.container ul {
 258        max-width: 98%;
 259        overflow-x: scroll;
 260      }
 261      table {
 262        position: relative;
 263      }
 264        tr:first-child td {
 265          padding-bottom: 25px;
 266        }
 267        td.text {
 268          line-height: 12px;
 269          padding: 0;
 270          position: absolute;
 271          left: 0;
 272          top: 48px;
 273        }
 274        tr:last-child td.text {
 275          top: 122px;
 276        }
 277      pre {
 278        overflow: scroll;
 279      }
 280    }
 281    img.figure {
 282      width: 100%;
 283    }
 284    div.columns {
 285      display: table;
 286      table-layout: fixed;
 287      width: 100%;
 288    }
 289      div.columns ul {
 290        margin: 10px 0;
 291      }
 292    div.col-50 {
 293      display: table-cell;
 294      width: 50%;
 295    }
 296  </style>
 297</head>
 298<body>
 299
 300  <div id="sidebar" class="interface">
 301
 302    <a class="toc_title" href="#">
 303      Backbone.js <span class="version">(1.2.0)</span>
 304    </a>
 305    <ul class="toc_section">
 306      <li>&raquo; <a href="http://github.com/jashkenas/backbone">GitHub Repository</a></li>
 307      <li>&raquo; <a href="docs/backbone.html">Annotated Source</a></li>
 308    </ul>
 309
 310    <a class="toc_title" href="#Getting-started">
 311      Getting Started
 312    </a>
 313    <ul class="toc_section">
 314      <li>- <a href="#Getting-Started">Introduction</a></li>
 315      <li><a href="#Model-View-separation">Models and Views</a></li>
 316      <li><a href="#Model-Collections">Collections</a></li>
 317      <li><a href="#API-integration">API Integration</a></li>
 318      <li><a href="#View-rendering">Rendering</a></li>
 319      <li><a href="#Routing">Routing</a></li>
 320    </ul>
 321
 322    <a class="toc_title" href="#Events">
 323      Events
 324    </a>
 325    <ul class="toc_section">
 326      <li><a href="#Events-on">on</a></li>
 327      <li><a href="#Events-off">off</a></li>
 328      <li><a href="#Events-trigger">trigger</a></li>
 329      <li><a href="#Events-once">once</a></li>
 330      <li><a href="#Events-listenTo">listenTo</a></li>
 331      <li><a href="#Events-stopListening">stopListening</a></li>
 332      <li><a href="#Events-listenToOnce">listenToOnce</a></li>
 333      <li>- <a href="#Events-catalog"><b>Catalog of Built-in Events</b></a></li>
 334    </ul>
 335
 336    <a class="toc_title" href="#Model">
 337      Model
 338    </a>
 339    <ul class="toc_section">
 340      <li><a href="#Model-extend">extend</a></li>
 341      <li><a href="#Model-constructor">constructor / initialize</a></li>
 342      <li><a href="#Model-get">get</a></li>
 343      <li><a href="#Model-set">set</a></li>
 344      <li><a href="#Model-escape">escape</a></li>
 345      <li><a href="#Model-has">has</a></li>
 346      <li><a href="#Model-unset">unset</a></li>
 347      <li><a href="#Model-clear">clear</a></li>
 348      <li><a href="#Model-id">id</a></li>
 349      <li><a href="#Model-idAttribute">idAttribute</a></li>
 350      <li><a href="#Model-cid">cid</a></li>
 351      <li><a href="#Model-attributes">attributes</a></li>
 352      <li><a href="#Model-changed">changed</a></li>
 353      <li><a href="#Model-defaults">defaults</a></li>
 354      <li><a href="#Model-toJSON">toJSON</a></li>
 355      <li><a href="#Model-sync">sync</a></li>
 356      <li><a href="#Model-fetch">fetch</a></li>
 357      <li><a href="#Model-save">save</a></li>
 358      <li><a href="#Model-destroy">destroy</a></li>
 359      <li><a href="#Model-Underscore-Methods"><b>Underscore Methods (9)</b></a></li>
 360      <li><a href="#Model-validate">validate</a></li>
 361      <li><a href="#Model-validationError">validationError</a></li>
 362      <li><a href="#Model-isValid">isValid</a></li>
 363      <li><a href="#Model-url">url</a></li>
 364      <li><a href="#Model-urlRoot">urlRoot</a></li>
 365      <li><a href="#Model-parse">parse</a></li>
 366      <li><a href="#Model-clone">clone</a></li>
 367      <li><a href="#Model-isNew">isNew</a></li>
 368      <li><a href="#Model-hasChanged">hasChanged</a></li>
 369      <li><a href="#Model-changedAttributes">changedAttributes</a></li>
 370      <li><a href="#Model-previous">previous</a></li>
 371      <li><a href="#Model-previousAttributes">previousAttributes</a></li>
 372    </ul>
 373
 374    <a class="toc_title" href="#Collection">
 375      Collection
 376    </a>
 377    <ul class="toc_section">
 378      <li><a href="#Collection-extend">extend</a></li>
 379      <li><a href="#Collection-model">model</a></li>
 380      <li><a href="#Collection-constructor">constructor / initialize</a></li>
 381      <li><a href="#Collection-models">models</a></li>
 382      <li><a href="#Collection-toJSON">toJSON</a></li>
 383      <li><a href="#Collection-sync">sync</a></li>
 384      <li><a href="#Collection-Underscore-Methods"><b>Underscore Methods (46)</b></a></li>
 385      <li><a href="#Collection-add">add</a></li>
 386      <li><a href="#Collection-remove">remove</a></li>
 387      <li><a href="#Collection-reset">reset</a></li>
 388      <li><a href="#Collection-set">set</a></li>
 389      <li><a href="#Collection-get">get</a></li>
 390      <li><a href="#Collection-at">at</a></li>
 391      <li><a href="#Collection-push">push</a></li>
 392      <li><a href="#Collection-pop">pop</a></li>
 393      <li><a href="#Collection-unshift">unshift</a></li>
 394      <li><a href="#Collection-shift">shift</a></li>
 395      <li><a href="#Collection-slice">slice</a></li>
 396      <li><a href="#Collection-length">length</a></li>
 397      <li><a href="#Collection-comparator">comparator</a></li>
 398      <li><a href="#Collection-sort">sort</a></li>
 399      <li><a href="#Collection-pluck">pluck</a></li>
 400      <li><a href="#Collection-where">where</a></li>
 401      <li><a href="#Collection-findWhere">findWhere</a></li>
 402      <li><a href="#Collection-url">url</a></li>
 403      <li><a href="#Collection-parse">parse</a></li>
 404      <li><a href="#Collection-clone">clone</a></li>
 405      <li><a href="#Collection-fetch">fetch</a></li>
 406      <li><a href="#Collection-create">create</a></li>
 407    </ul>
 408
 409    <a class="toc_title" href="#Router">
 410      Router
 411    </a>
 412    <ul class="toc_section">
 413      <li><a href="#Router-extend">extend</a></li>
 414      <li><a href="#Router-routes">routes</a></li>
 415      <li><a href="#Router-constructor">constructor / initialize</a></li>
 416      <li><a href="#Router-route">route</a></li>
 417      <li><a href="#Router-navigate">navigate</a></li>
 418      <li><a href="#Router-execute">execute</a></li>
 419    </ul>
 420
 421    <a class="toc_title" href="#History">
 422      History
 423    </a>
 424    <ul class="toc_section">
 425      <li><a href="#History-start">start</a></li>
 426    </ul>
 427
 428    <a class="toc_title" href="#Sync">
 429      Sync
 430    </a>
 431    <ul class="toc_section">
 432      <li><a href="#Sync">Backbone.sync</a></li>
 433      <li><a href="#Sync-ajax">Backbone.ajax</a></li>
 434      <li><a href="#Sync-emulateHTTP">Backbone.emulateHTTP</a></li>
 435      <li><a href="#Sync-emulateJSON">Backbone.emulateJSON</a></li>
 436    </ul>
 437
 438    <a class="toc_title" href="#View">
 439      View
 440    </a>
 441    <ul class="toc_section">
 442      <li><a href="#View-extend">extend</a></li>
 443      <li><a href="#View-constructor">constructor / initialize</a></li>
 444      <li><a href="#View-el">el</a></li>
 445      <li><a href="#View-$el">$el</a></li>
 446      <li><a href="#View-setElement">setElement</a></li>
 447      <li><a href="#View-attributes">attributes</a></li>
 448      <li><a href="#View-dollar">$ (jQuery)</a></li>
 449      <li><a href="#View-template">template</a></li>
 450      <li><a href="#View-render">render</a></li>
 451      <li><a href="#View-remove">remove</a></li>
 452      <li><a href="#View-delegateEvents">delegateEvents</a></li>
 453      <li><a href="#View-undelegateEvents">undelegateEvents</a></li>
 454    </ul>
 455
 456    <a class="toc_title" href="#Utility">
 457      Utility
 458    </a>
 459    <ul class="toc_section">
 460      <li><a href="#Utility-Backbone-noConflict">Backbone.noConflict</a></li>
 461      <li><a href="#Utility-Backbone-$">Backbone.$</a></li>
 462    </ul>
 463
 464    <a class="toc_title" href="#faq">
 465      F.A.Q.
 466    </a>
 467    <ul class="toc_section">
 468      <li><a href="#FAQ-why-backbone">Why Backbone?</a></li>
 469      <li><a href="#FAQ-tim-toady">More Than One Way To Do It</a></li>
 470      <li><a href="#FAQ-nested">Nested Models &amp; Collections</a></li>
 471      <li><a href="#FAQ-bootstrap">Loading Bootstrapped Models</a></li>
 472      <li><a href="#FAQ-extending">Extending Backbone</a></li>
 473      <li><a href="#FAQ-mvc">Traditional MVC</a></li>
 474      <li><a href="#FAQ-this">Binding "this"</a></li>
 475      <li><a href="#FAQ-rails">Working with Rails</a></li>
 476    </ul>
 477
 478    <a class="toc_title" href="#examples">
 479      Examples
 480    </a>
 481    <ul class="toc_section">
 482      <li><a href="#examples-todos">Todos</a></li>
 483      <li><a href="#examples-documentcloud">DocumentCloud</a></li>
 484      <li><a href="#examples-usa-today">USA Today</a></li>
 485      <li><a href="#examples-rdio">Rdio</a></li>
 486      <li><a href="#examples-hulu">Hulu</a></li>
 487      <li><a href="#examples-quartz">Quartz</a></li>
 488      <li><a href="#examples-earth">Earth</a></li>
 489      <li><a href="#examples-vox">Vox</a></li>
 490      <li><a href="#examples-gawker">Gawker Media</a></li>
 491      <li><a href="#examples-flow">Flow</a></li>
 492      <li><a href="#examples-gilt">Gilt Groupe</a></li>
 493      <li><a href="#examples-enigma">Enigma</a></li>
 494      <li><a href="#examples-newsblur">NewsBlur</a></li>
 495      <li><a href="#examples-wordpress">WordPress.com</a></li>
 496      <li><a href="#examples-foursquare">Foursquare</a></li>
 497      <li><a href="#examples-bitbucket">Bitbucket</a></li>
 498      <li><a href="#examples-disqus">Disqus</a></li>
 499      <li><a href="#examples-delicious">Delicious</a></li>
 500      <li><a href="#examples-khan-academy">Khan Academy</a></li>
 501      <li><a href="#examples-irccloud">IRCCloud</a></li>
 502      <li><a href="#examples-pitchfork">Pitchfork</a></li>
 503      <li><a href="#examples-spin">Spin</a></li>
 504      <li><a href="#examples-zocdoc">ZocDoc</a></li>
 505      <li><a href="#examples-walmart">Walmart Mobile</a></li>
 506      <li><a href="#examples-groupon">Groupon Now!</a></li>
 507      <li><a href="#examples-basecamp">Basecamp</a></li>
 508      <li><a href="#examples-slavery-footprint">Slavery Footprint</a></li>
 509      <li><a href="#examples-stripe">Stripe</a></li>
 510      <li><a href="#examples-airbnb">Airbnb</a></li>
 511      <li><a href="#examples-soundcloud">SoundCloud Mobile</a></li>
 512      <li>- <a href="#examples-artsy">Art.sy</a></li>
 513      <li><a href="#examples-pandora">Pandora</a></li>
 514      <li><a href="#examples-inkling">Inkling</a></li>
 515      <li><a href="#examples-code-school">Code School</a></li>
 516      <li><a href="#examples-cloudapp">CloudApp</a></li>
 517      <li><a href="#examples-seatgeek">SeatGeek</a></li>
 518      <li><a href="#examples-easel">Easel</a></li>
 519      <li>- <a href="#examples-jolicloud">Jolicloud</a></li>
 520      <li><a href="#examples-salon">Salon.io</a></li>
 521      <li><a href="#examples-tilemill">TileMill</a></li>
 522      <li><a href="#examples-blossom">Blossom</a></li>
 523      <li><a href="#examples-trello">Trello</a></li>
 524      <li><a href="#examples-tzigla">Tzigla</a></li>
 525    </ul>
 526
 527    <a class="toc_title" href="#changelog">
 528      Change Log
 529    </a>
 530
 531  </div>
 532
 533  <div class="container">
 534
 535    <p>
 536      <img id="logo" src="docs/images/backbone.png" alt="Backbone.js" />
 537    </p>
 538
 539    <p>
 540      Backbone.js gives structure to web applications
 541      by providing <b>models</b> with key-value binding and custom events,
 542      <b>collections</b> with a rich API of enumerable functions,
 543      <b>views</b> with declarative event handling, and connects it all to your
 544      existing API over a RESTful JSON interface.
 545    </p>
 546
 547    <p>
 548      The project is <a href="http://github.com/jashkenas/backbone/">hosted on GitHub</a>,
 549      and the <a href="docs/backbone.html">annotated source code</a> is available,
 550      as well as an online <a href="test/">test suite</a>,
 551      an <a href="examples/todos/index.html">example application</a>,
 552      a <a href="https://github.com/jashkenas/backbone/wiki/Tutorials%2C-blog-posts-and-example-sites">list of tutorials</a>
 553      and a <a href="#examples">long list of real-world projects</a> that use Backbone.
 554      Backbone is available for use under the <a href="http://github.com/jashkenas/backbone/blob/master/LICENSE">MIT software license</a>.
 555    </p>
 556
 557    <p>
 558      You can report bugs and discuss features on the
 559      <a href="http://github.com/jashkenas/backbone/issues">GitHub issues page</a>,
 560      on Freenode IRC in the <tt>#documentcloud</tt> channel, post questions to the
 561      <a href="https://groups.google.com/forum/#!forum/backbonejs">Google Group</a>,
 562      add pages to the <a href="https://github.com/jashkenas/backbone/wiki">wiki</a>
 563      or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>.
 564    </p>
 565
 566    <p>
 567      <i>
 568        Backbone is an open-source component of
 569        <a href="http://documentcloud.org/">DocumentCloud</a>.
 570      </i>
 571    </p>
 572
 573    <h2 id="downloads">
 574      Downloads &amp; Dependencies
 575      <span style="padding-left: 7px; font-size:11px; font-weight: normal;" class="interface">(Right-click, and use "Save As")</span>
 576    </h2>
 577
 578    <table>
 579      <tr>
 580        <td><a class="punch" href="backbone.js">Development Version (1.2.0)</a></td>
 581        <td class="text"><i>69kb, Full source, tons of comments</i></td>
 582      </tr>
 583      <tr>
 584        <td><a class="punch" href="backbone-min.js">Production Version (1.2.0)</a></td>
 585        <td class="text" style="line-height: 16px;">
 586          <i>7.3kb, Packed and gzipped</i><br />
 587          <small>(<a href="backbone-min.map">Source Map</a>)</small>
 588        </td>
 589      </tr>
 590      <tr>
 591        <td><a class="punch" href="https://raw.github.com/jashkenas/backbone/master/backbone.js">Edge Version (master)</a></td>
 592        <td>
 593          <i>Unreleased, use at your own risk</i>
 594          <a class="travis-badge" href="https://travis-ci.org/jashkenas/backbone">
 595            <img src="https://travis-ci.org/jashkenas/backbone.png" />
 596          </a>
 597        </td>
 598      </tr>
 599    </table>
 600
 601    <p>
 602      Backbone's only hard dependency is
 603      <a href="http://underscorejs.org/">Underscore.js</a> <small>( >= 1.7.0)</small>.
 604      For RESTful persistence and DOM manipulation with <a href="#View">Backbone.View</a>,
 605      include <b><a href="http://jquery.com">jQuery</a></b> ( >= 1.11.0), and
 606      <b><a href="https://github.com/douglascrockford/JSON-js">json2.js</a></b> for older
 607      Internet Explorer support.
 608      <i>(Mimics of the Underscore and jQuery APIs, such as
 609      <a href="http://lodash.com">Lo-Dash</a> and
 610      <a href="http://zeptojs.com">Zepto</a>, will
 611      also tend to work, with varying degrees of compatibility.)</i>
 612    </p>
 613    <h2 id="Getting-started">Getting Started</h2>
 614
 615    <p>
 616      When working on a web application that involves a lot of JavaScript, one
 617      of the first things you learn is to stop tying your data to the DOM. It's all
 618      too easy to create JavaScript applications that end up as tangled piles of
 619      jQuery selectors and callbacks, all trying frantically to keep data in
 620      sync between the HTML UI, your JavaScript logic, and the database on your
 621      server. For rich client-side applications, a more structured approach
 622      is often helpful.
 623    </p>
 624
 625    <p>
 626      With Backbone, you represent your data as
 627      <a href="#Model">Models</a>, which can be created, validated, destroyed,
 628      and saved to the server. Whenever a UI action causes an attribute of
 629      a model to change, the model triggers a <i>"change"</i> event; all
 630      the <a href="#View">Views</a> that display the model's state can be notified of the
 631      change, so that they are able to respond accordingly, re-rendering themselves with
 632      the new information. In a finished Backbone app, you don't have to write the glue
 633      code that looks into the DOM to find an element with a specific <i>id</i>,
 634      and update the HTML manually
 635      &mdash; when the model changes, the views simply update themselves.
 636    </p>
 637
 638    <p>
 639      Philosophically, Backbone is an attempt to discover the minimal set
 640      of data-structuring (models and collections) and user interface (views
 641      and URLs) primitives that are generally useful when building web applications with
 642      JavaScript. In an ecosystem where overarching, decides-everything-for-you
 643      frameworks are commonplace, and many libraries require your site to be
 644      reorganized to suit their look, feel, and default behavior — Backbone should
 645      continue to be a tool that gives you the <i>freedom</i> to design the full
 646      experience of your web application.
 647    </p>
 648
 649    <p>
 650      If you're new here, and aren't yet quite sure what Backbone is for, start by
 651      browsing the <a href="#examples">list of Backbone-based projects</a>.
 652    </p>
 653
 654    <p>
 655      Many of the code examples in this documentation are runnable, because
 656      Backbone is included on this page.
 657      Click the <i>play</i> button to execute them.
 658    </p>
 659
 660    <h2 id="Model-View-separation">Models and Views</h2>
 661
 662    <img class="figure" src="docs/images/intro-model-view.svg" alt="Model-View Separation.">
 663
 664    <p>
 665      The single most important thing that Backbone can help you with is keeping
 666      your business logic separate from your user interface. When the two are
 667      entangled, change is hard; when logic doesn't depend on UI, your
 668      interface becomes easier to work with.
 669    </p>
 670
 671    <div class="columns">
 672      <div class="col-50">
 673        <b>Model</b>
 674        <ul>
 675          <li>Orchestrates data and business logic.</li>
 676          <li>Loads and saves from the server.</li>
 677          <li>Emits events when data changes.</li>
 678        </ul>
 679      </div>
 680      <div class="col-50">
 681        <b>View</b>
 682        <ul>
 683          <li>Listens for changes and renders UI.</li>
 684          <li>Handles user input and interactivity.</li>
 685          <li>Sends captured input to the model.</li>
 686        </ul>
 687      </div>
 688    </div>
 689
 690    <p>
 691      A <b>Model</b> manages an internal table of data attributes, and
 692      triggers <tt>"change"</tt> events when any of its data is modified.
 693      Models handle syncing data with a persistence layer — usually a REST API
 694      with a backing database. Design your models as the atomic reusable objects
 695      containing all of the helpful functions for manipulating their particular
 696      bit of data. Models should be able to be passed around throughout your app,
 697      and used anywhere that bit of data is needed.
 698    </p>
 699
 700    <p>
 701      A <b>View</b> is an atomic chunk of user interface. It often renders the
 702      data from a specific model, or number of models &mdash; but views can
 703      also be data-less chunks of UI that stand alone.
 704      Models should be generally unaware of views. Instead, views listen to
 705      the model <tt>"change"</tt> events, and react or re-render themselves
 706      appropriately.
 707    </p>
 708
 709    <h2 id="Model-Collections">Collections</h2>
 710
 711    <img class="figure" src="docs/images/intro-collections.svg" alt="Model Collections.">
 712
 713    <p>
 714      A <b>Collection</b> helps you deal with a group of related models, handling
 715      the loading and saving of new models to the server and providing helper
 716      functions for performing aggregations or computations against a list of models.
 717      Aside from their own events, collections also proxy through all of the
 718      events that occur to models within them, allowing you to listen in one place
 719      for any change that might happen to any model in the collection.
 720    </p>
 721
 722    <h2 id="API-integration">API Integration</h2>
 723
 724    <p>
 725      Backbone is pre-configured to sync with a RESTful API. Simply create a
 726      new Collection with the <tt>url</tt> of your resource endpoint:
 727    </p>
 728
 729<pre>
 730var Books = Backbone.Collection.extend({
 731  url: '/books'
 732});
 733</pre>
 734
 735    <p>
 736      The <b>Collection</b> and <b>Model</b> components together form a direct
 737      mapping of REST resources using the following methods:
 738    </p>
 739
 740<pre>
 741GET  /books/ .... collection.fetch();
 742POST /books/ .... collection.create();
 743GET  /books/1 ... model.fetch();
 744PUT  /books/1 ... model.save();
 745DEL  /books/1 ... model.destroy();
 746</pre>
 747
 748    <p>
 749      When fetching raw JSON data from an API, a <b>Collection</b> will
 750      automatically populate itself with data formatted as an array, while
 751      a <b>Model</b> will automatically populate itself with data formatted
 752      as an object:
 753    </p>
 754
 755<pre>
 756[{"id": 1}] ..... populates a Collection with one model.
 757{"id": 1} ....... populates a Model with one attribute.
 758</pre>
 759
 760    <p>
 761      However, it's fairly common to encounter APIs that return data in a
 762      different format than what Backbone expects. For example, consider
 763      fetching a <b>Collection</b> from an API that returns the real data
 764      array wrapped in metadata:
 765    </p>
 766
 767<pre>
 768{
 769  "page": 1,
 770  "limit": 10,
 771  "total": 2,
 772  "books": [
 773    {"id": 1, "title": "Pride and Prejudice"},
 774    {"id": 4, "title": "The Great Gatsby"}
 775  ]
 776}
 777</pre>
 778
 779    <p>
 780      In the above example data, a <b>Collection</b> should populate using the
 781      <tt>"books"</tt> array rather than the root object structure. This
 782      difference is easily reconciled using a <tt>parse</tt> method that
 783      returns (or transforms) the desired portion of API data:
 784    </p>
 785
 786<pre>
 787var Books = Backbone.Collection.extend({
 788  url: '/books',
 789  parse: function(data) {
 790    return data.books;
 791  }
 792});
 793</pre>
 794
 795    <h2 id="View-rendering">View Rendering</h2>
 796
 797    <img class="figure" src="docs/images/intro-views.svg" alt="View rendering.">
 798
 799    <p>
 800      Each <b>View</b> manages the rendering and user interaction within its own
 801      DOM element. If you're strict about not allowing views to reach outside
 802      of themselves, it helps keep your interface flexible &mdash; allowing
 803      views to be rendered in isolation in any place where they might be needed.
 804    </p>
 805
 806    <p>
 807      Backbone remains unopinionated about the process used to render <b>View</b>
 808      objects and their subviews into UI: you define how your models get translated
 809      into HTML (or SVG, or Canvas, or something even more exotic).
 810      It could be as prosaic as a simple
 811      <a href="http://underscorejs.org/#template">Underscore template</a>, or as fancy as the
 812      <a href="http://facebook.github.io/react/docs/tutorial.html">React virtual DOM</a>.
 813      Some basic approaches to rendering views can be found
 814      in the <a href="https://github.com/jashkenas/backbone/wiki/Backbone%2C-The-Primer">Backbone primer</a>.
 815    </p>
 816
 817    <h2 id="Routing">Routing with URLs</h2>
 818
 819    <img class="figure" src="docs/images/intro-routing.svg" alt="Routing">
 820
 821    <p>
 822      In rich web applications, we still want to provide linkable,
 823      bookmarkable, and shareable URLs to meaningful locations within an app.
 824      Use the <b>Router</b> to update the browser URL whenever the user
 825      reaches a new "place" in your app that they might want to bookmark or share.
 826      Conversely, the <b>Router</b> detects changes to the URL &mdash; say,
 827      pressing the "Back" button &mdash; and can tell your application exactly where you
 828      are now.
 829    </p>
 830
 831    <h2 id="Events">Backbone.Events</h2>
 832
 833    <p>
 834      <b>Events</b> is a module that can be mixed in to any object, giving the
 835      object the ability to bind and trigger custom named events. Events do not
 836      have to be declared before they are bound, and may take passed arguments.
 837      For example:
 838    </p>
 839
 840<pre class="runnable">
 841var object = {};
 842
 843_.extend(object, Backbone.Events);
 844
 845object.on("alert", function(msg) {
 846  alert("Triggered " + msg);
 847});
 848
 849object.trigger("alert", "an event");
 850</pre>
 851
 852    <p>
 853      For example, to make a handy event dispatcher that can coordinate events
 854      among different areas of your application: <tt>var dispatcher = _.clone(Backbone.Events)</tt>
 855    </p>
 856
 857    <p id="Events-on">
 858      <b class="header">on</b><code>object.on(event, callback, [context])</code><span class="alias">Alias: bind</span>
 859      <br />
 860      Bind a <b>callback</b> function to an object. The callback will be invoked
 861      whenever the <b>event</b> is fired.
 862      If you have a large number of different events on a page, the convention is to use colons to
 863      namespace them: <tt>"poll:start"</tt>, or <tt>"change:selection"</tt>.
 864      The event string may also be a space-delimited list of several events...
 865    </p>
 866
 867<pre>
 868book.on("change:title change:author", ...);
 869</pre>
 870
 871    <p>
 872      To supply a <b>context</b> value for <tt>this</tt> when the callback is invoked,
 873      pass the optional third argument: <tt>model.on('change', this.render, this)</tt>
 874    </p>
 875
 876    <p>
 877      Callbacks bound to the special
 878      <tt>"all"</tt> event will be triggered when any event occurs, and are passed
 879      the name of the event as the first argument. For example, to proxy all events
 880      from one object to another:
 881    </p>
 882
 883<pre>
 884proxy.on("all", function(eventName) {
 885  object.trigger(eventName);
 886});
 887</pre>
 888
 889    <p>
 890      All Backbone event methods also support an event map syntax, as an alternative
 891      to positional arguments:
 892    </p>
 893
 894<pre>
 895book.on({
 896  "change:title": titleView.update,
 897  "change:author": authorPane.update,
 898  "destroy": bookView.remove
 899});
 900</pre>
 901
 902    <p id="Events-off">
 903      <b class="header">off</b><code>object.off([event], [callback], [context])</code><span class="alias">Alias: unbind</span>
 904      <br />
 905      Remove a previously-bound <b>callback</b> function from an object. If no
 906      <b>context</b> is specified, all of the versions of the callback with
 907      different contexts will be removed. If no
 908      callback is specified, all callbacks for the <b>event</b> will be
 909      removed. If no event is specified, callbacks for <i>all</i> events
 910      will be removed.
 911    </p>
 912
 913<pre>
 914// Removes just the `onChange` callback.
 915object.off("change", onChange);
 916
 917// Removes all "change" callbacks.
 918object.off("change");
 919
 920// Removes the `onChange` callback for all events.
 921object.off(null, onChange);
 922
 923// Removes all callbacks for `context` for all events.
 924object.off(null, null, context);
 925
 926// Removes all callbacks on `object`.
 927object.off();
 928</pre>
 929
 930    <p>
 931      Note that calling <tt>model.off()</tt>, for example, will indeed remove <i>all</i> events
 932      on the model &mdash; including events that Backbone uses for internal bookkeeping.
 933    </p>
 934
 935    <p id="Events-trigger">
 936      <b class="header">trigger</b><code>object.trigger(event, [*args])</code>
 937      <br />
 938      Trigger callbacks for the given <b>event</b>, or space-delimited list of events.
 939      Subsequent arguments to <b>trigger</b> will be passed along to the
 940      event callbacks.
 941    </p>
 942
 943    <p id="Events-once">
 944      <b class="header">once</b><code>object.once(event, callback, [context])</code>
 945      <br />
 946      Just like <a href="#Events-on">on</a>, but causes the bound callback to fire
 947      only once before being removed. Handy for saying "the next time that X happens, do this".
 948      When multiple events are passed in using the space separated syntax, the event will fire once
 949      for every event you passed in, not once for a combination of all events
 950    </p>
 951
 952    <p id="Events-listenTo">
 953      <b class="header">listenTo</b><code>object.listenTo(other, event, callback)</code>
 954      <br />
 955      Tell an <b>object</b> to listen to a particular event on an <b>other</b>
 956      object.  The advantage of using this form, instead of <tt>other.on(event,
 957      callback, object)</tt>, is that <b>listenTo</b> allows the <b>object</b>
 958      to keep track of the events, and they can be removed all at once later
 959      on.  The <b>callback</b> will always be called with <b>object</b> as
 960      context.
 961    </p>
 962
 963<pre>
 964view.listenTo(model, 'change', view.render);
 965</pre>
 966
 967    <p id="Events-stopListening">
 968      <b class="header">stopListening</b><code>object.stopListening([other], [event], [callback])</code>
 969      <br />
 970      Tell an <b>object</b> to stop listening to events. Either call
 971      <b>stopListening</b> with no arguments to have the <b>object</b> remove
 972      all of its <a href="#Events-listenTo">registered</a> callbacks ... or be more
 973      precise by telling it to remove just the events it's listening to on a
 974      specific object, or a specific event, or just a specific callback.
 975    </p>
 976
 977<pre>
 978view.stopListening();
 979
 980view.stopListening(model);
 981</pre>
 982
 983    <p id="Events-listenToOnce">
 984      <b class="header">listenToOnce</b><code>object.listenToOnce(other, event, callback)</code>
 985      <br />
 986      Just like <a href="#Events-listenTo">listenTo</a>, but causes the bound
 987      callback to fire only once before being removed.
 988    </p>
 989
 990    <p id="Events-catalog">
 991      <b class="header">Catalog of Events</b>
 992      <br />
 993      Here's the complete list of built-in Backbone events, with arguments.
 994      You're also free to trigger your own events on Models, Collections and
 995      Views as you see fit. The <tt>Backbone</tt> object itself mixes in <tt>Events</tt>,
 996      and can be used to emit any global events that your application needs.
 997    </p>
 998
 999    <ul class="small">
1000      <li><b>"add"</b> (model, collection, options) &mdash; when a model is added to a collection.</li>
1001      <li><b>"remove"</b> (model, collection, options) &mdash; when a model is removed from a collection.</li>
1002      <li><b>"update"</b> (collection, options) &mdash; single event triggered after any number of models have been added or removed from a collection.</li>
1003      <li><b>"reset"</b> (collection, options) &mdash; when the collection's entire contents have been replaced.</li>
1004      <li><b>"sort"</b> (collection, options) &mdash; when the collection has been re-sorted.</li>
1005      <li><b>"change"</b> (model, options) &mdash; when a model's attributes have changed.</li>
1006      <li><b>"change:[attribute]"</b> (model, value, options) &mdash; when a specific attribute has been updated.</li>
1007      <li><b>"destroy"</b> (model, collection, options) &mdash; when a model is <a href="#Model-destroy">destroyed</a>.</li>
1008      <li><b>"request"</b> (model_or_collection, xhr, options) &mdash; when a model or collection has started a request to the server.</li>
1009      <li><b>"sync"</b> (model_or_collection, resp, options) &mdash; when a model or collection has been successfully synced with the server.</li>
1010      <li><b>"error"</b> (model_or_collection, resp, options) &mdash; when a model's or collection's request to the server has failed.</li>
1011      <li><b>"invalid"</b> (model, error, options) &mdash; when a model's <a href="#Model-validate">validation</a> fails on the client.</li>
1012      <li><b>"route:[name]"</b> (params) &mdash; Fired by the router when a specific route is matched.</li>
1013      <li><b>"route"</b> (route, params) &mdash; Fired by the router when <i>any</i> route has been matched.</li>
1014      <li><b>"route"</b> (router, route, params) &mdash; Fired by history when <i>any</i> route has been matched.</li>
1015      <li><b>"all"</b> &mdash; this special event fires for <i>any</i> triggered event, passing the event name as the first argument.</li>
1016    </ul>
1017
1018    <p>
1019      Generally speaking, when calling a function that emits an event
1020      (<tt>model.set</tt>, <tt>collection.add</tt>, and so on...),
1021      if you'd like to prevent the event from being triggered, you may pass
1022      <tt>{silent: true}</tt> as an option. Note that this is <i>rarely</i>,
1023      perhaps even never, a good idea. Passing through a specific flag
1024      in the options for your event callback to look at, and choose to ignore,
1025      will usually work out better.
1026    </p>
1027
1028    <h2 id="Model">Backbone.Model</h2>
1029
1030    <p>
1031      <b>Models</b> are the heart of any JavaScript application, containing
1032      the interactive data as well as a large part of the logic surrounding it:
1033      conversions, validations, computed properties, and access control. You
1034      extend <b>Backbone.Model</b> with your domain-specific methods, and
1035      <b>Model</b> provides a basic set of functionality for managing changes.
1036    </p>
1037
1038    <p>
1039      The following is a contrived example, but it demonstrates defining a model
1040      with a custom method, setting an attribute, and firing an event keyed
1041      to changes in that specific attribute.
1042      After running this code once, <tt>sidebar</tt> will be
1043      available in your browser's console, so you can play around with it.
1044    </p>
1045
1046<pre class="runnable">
1047var Sidebar = Backbone.Model.extend({
1048  promptColor: function() {
1049    var cssColor = prompt("Please enter a CSS color:");
1050    this.set({color: cssColor});
1051  }
1052});
1053
1054window.sidebar = new Sidebar;
1055
1056sidebar.on('change:color', function(model, color) {
1057  $('#sidebar').css({background: color});
1058});
1059
1060sidebar.set({color: 'white'});
1061
1062sidebar.promptColor();
1063</pre>
1064
1065    <p id="Model-extend">
1066      <b class="header">extend</b><code>Backbone.Model.extend(properties, [classProperties])</code>
1067      <br />
1068      To create a <b>Model</b> class of your own, you extend <b>Backbone.Model</b>
1069      and provide instance <b>properties</b>, as well as optional
1070      <b>classProperties</b> to be attached directly to the constructor function.
1071    </p>
1072
1073    <p>
1074      <b>extend</b> correctly sets up the prototype chain, so subclasses created
1075      with <b>extend</b> can be further extended and subclassed as far as you like.
1076    </p>
1077
1078<pre>
1079var Note = Backbone.Model.extend({
1080
1081  initialize: function() { ... },
1082
1083  author: function() { ... },
1084
1085  coordinates: function() { ... },
1086
1087  allowedToEdit: function(account) {
1088    return true;
1089  }
1090
1091});
1092
1093var PrivateNote = Note.extend({
1094
1095  allowedToEdit: function(account) {
1096    return account.owns(this);
1097  }
1098
1099});
1100</pre>
1101
1102    <p class="warning">
1103        Brief aside on <tt>super</tt>: JavaScript does not provide
1104        a simple way to call super &mdash; the function of the same name defined
1105        higher on the prototype chain. If you override a core function like
1106        <tt>set</tt>, or <tt>save</tt>, and you want to invoke the
1107        parent object's implementation, you'll have to explicitly call it, along these lines:
1108    </p>
1109
1110<pre>
1111var Note = Backbone.Model.extend({
1112  set: function(attributes, options) {
1113    Backbone.Model.prototype.set.apply(this, arguments);
1114    ...
1115  }
1116});
1117</pre>
1118
1119    <p id="Model-constructor">
1120      <b class="header">constructor / initialize</b><code>new Model([attributes], [options])</code>
1121      <br />
1122      When creating an instance of a model, you can pass in the initial values
1123      of the <b>attributes</b>, which will be <a href="#Model-set">set</a> on the
1124      model. If you define an <b>initialize</b> function, it will be invoked when
1125      the model is created.
1126    </p>
1127
1128<pre>
1129new Book({
1130  title: "One Thousand and One Nights",
1131  author: "Scheherazade"
1132});
1133</pre>
1134
1135    <p>
1136      In rare cases, if you're looking to get fancy,
1137      you may want to override <b>constructor</b>, which allows
1138      you to replace the actual constructor function for your model.
1139    </p>
1140
1141<pre>
1142var Library = Backbone.Model.extend({
1143  constructor: function() {
1144    this.books = new Books();
1145    Backbone.Model.apply(this, arguments);
1146  },
1147  parse: function(data, options) {
1148    this.books.reset(data.books);
1149    return data.library;
1150  }
1151});
1152</pre>
1153
1154    <p>
1155      If you pass a <tt>{collection: ...}</tt> as the <b>options</b>, the model
1156      gains a <tt>collection</tt> property that will be used to indicate which
1157      collection the model belongs to, and is used to help compute the model's
1158      <a href="#Model-url">url</a>. The <tt>model.collection</tt> property is
1159      normally created automatically when you first add a model to a collection.
1160      Note that the reverse is not true, as passing this option to the constructor
1161      will not automatically add the model to the collection. Useful, sometimes.
1162    </p>
1163
1164    <p>
1165      If <tt>{parse: true}</tt> is passed as an <b>option</b>, the <b>attributes</b>
1166      will first be converted by <a href="#Model-parse">parse</a> before being
1167      <a href="#Model-set">set</a> on the model.
1168    </p>
1169
1170    <p id="Model-get">
1171      <b class="header">get</b><code>model.get(attribute)</code>
1172      <br />
1173      Get the current value of an attribute from the model. For example:
1174      <tt>note.get("title")</tt>
1175    </p>
1176
1177    <p id="Model-set">
1178      <b class="header">set</b><code>model.set(attributes, [options])</code>
1179      <br />
1180      Set a hash of attributes (one or many) on the model. If any of the attributes
1181      change the model's state, a <tt>"change"</tt> event will be triggered on the model.
1182      Change events for specific attributes are also triggered, and you can bind
1183      to those as well, for example: <tt>change:title</tt>, and <tt>change:content</tt>.
1184      You may also pass individual keys and values.
1185    </p>
1186
1187<pre>
1188note.set({title: "March 20", content: "In his eyes she eclipses..."});
1189
1190book.set("title", "A Scandal in Bohemia");
1191</pre>
1192
1193    <p id="Model-escape">
1194      <b class="header">escape</b><code>model.escape(attribute)</code>
1195      <br />
1196      Similar to <a href="#Model-get">get</a>, but returns the HTML-escaped version
1197      of a model's attribute. If you're interpolating data from the model into
1198      HTML, using <b>escape</b> to retrieve attributes will prevent
1199      <a href="http://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a> attacks.
1200    </p>
1201
1202<pre class="runnable">
1203var hacker = new Backbone.Model({
1204  name: "&lt;script&gt;alert('xss')&lt;/script&gt;"
1205});
1206
1207alert(hacker.escape('name'));
1208</pre>
1209
1210    <p id="Model-has">
1211      <b class="header">has</b><code>model.has(attribute)</code>
1212      <br />
1213      Returns <tt>true</tt> if the attribute is set to a non-null or non-undefined
1214      value.
1215    </p>
1216
1217<pre>
1218if (note.has("title")) {
1219  ...
1220}
1221</pre>
1222
1223    <p id="Model-unset">
1224      <b class="header">unset</b><code>model.unset(attribute, [options])</code>
1225      <br />
1226      Remove an attribute by deleting it from the internal attributes hash.
1227      Fires a <tt>"change"</tt> event unless <tt>silent</tt> is passed as an option.
1228    </p>
1229
1230    <p id="Model-clear">
1231      <b class="header">clear</b><code>model.clear([options])</code>
1232      <br />
1233      Removes all attributes from the model, including the <tt>id</tt> attribute. Fires a <tt>"change"</tt> event unless
1234      <tt>silent</tt> is passed as an option.
1235    </p>
1236
1237    <p id="Model-id">
1238      <b class="header">id</b><code>model.id</code>
1239      <br />
1240      A special property of models, the <b>id</b> is an arbitrary string
1241      (integer id or UUID). If you set the <b>id</b> in the
1242      attributes hash, it will be copied onto the model as a direct property.
1243      Models can be retrieved by id from collections, and the id is used to generate
1244      model URLs by default.
1245    </p>
1246
1247    <p id="Model-idAttribute">
1248      <b class="header">idAttribute</b><code>model.idAttribute</code>
1249      <br />
1250      A model's unique identifier is stored under the <tt>id</tt> attribute.
1251      If you're directly communicating with a backend (CouchDB, MongoDB) that uses
1252      a different unique key, you may set a Model's <tt>idAttribute</tt> to
1253      transparently map from that key to <tt>id</tt>.
1254
1255<pre class="runnable">
1256var Meal = Backbone.Model.extend({
1257  idAttribute: "_id"
1258});
1259
1260var cake = new Meal({ _id: 1, name: "Cake" });
1261alert("Cake id: " + cake.id);
1262</pre>
1263    </p>
1264
1265    <p id="Model-cid">
1266      <b class="header">cid</b><code>model.cid</code>
1267      <br />
1268      A special property of models, the <b>cid</b> or client id is a unique identifier
1269      automatically assigned to all models when they're first created. Client ids
1270      are handy when the model has not yet been saved to the server, and does not
1271      yet have its eventual true <b>id</b>, but already needs to be visible in the UI.
1272    </p>
1273
1274    <p id="Model-attributes">
1275      <b class="header">attributes</b><code>model.attributes</code>
1276      <br />
1277      The <b>attributes</b> property is the internal hash containing the model's
1278      state &mdash; usually (but not necessarily) a form of the JSON object
1279      representing the model data on the server. It's often a straightforward
1280      serialization of a row from the database, but it could also be client-side
1281      computed state.
1282    </p>
1283
1284    <p>
1285      Please use <a href="#Model-set">set</a> to update the <b>attributes</b>
1286      instead of modifying them directly. If you'd like to retrieve and munge a
1287      copy of the model's attributes, use <tt>_.clone(model.attributes)</tt>
1288      instead.
1289    </p>
1290
1291    <p class="warning">
1292      Due to the fact that <a href="#Events">Events</a> accepts space separated
1293      lists of events, attribute names should not include spaces.
1294    </p>
1295
1296    <p id="Model-changed">
1297      <b class="header">changed</b><code>model.changed</code>
1298      <br />
1299      The <b>changed</b> property is the internal hash containing all the attributes
1300      that have changed since its last <a href="#Model-set">set</a>.
1301      Please do not update <b>changed</b> directly since its state is internally maintained
1302      by <a href="#Model-set">set</a>.  A copy of <b>changed</b> can be acquired from
1303      <a href="#Model-changedAttributes">changedAttributes</a>.
1304    </p>
1305
1306    <p id="Model-defaults">
1307      <b class="header">defaults</b><code>model.defaults or model.defaults()</code>
1308      <br />
1309      The <b>defaults</b> hash (or function) can be used to specify the default
1310      attributes for your model. When creating an instance of the model,
1311      any unspecified attributes will be set to their default value.
1312    </p>
1313
1314<pre class="runnable">
1315var Meal = Backbone.Model.extend({
1316  defaults: {
1317    "appetizer":  "caesar salad",
1318    "entree":     "ravioli",
1319    "dessert":    "cheesecake"
1320  }
1321});
1322
1323alert("Dessert will be " + (new Meal).get('dessert'));
1324</pre>
1325
1326    <p class="warning">
1327      Remember that in JavaScript, objects are passed by reference, so if you
1328      include an object as a default value, it will be shared among all instances.
1329      Instead, define <b>defaults</b> as a function.
1330    </p>
1331
1332    <p id="Model-toJSON">
1333      <b class="header">toJSON</b><code>model.toJSON([options])</code>
1334      <br />
1335      Return a shallow copy of the model's <a href="#Model-attributes">attributes</a>
1336      for JSON stringification.  This can be used for persistence,
1337      serialization, or for augmentation before being sent to the server. The
1338      name of this method is a bit confusing, as it doesn't actually return a
1339      JSON string &mdash; but I'm afraid that it's the way that the
1340      <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON_behavior">JavaScript API for <b>JSON.stringify</b></a>
1341      works.
1342    </p>
1343
1344<pre class="runnable">
1345var artist = new Backbone.Model({
1346  firstName: "Wassily",
1347  lastName: "Kandinsky"
1348});
1349
1350artist.set({birthday: "December 16, 1866"});
1351
1352alert(JSON.stringify(artist));
1353</pre>
1354
1355    <p id="Model-sync">
1356      <b class="header">sync</b><code>model.sync(method, model, [options])</code>
1357      <br />
1358      Uses <a href="#Sync">Backbone.sync</a> to persist the state of a model to
1359      the server.  Can be overridden for custom behavior.
1360    </p>
1361
1362    <p id="Model-fetch">
1363      <b class="header">fetch</b><code>model.fetch([options])</code>
1364      <br />
1365      Merges the model's state with attributes fetched from the server by
1366      delegating to <a href="#Sync">Backbone.sync</a>. Returns a
1367      <a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a>.
1368      Useful if the model has never
1369      been populated with data, or if you'd like to ensure that you have the
1370      latest server state. Triggers a <tt>"change"</tt> event if the
1371      server's state differs from the current attributes. <tt>fetch</tt> accepts
1372      <tt>success</tt> and <tt>error</tt> callbacks in the options hash, which
1373      are both passed <tt>(model, response, options)</tt> as arguments.
1374    </p>
1375
1376<pre>
1377// Poll every 10 seconds to keep the channel model up-to-date.
1378setInterval(function() {
1379  channel.fetch();
1380}, 10000);
1381</pre>
1382
1383    <p id="Model-save">
1384      <b class="header">save</b><code>model.save([attributes], [options])</code>
1385      <br />
1386      Save a model to your database (or alternative persistence layer),
1387      by delegating to <a href="#Sync">Backbone.sync</a>.  Returns a
1388      <a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a> if
1389      validation is successful and <tt>false</tt> otherwise. The <b>attributes</b>
1390      hash (as in <a href="#Model-set">set</a>) should contain the attributes
1391      you'd like to change &mdash; keys that aren't mentioned won't be altered &mdash; but,
1392      a <i>complete representation</i> of the resource will be sent to the server.
1393      As with <tt>set</tt>, you may pass individual keys and values instead of a hash.
1394      If the model has a <a href="#Model-validate">validate</a>
1395      method, and validation fails, the model will not be saved. If the model
1396      <a href="#Model-isNew">isNew</a>, the save will be a <tt>"create"</tt>
1397      (HTTP <tt>POST</tt>), if the model already
1398      exists on the server, the save will be an <tt>"update"</tt> (HTTP <tt>PUT</tt>).
1399    </p>
1400
1401    <p>
1402      If instead, you'd only like the <i>changed</i> attributes to be sent to the
1403      server, call <tt>model.save(attrs, {patch: true})</tt>. You'll get an HTTP
1404      <tt>PATCH</tt> request to the server with just the passed-in attributes.
1405    </p>
1406
1407    <p>
1408      Calling <tt>save</tt> with new attributes will cause a <tt>"change"</tt>
1409      event immediately, a <tt>"request"</tt> event as the Ajax request begins to
1410      go to the server, and a <tt>"sync"</tt> event after the server has acknowledged
1411      the successful change. Pass <tt>{wait: true}</tt> if you'd like to wait
1412      for the server before setting the new attributes on the model.
1413    </p>
1414
1415    <p>
1416      In the following example, notice how our overridden version
1417      of <tt>Backbone.sync</tt> receives a <tt>"create"</tt> request
1418      the first time the model is saved and an <tt>"update"</tt>
1419      request the second time.
1420    </p>
1421
1422<pre class="runnable">
1423Backbone.sync = function(method, model) {
1424  alert(method + ": " + JSON.stringify(model));
1425  model.set('id', 1);
1426};
1427
1428var book = new Backbone.Model({
1429  title: "The Rough Riders",
1430  author: "Theodore Roosevelt"
1431});
1432
1433book.save();
1434
1435book.save({author: "Teddy"});
1436</pre>
1437
1438    <p>
1439      <b>save</b> accepts <tt>success</tt> and <tt>error</tt> callbacks in the
1440      options hash, which will be passed the arguments <tt>(model, response, options)</tt>.
1441      If a server-side validation fails, return a non-<tt>200</tt>
1442      HTTP response code, along with an error response in text or JSON.
1443    </p>
1444
1445<pre>
1446book.save("author", "F.D.R.", {error: function(){ ... }});
1447</pre>
1448
1449    <p id="Model-destroy">
1450      <b class="header">destroy</b><code>model.destroy([options])</code>
1451      <br />
1452      Destroys the model on the server by delegating an HTTP <tt>DELETE</tt>
1453      request to <a href="#Sync">Backbone.sync</a>. Returns a
1454      <a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a> object, or
1455      <tt>false</tt> if the model <a href="#Model-isNew">isNew</a>. Accepts
1456      <tt>success</tt> and <tt>error</tt> callbacks in the options hash, which
1457      will be passed <tt>(model, response, options)</tt>.
1458      Triggers a <tt>"destroy"</tt> event on the model, which will bubble up
1459      through any collections that contain it, a <tt>"request"</tt> event as it
1460      begins the Ajax request to the server, and a <tt>"sync"</tt> event, after
1461      the server has successfully acknowledged the model's deletion. Pass
1462      <tt>{wait: true}</tt> if you'd like to wait for the server to respond
1463      before removing the model from the collection.
1464    </p>
1465
1466<pre>
1467book.destroy({success: function(model, response) {
1468  ...
1469}});
1470</pre>
1471
1472    <p id="Model-Underscore-Methods">
1473      <b class="header">Underscore Methods (9)</b>
1474      <br />
1475      Backbone proxies to <b>Underscore.js</b> to provide 9 object functions
1476      on <b>Backbone.Model</b>. They aren't all documented here, but
1477      you can take a look at the Underscore documentation for the full details&hellip;
1478    </p>
1479
1480    <ul class="small">
1481      <li><a href="http://underscorejs.org/#keys">keys</a></li>
1482      <li><a href="http://underscorejs.org/#values">values</a></li>
1483      <li><a href="http://underscorejs.org/#pairs">pairs</a></li>
1484      <li><a href="http://underscorejs.org/#invert">invert</a></li>
1485      <li><a href="http://underscorejs.org/#pick">pick</a></li>
1486      <li><a href="http://underscorejs.org/#omit">omit</a></li>
1487      <li><a href="http://underscorejs.org/#matches">matches</a></li>
1488      <li><a href="http://underscorejs.org/#chain">chain</a></li>
1489      <li><a href="http://underscorejs.org/#isEmpty">isEmpty</a></li>
1490    </ul>
1491
1492<pre>
1493user.pick('first_name', 'last_name', 'email');
1494
1495chapters.keys().join(', ');
1496</pre>
1497
1498    <p id="Model-validate">
1499      <b class="header">validate</b><code>model.validate(attributes, options)</code>
1500      <br />
1501      This method is left undefined and you're encouraged to override it with
1502      any custom validation logic you have that can be performed in JavaScript.
1503      By default <tt>save</tt> checks <b>validate</b> before
1504      setting any attributes but you may also tell <tt>set</tt> to validate
1505      the new attributes by passing <tt>{validate: true}</tt> as an option.
1506      <br />
1507      The <b>validate</b> method receives the model attributes as well as any
1508      options passed to <tt>set</tt> or <tt>save</tt>.
1509      If the attributes are valid, don't return anything from <b>validate</b>;
1510      if they are invalid return an error of your choosing. It
1511      can be as simple as a string error message to be displayed, or a complete
1512      error object that describes the error programmatically. If <b>validate</b>
1513      returns an error, <tt>save</tt> will not continue, and the
1514      model attributes will not be modified on the server.
1515      Failed validations trigger an <tt>"invalid"</tt> event, and set the
1516      <tt>validationError</tt> property on the model with the value returned by
1517      this method.
1518    </p>
1519
1520<pre class="runnable">
1521var Chapter = Backbone.Model.extend({
1522  validate: function(attrs, options) {
1523    if (attrs.end &lt; attrs.start) {
1524      return "can't end before it starts";
1525    }
1526  }
1527});
1528
1529var one = new Chapter({
1530  title : "Chapter One: The Beginning"
1531});
1532
1533one.on("invalid", function(model, error) {
1534  alert(model.get("title") + " " + error);
1535});
1536
1537one.save({
1538  start: 15,
1539  end:   10
1540});
1541</pre>
1542
1543    <p>
1544      <tt>"invalid"</tt> events are useful for providing coarse-grained error
1545      messages at the model or collection level.
1546    </p>
1547
1548    <p id="Model-validationError">
1549      <b class="header">validationError</b><code>model.validationError</code>
1550      <br />
1551      The value returned by <a href="#Model-validate">validate</a> during the last failed validation.
1552    </p>
1553
1554    <p id="Model-isValid">
1555      <b class="header">isValid</b><code>model.isValid()</code>
1556      <br />
1557      Run <a href="#Model-validate">validate</a> to check the model state.
1558    </p>
1559
1560<pre class="runnable">
1561var Chapter = Backbone.Model.extend({
1562  validate: function(attrs, options) {
1563    if (attrs.end &lt; attrs.start) {
1564      return "can't end before it starts";
1565    }
1566  }
1567});
1568
1569var one = new Chapter({
1570  title : "Chapter One: The Beginning"
1571});
1572
1573one.set({
1574  start: 15,
1575  end:   10
1576});
1577
1578if (!one.isValid()) {
1579  alert(one.get("title") + " " + one.validationError);
1580}
1581</pre>
1582
1583    <p id="Model-url">
1584      <b class="header">url</b><code>model.url()</code>
1585      <br />
1586      Returns the relative URL where the model's resource would be located on
1587      the server. If your models are located somewhere else, override this method
1588      with the correct logic. Generates URLs of the form: <tt>"[collection.url]/[id]"</tt>
1589      by default, but you may override by specifying an explicit <tt>urlRoot</tt>
1590      if the model's collection shouldn't be taken into account.
1591    </p>
1592
1593    <p>
1594      Delegates to <a href="#Collection-url">Collection#url</a> to generate the
1595      URL, so make sure that you have it defined, or a <a href="#Model-urlRoot">urlRoot</a>
1596      property, if all models of this class share a common root URL.
1597      A model with an id of <tt>101</tt>, stored in a
1598      <a href="#Collection">Backbone.Collection</a> with a <tt>url</tt> of <tt>"/documents/7/notes"</tt>,
1599      would have this URL: <tt>"/documents/7/notes/101"</tt>
1600    </p>
1601
1602    <p id="Model-urlRoot">
1603      <b class="header">urlRoot</b><code>model.urlRoot or model.urlRoot()</code>
1604      <br />
1605      Specify a <tt>urlRoot</tt> if you're using a model <i>outside</i> of a collection,
1606      to enable the default <a href="#Model-url">url</a> function to generate
1607      URLs based on the model id. <tt>"[urlRoot]/id"</tt><br />
1608      Normally, you won't need to define this.
1609      Note that <tt>urlRoot</tt> may also be a function.
1610    </p>
1611
1612<pre class="runnable">
1613var Book = Backbone.Model.extend({urlRoot : '/books'});
1614
1615var solaris = new Book({id: "1083-lem-solaris"});
1616
1617alert(solaris.url());
1618</pre>
1619
1620    <p id="Model-parse">
1621      <b class="header">parse</b><code>model.parse(response, options)</code>
1622      <br />
1623      <b>parse</b> is called whenever a model's data is returned by the
1624      server, in <a href="#Model-fetch">fetch</a>, and <a href="#Model-save">save</a>.
1625      The function is passed the raw <tt>response</tt> object, and should return
1626      the attributes hash to be <a href="#Model-set">set</a> on the model. The
1627      default implementation is a no-op, simply passing through the JSON response.
1628      Override this if you need to work with a preexisting API, or better namespace
1629      your responses.
1630    </p>
1631
1632    <p>
1633      If you're working with a Rails backend that has a version prior to 3.1,
1634      you'll notice that its default <tt>to_json</tt> implementation includes
1635      a model's attributes under a namespace. To disable this behavior for
1636      seamless Backbone integration, set:
1637    </p>
1638
1639<pre>
1640ActiveRecord::Base.include_root_in_json = false
1641</pre>
1642
1643    <p id="Model-clone">
1644      <b class="header">clone</b><code>model.clone()</code>
1645      <br />
1646      Returns a new instance of the model with identical attributes.
1647    </p>
1648
1649    <p id="Model-isNew">
1650      <b class="header">isNew</b><code>model.isNew()</code>
1651      <br />
1652      Has this model been saved to the server yet? If the model does not yet have
1653      an <tt>id</tt>, it is considered to be new.
1654    </p>
1655
1656    <p id="Model-hasChanged">
1657      <b class="header">hasChanged</b><code>model.hasChanged([attribute])</code>
1658      <br />
1659      Has the model changed since its last <a href="#Model-set">set</a>? If an <b>attribute</b>
1660      is passed, returns <tt>true</tt> if that specific attribute has changed.
1661    </p>
1662
1663    <p class="warning">
1664      Note that this method, and the following change-related ones,
1665      are only useful during the course of a <tt>"change"</tt> event.
1666    </p>
1667
1668<pre>
1669book.on("change", function() {
1670  if (book.hasChanged("title")) {
1671    ...
1672  }
1673});
1674</pre>
1675
1676    <p id="Model-changedAttributes">
1677      <b class="header">changedAttributes</b><code>model.changedAttributes([attributes])</code>
1678      <br />
1679      Retrieve a hash of only the model's attributes that have changed since the last
1680      <a href="#Model-set">set</a>, or <tt>false</tt> if there are none. Optionally, an external
1681      <b>attributes</b> hash can be passed in, returning the attributes in that
1682      hash which differ from the model. This can be used to figure out which
1683      portions of a view should be updated, or what calls
1684      need to be made to sync the changes to the server.
1685    </p>
1686
1687    <p id="Model-previous">
1688      <b class="header">previous</b><code>model.previous(attribute)</code>
1689      <br />
1690      During a <tt>"change"</tt> event, this method can be used to get the
1691      previous value of a changed attribute.
1692    </p>
1693
1694<pre class="runnable">
1695var bill = new Backbone.Model({
1696  name: "Bill Smith"
1697});
1698
1699bill.on("change:name", function(model, name) {
1700  alert("Changed name from " + bill.previous("name") + " to " + name);
1701});
1702
1703bill.set({name : "Bill Jones"});
1704</pre>
1705
1706    <p id="Model-previousAttributes">
1707      <b class="header">previousAttributes</b><code>model.previousAttributes()</code>
1708      <br />
1709      Return a copy of the model's previous attributes. Useful for getting a
1710      diff between versions of a model, or getting back to a valid state after
1711      an error occurs.
1712    </p>
1713
1714    <h2 id="Collection">Backbone.Collection</h2>
1715
1716    <p>
1717      Collections are ordered sets of models. You can bind <tt>"change"</tt> events
1718      to be notified when any model in the collection has been modified,
1719      listen for <tt>"add"</tt> and <tt>"remove"</tt> events, <tt>fetch</tt>
1720      the collection from the server, and use a full suite of
1721      <a href="#Collection-Underscore-Methods">Underscore.js methods</a>.
1722    </p>
1723
1724    <p>
1725      Any event that is triggered on a model in a collection will also be
1726      triggered on the collection directly, for convenience.
1727      This allows you to listen for changes to specific attributes in any
1728      model in a collection, for example:
1729      <tt>documents.on("change:selected", ...)</tt>
1730    </p>
1731
1732    <p id="Collection-extend">
1733      <b class="header">extend</b><code>Backbone.Collection.extend(properties, [classProperties])</code>
1734      <br />
1735      To create a <b>Collection</b> class of your own, extend <b>Backbone.Collection</b>,
1736      providing instance <b>properties</b>, as well as optional <b>classProperties</b> to be attached
1737      directly to the collection's constructor function.
1738    </p>
1739
1740    <p id="Collection-model">
1741      <b class="header">model</b><code>collection.model</code>
1742      <br />
1743      Override this property to specify the model class that the collection
1744      contains. If defined, you can pass raw attributes objects (and arrays) to
1745      <a href="#Collection-add">add</a>, <a href="#Collection-create">create</a>,
1746      and <a href="#Collection-reset">reset</a>, and the attributes will be
1747      converted into a model of the proper type.
1748    </p>
1749
1750<pre>
1751var Library = Backbone.Collection.extend({
1752  model: Book
1753});
1754</pre>
1755
1756    <p>
1757      A collection can also contain polymorphic models by overriding this property
1758      with a constructor that returns a model.
1759    </p>
1760
1761<pre>
1762var Library = Backbone.Collection.extend({
1763
1764  model: function(attrs, options) {
1765    if (condition) {
1766      return new PublicDocument(attrs, options);
1767    } else {
1768      return new PrivateDocument(attrs, options);
1769    }
1770  }
1771
1772});
1773</pre>
1774
1775    <p id="Collection-constructor">
1776      <b class="header">constructor / initialize</b><code>new Backbone.Collection([models], [options])</code>
1777      <br />
1778      When creating a Collection, you may choose to pass in the initial array
1779      of <b>models</b>.  The collection's <a href="#Collection-comparator">comparator</a>
1780      may be included as an option. Passing <tt>false</tt> as the
1781      comparator option will prevent sorting. If you define an
1782      <b>initialize</b> function, it will be invoked when the collection is
1783      created. There are a couple of options that, if provided, are attached to
1784      the collection directly: <tt>model</tt> and <tt>comparator</tt>.<br />
1785      Pass <tt>null</tt> for <tt>models</tt> to create an empty Collection with <tt>options</tt>.
1786    </p>
1787
1788<pre>
1789var tabs = new TabSet([tab1, tab2, tab3]);
1790var spaces = new Backbone.Collection([], {
1791  model: Space
1792});
1793</pre>
1794
1795    <p id="Collection-models">
1796      <b class="header">models</b><code>collection.models</code>
1797      <br />
1798      Raw access to the JavaScript array of models inside of the collection. Usually you'll
1799      want to use <tt>get</tt>, <tt>at</tt>, or the <b>Underscore methods</b>
1800      to access model objects, but occasionally a direct reference to the array
1801      is desired.
1802    </p>
1803
1804    <p id="Collection-toJSON">
1805      <b class="header">toJSON</b><code>collection.toJSON([options])</code>
1806      <br />
1807      Return an array containing the attributes hash of each model
1808      (via <a href="#Model-toJSON">toJSON</a>) in the
1809      collection. This can be used to serialize and persist the
1810      collection as a whole. The name of this method is a bit confusing, because
1811      it conforms to
1812      <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#toJSON_behavior">JavaScript's JSON API</a>.
1813    </p>
1814
1815<pre class="runnable">
1816var collection = new Backbone.Collection([
1817  {name: "Tim", age: 5},
1818  {name: "Ida", age: 26},
1819  {name: "Rob", age: 55}
1820]);
1821
1822alert(JSON.stringify(collection));
1823</pre>
1824
1825    <p id="Collection-sync">
1826      <b class="header">sync</b><code>collection.sync(method, collection, [options])</code>
1827      <br />
1828      Uses <a href="#Sync">Backbone.sync</a> to persist the state of a
1829      collection to the server.  Can be overridden for custom behavior.
1830    </p>
1831
1832    <p id="Collection-Underscore-Methods">
1833      <b class="header">Underscore Methods (46)</b>
1834      <br />
1835      Backbone proxies to <b>Underscore.js</b> to provide 46 iteration functions
1836      on <b>Backbone.Collection</b>. They aren't all documented here, but
1837      you can take a look at the Underscore documentation for the full details&hellip;
1838    </p>
1839
1840    <ul class="small">
1841      <li><a href="http://underscorejs.org/#each">forEach (each)</a></li>
1842      <li><a href="http://underscorejs.org/#map">map (collect)</a></li>
1843      <li><a href="http://underscorejs.org/#reduce">reduce (foldl, inject)</a></li>
1844      <li><a href="http://underscorejs.org/#reduceRight">reduceRight (foldr)</a></li>
1845      <li><a href="http://underscorejs.org/#find">find (detect)</a></li>
1846      <li><a href="http://underscorejs.org/#filter">filter (select)</a></li>
1847      <li><a href="http://underscorejs.org/#reject">reject</a></li>
1848      <li><a href="http://underscorejs.org/#every">every (all)</a></li>
1849      <li><a href="http://underscorejs.org/#some">some (any)</a></li>
1850      <li><a href="http://underscorejs.org/#contains">contains (include)</a></li>
1851      <li><a href="http://underscorejs.org/#invoke">invoke</a></li>
1852      <li><a href="http://underscorejs.org/#max">max</a></li>
1853      <li><a href="http://underscorejs.org/#min">min</a></li>
1854      <li><a href="http://underscorejs.org/#sortBy">sortBy</a></li>
1855      <li><a href="http://underscorejs.org/#groupBy">groupBy</a></li>
1856      <li><a href="http://underscorejs.org/#shuffle">shuffle</a></li>
1857      <li><a href="http://underscorejs.org/#toArray">toArray</a></li>
1858      <li><a href="http://underscorejs.org/#size">size</a></li>
1859      <li><a href="http://underscorejs.org/#first">first (head, take)</a></li>
1860      <li><a href="http://underscorejs.org/#initial">initial</a></li>
1861      <li><a href="http://underscorejs.org/#rest">rest (tail, drop)</a></li>
1862      <li><a href="http://underscorejs.org/#last">last</a></li>
1863      <li><a href="http://underscorejs.org/#without">without</a></li>
1864      <li><a href="http://underscorejs.org/#indexOf">indexOf</a></li>
1865      <li><a href="http://underscorejs.org/#lastIndexOf">lastIndexOf</a></li>
1866      <li><a href="http://underscorejs.org/#isEmpty">isEmpty</a></li>
1867      <li><a href="http://underscorejs.org/#chain">chain</a></li>
1868      <li><a href="http://underscorejs.org/#difference">difference</a></li>
1869      <li><a href="http://underscorejs.org/#sample">sample</a></li>
1870      <li><a href="http://underscorejs.org/#partition">partition</a></li>
1871      <li><a href="http://underscorejs.org/#countBy">countBy</a></li>
1872      <li><a href="http://underscorejs.org/#indexBy">indexBy</a></li>
1873    </ul>
1874
1875<pre>
1876books.each(function(book) {
1877  book.publish();
1878});
1879
1880var titles = books.map(function(book) {
1881  return book.get("title");
1882});
1883
1884var publishedBooks = books.filter(function(book) {
1885  return book.get("published") === true;
1886});
1887
1888var alphabetical = books.sortBy(function(book) {
1889  return book.author.get("name").toLowerCase();
1890});
1891</pre>
1892
1893    <p id="Collection-add">
1894      <b class="header">add</b><code>collection.add(models, [options])</code>
1895      <br />
1896      Add a model (or an array of models) to the collection, firing an <tt>"add"</tt>
1897      event for each model, and an <tt>"update"</tt> event afterwards. If a <a href="#Collection-model">model</a> property is defined, you may also pass
1898      raw attributes objects, and have them be vivified as instances of the model.
1899      Returns the added (or preexisting, if duplicate) models.
1900      Pass <tt>{at: index}</tt> to splice the model into the collection at the
1901      specified <tt>index</tt>. If you're adding models to the collection that are
1902      <i>already</i> in the collection, they'll be ignored, unless you pass
1903      <tt>{merge: true}</tt>, in which case their attributes will be merged
1904      into the corresponding models, firing any appropriate <tt>"change"</tt> events.
1905    </p>
1906
1907<pre class="runnable">
1908var ships = new Backbone.Collection;
1909
1910ships.on("add", function(ship) {
1911  alert("Ahoy " + ship.get("name") + "!");
1912});
1913
1914ships.add([
1915  {name: "Flying Dutchman"},
1916  {name: "Black Pearl"}
1917]);
1918</pre>
1919
1920    <p class="warning">
1921      Note that adding the same model (a model with the same <tt>id</tt>) to
1922      a collection more than once <br /> is a no-op.
1923    </p>
1924
1925    <p id="Collection-remove">
1926      <b class="header">remove</b><code>collection.remove(models, [options])</code>
1927      <br />
1928      Remove a model (or an array of models) from the collection, and return
1929      them. Each model can be a Model instance, an <tt>id</tt> string or a JS
1930      object, any value acceptable as the <tt>id</tt> argument of
1931      <a href="#Collection-get"><tt>collection.get</tt></a>.
1932      Fires a <tt>"remove"</tt> event for each model, and a single
1933      <tt>"update"</tt> event afterwards.
1934      The model's index before removal is available to listeners as
1935      <tt>options.index</tt>.
1936    </p>
1937
1938    <p id="Collection-reset">
1939      <b class="header">reset</b><code>collection.reset([models], [options])</code>
1940      <br />
1941      Adding and removing models one at a time is all well and good, but sometimes
1942      you have so many models to change that you'd rather just update the collection
1943      in bulk. Use <b>reset</b> to replace a collection with a new list
1944      of models (or attribute hashes), triggering a single <tt>"reset"</tt> event
1945      at the end. Returns the newly-set models.
1946      For convenience, within a <tt>"reset"</tt> event, the list of any
1947      previous models is available as <tt>options.previousModels</tt>.<br />
1948      Pass <tt>null</tt> for <tt>models</tt> to empty your Collection with <tt>options</tt>.
1949    </p>
1950
1951    <p>
1952      Here's an example using <b>reset</b> to bootstrap a collection during initial page load,
1953      in a Rails application:
1954    </p>
1955
1956<pre>
1957&lt;script&gt;
1958  var accounts = new Backbone.Collection;
1959  accounts.reset(&lt;%= @accounts.to_json %&gt;);
1960&lt;/script&gt;
1961</pre>
1962
1963    <p>
1964      Calling <tt>collection.reset()</tt> without passing any models as arguments
1965      will empty the entire collection.
1966    </p>
1967
1968    <p id="Collection-set">
1969      <b class="header">set</b><code>collection.set(models, [options])</code>
1970      <br />
1971      The <b>set</b> method performs a "smart" update of the collection
1972      with the passed list of models. If a model in the list isn't yet in the
1973      collection it will be added; if the model is already in the collection
1974      its attributes will be merged; and if the collection contains any models that
1975      <i>aren't</i> present in the list, they'll be removed. All of the appropriate
1976      <tt>"add"</tt>, <tt>"remove"</tt>, and <tt>"change"</tt> events are fired
1977      as this happens. Returns the touched models in the collection.
1978      If you'd like to customize the behavior, you can disable
1979      it with options: <tt>{add: false}</tt>, <tt>{remove: false}</tt>, or <tt>{merge: false}</tt>.
1980    </p>
1981
1982<pre>
1983var vanHalen = new Backbone.Collection([eddie, alex, stone, roth]);
1984
1985vanHalen.set([eddie, alex, stone, hagar]);
1986
1987// Fires a "remove" event for roth, and an "add" event for "hagar".
1988// Updates any of stone, alex, and eddie's attributes that may have
1989// changed over the years.
1990</pre>
1991
1992    <p id="Collection-get">
1993      <b class="header">get</b><code>collection.get(id)</code>
1994      <br />
1995      Get a model from a collection, specified by an <a href="#Model-id">id</a>,
1996      a <a href="#Model-cid">cid</a>, or by passing in a <b>model</b>.
1997    </p>
1998
1999<pre>
2000var book = library.get(110);
2001</pre>
2002
2003    <p id="Collection-at">
2004      <b class="header">at</b><code>collection.at(index)</code>
2005      <br />
2006      Get a model from a collection, specified by index. Useful if your collection
2007      is sorted, and if your collection isn't sorted, <b>at</b> will still
2008      retrieve models in insertion order.
2009    </p>
2010
2011    <p id="Collection-push">
2012      <b class="header">push</b><code>collection.push(model, [options])</code>
2013      <br />
2014      Add a model at the end of a collection. Takes the same options as
2015      <a href="#Collection-add">add</a>.
2016    </p>
2017
2018    <p id="Collection-pop">
2019      <b class="header">pop</b><code>collection.pop([options])</code>
2020      <br />
2021      Remove and return the last model from a collection. Takes the same options as
2022      <a href="#Collection-remove">remove</a>.
2023    </p>
2024
2025    <p id="Collection-unshift">
2026      <b class="header">unshift</b><code>collection.unshift(model, [options])</code>
2027      <br />
2028      Add a model at the beginning of a collection. Takes the same options as
2029      <a href="#Collection-add">add</a>.
2030    </p>
2031
2032    <p id="Collection-shift">
2033      <b class="header">shift</b><code>collection.shift([options])</code>
2034      <br />
2035      Remove and return the first model from a collection. Takes the same options as
2036      <a href="#Collection-remove">remove</a>.
2037    </p>
2038
2039    <p id="Collection-slice">
2040      <b class="header">slice</b><code>collection.slice(begin, end)</code>
2041      <br />
2042      Return a shallow copy of this collection's models, using the same options as
2043      native
2044      <a href="https://developer.mozilla.org/JavaScript/Reference/Global_Objects/Array/slice">Array#slice</a>.
2045    </p>
2046
2047    <p id="Collection-length">
2048      <b class="header">length</b><code>collection.length</code>
2049      <br />
2050      Like an array, a Collection maintains a <tt>length</tt> property, counting
2051      the number of models it contains.
2052    </p>
2053
2054    <p id="Collection-comparator">
2055      <b class="header">comparator</b><code>collection.comparator</code>
2056      <br />
2057      By default there is no <b>comparator</b> for a collection.
2058      If you define a comparator, it will be used to maintain
2059      the collection in sorted order. This means that as models are added,
2060      they are inserted at the correct index in <tt>collection.models</tt>.
2061      A comparator can be defined as a
2062      <a href="http://underscorejs.org/#sortBy">sortBy</a>
2063      (pass a function that takes a single argument),
2064      as a
2065      <a href="https://developer.mozilla.org/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
2066      (pass a comparator function that expects two arguments),
2067      or as a string indicating the attribute to sort by.
2068    </p>
2069
2070    <p>
2071      "sortBy" comparator functions take a model and return a numeric or string
2072      value by which the model should be ordered relative to others.
2073      "sort" comparator functions take two models, and return <tt>-1</tt> if
2074      the first model should come before the second, <tt>0</tt> if they are of
2075      the same rank and <tt>1</tt> if the first model should come after.
2076      <i>Note that Backbone depends on the arity of your comparator function to
2077      determine between the two styles, so be careful if your comparator function
2078      is bound.</i>
2079    </p>
2080
2081    <p>
2082      Note how even though all of the chapters in this example are added backwards,
2083      they come out in the proper order:
2084    </p>
2085
2086<pre class="runnable">
2087var Chapter  = Backbone.Model;
2088var chapters = new Backbone.Collection;
2089
2090chapters.comparator = 'page';
2091
2092chapters.add(new Chapter({page: 9, title: "The End"}));
2093chapters.add(new Chapter({page: 5, title: "The Middle"}));
2094chapters.add(new Chapter({page: 1, title: "The Beginning"}));
2095
2096alert(chapters.pluck('title'));
2097</pre>
2098
2099    <p class="warning">
2100      Collections with a comparator will not automatically re-sort if you
2101      later change model attributes, so you may wish to call
2102      <tt>sort</tt> after changing model attributes that would affect the order.
2103    </p>
2104
2105    <p id="Collection-sort">
2106      <b class="header">sort</b><code>collection.sort([options])</code>
2107      <br />
2108      Force a collection to re-sort itself. You don't need to call this under
2109      normal circumstances, as a collection with a <a href="#Collection-comparator">comparator</a>
2110      will sort itself whenever a model is added. To disable sorting when adding
2111      a model, pass <tt>{sort: false}</tt> to <tt>add</tt>. Calling <b>sort</b>
2112      triggers a <tt>"sort"</tt> event on the collection.
2113    </p>
2114
2115    <p id="Collection-pluck">
2116      <b class="header">pluck</b><code>collection.pluck(attribute)</code>
2117      <br />
2118      Pluck an attribute from each model in the collection. Equivalent to calling
2119      <tt>map</tt> and returning a single attribute from the iterator.
2120    </p>
2121
2122<pre class="runnable">
2123var stooges = new Backbone.Collection([
2124  {name: "Curly"},
2125  {name: "Larry"},
2126  {name: "Moe"}
2127]);
2128
2129var names = stooges.pluck("name");
2130
2131alert(JSON.stringify(names));
2132</pre>
2133
2134    <p id="Collection-where">
2135      <b class="header">where</b><code>collection.where(attributes)</code>
2136      <br />
2137      Return an array of all the models in a collection that match the
2138      passed <b>attributes</b>. Useful for simple cases of <tt>filter</tt>.
2139    </p>
2140
2141<pre class="runnable">
2142var friends = new Backbone.Collection([
2143  {name: "Athos",      job: "Musketeer"},
2144  {name: "Porthos",    job: "Musketeer"},
2145  {name: "Aramis",     job: "Musketeer"},
2146  {name: "d'Artagnan", job: "Guard"},
2147]);
2148
2149var musketeers = friends.where({job: "Musketeer"});
2150
2151alert(musketeers.length);
2152</pre>
2153
2154    <p id="Collection-findWhere">
2155      <b class="header">findWhere</b><code>collection.findWhere(attributes)</code>
2156      <br />
2157      Just like <a href="#Collection-where">where</a>, but directly returns only
2158      the first model in the collection that matches the passed <b>attributes</b>.
2159    </p>
2160
2161    <p id="Collection-url">
2162      <b class="header">url</b><code>collection.url or collection.url()</code>
2163      <br />
2164      Set the <b>url</b> property (or function) on a collection to reference
2165      its location on the server. Models within the collection will use <b>url</b>
2166      to construct URLs of their own.
2167    </p>
2168
2169<pre>
2170var Notes = Backbone.Collection.extend({
2171  url: '/notes'
2172});
2173
2174// Or, something more sophisticated:
2175
2176var Notes = Backbone.Collection.extend({
2177  url: function() {
2178    return this.document.url() + '/notes';
2179  }
2180});
2181</pre>
2182
2183    <p id="Collection-parse">
2184      <b class="header">parse</b><code>collection.parse(response, options)</code>
2185      <br />
2186      <b>parse</b> is called by Backbone whenever a collection's models are
2187      returned by the server, in <a href="#Collection-fetch">fetch</a>.
2188      The function is passed the raw <tt>response</tt> object, and should return
2189      the array of model attributes to be <a href="#Collection-add">added</a>
2190      to the collection. The default implementation is a no-op, simply passing
2191      through the JSON response. Override this if you need to work with a
2192      preexisting API, or better namespace your responses.
2193    </p>
2194
2195<pre>
2196var Tweets = Backbone.Collection.extend({
2197  // The Twitter Search API returns tweets under "results".
2198  parse: function(response) {
2199    return response.results;
2200  }
2201});
2202</pre>
2203
2204    <p id="Collection-clone">
2205      <b class="header">clone</b><code>collection.clone()</code>
2206      <br />
2207      Returns a new instance of the collection with an identical list of models.
2208    </p>
2209
2210    <p id="Collection-fetch">
2211      <b class="header">fetch</b><code>collection.fetch([options])</code>
2212      <br />
2213      Fetch the default set of models for this collection from the server,
2214      <a href="#Collection-set">setting</a> them on the collection when they arrive.
2215      The <b>options</b> hash takes <tt>success</tt> and <tt>error</tt> callbacks
2216      which will both be passed <tt>(collection, response, options)</tt> as arguments.
2217      When the model data returns from the server, it uses <a href="#Collection-set">set</a>
2218      to (intelligently) merge the fetched models, unless you pass <tt>{reset: true}</tt>,
2219      in which case the collection will be (efficiently) <a href="#Collection-reset">reset</a>.
2220      Delegates to <a href="#Sync">Backbone.sync</a>
2221      under the covers for custom persistence strategies and returns a
2222      <a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a>.
2223      The server handler for <b>fetch</b> requests should return a JSON array of
2224      models.
2225    </p>
2226
2227<pre class="runnable">
2228Backbone.sync = function(method, model) {
2229  alert(method + ": " + model.url);
2230};
2231
2232var accounts = new Backbone.Collection;
2233accounts.url = '/accounts';
2234
2235accounts.fetch();
2236</pre>
2237
2238    <p>
2239      The behavior of <b>fetch</b> can be customized by using the available
2240      <a href="#Collection-set">set</a> options. For example, to fetch a
2241      collection, getting an <tt>"add"</tt> event for every new model, and
2242      a <tt>"change"</tt> event for every changed existing model, without
2243      removing anything: <tt>collection.fetch({remove: false})</tt>
2244    </p>
2245
2246    <p>
2247      <b>jQuery.ajax</b> options can also be passed directly as <b>fetch</b> options,
2248      so to fetch a specific page of a paginated collection:
2249      <tt>Documents.fetch({data: {page: 3}})</tt>
2250    </p>
2251
2252    <p>
2253      Note that <b>fetch</b> should not be used to populate collections on
2254      page load &mdash; all models needed at load time should already be
2255      <a href="#FAQ-bootstrap">bootstrapped</a> in to place. <b>fetch</b> is
2256      intended for lazily-loading models for interfaces that are not needed
2257      immediately: for example, documents with collections of notes that may be
2258      toggled open and closed.
2259    </p>
2260
2261    <p id="Collection-create">
2262      <b class="header">create</b><code>collection.create(attributes, [options])</code>
2263      <br />
2264      Convenience to create a new instance of a model within a collection.
2265      Equivalent to instantiating a model with a hash of attributes,
2266      saving the model to the server, and adding the model to the set after being
2267      successfully created. Returns the new model. If client-side validation
2268      failed, the model will be unsaved, with validation errors.
2269      In order for this to work, you should set the
2270      <a href="#Collection-model">model</a> property of the collection.
2271      The <b>create</b> method can accept either an attributes hash or an
2272      existing, unsaved model object.
2273    </p>
2274
2275    <p>
2276      Creating a model will cause an immediate <tt>"add"</tt> event to be
2277      triggered on the collection, a <tt>"request"</tt> event as the new model is
2278      sent to the server, as well as a <tt>"sync"</tt> event, once the
2279      server has responded with the successful creation of the model. Pass <tt>{wait: true}</tt>
2280      if you'd like to wait for the server before adding the new model to the collection.
2281    </p>
2282
2283<pre>
2284var Library = Backbone.Collection.extend({
2285  model: Book
2286});
2287
2288var nypl = new Library;
2289
2290var othello = nypl.create({
2291  title: "Othello",
2292  author: "William Shakespeare"
2293});
2294</pre>
2295
2296    <h2 id="Router">Backbone.Router</h2>
2297
2298    <p>
2299      Web applications often provide linkable, bookmarkable, shareable URLs for
2300      important locations in the app. Until recently, hash fragments
2301      (<tt>#page</tt>) were used to provide these permalinks, but with the
2302      arrival of the History API, it's now possible to use standard URLs (<tt>/page</tt>).
2303      <b>Backbone.Router</b> provides methods for routing client-side pages, and
2304      connecting them to actions and events. For browsers which don't yet support
2305      the History API, the Router handles graceful fallback and transparent
2306      translation to the fragment version of the URL.
2307    </p>
2308
2309    <p>
2310      During page load, after your application has finished creating all of its routers,
2311      be sure to call <tt>Backbone.history.start()</tt> or
2312      <tt>Backbone.history.start({pushState: true})</tt> to route the initial URL.
2313    </p>
2314
2315    <p id="Router-extend">
2316      <b class="header">extend</b><code>Backbone.Router.extend(properties, [classProperties])</code>
2317      <br />
2318      Get started by creating a custom router class. Define actions that are
2319      triggered when certain URL fragments are
2320      matched, and provide a <a href="#Router-routes">routes</a> hash
2321      that pairs routes to actions. Note that you'll want to avoid using a
2322      leading slash in your route definitions:
2323    </p>
2324
2325<pre>
2326var Workspace = Backbone.Router.extend({
2327
2328  routes: {
2329    "help":                 "help",    // #help
2330    "search/:query":        "search",  // #search/kiwis
2331    "search/:query/p:page": "search"   // #search/kiwis/p7
2332  },
2333
2334  help: function() {
2335    ...
2336  },
2337
2338  search: function(query, page) {
2339    ...
2340  }
2341
2342});
2343</pre>
2344
2345    <p id="Router-routes">
2346      <b class="header">routes</b><code>router.routes</code>
2347      <br />
2348      The routes hash maps URLs with parameters to functions on your router
2349      (or just direct function definitions, if you prefer),
2350      similar to the <a href="#View">View</a>'s <a href="#View-delegateEvents">events hash</a>.
2351      Routes can contain parameter parts, <tt>:param</tt>, which match a single URL
2352      component between slashes; and splat parts <tt>*splat</tt>, which can match
2353      any number of URL components. Part of a route can be made optional by
2354      surrounding it in parentheses <tt>(/:optional)</tt>.
2355    </p>
2356
2357    <p>
2358      For example, a route of <tt>"search/:query/p:page"</tt> will match
2359      a fragment of <tt>#search/obama/p2</tt>, passing <tt>"obama"</tt>
2360      and <tt>"2"</tt> to the action.
2361    </p>
2362
2363    <p>
2364      A route of <tt>"file/*path"</tt> will match
2365      <tt>#file/nested/folder/file.txt</tt>, passing
2366      <tt>"nested/folder/file.txt"</tt> to the action.
2367    </p>
2368
2369    <p>
2370      A route of <tt>"docs/:section(/:subsection)"</tt> will match
2371      <tt>#docs/faq</tt> and <tt>#docs/faq/installing</tt>, passing
2372      <tt>"faq"</tt> to the action in the first case, and passing <tt>"faq"</tt>
2373      and <tt>"installing"</tt> to the action in the second.
2374    </p>
2375
2376    <p>
2377      Trailing slashes are treated as part of the URL, and (correctly) treated
2378      as a unique route when accessed. <tt>docs</tt> and <tt>docs/</tt> will fire
2379      different callbacks. If you can't avoid generating both types of URLs, you
2380      can define a <tt>"docs(/)"</tt> matcher to capture both cases.
2381    </p>
2382
2383    <p>
2384      When the visitor presses the back button, or enters a URL, and a particular
2385      route is matched, the name of the action will be fired as an
2386      <a href="#Events">event</a>, so that other objects can listen to the router,
2387      and be notified. In the following example, visiting <tt>#help/uploading</tt>
2388      will fire a <tt>route:help</tt> event from the router.
2389    </p>
2390
2391<pre>
2392routes: {
2393  "help/:page":         "help",
2394  "download/*path":     "download",
2395  "folder/:name":       "openFolder",
2396  "folder/:name-:mode": "openFolder"
2397}
2398</pre>
2399
2400<pre>
2401router.on("route:help", function(page) {
2402  ...
2403});
2404</pre>
2405
2406    <p id="Router-constructor">
2407      <b class="header">constructor / initialize</b><code>new Router([options])</code>
2408      <br />
2409      When creating a new router, you may pass its
2410      <a href="#Router-routes">routes</a> hash directly as an option, if you
2411      choose. All <tt>options</tt> will also be passed to your <tt>initialize</tt>
2412      function, if defined.
2413    </p>
2414
2415    <p id="Router-route">
2416      <b class="header">route</b><code>router.route(route, name, [callback])</code>
2417      <br />
2418      Manually create a route for the router, The <tt>route</tt> argument may
2419      be a <a href="#Router-routes">routing string</a> or regular expression.
2420      Each matching capture from the route or regular expression will be passed as
2421      an argument to the callback. The <tt>name</tt> argument will be triggered as
2422      a <tt>"route:name"</tt> event whenever the route is matched.  If the
2423      <tt>callback</tt> argument is omitted <tt>router[name]</tt> will be used
2424      instead. Routes added later may override previously declared routes.
2425    </p>
2426
2427<pre>
2428initialize: function(options) {
2429
2430  // Matches #page/10, passing "10"
2431  this.route("page/:number", "page", function(number){ ... });
2432
2433  // Matches /117-a/b/c/open, passing "117-a/b/c" to this.open
2434  this.route(/^(.*?)\/open$/, "open");
2435
2436},
2437
2438open: function(id) { ... }
2439</pre>
2440
2441    <p id="Router-navigate">
2442      <b class="header">navigate</b><code>router.navigate(fragment, [options])</code>
2443      <br />
2444      Whenever you reach a point in your application that you'd like to save
2445      as a URL, call <b>navigate</b> in order to update the URL.
2446      If you also wish to call the route function, set the <b>trigger</b>
2447      option to <tt>true</tt>.
2448      To update the URL without creating an entry in the browser's history,
2449      set the <b>replace</b> option to <tt>true</tt>.
2450    </p>
2451
2452<pre>
2453openPage: function(pageNumber) {
2454  this.document.pages.at(pageNumber).open();
2455  this.navigate("page/" + pageNumber);
2456}
2457
2458# Or ...
2459
2460app.navigate("help/troubleshooting", {trigger: true});
2461
2462# Or ...
2463
2464app.navigate("help/troubleshooting", {trigger: true, replace: true});
2465</pre>
2466
2467    <p id="Router-execute">
2468      <b class="header">execute</b><code>router.execute(callback, args, name)</code>
2469      <br />
2470      This method is called internally within the router, whenever a route
2471      matches and its corresponding <b>callback</b> is about to be executed.
2472      Return <b>false</b> from execute to cancel the current transition.
2473      Override it to perform custom parsing or wrapping of your routes, for
2474      example, to parse query strings before handing them to your route
2475      callback, like so:
2476    </p>
2477
2478<pre>
2479var Router = Backbone.Router.extend({
2480  execute: function(callback, args, name) {
2481    if (!loggedIn) {
2482      goToLogin();
2483      return false;
2484    }
2485    args.push(parseQueryString(args.pop()));
2486    if (callback) callback.apply(this, args);
2487  }
2488});
2489</pre>
2490
2491    <h2 id="History">Backbone.history</h2>
2492
2493    <p>
2494      <b>History</b> serves as a global router (per frame) to handle <tt>hashchange</tt>
2495      events or <tt>pushState</tt>, match the appropriate route, and trigger callbacks.
2496      You shouldn't ever have to create one of these yourself since <tt>Backbone.history</tt>
2497      already contains one.
2498    </p>
2499
2500    <p>
2501      <b>pushState</b> support exists on a purely opt-in basis in Backbone.
2502      Older browsers that don't support <tt>pushState</tt> will continue to use
2503      hash-based URL fragments, and if a hash URL is visited by a
2504      <tt>pushState</tt>-capable browser, it will be transparently upgraded to
2505      the true URL. Note that using real URLs requires your web server to be
2506      able to correctly render those pages, so back-end changes are required
2507      as well. For example, if you have a route of <tt>/documents/100</tt>,
2508      your web server must be able to serve that page, if the browser
2509      visits that URL directly. For full search-engine crawlability, it's best to
2510      have the server generate the complete HTML for the page ... but if it's a web
2511      application, just rendering the same content you would have for the root URL,
2512      and filling in the rest with Backbone Views and JavaScript works fine.
2513    </p>
2514
2515    <p id="History-start">
2516      <b class="header">start</b><code>Backbone.history.start([options])</code>
2517      <br />
2518      When all of your <a href="#Router">Routers</a> have been created,
2519      and all of the routes are set up properly, call <tt>Backbone.history.start()</tt>
2520      to begin monitoring <tt>hashchange</tt> events, and dispatching routes.
2521      Subsequent calls to <tt>Backbone.history.start()</tt> will throw an error,
2522      and <tt>Backbone.History.started</tt> is a boolean value indicating whether
2523      it has already been called.
2524    </p>
2525
2526    <p>
2527      To indicate that you'd like to use HTML5 <tt>pushState</tt> support in
2528      your application, use <tt>Backbone.history.start({pushState: true})</tt>.
2529      If you'd like to use <tt>pushState</tt>, but have browsers that don't support
2530      it natively use full page refreshes instead, you can add
2531      <tt>{hashChange: false}</tt> to the options.
2532    </p>
2533
2534    <p>
2535      If your application is not being served from the root url <tt>/</tt> of your
2536      domain, be sure to tell History where the root really is, as an option:
2537      <tt>Backbone.history.start({pushState: true, root: "/public/search/"})</tt>
2538    </p>
2539
2540    <p>
2541      When called, if a route succeeds with a match for the current URL,
2542      <tt>Backbone.history.start()</tt> returns <tt>true</tt>. If no defined
2543      route matches the current URL, it returns <tt>false</tt>.
2544    </p>
2545
2546    <p>
2547      If the server has already rendered the entire page, and you don't want the
2548      initial route to trigger when starting History, pass <tt>silent: true</tt>.
2549    </p>
2550
2551    <p>
2552      Because hash-based history in Internet Explorer relies on an
2553      <tt>&lt;iframe&gt;</tt>, be sure to call <tt>start()</tt> only after the DOM
2554      is ready.
2555    </p>
2556
2557<pre>
2558$(function(){
2559  new WorkspaceRouter();
2560  new HelpPaneRouter();
2561  Backbone.history.start({pushState: true});
2562});
2563</pre>
2564
2565    <h2 id="Sync">Backbone.sync</h2>
2566
2567    <p>
2568      <b>Backbone.sync</b> is the function that Backbone calls every time it
2569      attempts to read or save a model to the server. By default, it uses
2570      <tt>jQuery.ajax</tt> to make a RESTful JSON request and returns a
2571      <a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a>. You can override
2572      it in order to use a different persistence strategy, such as WebSockets,
2573      XML transport, or Local Storage.
2574    </p>
2575
2576    <p>
2577      The method signature of <b>Backbone.sync</b> is <tt>sync(method, model, [options])</tt>
2578    </p>
2579
2580    <ul>
2581      <li><b>method</b> – the CRUD method (<tt>"create"</tt>, <tt>"read"</tt>, <tt>"update"</tt>, or <tt>"delete"</tt>)</li>
2582      <li><b>model</b> – the model to be saved (or collection to be read)</li>
2583      <li><b>options</b> – success and error callbacks, and all other jQuery request options</li>
2584    </ul>
2585
2586    <p>
2587      With the default implementation, when <b>Backbone.sync</b> sends up a request to save
2588      a model, its attributes will be passed, serialized as JSON, and sent in the HTTP body
2589      with content-type <tt>application/json</tt>. When returning a JSON response,
2590      send down the attributes of the  model that have been changed by the server, and need
2591      to be updated on the client. When responding to a <tt>"read"</tt> request from a collection
2592      (<a href="#Collection-fetch">Collection#fetch</a>), send down an array
2593      of model attribute objects.
2594    </p>
2595
2596    <p>
2597      Whenever a model or collection begins a <b>sync</b> with the server, a
2598      <tt>"request"</tt> event is emitted. If the request completes successfully
2599      you'll get a <tt>"sync"</tt> event, and an <tt>"error"</tt> event if not.
2600    </p>
2601
2602    <p>
2603      The <b>sync</b> function may be overridden globally as <tt>Backbone.sync</tt>,
2604      or at a finer-grained level, by adding a <tt>sync</tt> function to a Backbone
2605      collection or to an individual model.
2606    </p>
2607
2608    <p>
2609      The default <b>sync</b> handler maps CRUD to REST like so:
2610    </p>
2611
2612    <ul>
2613      <li><b>create &rarr; POST &nbsp; </b><tt>/collection</tt></li>
2614      <li><b>read &rarr; GET &nbsp; </b><tt>/collection[/id]</tt></li>
2615      <li><b>update &rarr; PUT &nbsp; </b><tt>/collection/id</tt></li>
2616      <li><b>patch &rarr; PATCH &nbsp; </b><tt>/collection/id</tt></li>
2617      <li><b>delete &rarr; DELETE &nbsp; </b><tt>/collection/id</tt></li>
2618    </ul>
2619
2620    <p>
2621      As an example, a Rails 4 handler responding to an <tt>"update"</tt> call from
2622      <tt>Backbone</tt> might look like this:
2623    </p>
2624
2625<pre>
2626def update
2627  account = Account.find params[:id]
2628  account.update_attributes params.require(:account).permit(:name, :otherparam)
2629  render :json => account
2630end
2631</pre>
2632
2633    <p>
2634      One more tip for integrating Rails versions prior to 3.1 is to disable
2635      the default namespacing for <tt>to_json</tt> calls on models by setting
2636      <tt>ActiveRecord::Base.include_root_in_json = false</tt>
2637    </p>
2638
2639    <p id="Sync-ajax">
2640      <b class="header">ajax</b><code>Backbone.ajax = function(request) { ... };</code>
2641      <br />
2642      If you want to use a custom AJAX function, or your endpoint doesn't support
2643      the <a href="http://api.jquery.com/jQuery.ajax/">jQuery.ajax</a> API
2644      and you need to tweak things, you can do so by setting <tt>Backbone.ajax</tt>.
2645    </p>
2646
2647    <p id="Sync-emulateHTTP">
2648      <b class="header">emulateHTTP</b><code>Backbone.emulateHTTP = true</code>
2649      <br />
2650      If you want to work with a legacy web server that doesn't support Backbone's
2651      default REST/HTTP approach, you may choose to turn on <tt>Backbone.emulateHTTP</tt>.
2652      Setting this option will fake <tt>PUT</tt>, <tt>PATCH</tt> and <tt>DELETE</tt> requests with
2653      a HTTP <tt>POST</tt>, setting the <tt>X-HTTP-Method-Override</tt> header
2654      with the true method. If <tt>emulateJSON</tt> is also on, the true method
2655      will be passed as an additional <tt>_method</tt> parameter.
2656    </p>
2657
2658<pre>
2659Backbone.emulateHTTP = true;
2660
2661model.save();  // POST to "/collection/id", with "_method=PUT" + header.
2662</pre>
2663
2664    <p id="Sync-emulateJSON">
2665      <b class="header">emulateJSON</b><code>Backbone.emulateJSON = true</code>
2666      <br />
2667      If you're working with a legacy web server that can't handle requests
2668      encoded as <tt>application/json</tt>, setting <tt>Backbone.emulateJSON = true;</tt>
2669      will cause the JSON to be serialized under a <tt>model</tt> parameter, and
2670      the request to be made with a <tt>application/x-www-form-urlencoded</tt>
2671      MIME type, as if from an HTML form.
2672    </p>
2673
2674    <h2 id="View">Backbone.View</h2>
2675
2676    <p>
2677      Backbone views are almost more convention than they are code &mdash; they
2678      don't determine anything about your HTML or CSS for you, and can be used
2679      with any JavaScript templating library.
2680      The general idea is to organize your interface into logical views,
2681      backed by models, each of which can be updated independently when the
2682      model changes, without having to redraw the page. Instead of digging into
2683      a JSON object, looking up an element in the DOM, and updating the HTML by hand,
2684      you can bind your view's <tt>render</tt> function to the model's <tt>"change"</tt>
2685      event &mdash; and now everywhere that
2686      model data is displayed in the UI, it is always immediately up to date.
2687    </p>
2688
2689    <p id="View-extend">
2690      <b class="header">extend</b><code>Backbone.View.extend(properties, [classProperties])</code>
2691      <br />
2692      Get started with views by creating a custom view class. You'll want to
2693      override the <a href="#View-render">render</a> function, specify your
2694      declarative <a href="#View-delegateEvents">events</a>, and perhaps the
2695      <tt>tagName</tt>, <tt>className</tt>, or <tt>id</tt> of the View's root
2696      element.
2697    </p>
2698
2699<pre>
2700var DocumentRow = Backbone.View.extend({
2701
2702  tagName: "li",
2703
2704  className: "document-row",
2705
2706  events: {
2707    "click .icon":          "open",
2708    "click .button.edit":   "openEditDialog",
2709    "click .button.delete": "destroy"
2710  },
2711
2712  initialize: function() {
2713    this.listenTo(this.model, "change", this.render);
2714  },
2715
2716  render: function() {
2717    ...
2718  }
2719
2720});
2721</pre>
2722
2723    <p>
2724      Properties like <tt>tagName</tt>, <tt>id</tt>, <tt>className</tt>,
2725      <tt>el</tt>, and <tt>events</tt> may also be defined as a function, if
2726      you want to wait to define them until runtime.
2727    </p>
2728
2729    <p id="View-constructor">
2730      <b class="header">constructor / initialize</b><code>new View([options])</code>
2731      <br />
2732      There are several special
2733      options that, if passed, will be attached directly to the view:
2734      <tt>model</tt>, <tt>collection</tt>,
2735      <tt>el</tt>, <tt>id</tt>, <tt>className</tt>, <tt>tagName</tt>, <tt>attributes</tt> and <tt>events</tt>.
2736      If the view defines an <b>initialize</b> function, it will be called when
2737      the view is first created. If you'd like to create a view that references
2738      an element <i>already</i> in the DOM, pass in the element as an option:
2739      <tt>new View({el: existingElement})</tt>
2740    </p>
2741
2742<pre>
2743var doc = documents.first();
2744
2745new DocumentRow({
2746  model: doc,
2747  id: "document-row-" + doc.id
2748});
2749</pre>
2750
2751    <p id="View-el">
2752      <b class="header">el</b><code>view.el</code>
2753      <br />
2754      All views have a DOM element at all times (the <b>el</b> property),
2755      whether they've already been inserted into the page or not. In this
2756      fashion, views can be rendered at any time, and inserted into the DOM all
2757      at once, in order to get high-performance UI rendering with as few
2758      reflows and repaints as possible.
2759    </p>
2760
2761    <p>
2762      <tt>this.el</tt> can be resolved from a DOM selector string or an Element;
2763      otherwise it will be created from the view's <tt>tagName</tt>, <tt>className</tt>,
2764      <tt>id</tt> and <a href="#View-attributes"><tt>attributes</tt></a> properties.
2765      If none are set, <tt>this.el</tt> is an empty <tt>div</tt>, which is often just
2766      fine. An <b>el</b> reference may also be passed in to the view's constructor.
2767    </p>
2768
2769<pre class="runnable">
2770var ItemView = Backbone.View.extend({
2771  tagName: 'li'
2772});
2773
2774var BodyView = Backbone.View.extend({
2775  el: 'body'
2776});
2777
2778var item = new ItemView();
2779var body = new BodyView();
2780
2781alert(item.el + ' ' + body.el);
2782</pre>
2783
2784    <p id="View-$el">
2785      <b class="header">$el</b><code>view.$el</code>
2786      <br />
2787      A cached jQuery object for the view's element. A handy
2788      reference instead of re-wrapping the DOM element all the time.
2789    </p>
2790
2791<pre>
2792view.$el.show();
2793
2794listView.$el.append(itemView.el);
2795</pre>
2796
2797    <p id="View-setElement">
2798      <b class="header">setElement</b><code>view.setElement(element)</code>
2799      <br />
2800      If you'd like to apply a Backbone view to a different DOM element, use
2801      <b>setElement</b>, which will also create the cached <tt>$el</tt> reference
2802      and move the view's delegated events from the old element to the new one.
2803    </p>
2804
2805    <p id="View-attributes">
2806      <b class="header">attributes</b><code>view.attributes</code>
2807      <br />
2808      A hash of attributes that will be set as HTML DOM element attributes on the
2809      view's <tt>el</tt> (id, class, data-properties, etc.), or a function that
2810      returns such a hash.
2811    </p>
2812
2813    <p id="View-dollar">
2814      <b class="header">$ (jQuery)</b><code>view.$(selector)</code>
2815      <br />
2816      If jQuery is included on the page, each view has a
2817      <b>$</b> function that runs queries scoped within the view's element. If you use this
2818      scoped jQuery function, you don't have to use model ids as part of your query
2819      to pull out specific elements in a list, and can rely much more on HTML class
2820      attributes. It's equivalent to running: <tt>view.$el.find(selector)</tt>
2821    </p>
2822
2823<pre>
2824ui.Chapter = Backbone.View.extend({
2825  serialize : function() {
2826    return {
2827      title: this.$(".title").text(),
2828      start: this.$(".start-page").text(),
2829      end:   this.$(".end-page").text()
2830    };
2831  }
2832});
2833</pre>
2834
2835    <p id="View-template">
2836      <b class="header">template</b><code>view.template([data])</code>
2837      <br />
2838      While templating for a view isn't a function provided directly by Backbone,
2839      it's often a nice convention to define a <b>template</b> function on your
2840      views. In this way, when rendering your view, you have convenient access to
2841      instance data.
2842      For example, using Underscore templates:
2843    </p>
2844
2845<pre>
2846var LibraryView = Backbone.View.extend({
2847  template: _.template(...)
2848});
2849</pre>
2850
2851    <p id="View-render">
2852      <b class="header">render</b><code>view.render()</code>
2853      <br />
2854      The default implementation of <b>render</b> is a no-op. Override this
2855      function with your code that renders the view template from model data,
2856      and updates <tt>this.el</tt> with the new HTML. A good
2857      convention is to <tt>return this</tt> at the end of <b>render</b> to
2858      enable chained calls.
2859    </p>
2860
2861<pre>
2862var Bookmark = Backbone.View.extend({
2863  template: _.template(...),
2864  render: function() {
2865    this.$el.html(this.template(this.model.attributes));
2866    return this;
2867  }
2868});
2869</pre>
2870
2871    <p>
2872      Backbone is agnostic with respect to your preferred method of HTML templating.
2873      Your <b>render</b> function could even munge together an HTML string, or use
2874      <tt>document.createElement</tt> to generate a DOM tree. However, we suggest
2875      choosing a nice JavaScript templating library.
2876      <a href="http://github.com/janl/mustache.js">Mustache.js</a>,
2877      <a href="http://github.com/creationix/haml-js">Haml-js</a>, and
2878      <a href="http://github.com/sstephenson/eco">Eco</a> are all fine alternatives.
2879      Because <a href="http://underscorejs.org/">Underscore.js</a> is already on the page,
2880      <a href="http://underscorejs.org/#template">_.template</a>
2881      is available, and is an excellent choice if you prefer simple
2882      interpolated-JavaScript style templates.
2883    </p>
2884
2885    <p>
2886      Whatever templating strategy you end up with, it's nice if you <i>never</i>
2887      have to put strings of HTML in your JavaScript. At DocumentCloud, we
2888      use <a href="http://documentcloud.github.com/jammit/">Jammit</a> in order
2889      to package up JavaScript templates stored in <tt>/app/views</tt> as part
2890      of our main <tt>core.js</tt> asset package.
2891    </p>
2892
2893    <p id="View-remove">
2894      <b class="header">remove</b><code>view.remove()</code>
2895      <br />
2896      Removes a view from the DOM, and calls
2897      <a href="#Events-stopListening">stopListening</a> to remove any bound
2898      events that the view has <a href="#Events-listenTo">listenTo</a>'d.
2899    </p>
2900
2901    <p id="View-delegateEvents">
2902      <b class="header">delegateEvents</b><code>delegateEvents([events])</code>
2903      <br />
2904      Uses jQuery's <tt>on</tt> function to provide declarative callbacks
2905      for DOM events within a view.
2906      If an <b>events</b> hash is not passed directly, uses <tt>this.events</tt>
2907      as the source. Events are written in the format <tt>{"event selector": "callback"}</tt>.
2908      The callback may be either the name of a method on the view, or a direct
2909      function body.
2910      Omitting the <tt>selector</tt> causes the event to be bound to the view's
2911      root element (<tt>this.el</tt>). By default, <tt>delegateEvents</tt> is called
2912      within the View's constructor for you, so if you have a simple <tt>events</tt>
2913      hash, all of your DOM events will always already be connected, and you will
2914      never have to call this function yourself.
2915    </p>
2916
2917    <p>
2918      The <tt>events</tt> property may also be defined as a function that returns
2919      an <b>events</b> hash, to make it easier to programmatically define your
2920      events, as well as inherit them from parent views.
2921    </p>
2922
2923    <p>
2924      Using <b>delegateEvents</b> provides a number of advantages over manually
2925      using jQuery to bind events to child elements during <a href="#View-render">render</a>. All attached
2926      callbacks are bound to the view before being handed off to jQuery, so when
2927      the callbacks are invoked, <tt>this</tt> continues to refer to the view object. When
2928      <b>delegateEvents</b> is run again, perhaps with a different <tt>events</tt>
2929      hash, all callbacks are removed and delegated afresh &mdash; useful for
2930      views which need to behave differently when in different modes.
2931    </p>
2932
2933    <p>
2934      A view that displays a document in a search result might look
2935      something like this:
2936    </p>
2937
2938<pre>
2939var DocumentView = Backbone.View.extend({
2940
2941  events: {
2942    "dblclick"                : "open",
2943    "click .icon.doc"         : "select",
2944    "contextmenu .icon.doc"   : "showMenu",
2945    "click .show_notes"       : "toggleNotes",
2946    "click .title .lock"      : "editAccessLevel",
2947    "mouseover .title .date"  : "showTooltip"
2948  },
2949
2950  render: function() {
2951    this.$el.html(this.template(this.model.attributes));
2952    return this;
2953  },
2954
2955  open: function() {
2956    window.open(this.model.get("viewer_url"));
2957  },
2958
2959  select: function() {
2960    this.model.set({selected: true});
2961  },
2962
2963  ...
2964
2965});
2966</pre>
2967
2968    <p id="View-undelegateEvents">
2969      <b class="header">undelegateEvents</b><code>undelegateEvents()</code>
2970      <br />
2971      Removes all of the view's delegated events. Useful if you want to disable
2972      or remove a view from the DOM temporarily.
2973    </p>
2974
2975    <h2 id="Utility">Utility</h2>
2976
2977    <p id="Utility-Backbone-noConflict">
2978      <b class="header">Backbone.noConflict</b><code>var backbone = Backbone.noConflict();</code>
2979      <br />
2980      Returns the <tt>Backbone</tt> object back to its original value. You can
2981      use the return value of <tt>Backbone.noConflict()</tt> to keep a local
2982      reference to Backbone. Useful for embedding Backbone on third-party
2983      websites, where you don't want to clobber the existing Backbone.
2984    </p>
2985
2986<pre>
2987var localBackbone = Backbone.noConflict();
2988var model = localBackbone.Model.extend(...);
2989</pre>
2990
2991    <p id="Utility-Backbone-$">
2992      <b class="header">Backbone.$</b><code>Backbone.$ = $;</code>
2993      <br />
2994      If you have multiple copies of <tt>jQuery</tt> on the page, or simply want
2995      to tell Backbone to use a particular object as its DOM / Ajax library,
2996      this is the property for you.
2997    </p>
2998
2999<pre>
3000Backbone.$ = require('jquery');
3001</pre>
3002
3003    <h2 id="faq">F.A.Q.</h2>
3004
3005    <p id="FAQ-why-backbone">
3006      <b class="header">Why use Backbone, not [other framework X]?</b>
3007      <br />
3008      If your eye hasn't already been caught by the adaptability and elan on display
3009      in the above <a href="#examples">list of examples</a>, we can get more specific:
3010      Backbone.js aims to provide the common foundation that data-rich web applications
3011      with ambitious interfaces require &mdash; while very deliberately avoiding
3012      painting you into a corner by making any decisions that you're
3013      better equipped to make yourself.
3014    </p>
3015
3016    <ul>
3017      <li>
3018        The focus is on supplying you with
3019        <a href="#Collection-Underscore-Methods">helpful methods to manipulate and
3020        query your data</a>, not on HTML widgets or reinventing the JavaScript
3021        object model.
3022      </li>
3023      <li>
3024        Backbone does not force you to use a single template engine. Views can bind
3025        to HTML constructed in
3026        <a href="http://underscorejs.org/#template">your</a>
3027        <a href="http://guides.rubyonrails.org/layouts_and_rendering.html">favorite</a>
3028        <a href="http://mustache.github.com">way</a>.
3029      </li>
3030      <li>
3031        It's smaller. There are fewer kilobytes for your browser or phone to download,
3032        and less <i>conceptual</i> surface area. You can read and understand
3033        the source in an afternoon.
3034      </li>
3035      <li>
3036        It doesn't depend on stuffing application logic into your HTML.
3037        There's no embedded JavaScript, template logic, or binding hookup code in
3038        <tt>data-</tt> or <tt>ng-</tt> attributes, and no need to invent your own HTML tags.
3039      </li>
3040      <li>
3041        <a href="#Events">Synchronous events</a> are used as the fundamental
3042        building block, not a difficult-to-reason-about run loop, or by constantly
3043        polling and traversing your data structures to hunt for changes. And if
3044        you want a specific event to be asynchronous and aggregated,
3045        <a href="http://underscorejs.org/#debounce">no problem</a>.
3046      </li>
3047      <li>
3048        Backbone scales well, from <a href="http://disqus.com">embedded widgets</a>
3049        to <a href="http://www.usatoday.com">massive apps</a>.
3050      </li>
3051      <li>
3052        Backbone is a library, not a framework, and plays well with others.
3053        You can embed Backbone widgets in Dojo apps without trouble, or use Backbone
3054        models as the data backing for D3 visualizations (to pick two entirely
3055        random examples).
3056      </li>
3057      <li>
3058        "Two-way data-binding" is avoided. While it certainly makes for a nifty
3059        demo, and works for the most basic CRUD, it doesn't tend to be terribly
3060        useful in your real-world app. Sometimes you want to update on
3061        every keypress, sometimes on blur, sometimes when the panel is closed,
3062        and sometimes when the "save" button is clicked. In almost all cases, simply
3063        serializing the form to JSON is faster and easier. All that aside, if your
3064        heart is set, <a href="http://rivetsjs.com">go</a>
3065        <a href="http://nytimes.github.com/backbone.stickit/">for it</a>.
3066      </li>
3067      <li>
3068        There's no built-in performance penalty for choosing to structure your
3069        code with Backbone. And if you do want to optimize further, thin models and
3070        templates with flexible granularity make it easy to squeeze every last
3071        drop of potential performance out of, say, IE8.
3072      </li>
3073    </ul>
3074
3075    <p id="FAQ-tim-toady">
3076      <b class="header">There's More Than One Way To Do It</b>
3077      <br />
3078      It's common for folks just getting started to treat the examples listed
3079      on this page as some sort of gospel truth. In fact, Backbone.js is intended
3080      to be fairly agnostic about many common patterns in client-side code.
3081      For example...
3082    </p>
3083
3084    <p>
3085      <b>References between Models and Views</b> can be handled several ways.
3086      Some people like to have direct pointers, where views correspond 1:1 with
3087      models (<tt>model.view</tt> and <tt>view.model</tt>). Others prefer to have intermediate
3088      "controller" objects that orchestrate the creation and organization of
3089      views into a hierarchy. Others still prefer the evented approach, and always
3090      fire events instead of calling methods directly. All of these styles work well.
3091    </p>
3092
3093    <p>
3094      <b>Batch operations</b> on Models are common, but often best handled differently
3095      depending on your server-side setup. Some folks don't mind making individual
3096      Ajax requests. Others create explicit resources for RESTful batch operations:
3097      <tt>/notes/batch/destroy?ids=1,2,3,4</tt>. Others tunnel REST over JSON, with the
3098      creation of "changeset" requests:
3099    </p>
3100
3101<pre>
3102  {
3103    "create":  [array of models to create]
3104    "update":  [array of models to update]
3105    "destroy": [array of model ids to destroy]
3106  }
3107</pre>
3108
3109    <p>
3110      <b>Feel free to define your own events.</b> <a href="#Events">Backbone.Events</a>
3111      is designed so that you can mix it in to any JavaScript object or prototype.
3112      Since you can use any string as an event, it's often handy to bind
3113      and trigger your own custom events: <tt>model.on("selected:true")</tt> or
3114      <tt>model.on("editing")</tt>
3115    </p>
3116
3117    <p>
3118      <b>Render the UI</b> as you see fit. Backbone is agnostic as to whether you
3119      use <a href="http://underscorejs.org/#template">Underscore templates</a>,
3120      <a href="https://github.com/janl/mustache.js">Mustache.js</a>, direct DOM
3121      manipulation, server-side rendered snippets of HTML, or
3122      <a href="http://jqueryui.com/">jQuery UI</a> in your <tt>render</tt> function.
3123      Sometimes you'll create a view for each model ... sometimes you'll have a
3124      view that renders thousands of models at once, in a tight loop. Both can be
3125      appropriate in the same app, depending on the quantity of data involved,
3126      and the complexity of the UI.
3127    </p>
3128
3129    <p id="FAQ-nested">
3130      <b class="header">Nested Models &amp; Collections</b>
3131      <br />
3132      It's common to nest collections inside of models with Backbone. For example,
3133      consider a <tt>Mailbox</tt> model that contains many <tt>Message</tt> models.
3134      One nice pattern for handling this is have a <tt>this.messages</tt> collection
3135      for each mailbox, enabling the lazy-loading of messages, when the mailbox
3136      is first opened ... perhaps with <tt>MessageList</tt> views listening for
3137      <tt>"add"</tt> and <tt>"remove"</tt> events.
3138    </p>
3139
3140<pre>
3141var Mailbox = Backbone.Model.extend({
3142
3143  initialize: function() {
3144    this.messages = new Messages;
3145    this.messages.url = '/mailbox/' + this.id + '/messages';
3146    this.messages.on("reset", this.updateCounts);
3147  },
3148
3149  ...
3150
3151});
3152
3153var inbox = new Mailbox;
3154
3155// And then, when the Inbox is opened:
3156
3157inbox.messages.fetch({reset: true});
3158</pre>
3159
3160    <p>
3161      If you're looking for something more opinionated, there are a number of
3162      Backbone plugins that add sophisticated associations among models,
3163      <a href="https://github.com/jashkenas/backbone/wiki/Extensions%2C-Plugins%2C-Resources">available on the wiki</a>.
3164    </p>
3165
3166    <p>
3167      Backbone doesn't include direct support for nested models and collections
3168      or "has many" associations because there are a number
3169      of good patterns for modeling structured data on the client side, and
3170      <i>Backbone should provide the foundation for implementing any of them.</i>
3171      You may want to&hellip;
3172    </p>
3173
3174    <ul>
3175      <li>
3176        Mirror an SQL database's structure, or the structure of a NoSQL database.
3177      </li>
3178      <li>
3179        Use models with arrays of "foreign key" ids, and join to top level
3180        collections (a-la tables).
3181      </li>
3182      <li>
3183        For associations that are numerous, use a range of ids instead of an
3184        explicit list.
3185      </li>
3186      <li>
3187        Avoid ids, and use direct references, creating a partial object graph
3188        representing your data set.
3189      </li>
3190      <li>
3191        Lazily load joined models from the server, or lazily deserialize nested
3192        models from JSON documents.
3193      </li>
3194    </ul>
3195
3196    <p id="FAQ-bootstrap">
3197      <b class="header">Loading Bootstrapped Models</b>
3198      <br />
3199      When your app first loads, it's common to have a set of initial models that
3200      you know you're going to need, in order to render the page. Instead of
3201      firing an extra AJAX request to <a href="#Collection-fetch">fetch</a> them,
3202      a nicer pattern is to have their data already bootstrapped into the page.
3203      You can then use <a href="#Collection-reset">reset</a> to populate your
3204      collections with the initial data. At DocumentCloud, in the
3205      <a href="http://en.wikipedia.org/wiki/ERuby">ERB</a> template for the
3206      workspace, we do something along these lines:
3207    </p>
3208
3209<pre>
3210&lt;script&gt;
3211  var accounts = new Backbone.Collection;
3212  accounts.reset(&lt;%= @accounts.to_json %&gt;);
3213  var projects = new Backbone.Collection;
3214  projects.reset(&lt;%= @projects.to_json(:collaborators => true) %&gt;);
3215&lt;/script&gt;
3216</pre>
3217
3218    <p>You have to <a href="http://mathiasbynens.be/notes/etago">escape</a>
3219    <tt>&lt;/</tt> within the JSON string, to prevent javascript injection
3220    attacks.
3221
3222    <p id="FAQ-extending">
3223      <b class="header">Extending Backbone</b>
3224      <br />
3225      Many JavaScript libraries are meant to be insular and self-enclosed,
3226      where you interact with them by calling their public API, but never peek
3227      inside at the guts. Backbone.js is <i>not</i> that kind of library.
3228    </p>
3229
3230    <p>
3231      Because it serves as a foundation for your application, you're meant to
3232      extend and enhance it in the ways you see fit &mdash; the entire source
3233      code is <a href="docs/backbone.html">annotated</a> to make this easier
3234      for you. You'll find that there's very little there apart from core
3235      functions, and most of those can be overridden or augmented should you find
3236      the need. If you catch yourself adding methods to <tt>Backbone.Model.prototype</tt>,
3237      or creating your own base subclass, don't worry &mdash; that's how things are
3238      supposed to work.
3239    </p>
3240
3241    <p id="FAQ-mvc">
3242      <b class="header">How does Backbone relate to "traditional" MVC?</b>
3243      <br />
3244      Different implementations of the
3245      <a href="http://en.wikipedia.org/wiki/Model–View–Controller">Model-View-Controller</a>
3246      pattern tend to disagree about the definition of a controller. If it helps any, in
3247      Backbone, the <a href="#View">View</a> class can also be thought of as a
3248      kind of controller, dispatching events that originate from the UI, with
3249      the HTML template serving as the true view. We call it a View because it
3250      represents a logical chunk of UI, responsible for the contents of a single
3251      DOM element.
3252    </p>
3253
3254    <p>
3255      Comparing the overall structure of Backbone to a server-side MVC framework
3256      like <b>Rails</b>, the pieces line up like so:
3257    </p>
3258
3259    <ul>
3260      <li>
3261        <b>Backbone.Model</b> &ndash; Like a Rails model minus the class
3262        methods. Wraps a row of data in business logic.
3263      </li>
3264      <li>
3265        <b>Backbone.Collection</b> &ndash; A group of models on the client-side,
3266        with sorting/filtering/aggregation logic.
3267      </li>
3268      <li>
3269        <b>Backbone.Router</b> &ndash; Rails <tt>routes.rb</tt> + Rails controller
3270        actions. Maps URLs to functions.
3271      </li>
3272      <li>
3273        <b>Backbone.View</b> &ndash; A logical, re-usable piece of UI. Often,
3274        but not always, associated with a model.
3275      </li>
3276      <li>
3277        <b>Client-side Templates</b> &ndash; Rails <tt>.html.erb</tt> views,
3278        rendering a chunk of HTML.
3279      </li>
3280    </ul>
3281
3282    <p id="FAQ-this">
3283      <b class="header">Binding "this"</b>
3284      <br />
3285      Perhaps the single most common JavaScript "gotcha" is the fact that when
3286      you pass a function as a callback, its value for <tt>this</tt> is lost.
3287      When dealing with <a href="#Events">events</a> and callbacks in Backbone,
3288      you'll often find it useful to rely on <a href="#Events-listenTo">listenTo</a>
3289      or the optional <tt>context</tt> argument that many of Underscore
3290      and Backbone's methods use to specify the <tt>this</tt>
3291      that will be used when the callback is later invoked. (See
3292      <a href="http://underscorejs.org/#each">_.each</a>,
3293      <a href="http://underscorejs.org/#map">_.map</a>, and
3294      <a href="#Events-on">object.on</a>, to name a few).
3295      <a href="#View-delegateEvents">View events</a> are automatically bound to
3296      the view's context for you.
3297      You may also find it helpful to use
3298      <a href="http://underscorejs.org/#bind">_.bind</a> and
3299      <a href="http://underscorejs.org/#bindAll">_.bindAll</a>
3300      from Underscore.js.
3301    </p>
3302
3303<pre>
3304var MessageList = Backbone.View.extend({
3305
3306  initialize: function() {
3307    var messages = this.collection;
3308    messages.on("reset", this.render, this);
3309    messages.on("add", this.addMessage, this);
3310    messages.on("remove", this.removeMessage, this);
3311
3312    messsages.each(this.addMessage, 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 versions prior to 3.1 add an extra layer of wrapping
3333      around the JSON representation of models. You can disable this wrapping
3334      by setting:
3335    </p>
3336
3337<pre>
3338ActiveRecord::Base.include_root_in_json = false
3339</pre>
3340
3341    <p>
3342      ... in your configuration. Otherwise, override
3343      <a href="#Model-parse">parse</a> to pull model attributes out of the
3344      wrapper. Similarly, Backbone PUTs and POSTs direct JSON representations
3345      of models, where by default Rails expects namespaced attributes. You can
3346      have your controllers filter attributes directly from <tt>params</tt>, or
3347      you can override <a href="#Model-toJSON">toJSON</a> in Backbone to add
3348      the extra wrapping Rails expects.
3349    </p>
3350
3351    <h2 id="examples">Examples</h2>
3352
3353    <p>
3354      The list of examples that follows, while long, is not exhaustive. If you've
3355      worked on an app that uses Backbone, please add it to the
3356      <a href="https://github.com/jashkenas/backbone/wiki/Projects-and-Companies-using-Backbone">wiki page of Backbone apps</a>.
3357    </p>
3358
3359    <p id="examples-todos">
3360      <a href="http://jgn.me/">Jérôme Gravel-Niquet</a> has contributed a
3361      <a href="examples/todos/index.html">Todo List application</a>
3362      that is bundled in the repository as Backbone example. If you're wondering
3363      where to get started with Backbone in general, take a moment to
3364      <a href="docs/todos.html">read through the annotated source</a>. The app uses a
3365      <a href="http://github.com/jeromegn/Backbone.localStorage">LocalStorage adapter</a>
3366      to transparently save all of your todos within your browser, instead of
3367      sending them to a server. Jérôme also has a version hosted at
3368      <a href="http://localtodos.com/">localtodos.com</a>.
3369    </p>
3370
3371    <div style="text-align: center;">
3372      <a href="examples/todos/index.html">
3373        <img width="400" height="427" data-original="docs/images/todos.jpg" alt="Todos" class="example_retina" />
3374      </a>
3375    </div>
3376
3377    <h2 id="examples-documentcloud">DocumentCloud</h2>
3378
3379    <p>
3380      The <a href="http://www.documentcloud.org/public/#search/">DocumentCloud workspace</a>
3381      is built on Backbone.js, with <i>Documents</i>, <i>Projects</i>,
3382      <i>Notes</i>, and <i>Accounts</i> all as Backbone models and collections.
3383      If you're interested in history &mdash; both Underscore.js and Backbone.js
3384      were originally extracted from the DocumentCloud codebase, and packaged
3385      into standalone JS libraries.
3386    </p>
3387
3388    <div style="text-align: center;">
3389      <a href="http://www.documentcloud.org/public/#search/">
3390        <img width="550" height="453" data-original="docs/images/dc-workspace.jpg" alt="DocumentCloud Workspace" class="example_retina" />
3391      </a>
3392    </div>
3393
3394    <h2 id="examples-usa-today">USA Today</h2>
3395
3396    <p>
3397      <a href="http://usatoday.com">USA Today</a> takes advantage of the modularity of
3398      Backbone's data/model lifecycle &mdash; which makes it simple to create, inherit,
3399      isolate, and link application objects &mdash; to keep the codebase both manageable and efficient.
3400      The new website also makes heavy use of the Backbone Router to control the
3401      page for both pushState-capable and legacy browsers.
3402      Finally, the team took advantage of Backbone's Event module to create a
3403      PubSub API that allows third parties and analytics packages to hook into the
3404      heart of the app.
3405    </p>
3406
3407    <div style="text-align: center;">
3408      <a href="http://usatoday.com">
3409        <img width="550" height="532" data-original="docs/images/usa-today.jpg" alt="USA Today" class="example_retina" />
3410      </a>
3411    </div>
3412
3413    <h2 id="examples-rdio">Rdio</h2>
3414
3415    <p>
3416      <a href="http://rdio.com/new">New Rdio</a> was developed from the ground
3417      up with a component based framework based on Backbone.js. Every component
3418      on the screen is dynamically loaded and rendered, with data provided by the
3419      <a href="http://developer.rdio.com/">Rdio API</a>. When changes are pushed,
3420      every component can update itself without reloading the page or interrupting
3421      the user's music. All of this relies on Backbone's views and models,
3422      and all URL routing is handled by Backbone's Router. When data changes are
3423      signaled in realtime, Backbone's Events notify the interested components
3424      in the data changes. Backbone forms the core of the new, dynamic, realtime
3425      Rdio web and <i>desktop</i> applications.
3426    </p>
3427
3428    <div style="text-align: center;">
3429      <a href="http://rdio.com/new">
3430        <img width="550" height="344" data-original="docs/images/rdio.jpg" alt="Rdio" class="example_retina" />
3431      </a>
3432    </div>
3433
3434    <h2 id="examples-hulu">Hulu</h2>
3435
3436    <p>
3437      <a href="http://hulu.com">Hulu</a> used Backbone.js to build its next
3438      generation online video experience. With Backbone as a foundation, the
3439      web interface was rewritten from scratch so that all page content can
3440      be loaded dynamically with smooth transitions as you navigate.
3441      Backbone makes it easy to move through the app quickly without the
3442      reloading of scripts and embedded videos, while also offering models and
3443      collections for additional data manipulation support.
3444    </p>
3445
3446    <div style="text-align: center;">
3447      <a href="http://hulu.com">
3448        <img width="550" height="449" data-original="docs/images/hulu.jpg" alt="Hulu" class="example_retina" />
3449      </a>
3450    </div>
3451
3452    <h2 id="examples-quartz">Quartz</h2>
3453
3454    <p>
3455      <a href="http://qz.com">Quartz</a> sees itself as a digitally native news
3456      outlet for the new
3457      global economy. Because Quartz believes in the future of open,
3458      cross-platform web applications, they selected Backbone and Underscore
3459      to fetch, sort, store, and display content from a custom WordPress
3460      API. Although <a href="http://qz.com">qz.com</a> uses responsive design
3461      for phone, tablet, and
3462      desktop browsers, it also takes advantage of Backbone events and views
3463      to render device-specific templates in some cases.
3464    </p>
3465
3466    <div style="text-align: center;">
3467      <a href="http://qz.com">
3468        <img width="510" height="360" data-original="docs/images/quartz.jpg" alt="Quartz" class="example_retina" />
3469      </a>
3470    </div>
3471
3472    <h2 id="examples-earth">Earth</h2>
3473
3474    <p>
3475      <a href="http://earth.nullschool.net">Earth.nullschool.net</a> displays real-time weather
3476      conditions on an interactive animated globe, and Backbone provides the
3477      foundation upon which all of the site's components are built. Despite the
3478      presence of several other javascript libraries, Backbone's non-opinionated
3479      design made it effortless to mix-in the <a href="#Events">Events</a> functionality used for
3480      distributing state changes throughout the page. When the decision was made
3481      to switch to Backbone, large blocks of custom logic simply disappeared.
3482    </p>
3483
3484    <div style="text-align: center;">
3485      <a href="http://earth.nullschool.net">
3486        <img width="545" height="583" data-original="docs/images/earth.jpg" alt="Earth" class="example_retina" />
3487      </a>
3488    </div>
3489
3490    <h2 id="examples-vox">Vox</h2>
3491
3492    <p>
3493      Vox Media, the publisher of
3494      <a href="http://www.sbnation.com/">SB Nation</a>,
3495      <a href="http://www.theverge.com/">The Verge</a>,
3496      <a href="http://www.polygon.com/">Polygon</a>,
3497      <a href="http://www.eater.com/">Eater</a>,
3498      <a href="http://www.racked.com/">Racked</a>,
3499      <a href="http://www.curbed.com/">Curbed</a>, and
3500      <a href="http://www.vox.com/">Vox.com</a>, uses Backbone throughout
3501      <a href="http://techcrunch.com/2012/05/07/a-closer-look-at-chorus-the-next-generation-publishing-platform-that-runs-vox-media/">Chorus</a>,
3502      its home-grown publishing platform. Backbone powers the
3503      <a href="http://product.voxmedia.com/post/25113965826/introducing-syllabus-vox-medias-s3-powered-liveblog">liveblogging platform</a>
3504      and <a href="http://product.voxmedia.com/2013/11/11/5426878/using-backbone-js-for-sanity-and-stability">commenting system</a>
3505      used across all Vox Media properties; Coverage, an internal editorial coordination tool;
3506      <a href="http://www.sbnation.com/college-basketball/2014/4/7/5592112/kentucky-vs-uconn-2014-ncaa-tournament-championship-live-chat">SB Nation Live</a>,
3507      a live event coverage and chat tool; and
3508      <a href="http://www.vox.com/cards/ukraine-everything-you-need-to-know/what-is-the-ukraine-crisis">Vox Cards</a>,
3509      Vox.com's highlighter-and-index-card inspired app for providing context about the news.
3510    </p>
3511
3512    <div style="text-align: center;">
3513      <a href="http://vox.com">
3514        <img width="550" height="402" data-original="docs/images/vox.jpg" alt="Vox" class="example_retina" />
3515      </a>
3516    </div>
3517
3518    <h2 id="examples-gawker">Gawker Media</h2>
3519
3520    <p>
3521      <a href="http://kinja.com">Kinja</a> is Gawker Media's publishing platform designed
3522      to create great stories by breaking down the lines between the traditional
3523      roles of content creators and consumers. Everyone — editors, readers,
3524      marketers — have access to the same tools to engage in passionate discussion
3525      and pursue the truth of the story. Sharing, recommending, and following within the
3526      Kinja ecosystem allows for improved information discovery across all the sites.
3527    </p>
3528    <p>
3529      Kinja is the platform behind
3530      <a href="http://gawker.com/">Gawker</a>,
3531      <a href="http://gizmodo.com/">Gizmodo</a>,
3532      <a href="http://lifehacker.com/">Lifehacker</a>,
3533      <a href="http://io9.com/">io9</a> and other Gawker Media
3534      blogs. Backbone.js underlies the front-end application code that powers
3535      everything from user authentication to post authoring, commenting, and even serving
3536      ads. The JavaScript stack includes
3537      <a href="http://underscorejs.org/">Underscore.js</a> and
3538      <a href="http://jquery.com/">jQuery</a>, with some plugins,
3539      all loaded with
3540      <a href="http://requirejs.org/">RequireJS</a>. Closure templates are shared between the
3541      <a href="http://www.playframework.com/">Play! Framework</a> based Scala application and Backbone views, and the responsive layout
3542      is done with the
3543      <a href="http://foundation.zurb.com/">Foundation</a> framework using
3544      <a href="http://sass-lang.com/">SASS</a>.
3545    </p>
3546
3547    <div style="text-align: center;">
3548      <a href="http://gawker.com">
3549        <img width="558" height="473" data-original="docs/images/gawker.jpg" alt="Gawker" class="example_retina" />
3550      </a>
3551    </div>
3552
3553    <h2 id="examples-flow">Flow</h2>
3554
3555    <p>
3556      <a href="http://www.metalabdesign.com/">MetaLab</a> used Backbone.js to create
3557      <a href="http://www.getflow.com/">Flow</a>, a task management app for teams. The
3558      workspace relies on Backbone.js to construct task views, activities, accounts,
3559      folders, projects, and tags. You can see the internals under <tt>window.Flow</tt>.
3560    </p>
3561
3562    <div style="text-align: center;">
3563      <a href="http://www.getflow.com/">
3564        <img width="550" height="416" data-original="docs/images/flow.jpg" alt="Flow" class="example_retina" />
3565      </a>
3566    </div>
3567
3568    <h2 id="examples-gilt">Gilt Groupe</h2>
3569
3570    <p>
3571      <a href="http://gilt.com">Gilt Groupe</a> uses Backbone.js to build multiple
3572      applications across their family of sites.
3573      <a href="http://m.gilt.com">Gilt's mobile website</a> uses Backbone and
3574      <a href="http://zeptojs.com">Zepto.js</a> to create a blazing-fast
3575      shopping experience for users on-the-go, while
3576      <a href="http://live.gilt.com">Gilt Live</a> combines Backbone with
3577      WebSockets to display the items that customers are buying in real-time. Gilt's search
3578      functionality also uses Backbone to filter and sort products efficiently
3579      by moving those actions to the client-side.
3580    </p>
3581
3582    <div style="text-align: center;">
3583      <a href="http://www.gilt.com/">
3584        <img width="550" height="444" data-original="docs/images/gilt.jpg" alt="Gilt Groupe" class="example_retina" />
3585      </a>
3586    </div>
3587
3588    <h2 id="examples-enigma">Enigma</h2>
3589
3590    <p>
3591      <a href="http://enigma.io">Enigma</a> is a portal amassing the largest
3592      collection of public data produced by governments, universities, companies,
3593      and organizations. Enigma uses Backbone Models and Collections to represent
3594      complex data structures; and Backbone's Router gives Enigma users unique URLs for
3595      application states, allowing them to navigate quickly through the site while
3596      maintaining the ability to bookmark pages and navigate forward and backward
3597      through their session.
3598    </p>
3599
3600    <div style="text-align: center;">
3601      <a href="http://www.enigma.io/">
3602        <img width="550" height="409" data-original="docs/images/enigma.jpg" alt="Enigma" class="example_retina" />
3603      </a>
3604    </div>
3605
3606    <h2 id="examples-newsblur">NewsBlur</h2>
3607
3608    <p>
3609      <a href="http://www.newsblur.com">NewsBlur</a> is an RSS feed reader and
3610      social news network with a fast and responsive UI that feels like a
3611      native desktop app. Backbone.js was selected for
3612      <a href="http://www.ofbrooklyn.com/2012/11/13/backbonification-migrating-javascript-to-backbone/">a major rewrite and transition from spaghetti code</a>
3613      because of its powerful yet simple feature set, easy integration, and large
3614      community. If you want to poke around under the hood, NewsBlur is also entirely
3615      <a href="http://github.com/samuelclay/NewsBlur">open-source</a>.
3616    </p>
3617
3618    <div style="text-align: center;">
3619      <a href="http://newsblur.com">
3620        <img width="510" height="340" data-original="docs/images/newsblur.jpg" alt="Newsblur" class="example_retina" />
3621      </a>
3622    </div>
3623
3624    <h2 id="examples-wordpress">WordPress.com</h2>
3625
3626    <p>
3627      <a href="http://wordpress.com/">WordPress.com</a> is the software-as-a-service
3628      version of <a href="http://wordpress.org">WordPress</a>. It uses Backbone.js
3629      Models, Collections, and Views in its
3630      <a href="http://en.blog.wordpress.com/2012/05/25/notifications-refreshed/">Notifications system</a>.  Backbone.js was selected
3631      because it was easy to fit into the structure of the application, not the
3632      other way around. <a href="http://automattic.com">Automattic</a>
3633      (the company behind WordPress.com) is integrating Backbone.js into the
3634      Stats tab and other features throughout the homepage.
3635    </p>
3636
3637    <div style="text-align: center;">
3638      <a href="http://wordpress.com/">
3639        <img width="550" height="387" data-original="docs/images/wpcom-notifications.jpg" alt="WordPress.com Notifications"
3640    title="WordPress.com Notifications" class="example_retina" />
3641      </a>
3642    </div>
3643
3644    <h2 id="examples-foursquare">Foursquare</h2>
3645
3646    <p>
3647      Foursquare is a fun little startup that helps you meet up with friends,
3648      discover new places, and save money. Backbone Models are heavily used in
3649      the core JavaScript API layer and Views power many popular features like
3650      the <a href="https://foursquare.com">homepage map</a> and
3651      <a href="https://foursquare.com/seriouseats/list/the-best-doughnuts-in-ny">lists</a>.
3652    </p>
3653
3654    <div style="text-align: center;">
3655      <a href="http://foursquare.com">
3656        <img width="550" height="427" data-original="docs/images/foursquare.jpg" alt="Foursquare" class="example_retina" />
3657      </a>
3658    </div>
3659
3660    <h2 id="examples-bitbucket">Bitbucket</h2>
3661
3662    <p>
3663      <a href="http://www.bitbucket.org">Bitbucket</a> is a free source code hosting
3664      service for Git and Mercurial. Through its models and collections,
3665      Backbone.js has proved valuable in supporting Bitbucket's
3666      <a href="https://api.bitbucket.org">REST API</a>, as well as newer
3667      components such as in-line code comments and approvals for pull requests.
3668      Mustache templates provide server and client-side rendering, while a custom
3669      <a href="https://developers.google.com/closure/library/">Google Closure</a>
3670      inspired life-cycle for widgets allows Bitbucket to decorate existing DOM
3671      trees and insert new ones.
3672    </p>
3673
3674    <div style="text-align: center;">
3675      <a href="http://www.bitbucket.org">
3676        <img width="550" height="356" data-original="docs/images/bitbucket.jpg" alt="Bitbucket" class="example_retina" />
3677      </a>
3678    </div>
3679
3680    <h2 id="examples-disqus">Disqus</h2>
3681
3682    <p>
3683      <a href="http://www.disqus.com">Disqus</a> chose Backbone.js to power the
3684      latest version of their commenting widget. Backbone&rsquo;s small
3685      footprint and easy extensibility made it the right choice for Disqus&rsquo;
3686      distributed web application, which is hosted entirely inside an iframe and
3687      served on thousands of large web properties, including IGN, Wired, CNN, MLB, and more.
3688    </p>
3689
3690    <div style="text-align: center;">
3691      <a href="http://www.disqus.com">
3692        <img width="550" height="454" data-original="docs/images/disqus.jpg" alt="Disqus" class="example_retina" />
3693      </a>
3694    </div>
3695
3696    <h2 id="examples-delicious">Delicious</h2>
3697
3698    <p>
3699      <a href="https://delicious.com/">Delicious</a> is a social bookmarking
3700      platform making it easy to save, sort, and store bookmarks from across
3701      the web. Delicious uses <a href="http://chaplinjs.org">Chaplin.js</a>,
3702      Backbone.js and AppCache to build a full-featured MVC web app.
3703      The use of Backbone helped the website and
3704      <a href="http://delicious.com/tools">mobile apps</a> share a
3705      single API service, and the reuse of the model tier made it significantly
3706      easier to share code during the recent Delicious redesign.
3707    </p>
3708
3709    <div style="text-align: center;">
3710      <a href="http://www.delicious.com">
3711        <img width="510" height="321" data-original="docs/images/delicious.jpg" alt="Delicious" class="example_retina" />
3712      </a>
3713    </div>
3714
3715    <h2 id="examples-khan-academy">Khan Academy</h2>
3716
3717    <p>
3718      <a href="http://www.khanacademy.org">Khan Academy</a> is on a mission to
3719      provide a free world-class education to anyone anywhere. With thousands of
3720      videos, hundreds of JavaScript-driven exercises, and big plans for the
3721      future, Khan Academy uses Backbone to keep frontend code modular and organized.
3722      User profiles and goal setting are implemented with Backbone,
3723      <a href="http://jquery.com/">jQuery</a> and
3724      <a href="http://handlebarsjs.com/">Handlebars</a>, and most new feature
3725      work is being pushed to the client side, greatly increasing the quality of
3726      <a href="https://github.com/Khan/khan-api/">the API</a>.
3727    </p>
3728
3729    <div style="text-align: center;">
3730      <a href="http://www.khanacademy.org">
3731        <img width="550" height="454" data-original="docs/images/khan-academy.jpg" alt="Khan Academy" class="example_retina" />
3732      </a>
3733    </div>
3734
3735    <h2 id="examples-irccloud">IRCCloud</h2>
3736
3737    <p>
3738      <a href="http://irccloud.com/">IRCCloud</a>
3739      is an always-connected IRC client that you use in your
3740      browser &mdash; often leaving it open all day in a tab.
3741      The sleek web interface communicates with an
3742      Erlang backend via websockets and the
3743      <a href="https://github.com/irccloud/irccloud-tools/wiki/API-Overview">IRCCloud API</a>.
3744      It makes heavy use of Backbone.js events, models, views and routing to keep
3745      your IRC conversations flowing in real time.
3746    </p>
3747
3748    <div style="text-align: center;">
3749      <a href="http://irccloud.com/">
3750        <img width="550" height="392" data-original="docs/images/irccloud.png" alt="IRCCloud" class="example_image" />
3751      </a>
3752    </div>
3753
3754    <h2 id="examples-pitchfork">Pitchfork</h2>
3755
3756    <p>
3757      <a href="http://pitchfork.com/">Pitchfork</a> uses Backbone.js to power
3758      its site-wide audio player, <a href="http://pitchfork.com/tv/">Pitchfork.tv</a>,
3759      location routing, a write-thru page fragment cache, and more. Backbone.js
3760      (and <a href="http://underscorejs.org/">Underscore.js</a>) helps the team
3761      create clean and modular components,
3762      move very quickly, and focus on the site, not the spaghetti.
3763    </p>
3764
3765    <div style="text-align: center;">
3766      <a href="http://pitchfork.com/">
3767        <img width="550" height="428" data-original="docs/images/pitchfork.jpg" alt="Pitchfork" class="example_retina" />
3768      </a>
3769    </div>
3770
3771    <h2 id="examples-spin">Spin</h2>
3772
3773    <p>
3774      <a href="http://spin.com/">Spin</a> pulls in the
3775      <a href="http://www.spin.com/news">latest news stories</a> from
3776      their internal API onto their site using Backbone models and collections, and a
3777      custom <tt>sync</tt> method. Because the music should never stop playing,
3778      even as you click through to different "pages", Spin uses a Backbone router
3779      for navigation within the site.
3780    </p>
3781
3782    <div style="text-align: center;">
3783      <a href="http://spin.com/">
3784        <img width="550" height="543" data-original="docs/images/spin.jpg" alt="Spin" class="example_retina" />
3785      </a>
3786    </div>
3787
3788    <h2 id="examples-zocdoc">ZocDoc</h2>
3789
3790    <p>
3791      <a href="http://www.zocdoc.com">ZocDoc</a> helps patients
3792      find local, in-network doctors and dentists, see their real-time
3793      availability, and instantly book appointments.
3794      On the public side, the webapp uses Backbone.js to handle client-side state and rendering in
3795      <a href="http://www.zocdoc.com/primary-care-doctors/los-angeles-13122pm">search pages</a>
3796      and <a href="http://www.zocdoc.com/doctor/nathan-hashimoto-md-58078">doctor profiles</a>.
3797      In addition, the new version of the doctor-facing part of the website is a
3798      large single-page application that
3799      benefits from Backbone's structure and modularity. ZocDoc's Backbone
3800      classes are tested with
3801      <a href="http://pivotal.github.io/jasmine/">Jasmine</a>, and delivered
3802      to the end user with
3803      <a href="http://getcassette.net/">Cassette</a>.
3804    </p>
3805
3806    <div style="text-align: center;">
3807      <a href="http://www.zocdoc.com">
3808        <img width="510" height="464" data-original="docs/images/zocdoc.jpg" alt="ZocDoc" class="example_retina" />
3809      </a>
3810    </div>
3811
3812    <h2 id="examples-walmart">Walmart Mobile</h2>
3813
3814    <p>
3815      <a href="http://www.walmart.com/">Walmart</a> used Backbone.js to create the new version
3816      of <a href="http://mobile.walmart.com/">their mobile web application</a> and
3817      created two new frameworks in the process.
3818      <a href="http://walmartlabs.github.com/thorax/">Thorax</a> provides mixins, inheritable
3819      events, as well as model and collection view bindings that integrate directly with
3820      <a href="http://handlebarsjs.com/">Handlebars</a> templates.
3821      <a href="http://walmartlabs.github.com/lumbar/">Lumbar</a> allows the application to be
3822      split into modules which can be loaded on demand, and creates platform specific builds
3823      for the portions of the web application that are embedded in Walmart's native Android
3824      and iOS applications.
3825    </p>
3826
3827    <div style="text-align: center;">
3828      <a href="http://mobile.walmart.com/r/phoenix">
3829        <img width="256" height="534" data-original="docs/images/walmart-mobile.png" alt="Walmart Mobile" class="example_image" />
3830      </a>
3831    </div>
3832
3833    <h2 id="examples-groupon">Groupon Now!</h2>
3834
3835    <p>
3836      <a href="http://www.groupon.com/now">Groupon Now!</a> helps you find
3837      local deals that you can buy and use right now. When first developing
3838      the product, the team decided it would be AJAX heavy with smooth transitions
3839      between sections instead of full refreshes, but still needed to be fully
3840      linkable and shareable. Despite never having used Backbone before, the
3841      learning curve was incredibly quick &mdash; a prototype was hacked out in an
3842      afternoon, and the team was able to ship the product in two weeks.
3843      Because the source is minimal and understandable, it was easy to
3844      add several Backbone extensions for Groupon Now!: changing the router
3845      to handle URLs with querystring parameters, and adding a simple
3846      in-memory store for caching repeated requests for the same data.
3847    </p>
3848
3849    <div style="text-align: center;">
3850      <a href="http://www.groupon.com/now">
3851        <img width="550" height="466" data-original="docs/images/groupon.jpg" alt="Groupon Now!" class="example_retina" />
3852      </a>
3853    </div>
3854
3855    <h2 id="examples-basecamp">Basecamp</h2>
3856
3857    <p>
3858      <a href="http://37signals.com/">37Signals</a> chose Backbone.js to create
3859      the <a href="http://basecamp.com/calendar">calendar feature</a> of its
3860      popular project management software <a href="http://basecamp.com/">Basecamp</a>.
3861      The Basecamp Calendar uses Backbone.js models and views in conjunction with the
3862      <a href="https://github.com/sstephenson/eco">Eco</a> templating system to
3863      present a polished, highly interactive group scheduling interface.
3864    </p>
3865
3866    <div style="text-align: center;">
3867      <a href="http://basecamp.com/calendar">
3868        <img width="530" height="380" data-original="docs/images/basecamp-calendar.jpg" alt="Basecamp Calendar" class="example_retina" />
3869      </a>
3870    </div>
3871
3872    <h2 id="examples-slavery-footprint">Slavery Footprint</h2>
3873
3874    <p>
3875      <a href="http://slaveryfootprint.org/survey">Slavery Footprint</a>
3876      allows consumers to visualize how their consumption habits are
3877      connected to modern-day slavery and provides them with an opportunity
3878      to have a deeper conversation with the companies that manufacture the
3879      goods they purchased.
3880      Based in Oakland, California, the Slavery Footprint team works to engage
3881      individuals, groups, and businesses to build awareness for and create
3882      deployable action against forced labor, human trafficking, and modern-day
3883      slavery through online tools, as well as off-line community education and
3884      mobilization programs.
3885    </p>
3886
3887    <div style="text-align: center;">
3888      <a href="http://slaveryfootprint.org/survey">
3889        <img width="550" height="394" data-original="docs/images/slavery-footprint.jpg" alt="Slavery Footprint" class="example_retina" />
3890      </a>
3891    </div>
3892
3893    <h2 id="examples-stripe">Stripe</h2>
3894
3895    <p>
3896      <a href="https://stripe.com">Stripe</a> provides an API for accepting
3897      credit cards on the web. Stripe's
3898      <a href="https://manage.stripe.com">management interface</a> was recently
3899      rewritten from scratch in CoffeeScript using Backbone.js as the primary
3900      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
3901      everything together as <a href="http://commonjs.org/">CommonJS</a> modules. The new app uses
3902      <a href="https://stripe.com/docs/api">Stripe's API</a> directly for the
3903      majority of its actions; Backbone.js models made it simple to map
3904      client-side models to their corresponding RESTful resources.
3905    </p>
3906
3907    <div style="text-align: center;">
3908      <a href="https://stripe.com">
3909        <img width="555" height="372" data-original="docs/images/stripe.png" alt="Stripe" class="example_retina" />
3910      </a>
3911    </div>
3912
3913    <h2 id="examples-airbnb">Airbnb</h2>
3914
3915    <p>
3916      <a href="http://airbnb.com">Airbnb</a> uses Backbone in many of its products.
3917      It started with <a href="http://m.airbnb.com">Airbnb Mobile Web</a>
3918      (built in six weeks by a team of three) and has since grown to
3919      <a href="https://www.airbnb.com/wishlists/popular">Wish Lists</a>,
3920      <a href="http://www.airbnb.com/match">Match</a>,
3921      <a href="http://www.airbnb.com/s/">Search</a>, Communities, Payments, and
3922      Internal Tools.
3923    </p>
3924
3925    <div style="text-align: center;">
3926      <a href="http://m.airbnb.com/">
3927        <img width="500" height="489" data-original="docs/images/airbnb.png" alt="Airbnb" class="example_image" />
3928      </a>
3929    </div>
3930
3931    <h2 id="examples-soundcloud">SoundCloud Mobile</h2>
3932
3933    <p>
3934      <a href="http://soundcloud.com">SoundCloud</a> is the leading sound sharing
3935      platform on the internet, and Backbone.js provides the foundation for
3936      <a href="http://m.soundcloud.com">SoundCloud Mobile</a>. The project uses
3937      the public SoundCloud <a href="http://soundcloud.com/developers">API</a>
3938      as a data source (channeled through a nginx proxy),
3939      <a href="http://api.jquery.com/category/plugins/templates/">jQuery templates</a>
3940      for the rendering, <a href="http://docs.jquery.com/Qunit">Qunit
3941      </a> and <a href="http://www.phantomjs.org/">PhantomJS</a> for
3942      the testing suite. The JS code, templates and CSS are built for the
3943      production deployment with various Node.js tools like
3944      <a href="https://github.com/dsimard/ready.js">ready.js</a>,
3945      <a href="https://github.com/mde/jake">Jake</a>,
3946      <a href="https://github.com/tmpvar/jsdom">jsdom</a>.
3947      The <b>Backbone.History</b> was modified to support the HTML5 <tt>history.pushState</tt>.
3948      <b>Backbone.sync</b> was extended with an additional SessionStorage based cache
3949      layer.
3950    </p>
3951
3952    <div style="text-align: center;">
3953      <a href="http://m.soundcloud.com">
3954        <img width="266" height="555" data-original="docs/images/soundcloud.png" alt="SoundCloud" class="example_image" />
3955      </a>
3956    </div>
3957
3958    <h2 id="examples-artsy">Art.sy</h2>
3959
3960    <p>
3961      <a href="http://artsy.net">Art.sy</a> is a place to discover art you'll
3962      love. Art.sy is built on Rails, using
3963      <a href="https://github.com/intridea/grape">Grape</a> to serve a robust
3964      <a href="http://artsy.net/api">JSON API</a>. The main site is a single page
3965      app written in CoffeeScript and uses Backbone to provide structure around
3966      this API. An admin panel and partner CMS have also been extracted into
3967      their own API-consuming Backbone projects.
3968    </p>
3969
3970    <div style="text-align: center;">
3971      <a href="http://artsy.net">
3972        <img width="550" height="550" data-original="docs/images/artsy.jpg" alt="Art.sy" class="example_retina" />
3973      </a>
3974    </div>
3975
3976    <h2 id="examples-pandora">Pandora</h2>
3977
3978    <p>
3979      When <a href="http://www.pandora.com/newpandora">Pandora</a> redesigned
3980      their site in HTML5, they chose Backbone.js to help
3981      manage the user interface and interactions. For example, there's a model
3982      that represents the "currently playing track", and multiple views that
3983      automatically update when the current track changes. The station list is a
3984      collection, so that when stations are added or changed, the UI stays up to date.
3985    </p>
3986
3987    <div style="text-align: center;">
3988      <a href="http://www.pandora.com/newpandora">
3989        <img width="476" height="359" data-original="docs/images/pandora.jpg" alt="Pandora" class="example_retina" />
3990      </a>
3991    </div>
3992
3993    <h2 id="examples-inkling">Inkling</h2>
3994
3995    <p>
3996      <a href="http://inkling.com/">Inkling</a> is a cross-platform way to
3997      publish interactive learning content.
3998      <a href="https://www.inkling.com/read/">Inkling for Web</a> uses Backbone.js
3999      to make hundreds of complex books — from student textbooks to travel guides and
4000      programming manuals — engaging and accessible on the web. Inkling supports
4001      WebGL-enabled 3D graphics, interactive assessments, social sharing,
4002      and a system for running practice code right
4003      in the book, all within a single page Backbone-driven app. Early on, the
4004      team decided to keep the site lightweight by using only Backbone.js and
4005      raw JavaScript. The result? Complete source code weighing in at a mere
4006      350kb with feature-parity across the iPad, iPhone and web clients.
4007      Give it a try with
4008      <a href="https://www.inkling.com/read/javascript-definitive-guide-david-flanagan-6th/chapter-4/function-definition-expressions">this excerpt from JavaScript: The Definitive Guide</a>.
4009    </p>
4010
4011    <div style="text-align: center;">
4012      <a href="http://inkling.com">
4013        <img width="550" height="361" data-original="docs/images/inkling.jpg" alt="Inkling" class="example_retina" />
4014      </a>
4015    </div>
4016
4017    <h2 id="examples-code-school">Code School</h2>
4018
4019    <p>
4020      <a href="http://www.codeschool.com">Code School</a> courses teach people
4021      about various programming topics like <a href="http://coffeescript.org">CoffeeScript</a>, CSS, Ruby on Rails,
4022      and more. The new Code School course
4023      <a href="http://coffeescript.codeschool.com/levels/1/challenges/1">challenge page</a>
4024      is built from the ground up on Backbone.js, using
4025      everything it has to offer: the router, collections, models, and complex
4026      event handling. Before, the page was a mess of <a href="http://jquery.com/">jQuery</a> DOM manipulation
4027      and manual Ajax calls. Backbone.js helped introduce a new way to
4028      think about developing an organized front-end application in JavaScript.
4029    </p>
4030
4031    <div style="text-align: center;">
4032      <a href="http://www.codeschool.com">
4033        <img width="550" height="482" data-original="docs/images/code-school.jpg" alt="Code School" class="example_retina" />
4034      </a>
4035    </div>
4036
4037    <h2 id="examples-cloudapp">CloudApp</h2>
4038
4039    <p>
4040      <a href="http://getcloudapp.com">CloudApp</a> is simple file and link
4041      sharing for the Mac. Backbone.js powers the web tools
4042      which consume the <a href="http://developer.getcloudapp.com">documented API</a>
4043      to manage Drops. Data is either pulled manually or pushed by
4044      <a href="http://pusher.com">Pusher</a> and fed to
4045      <a href="http://github.com/janl/mustache.js">Mustache</a> templates for
4046      rendering. Check out the <a href="http://cloudapp.github.com/engine">annotated source code</a>
4047      to see the magic.
4048    </p>
4049
4050    <div style="text-align: center;">
4051      <a href="http://getcloudapp.com">
4052        <img width="550" height="426" data-original="docs/images/cloudapp.jpg" alt="CloudApp" class="example_retina" />
4053      </a>
4054    </div>
4055
4056    <h2 id="examples-seatgeek">SeatGeek</h2>
4057
4058    <p>
4059      <a href="http://seatgeek.com">SeatGeek</a>'s stadium ticket maps were originally
4060      developed with <a href="http://prototypejs.org/">Prototype.js</a>. Moving to Backbone.js and <a href="http://jquery.com/">jQuery</a> helped organize
4061      a lot of the UI code, and the increased structure has made adding features
4062      a lot easier. SeatGeek is also in the process of building a mobile
4063      interface that will be Backbone.js from top to bottom.
4064    </p>
4065
4066    <div style="text-align: center;">
4067      <a href="http://seatgeek.com">
4068        <img width="550" height="455" data-original="docs/images/seatgeek.jpg" alt="SeatGeek" class="example_retina" />
4069      </a>
4070    </div>
4071
4072    <h2 id="examples-easel">Easel</h2>
4073
4074    <p>
4075      <a href="http://easel.io">Easel</a> is an in-browser, high fidelity web
4076      design tool that integrates with your design and development
4077      process. The Easel team uses CoffeeScript, Underscore.js and Backbone.js for
4078      their <a href="http://easel.io/demo">rich visual editor</a> as well as other
4079      management functions throughout the site. The structure of Backbone allowed
4080      the team to break the complex problem of building a visual editor into
4081      manageable components and still move quickly.
4082    </p>
4083
4084    <div style="text-align: center;">
4085      <a href="http://easel.io">
4086        <img width="550" height="395" data-original="docs/images/easel.jpg" alt="Easel" class="example_retina" />
4087      </a>
4088    </div>
4089
4090    <h2 id="examples-jolicloud">Jolicloud</h2>
4091
4092    <p>
4093      <a href="http://www.jolicloud.com/">Jolicloud</a> is an open and independent
4094      platform and <a href="http://www.jolicloud.com/jolios">operating system</a>
4095      that provides music playback, video streaming, photo browsing and
4096      document editing &mdash; transforming low cost computers into beautiful cloud devices.
4097      The <a href="https://my.jolicloud.com/">new Jolicloud HTML5 app</a> was built
4098      from the ground up using Backbone and talks to the
4099      <a href="http://developers.jolicloud.com">Jolicloud Platform</a>, which is
4100      based on Node.js. Jolicloud works offline using the HTML5 AppCache, extends
4101      Backbone.sync to store data in IndexedDB or localStorage, and communicates
4102      with the <a href="http://www.jolicloud.com/jolios">Joli OS</a> via WebSockets.
4103    </p>
4104
4105    <div style="text-align: center;">
4106      <a href="http://jolicloud.com/">
4107        <img width="510" height="384" data-original="docs/images/jolicloud.jpg" alt="Jolicloud" class="example_retina" />
4108      </a>
4109    </div>
4110
4111    <h2 id="examples-salon">Salon.io</h2>
4112
4113    <p>
4114      <a href="http://salon.io">Salon.io</a> provides a space where photographers,
4115      artists and designers freely arrange their visual art on virtual walls.
4116      <a href="http://salon.io">Salon.io</a> runs on <a href="http://rubyonrails.org/">Rails</a>, but does not use
4117      much of the traditional stack, as the entire frontend is designed as a
4118      single page web app, using Backbone.js, <a href="http://brunch.io/">Brunch</a> and
4119      <a href="http://coffeescript.org">CoffeeScript</a>.
4120    </p>
4121
4122    <div style="text-align: center;">
4123      <a href="http://salon.io">
4124        <img width="550" height="483" data-original="docs/images/salon.jpg" alt="Salon.io" class="example_retina" />
4125      </a>
4126    </div>
4127
4128    <h2 id="examples-tilemill">TileMill</h2>
4129
4130    <p>
4131      Our fellow
4132      <a href="http://www.newschallenge.org/">Knight Foundation News Challenge</a>
4133      winners, <a href="http://mapbox.com/">MapBox</a>, created an open-source
4134      map design studio with Backbone.js:
4135      <a href="https://www.mapbox.com/tilemill/">TileMill</a>.
4136      TileMill lets you manage map layers based on shapefiles and rasters, and
4137      edit their appearance directly in the browser with the
4138      <a href="https://github.com/mapbox/carto">Carto styling language</a>.
4139      Note that the gorgeous <a href="http://mapbox.com/">MapBox</a> homepage
4140      is also a Backbone.js app.
4141    </p>
4142
4143    <div style="text-align: center;">
4144      <a href="https://www.mapbox.com/tilemill/">
4145        <img width="544" height="375" data-original="docs/images/tilemill.jpg" alt="TileMill" class="example_retina" />
4146      </a>
4147    </div>
4148
4149    <h2 id="examples-blossom">Blossom</h2>
4150
4151    <p>
4152      <a href="http://blossom.io">Blossom</a> is a lightweight project management
4153      tool for lean teams. Backbone.js is heavily used in combination with
4154      <a href="http://coffeescript.org">CoffeeScript</a> to provide a smooth
4155      interaction experience. The app is packaged with <a href="http://brunch.io">Brunch</a>.
4156      The RESTful backend is built with <a href="http://flask.pocoo.org/">Flask</a> on Google App Engine.
4157    </p>
4158
4159    <div style="text-align: center;">
4160      <a href="http://blossom.io">
4161        <img width="550" height="367" data-original="docs/images/blossom.jpg" alt="Blossom" class="example_retina" />
4162      </a>
4163    </div>
4164
4165    <h2 id="examples-trello">Trello</h2>
4166
4167    <p>
4168      <a href="http://trello.com">Trello</a> is a collaboration tool that
4169      organizes your projects into boards. A Trello board holds many lists of
4170      cards, which can contain checklists, files and conversations, and may be
4171      voted on and organized with labels. Updates on the board happen in
4172      real time. The site was built ground up using Backbone.js for all the
4173      models, views, and routes.
4174    </p>
4175
4176    <div style="text-align: center;">
4177      <a href="http://trello.com">
4178        <img width="550" height="416" data-original="docs/images/trello.jpg" alt="Trello" class="example_retina" />
4179      </a>
4180    </div>
4181
4182    <h2 id="examples-tzigla">Tzigla</h2>
4183
4184    <p>
4185      <a href="http://twitter.com/evilchelu">Cristi Balan</a> and
4186      <a href="http://dira.ro">Irina Dumitrascu</a> created
4187      <a href="http://tzigla.com">Tzigla</a>, a collaborative drawing
4188      application where artists make tiles that connect to each other to
4189      create <a href="http://tzigla.com/boards/1">surreal drawings</a>.
4190      Backbone models help organize the code, routers provide
4191      <a href="http://tzigla.com/boards/1#!/tiles/2-2">bookmarkable deep links</a>,
4192      and the views are rendered with
4193      <a href="https://github.com/creationix/haml-js">haml.js</a> and
4194      <a href="http://zeptojs.com/">Zepto</a>.
4195      Tzigla is written in Ruby (<a href="http://rubyonrails.org/">Rails</a>) on the backend, and
4196      <a href="http://coffeescript.org">CoffeeScript</a> on the frontend, with
4197      <a href="http://documentcloud.github.com/jammit/">Jammit</a>
4198      prepackaging the static assets.
4199    </p>
4200
4201    <div style="text-align: center;">
4202      <a href="http://www.tzigla.com/">
4203        <img width="550" height="376" data-original="docs/images/tzigla.jpg" alt="Tzigla" class="example_retina" />
4204      </a>
4205    </div>
4206
4207    <h2 id="changelog">Change Log</h2>
4208
4209    <b class="header">1.2.0</b> &mdash; <small><i>May 13, 2015</i></small>
4210    &mdash; <a href="https://github.com/jashkenas/backbone/compare/1.1.2...1.2.0">Diff</a>
4211    &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/1.2.0/index.html">Docs</a>
4212    <br />
4213    <ul style="margin-top: 5px;">
4214      <li>
4215        Added new hooks to Views to allow them to work without jQuery. See the
4216        <a href="https://github.com/jashkenas/backbone/wiki/Using-Backbone-without-jQuery">wiki page</a>
4217        for more info.
4218      </li>
4219      <li>
4220        As a neat side effect, Backbone.History no longer uses jQuery's
4221        event methods for <tt>pushState</tt> and <tt>hashChange</tt> listeners.
4222        We're native all the way.
4223      </li>
4224      <li>
4225        Also on the subject of jQuery, if you're using Backbone with CommonJS (node, browserify, webpack)
4226        Backbone will automatically try to load jQuery for you.
4227      </li>
4228      <li>
4229        Added an <tt>"update"</tt> event that triggers after any amount of
4230        models are added or removed from a collection. Handy to re-render lists
4231        of things without debouncing.
4232      </li>
4233      <li>
4234        Added <tt>modelId</tt> to Collection for generating unique ids on
4235        polymorphic collections. Handy for cases when your model ids would
4236        otherwise collide.
4237      </li>
4238      <li>
4239        Added an overridable <tt>_isModel</tt> for more advanced
4240        control of what's considered a model by your Collection.
4241      </li>
4242      <li>
4243        The <tt>success</tt> callback passed to <tt>Model#destroy</tt> is always
4244        called asynchronously now.
4245      </li>
4246      <li>
4247        <tt>Router#execute</tt> passes back the route name as its third argument.
4248      </li>
4249      <li>
4250        Cancel the current Router transition by returning <tt>false</tt> in
4251        <tt>Router#execute</tt>. Great for checking logged-in status or other
4252        prerequisites.
4253      </li>
4254      <li>
4255        Added <tt>getSearch</tt> and <tt>getPath</tt> methods to Backbone.History as
4256        cross-browser and overridable ways of slicing up the URL.
4257      </li>
4258      <li>
4259        Added <tt>delegate</tt> and <tt>undelegate</tt> as finer-grained versions
4260        of <tt>delegateEvents</tt> and <tt>undelegateEvents</tt>. Useful for plugin
4261        authors to use a consistent events interface in Backbone.
4262      </li>
4263      <li>
4264        A collection will only fire a "sort" event if its order was actually
4265        updated, not on every <tt>set</tt>.
4266      </li>
4267      <li>
4268        Any passed <tt>options.attrs</tt> are now respected when saving a model with
4269        <tt>patch: true</tt>.
4270      </li>
4271      <li>
4272        <tt>Collection#clone</tt> now sets the <tt>model</tt> and <tt>comparator</tt>
4273        functions of the cloned collection to the new one.
4274      </li>
4275      <li>
4276        Adding models to your Collection when specifying an <tt>at</tt> position
4277        now sends the actual position of your model in the <tt>add</tt>
4278        event, not just the one you've passed in.
4279      </li>
4280      <li>
4281        <tt>Collection#remove</tt> will now only return a list of models that
4282        have actually been removed from the collection.
4283      </li>
4284      <li>
4285        Fixed loading Backbone.js in strict ES6 module loaders.
4286      </li>
4287    </ul>
4288
4289    <b class="header">1.1.2</b> &mdash; <small><i>Feb. 20, 2014</i></small>
4290    &mdash; <a href="https://github.com/jashkenas/backbone/compare/1.1.1...1.1.2">Diff</a>
4291    &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/1.1.2/index.html">Docs</a>
4292    <br />
4293    <ul style="margin-top: 5px;">
4294      <li>
4295        Backbone no longer tries to require jQuery in Node/CommonJS environments,
4296        for better compatibility with folks using Browserify.
4297        If you'd like to have Backbone use jQuery from Node, assign it like so:
4298        <tt>Backbone.$ = require('jquery');</tt>
4299      </li>
4300      <li>
4301        Bugfix for route parameters with newlines in them.
4302      </li>
4303    </ul>
4304
4305    <b class="header">1.1.1</b> &mdash; <small><i>Feb. 13, 2014</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/1.1.0...1.1.1">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/1.1.1/index.html">Docs</a><br />
4306    <ul style="margin-top: 5px;">
4307      <li>
4308        Backbone now registers itself for AMD (Require.js), Bower and Component,
4309        as well as being a CommonJS module and a regular (Java)Script. Whew.
4310      </li>
4311      <li>
4312        Added an <tt>execute</tt> hook to the Router, which allows you to hook
4313        in and custom-parse route arguments, like query strings, for example.
4314      </li>
4315      <li>
4316        Performance fine-tuning for Backbone Events.
4317      </li>
4318      <li>
4319        Better matching for Unicode in routes, in old browsers.
4320      </li>
4321      <li>
4322        Backbone Routers now handle query params in route fragments, passing
4323        them into the handler as the last argument.  Routes specified as
4324        strings should no longer include the query string
4325        (<tt>'foo?:query'</tt> should be <tt>'foo'</tt>).
4326      </li>
4327    </ul>
4328
4329    <b class="header">1.1.0</b> &mdash; <small><i>Oct. 10, 2013</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/1.0.0...1.1.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/1.1.0/index.html">Docs</a><br />
4330    <ul style="margin-top: 5px;">
4331      <li>
4332        Made the return values of Collection's <tt>set</tt>, <tt>add</tt>,
4333        <tt>remove</tt>, and <tt>reset</tt> more useful. Instead of returning
4334        <tt>this</tt>, they now return the changed (added, removed or updated)
4335        model or list of models.
4336      </li>
4337      <li>
4338        Backbone Views no longer automatically attach options passed to the constructor as
4339        <tt>this.options</tt> and Backbone Models no longer attach <tt>url</tt> and
4340        <tt>urlRoot</tt> options, but you can do it yourself if you prefer.
4341      </li>
4342      <li>
4343        All <tt>"invalid"</tt> events now pass consistent arguments. First the
4344        model in question, then the error object, then options.
4345      </li>
4346      <li>
4347        You are no longer permitted to change the <b>id</b> of your model during
4348        <tt>parse</tt>. Use <tt>idAttribute</tt> instead.
4349      </li>
4350      <li>
4351        On the other hand, <tt>parse</tt> is now an excellent place to extract
4352        and vivify incoming nested JSON into associated submodels.
4353      </li>
4354      <li>
4355        Many tweaks, optimizations and bugfixes relating to Backbone 1.0,
4356        including URL overrides, mutation of options, bulk ordering, trailing
4357        slashes, edge-case listener leaks, nested model parsing...
4358      </li>
4359    </ul>
4360
4361    <b class="header">1.0.0</b> &mdash; <small><i>March 20, 2013</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.9.10...1.0.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/1.0.0/index.html">Docs</a><br />
4362    <ul style="margin-top: 5px;">
4363      <li>
4364        Renamed Collection's "update" to <a href="#Collection-set">set</a>, for
4365        parallelism with the similar <tt>model.set()</tt>, and contrast with
4366        <a href="#Collection-reset">reset</a>. It's now the default
4367        updating mechanism after a <a href="#Collection-fetch">fetch</a>. If you'd
4368        like to continue using "reset", pass <tt>{reset: true}</tt>.
4369      </li>
4370      <li>
4371        Your route handlers will now receive their URL parameters pre-decoded.
4372      </li>
4373      <li>
4374        Added <a href="#Events-listenToOnce">listenToOnce</a> as the analogue of
4375        <a href="#Events-once">once</a>.
4376      </li>
4377      <li>
4378        Added the <a href="#Collection-findWhere">findWhere</a> method to Collections,
4379        similar to <a href="#Collection-where">where</a>.
4380      </li>
4381      <li>
4382        Added the <tt>keys</tt>, <tt>values</tt>, <tt>pairs</tt>, <tt>invert</tt>,
4383        <tt>pick</tt>, and <tt>omit</tt> Underscore.js methods to Backbone Models.
4384      </li>
4385      <li>
4386        The routes in a Router's route map may now be function literals,
4387        instead of references to methods, if you like.
4388      </li>
4389      <li>
4390        <tt>url</tt> and <tt>urlRoot</tt> properties may now be passed as options
4391        when instantiating a new Model.
4392      </li>
4393    </ul>
4394
4395    <b class="header">0.9.10</b> &mdash; <small><i>Jan. 15, 2013</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.9.9...0.9.10">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.9.10/index.html">Docs</a><br />
4396    <ul style="margin-top: 5px;">
4397      <li>
4398        A <tt>"route"</tt> event is triggered on the router in addition
4399        to being fired on <tt>Backbone.history</tt>.
4400      </li>
4401      <li>
4402        Model validation is now only enforced by default in
4403        <tt>Model#save</tt> and no longer enforced by default upon
4404        construction or in <tt>Model#set</tt>, unless the <tt>{validate:true}</tt>
4405        option is passed.
4406      </li>
4407      <li>
4408        <tt>View#make</tt> has been removed. You'll need to use <tt>$</tt> directly to
4409        construct DOM elements now.
4410      </li>
4411      <li>
4412        Passing <tt>{silent:true}</tt> on change will no longer delay individual
4413        <tt>"change:attr"</tt> events, instead they are silenced entirely.
4414      </li>
4415      <li>
4416        The <tt>Model#change</tt> method has been removed, as delayed attribute
4417        changes are no longer available.
4418      </li>
4419      <li>
4420        Bug fix on <tt>change</tt> where attribute comparison uses <tt>!==</tt>
4421        instead of <tt>_.isEqual</tt>.
4422      </li>
4423      <li>
4424        Bug fix where an empty response from the server on save would not call
4425        the success function.
4426      </li>
4427      <li>
4428        <tt>parse</tt> now receives <tt>options</tt> as its second argument.
4429      </li>
4430      <li>
4431        Model validation now fires <tt>invalid</tt> event instead of
4432        <tt>error</tt>.
4433      </li>
4434    </ul>
4435
4436    <b class="header">0.9.9</b> &mdash; <small><i>Dec. 13, 2012</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.9.2...0.9.9">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.9.9/index.html">Docs</a><br />
4437    <ul style="margin-top: 5px;">
4438      <li>
4439        Added <a href="#Events-listenTo">listenTo</a>
4440        and <a href="#Events-stopListening">stopListening</a> to Events. They
4441        can be used as inversion-of-control flavors of <tt>on</tt> and <tt>off</tt>,
4442        for convenient unbinding of all events an object is currently listening to.
4443        <tt>view.remove()</tt> automatically calls <tt>view.stopListening()</tt>.
4444      </li>
4445      <li>
4446        When using <tt>add</tt> on a collection, passing <tt>{merge: true}</tt>
4447        will now cause duplicate models to have their attributes merged in to
4448        the existing models, instead of being ignored.
4449      </li>
4450      <li>
4451        Added <a href="#Collection-update">update</a> (which is also available as
4452        an option to <tt>fetch</tt>) for "smart" updating of sets of models.
4453      </li>
4454      <li>
4455        HTTP <tt>PATCH</tt> support in <a href="#Model-save">save</a> by passing
4456        <tt>{patch: true}</tt>.
4457      </li>
4458      <li>
4459        The <tt>Backbone</tt> object now extends <tt>Events</tt> so that you can
4460        use it as a global event bus, if you like.
4461      </li>
4462      <li>
4463        Added a <tt>"request"</tt> event to <a href="#Sync">Backbone.sync</a>,
4464        which triggers whenever a request begins to be made to the server.
4465        The natural complement to the <tt>"sync"</tt> event.
4466      </li>
4467      <li>
4468        Router URLs now support optional parts via parentheses, without having
4469        to use a regex.
4470      </li>
4471      <li>
4472        Backbone events now supports <tt>once</tt>, similar to Node's <tt>once</tt>,
4473        or jQuery's <tt>one</tt>.
4474      </li>
4475      <li>
4476        Backbone events now support jQuery-style event maps <tt>obj.on({click: action})</tt>.
4477      </li>
4478      <li>
4479        While listening to a <tt>reset</tt> event, the list of previous models
4480        is now available in <tt>options.previousModels</tt>, for convenience.
4481      </li>
4482      <li>
4483        <a href="#Model-validate">Validation</a> now occurs even during "silent"
4484        changes. This change means that the <tt>isValid</tt> method has
4485        been removed. Failed validations also trigger an error, even if an error
4486        callback is specified in the options.
4487      </li>
4488      <li>
4489        Consolidated <tt>"sync"</tt> and <tt>"error"</tt> events within
4490        <a href="#Sync">Backbone.sync</a>. They are now triggered regardless
4491        of the existence of <tt>success</tt> or <tt>error</tt> callbacks.
4492      </li>
4493      <li>
4494        For mixed-mode APIs, <tt>Backbone.sync</tt> now accepts
4495        <tt>emulateHTTP</tt> and <tt>emulateJSON</tt> as inline options.
4496      </li>
4497      <li>
4498        Collections now also proxy Underscore method name aliases (collect,
4499        inject, foldl, foldr, head, tail, take, and so on...)
4500      </li>
4501      <li>
4502        Removed <tt>getByCid</tt> from Collections. <tt>collection.get</tt> now
4503        supports lookup by both <tt>id</tt> and <tt>cid</tt>.
4504      </li>
4505      <li>
4506        After fetching a model or a collection, <i>all</i> defined <tt>parse</tt>
4507        functions will now be run. So fetching a collection and getting back new
4508        models could cause both the collection to parse the list, and then each model
4509        to be parsed in turn, if you have both functions defined.
4510      </li>
4511      <li>
4512        Bugfix for normalizing leading and trailing slashes in the Router
4513        definitions. Their presence (or absence) should not affect behavior.
4514      </li>
4515      <li>
4516        When declaring a View, <tt>options</tt>, <tt>el</tt>, <tt>tagName</tt>,
4517        <tt>id</tt> and <tt>className</tt> may now be defined as functions, if
4518        you want their values to be determined at runtime.
4519      </li>
4520      <li>
4521        Added a <tt>Backbone.ajax</tt> hook for more convenient overriding of
4522        the default use of <tt>$.ajax</tt>. If AJAX is too passé, set it to your
4523        preferred method for server communication.
4524      </li>
4525      <li>
4526        <tt>Collection#sort</tt> now triggers a <tt>sort</tt> event, instead
4527        of a <tt>reset</tt> event.
4528      </li>
4529      <li>
4530        Calling <tt>destroy</tt> on a Model will now return <tt>false</tt> if
4531        the model <tt>isNew</tt>.
4532      </li>
4533      <li>
4534        To set what library Backbone uses for DOM manipulation and Ajax calls,
4535        use <tt>Backbone.$ = ...</tt> instead of <tt>setDomLibrary</tt>.
4536      </li>
4537      <li>
4538        Removed the <tt>Backbone.wrapError</tt> helper method. Overriding
4539        <tt>sync</tt> should work better for those particular use cases.
4540      </li>
4541      <li>
4542        To improve the performance of <tt>add</tt>, <tt>options.index</tt>
4543        will no longer be set in the `add` event callback.
4544        <tt>collection.indexOf(model)</tt> can be used to retrieve the index
4545        of a model as necessary.
4546      </li>
4547      <li>
4548        For semantic and cross browser reasons, routes will now ignore search
4549        parameters.  Routes like <tt>search?query=…&amp;page=3</tt> should become
4550        <tt>search/…/3</tt>.
4551      </li>
4552      <li>
4553        <tt>Model#set</tt> no longer accepts another model as an argument.  This leads
4554        to subtle problems and is easily replaced with <tt>model.set(other.attributes)</tt>.
4555      </li>
4556    </ul>
4557
4558    <b class="header">0.9.2</b> &mdash; <small><i>March 21, 2012</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.9.1...0.9.2">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.9.2/index.html">Docs</a><br />
4559    <ul style="margin-top: 5px;">
4560      <li>
4561        Instead of throwing an error when adding duplicate models to a collection,
4562        Backbone will now silently skip them instead.
4563      </li>
4564      <li>
4565        Added <a href="#Collection-push">push</a>,
4566        <a href="#Collection-pop">pop</a>,
4567        <a href="#Collection-unshift">unshift</a>, and
4568        <a href="#Collection-shift">shift</a> to collections.
4569      </li>
4570      <li>
4571        A model's <a href="#Model-changed">changed</a> hash is now exposed for
4572        easy reading of the changed attribute delta, since the model's last
4573        <tt>"change"</tt> event.
4574      </li>
4575      <li>
4576        Added <a href="#Collection-where">where</a> to collections for simple
4577        filtering.
4578      </li>
4579      <li>
4580        You can now use a single <a href="#Events-off">off</a> call
4581        to remove all callbacks bound to a specific object.
4582      </li>
4583      <li>
4584        Bug fixes for nested individual change events, some of which may be
4585        "silent".
4586      </li>
4587      <li>
4588        Bug fixes for URL encoding in <tt>location.hash</tt> fragments.
4589      </li>
4590      <li>
4591        Bug fix for client-side validation in advance of a <tt>save</tt> call
4592        with <tt>{wait: true}</tt>.
4593      </li>
4594      <li>
4595        Updated / refreshed the example
4596        <a href="examples/todos/index.html">Todo List</a> app.
4597      </li>
4598    </ul>
4599
4600    <b class="header">0.9.1</b> &mdash; <small><i>Feb. 2, 2012</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.9.0...0.9.1">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.9.1/index.html">Docs</a><br />
4601    <ul style="margin-top: 5px;">
4602      <li>
4603        Reverted to 0.5.3-esque behavior for validating models. Silent changes
4604        no longer trigger validation (making it easier to work with forms).
4605        Added an <tt>isValid</tt> function that you can use to check if a model
4606        is currently in a valid state.
4607      </li>
4608      <li>
4609        If you have multiple versions of jQuery on the page, you can now tell
4610        Backbone which one to use with <tt>Backbone.setDomLibrary</tt>.
4611      </li>
4612      <li>
4613        Fixes regressions in <b>0.9.0</b> for routing with "root", saving with
4614        both "wait" and "validate", and the order of nested "change" events.
4615      </li>
4616    </ul>
4617
4618    <b class="header">0.9.0</b> &mdash; <small><i>Jan. 30, 2012</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.5.3...0.9.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.9.0/index.html">Docs</a><br />
4619    <ul style="margin-top: 5px;">
4620      <li>
4621        Creating and destroying models with <tt>create</tt> and <tt>destroy</tt>
4622        are now optimistic by default. Pass <tt>{wait: true}</tt> as an option
4623        if you'd like them to wait for a successful server response to proceed.
4624      </li>
4625      <li>
4626        Two new properties on views: <tt>$el</tt> &mdash; a cached jQuery (or Zepto)
4627        reference to the view's element, and <tt>setElement</tt>, which should
4628        be used instead of manually setting a view's <tt>el</tt>. It will
4629        both set <tt>view.el</tt> and <tt>view.$el</tt> correctly, as well as
4630        re-delegating events on the new DOM element.
4631      </li>
4632      <li>
4633        You can now bind and trigger multiple spaced-delimited events at once.
4634        For example: <tt>model.on("change:name change:age", ...)</tt>
4635      </li>
4636      <li>
4637        When you don't know the key in advance, you may now call
4638        <tt>model.set(key, value)</tt> as well as <tt>save</tt>.
4639      </li>
4640      <li>
4641        Multiple models with the same <tt>id</tt> are no longer allowed in a
4642        single collection.
4643      </li>
4644      <li>
4645        Added a <tt>"sync"</tt> event, which triggers whenever a model's state
4646        has been successfully synced with the server (create, save, destroy).
4647      </li>
4648      <li>
4649        <tt>bind</tt> and <tt>unbind</tt> have been renamed to <tt>on</tt>
4650        and <tt>off</tt> for clarity, following jQuery's lead.
4651        The old names are also still supported.
4652      </li>
4653      <li>
4654        A Backbone collection's <tt>comparator</tt> function may now behave
4655        either like a <a href="http://underscorejs.org/#sortBy">sortBy</a>
4656        (pass a function that takes a single argument),
4657        or like a <a href="https://developer.mozilla.org/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
4658        (pass a comparator function that expects two arguments). The comparator
4659        function is also now bound by default to the collection &mdash; so you
4660        can refer to <tt>this</tt> within it.
4661      </li>
4662      <li>
4663        A view's <tt>events</tt> hash may now also contain direct function
4664        values as well as the string names of existing view methods.
4665      </li>
4666      <li>
4667        Validation has gotten an overhaul &mdash; a model's <tt>validate</tt> function
4668        will now be run even for silent changes, and you can no longer create
4669        a model in an initially invalid state.
4670      </li>
4671      <li>
4672        Added <tt>shuffle</tt> and <tt>initial</tt> to collections, proxied
4673        from Underscore.
4674      </li>
4675      <li>
4676        <tt>Model#urlRoot</tt> may now be defined as a function as well as a
4677        value.
4678      </li>
4679      <li>
4680        <tt>View#attributes</tt> may now be defined as a function as well as a
4681        value.
4682      </li>
4683      <li>
4684        Calling <tt>fetch</tt> on a collection will now cause all fetched JSON
4685        to be run through the collection's model's <tt>parse</tt> function, if
4686        one is defined.
4687      </li>
4688      <li>
4689        You may now tell a router to <tt>navigate(fragment, {replace: true})</tt>,
4690        which will either use <tt>history.replaceState</tt> or
4691        <tt>location.hash.replace</tt>, in order to change the URL without adding
4692        a history entry.
4693      </li>
4694      <li>
4695        Within a collection's <tt>add</tt> and <tt>remove</tt> events, the index
4696        of the model being added or removed is now available as <tt>options.index</tt>.
4697      </li>
4698      <li>
4699        Added an <tt>undelegateEvents</tt> to views, allowing you to manually
4700        remove all configured event delegations.
4701      </li>
4702      <li>
4703        Although you shouldn't be writing your routes with them in any case &mdash;
4704        leading slashes (<tt>/</tt>) are now stripped from routes.
4705      </li>
4706      <li>
4707        Calling <tt>clone</tt> on a model now only passes the attributes
4708        for duplication, not a reference to the model itself.
4709      </li>
4710      <li>
4711        Calling <tt>clear</tt> on a model now removes the <tt>id</tt> attribute.
4712      </li>
4713    </ul>
4714
4715    <p>
4716      <b class="header">0.5.3</b> &mdash; <small><i>August 9, 2011</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.5.2...0.5.3">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.5.3/index.html">Docs</a><br />
4717      A View's <tt>events</tt> property may now be defined as a function, as well
4718      as an object literal, making it easier to programmatically define and inherit
4719      events. <tt>groupBy</tt> is now proxied from Underscore as a method on Collections.
4720      If the server has already rendered everything on page load, pass
4721      <tt>Backbone.history.start({silent: true})</tt> to prevent the initial route
4722      from triggering. Bugfix for pushState with encoded URLs.
4723    </p>
4724
4725    <p>
4726      <b class="header">0.5.2</b> &mdash; <small><i>July 26, 2011</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.5.1...0.5.2">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.5.2/index.html">Docs</a><br />
4727      The <tt>bind</tt> function, can now take an optional third argument, to specify
4728      the <tt>this</tt> of the callback function.
4729      Multiple models with the same <tt>id</tt> are now allowed in a collection.
4730      Fixed a bug where calling <tt>.fetch(jQueryOptions)</tt> could cause an
4731      incorrect URL to be serialized.
4732      Fixed a brief extra route fire before redirect, when degrading from
4733      <tt>pushState</tt>.
4734    </p>
4735
4736    <p>
4737      <b class="header">0.5.1</b> &mdash; <small><i>July 5, 2011</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.5.0...0.5.1">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.5.1/index.html">Docs</a><br />
4738      Cleanups from the 0.5.0 release, to wit: improved transparent upgrades from
4739      hash-based URLs to pushState, and vice-versa. Fixed inconsistency with
4740      non-modified attributes being passed to <tt>Model#initialize</tt>. Reverted
4741      a <b>0.5.0</b> change that would strip leading hashbangs from routes.
4742      Added <tt>contains</tt> as an alias for <tt>includes</tt>.
4743    </p>
4744
4745    <p>
4746      <b class="header">0.5.0</b> &mdash; <small><i>July 1, 2011</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.3.3...0.5.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.5.0/index.html">Docs</a><br />
4747      A large number of tiny tweaks and micro bugfixes, best viewed by looking
4748      at <a href="https://github.com/jashkenas/backbone/compare/0.3.3...0.5.0">the commit diff</a>.
4749      HTML5 <tt>pushState</tt> support, enabled by opting-in with:
4750      <tt>Backbone.history.start({pushState: true})</tt>.
4751      <tt>Controller</tt> was renamed to <tt>Router</tt>, for clarity.
4752      <tt>Collection#refresh</tt> was renamed to <tt>Collection#reset</tt> to emphasize
4753      its ability to both reset the collection with new models, as well as empty
4754      out the collection when used with no parameters.
4755      <tt>saveLocation</tt> was replaced with <tt>navigate</tt>.
4756      RESTful persistence methods (save, fetch, etc.) now return the jQuery deferred
4757      object for further success/error chaining and general convenience.
4758      Improved XSS escaping for <tt>Model#escape</tt>.
4759      Added a <tt>urlRoot</tt> option to allow specifying RESTful urls without
4760      the use of a collection.
4761      An error is thrown if <tt>Backbone.history.start</tt> is called multiple times.
4762      <tt>Collection#create</tt> now validates before initializing the new model.
4763      <tt>view.el</tt> can now be a jQuery string lookup.
4764      Backbone Views can now also take an <tt>attributes</tt> parameter.
4765      <tt>Model#defaults</tt> can now be a function as well as a literal attributes
4766      object.
4767    </p>
4768
4769    <p>
4770      <b class="header">0.3.3</b> &mdash; <small><i>Dec 1, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.3.2...0.3.3">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.3.3/index.html">Docs</a><br />
4771      Backbone.js now supports <a href="http://zeptojs.com">Zepto</a>, alongside
4772      jQuery, as a framework for DOM manipulation and Ajax support.
4773      Implemented <a href="#Model-escape">Model#escape</a>, to efficiently handle
4774      attributes intended for HTML interpolation. When trying to persist a model,
4775      failed requests will now trigger an <tt>"error"</tt> event. The
4776      ubiquitous <tt>options</tt> argument is now passed as the final argument
4777      to all <tt>"change"</tt> events.
4778    </p>
4779
4780    <p>
4781      <b class="header">0.3.2</b> &mdash; <small><i>Nov 23, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.3.1...0.3.2">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.3.2/index.html">Docs</a><br />
4782      Bugfix for IE7 + iframe-based "hashchange" events. <tt>sync</tt> may now be
4783      overridden on a per-model, or per-collection basis. Fixed recursion error
4784      when calling <tt>save</tt> with no changed attributes, within a
4785      <tt>"change"</tt> event.
4786    </p>
4787
4788    <p>
4789      <b class="header">0.3.1</b> &mdash; <small><i>Nov 15, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.3.0...0.3.1">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.3.1/index.html">Docs</a><br />
4790      All <tt>"add"</tt> and <tt>"remove"</tt> events are now sent through the
4791      model, so that views can listen for them without having to know about the
4792      collection. Added a <tt>remove</tt> method to <a href="#View">Backbone.View</a>.
4793      <tt>toJSON</tt> is no longer called at all for <tt>'read'</tt> and <tt>'delete'</tt> requests.
4794      Backbone routes are now able to load empty URL fragments.
4795    </p>
4796
4797    <p>
4798      <b class="header">0.3.0</b> &mdash; <small><i>Nov 9, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.2.0...0.3.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.3.0/index.html">Docs</a><br />
4799      Backbone now has <a href="#Controller">Controllers</a> and
4800      <a href="#History">History</a>, for doing client-side routing based on
4801      URL fragments.
4802      Added <tt>emulateHTTP</tt> to provide support for legacy servers that don't
4803      do <tt>PUT</tt> and <tt>DELETE</tt>.
4804      Added <tt>emulateJSON</tt> for servers that can't accept <tt>application/json</tt>
4805      encoded requests.
4806      Added <a href="#Model-clear">Model#clear</a>, which removes all attributes
4807      from a model.
4808      All Backbone classes may now be seamlessly inherited by CoffeeScript classes.
4809    </p>
4810
4811    <p>
4812      <b class="header">0.2.0</b> &mdash; <small><i>Oct 25, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.1.2...0.2.0">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.2.0/index.html">Docs</a><br />
4813      Instead of requiring server responses to be namespaced under a <tt>model</tt>
4814      key, now you can define your own <a href="#Model-parse">parse</a> method
4815      to convert responses into attributes for Models and Collections.
4816      The old <tt>handleEvents</tt> function is now named
4817      <a href="#View-delegateEvents">delegateEvents</a>, and is automatically
4818      called as part of the View's constructor.
4819      Added a <a href="#Collection-toJSON">toJSON</a> function to Collections.
4820      Added <a href="#Collection-chain">Underscore's chain</a> to Collections.
4821    </p>
4822
4823    <p>
4824      <b class="header">0.1.2</b> &mdash; <small><i>Oct 19, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.1.1...0.1.2">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.1.2/index.html">Docs</a><br />
4825      Added a <a href="#Model-fetch">Model#fetch</a> method for refreshing the
4826      attributes of single model from the server.
4827      An <tt>error</tt> callback may now be passed to <tt>set</tt> and <tt>save</tt>
4828      as an option, which will be invoked if validation fails, overriding the
4829      <tt>"error"</tt> event.
4830      You can now tell backbone to use the <tt>_method</tt> hack instead of HTTP
4831      methods by setting <tt>Backbone.emulateHTTP = true</tt>.
4832      Existing Model and Collection data is no longer sent up unnecessarily with
4833      <tt>GET</tt> and <tt>DELETE</tt> requests. Added a <tt>rake lint</tt> task.
4834      Backbone is now published as an <a href="http://npmjs.org">NPM</a> module.
4835    </p>
4836
4837    <p>
4838      <b class="header">0.1.1</b> &mdash; <small><i>Oct 14, 2010</i></small> &mdash; <a href="https://github.com/jashkenas/backbone/compare/0.1.0...0.1.1">Diff</a> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.1.1/index.html">Docs</a><br />
4839      Added a convention for <tt>initialize</tt> functions to be called
4840      upon instance construction, if defined. Documentation tweaks.
4841    </p>
4842
4843    <p>
4844      <b class="header">0.1.0</b> &mdash; <small><i>Oct 13, 2010</i></small> &mdash; <a href="https://cdn.rawgit.com/jashkenas/backbone/0.1.0/index.html">Docs</a><br />
4845      Initial Backbone release.
4846    </p>
4847
4848    <p>
4849      <br />
4850      <a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;">
4851        <img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" style="position:relative;left:-10px;" />
4852      </a>
4853    </p>
4854
4855  </div>
4856
4857  <script src="test/vendor/underscore.js"></script>
4858  <script src="test/vendor/jquery.js"></script>
4859  <script src="docs/js/jquery.lazyload.js"></script>
4860  <script src="test/vendor/json2.js"></script>
4861  <script src="backbone.js"></script>
4862
4863  <script>
4864    // Set up the "play" buttons for each runnable code example.
4865    $(function() {
4866      $('.runnable').each(function() {
4867        var code = this;
4868        var button = '<div class="run" title="Run"></div>';
4869        $(button).insertBefore(code).bind('click', function(){
4870          eval($(code).text());
4871        });
4872      });
4873      $('[data-original]').lazyload();
4874    });
4875  </script>
4876
4877</body>
4878</html>