PageRenderTime 11ms CodeModel.GetById 17ms app.highlight 60ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

https://github.com/anushr/backbone
HTML | 3518 lines | 3044 code | 474 blank | 0 comment | 0 complexity | 392c4078188549fa6d0c2a674e0f5163 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1<!DOCTYPE HTML>
   2<html>
   3<head>
   4  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
   5  <meta http-equiv="X-UA-Compatible" content="chrome=1" />
   6  <link rel="icon" href="docs/images/favicon.ico" />
   7  <title>Backbone.js</title>
   8  <style>
   9    body {
  10      font-size: 14px;
  11      line-height: 22px;
  12      font-family: Helvetica Neue, Helvetica, Arial;
  13      background: #f4f4f4 url(docs/images/background.png);
  14    }
  15    .interface {
  16      font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, sans-serif !important;
  17    }
  18    div#sidebar {
  19      background: #fff;
  20      position: fixed;
  21      top: 0; left: 0; bottom: 0;
  22      width: 200px;
  23      overflow-y: auto;
  24      overflow-x: hidden;
  25      padding: 15px 0 30px 30px;
  26      border-right: 1px solid #bbb;
  27      box-shadow: 0 0 20px #ccc; -webkit-box-shadow: 0 0 20px #ccc; -moz-box-shadow: 0 0 20px #ccc;
  28    }
  29      a.toc_title, a.toc_title:visited {
  30        display: block;
  31        color: black;
  32        font-weight: bold;
  33        margin-top: 15px;
  34      }
  35        a.toc_title:hover {
  36          text-decoration: underline;
  37        }
  38        #sidebar .version {
  39          font-size: 10px;
  40          font-weight: normal;
  41        }
  42      ul.toc_section {
  43        font-size: 11px;
  44        line-height: 14px;
  45        margin: 5px 0 0 0;
  46        padding-left: 0px;
  47        list-style-type: none;
  48        font-family: Lucida Grande;
  49      }
  50        .toc_section li {
  51          cursor: pointer;
  52          margin: 0 0 3px 0;
  53        }
  54          .toc_section li a {
  55            text-decoration: none;
  56            color: black;
  57          }
  58            .toc_section li a:hover {
  59              text-decoration: underline;
  60            }
  61    div.container {
  62      position: relative;
  63      width: 550px;
  64      margin: 40px 0 50px 260px;
  65    }
  66    div.run {
  67      position: absolute;
  68      right: 15px;
  69      width: 26px; height: 18px;
  70      background: url('docs/images/arrows.png') no-repeat -26px 0;
  71    }
  72      div.run:active {
  73        background-position: -51px 0;
  74      }
  75    p, div.container ul {
  76      margin: 25px 0;
  77      width: 550px;
  78    }
  79      p.warning {
  80        font-size: 12px;
  81        line-height: 18px;
  82        font-style: italic;
  83      }
  84      div.container ul {
  85        list-style: circle;
  86        padding-left: 15px;
  87        font-size: 13px;
  88        line-height: 18px;
  89      }
  90        div.container ul li {
  91          margin-bottom: 10px;
  92        }
  93        div.container ul.small {
  94          font-size: 12px;
  95        }
  96    a, a:visited {
  97      color: #444;
  98    }
  99    a:active, a:hover {
 100      color: #000;
 101    }
 102    a.punch {
 103      display: inline-block;
 104      background: #4162a8;
 105      border-top: 1px solid #38538c;
 106      border-right: 1px solid #1f2d4d;
 107      border-bottom: 1px solid #151e33;
 108      border-left: 1px solid #1f2d4d;
 109      -webkit-border-radius: 4px;
 110      -moz-border-radius: 4px;
 111      -ms-border-radius: 4px;
 112      -o-border-radius: 4px;
 113      border-radius: 4px;
 114      -webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 115      -moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 116      -ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 117      -o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 118      box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 119      color: #fff;
 120      font: bold 14px "helvetica neue", helvetica, arial, sans-serif;
 121      line-height: 1;
 122      margin-bottom: 15px;
 123      padding: 8px 0 10px 0;
 124      text-align: center;
 125      text-shadow: 0px -1px 1px #1e2d4d;
 126      text-decoration: none;
 127      width: 225px;
 128      -webkit-background-clip: padding-box; }
 129      a.punch:hover {
 130        -webkit-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 131        -moz-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 132        -ms-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 133        -o-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 134        box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
 135        cursor: pointer; }
 136      a.punch:active {
 137        -webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 138        -moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 139        -ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 140        -o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 141        box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
 142        margin-top: 5px; margin-bottom: 10px }
 143    a img {
 144      border: 0;
 145    }
 146    h1, h2, h3, h4, h5, h6 {
 147      padding-top: 20px;
 148    }
 149      h2 {
 150        font-size: 22px;
 151      }
 152    b.header {
 153      font-size: 18px;
 154      line-height: 35px;
 155    }
 156    span.alias {
 157      font-size: 14px;
 158      font-style: italic;
 159      margin-left: 20px;
 160    }
 161    table {
 162      margin: 15px 0 0; padding: 0;
 163    }
 164      tr, td {
 165        margin: 0; padding: 0;
 166      }
 167        td {
 168          padding: 0px 15px 5px 0;
 169        }
 170    code, pre, tt {
 171      font-family: Monaco, Consolas, "Lucida Console", monospace;
 172      font-size: 12px;
 173      line-height: 18px;
 174      font-style: normal;
 175    }
 176      tt {
 177        padding: 0px 3px;
 178        background: #fff;
 179        border: 1px solid #ddd;
 180        zoom: 1;
 181      }
 182      code {
 183        margin-left: 20px;
 184      }
 185      pre {
 186        font-size: 12px;
 187        padding: 2px 0 2px 15px;
 188        border: 4px solid #bbb; border-top: 0; border-bottom: 0;
 189        margin: 0px 0 25px;
 190      }
 191      img.example_image {
 192        margin: 0px auto;
 193      }
 194  </style>
 195</head>
 196<body>
 197
 198  <div id="sidebar" class="interface">
 199
 200    <a class="toc_title" href="#">
 201      Backbone.js <span class="version">(0.9.1)</span>
 202    </a>
 203    <ul class="toc_section">
 204      <li><a href="http://github.com/documentcloud/backbone">github repo</a></li>
 205      <li><a href="docs/backbone.html">annotated source</a></li>
 206    </ul>
 207
 208    <a class="toc_title" href="#introduction">
 209      Introduction
 210    </a>
 211
 212    <a class="toc_title" href="#upgrading">
 213      Upgrading
 214    </a>
 215
 216    <a class="toc_title" href="#Events">
 217      Events
 218    </a>
 219    <ul class="toc_section">
 220      <li><a href="#Events-on">on</a></li>
 221      <li><a href="#Events-off">off</a></li>
 222      <li><a href="#Events-trigger">trigger</a></li>
 223    </ul>
 224
 225    <a class="toc_title" href="#Model">
 226      Model
 227    </a>
 228    <ul class="toc_section">
 229      <li><a href="#Model-extend">extend</a></li>
 230      <li><a href="#Model-constructor">constructor / initialize</a></li>
 231      <li><a href="#Model-get">get</a></li>
 232      <li><a href="#Model-set">set</a></li>
 233      <li><a href="#Model-escape">escape</a></li>
 234      <li><a href="#Model-has">has</a></li>
 235      <li><a href="#Model-unset">unset</a></li>
 236      <li><a href="#Model-clear">clear</a></li>
 237      <li><a href="#Model-id">id</a></li>
 238      <li><a href="#Model-idAttribute">idAttribute</a></li>
 239      <li><a href="#Model-cid">cid</a></li>
 240      <li><a href="#Model-attributes">attributes</a></li>
 241      <li><a href="#Model-changed">changed</a></li>
 242      <li><a href="#Model-defaults">defaults</a></li>
 243      <li><a href="#Model-toJSON">toJSON</a></li>
 244      <li><a href="#Model-fetch">fetch</a></li>
 245      <li><a href="#Model-save">save</a></li>
 246      <li><a href="#Model-destroy">destroy</a></li>
 247      <li><a href="#Model-validate">validate</a></li>
 248      <li><a href="#Model-isValid">isValid</a></li>
 249      <li><a href="#Model-url">url</a></li>
 250      <li><a href="#Model-urlRoot">urlRoot</a></li>
 251      <li><a href="#Model-parse">parse</a></li>
 252      <li><a href="#Model-clone">clone</a></li>
 253      <li><a href="#Model-isNew">isNew</a></li>
 254      <li><a href="#Model-change">change</a></li>
 255      <li><a href="#Model-hasChanged">hasChanged</a></li>
 256      <li><a href="#Model-changedAttributes">changedAttributes</a></li>
 257      <li><a href="#Model-previous">previous</a></li>
 258      <li><a href="#Model-previousAttributes">previousAttributes</a></li>
 259    </ul>
 260
 261    <a class="toc_title" href="#Collection">
 262      Collection
 263    </a>
 264    <ul class="toc_section">
 265      <li><a href="#Collection-extend">extend</a></li>
 266      <li><a href="#Collection-model">model</a></li>
 267      <li><a href="#Collection-constructor">constructor / initialize</a></li>
 268      <li><a href="#Collection-models">models</a></li>
 269      <li><a href="#Collection-toJSON">toJSON</a></li>
 270      <li><a href="#Collection-Underscore-Methods"><b>Underscore Methods (28)</b></a></li>
 271      <li><a href="#Collection-add">add</a></li>
 272      <li><a href="#Collection-remove">remove</a></li>
 273      <li><a href="#Collection-get">get</a></li>
 274      <li><a href="#Collection-getByCid">getByCid</a></li>
 275      <li><a href="#Collection-at">at</a></li>
 276      <li><a href="#Collection-length">length</a></li>
 277      <li><a href="#Collection-comparator">comparator</a></li>
 278      <li><a href="#Collection-sort">sort</a></li>
 279      <li><a href="#Collection-pluck">pluck</a></li>
 280      <li><a href="#Collection-url">url</a></li>
 281      <li><a href="#Collection-parse">parse</a></li>
 282      <li><a href="#Collection-fetch">fetch</a></li>
 283      <li><a href="#Collection-reset">reset</a></li>
 284      <li><a href="#Collection-create">create</a></li>
 285    </ul>
 286
 287    <a class="toc_title" href="#Router">
 288      Router
 289    </a>
 290    <ul class="toc_section">
 291      <li><a href="#Router-extend">extend</a></li>
 292      <li><a href="#Router-routes">routes</a></li>
 293      <li><a href="#Router-constructor">constructor / initialize</a></li>
 294      <li><a href="#Router-route">route</a></li>
 295      <li><a href="#Router-navigate">navigate</a></li>
 296    </ul>
 297
 298    <a class="toc_title" href="#History">
 299      History
 300    </a>
 301    <ul class="toc_section">
 302      <li><a href="#History-start">start</a></li>
 303    </ul>
 304
 305    <a class="toc_title" href="#Sync">
 306      Sync
 307    </a>
 308    <ul class="toc_section">
 309      <li><a href="#Sync">Backbone.sync</a></li>
 310      <li><a href="#Sync-emulateHTTP">Backbone.emulateHTTP</a></li>
 311      <li><a href="#Sync-emulateJSON">Backbone.emulateJSON</a></li>
 312    </ul>
 313
 314    <a class="toc_title" href="#View">
 315      View
 316    </a>
 317    <ul class="toc_section">
 318      <li><a href="#View-extend">extend</a></li>
 319      <li><a href="#View-constructor">constructor / initialize</a></li>
 320      <li><a href="#View-el">el</a></li>
 321      <li><a href="#View-$el">$el</a></li>
 322      <li><a href="#View-setElement">setElement</a></li>
 323      <li><a href="#View-attributes">attributes</a></li>
 324      <li><a href="#View-dollar">$ (jQuery or Zepto)</a></li>
 325      <li><a href="#View-render">render</a></li>
 326      <li><a href="#View-remove">remove</a></li>
 327      <li><a href="#View-make">make</a></li>
 328      <li><a href="#View-delegateEvents">delegateEvents</a></li>
 329      <li><a href="#View-undelegateEvents">undelegateEvents</a></li>
 330    </ul>
 331
 332    <a class="toc_title" href="#Utility">
 333      Utility
 334    </a>
 335    <ul class="toc_section">
 336      <li><a href="#Utility-noConflict">noConflict</a></li>
 337      <li><a href="#Utility-setDomLibrary">setDomLibrary</a></li>
 338    </ul>
 339
 340    <a class="toc_title" href="#examples">
 341      Examples
 342    </a>
 343    <ul class="toc_section">
 344      <li><a href="#examples-todos">Todos</a></li>
 345      <li><a href="#examples-documentcloud">DocumentCloud</a></li>
 346      <li><a href="#examples-linkedin">LinkedIn Mobile</a></li>
 347      <li><a href="#examples-flow">Flow</a></li>
 348      <li><a href="#examples-audiovroom">AudioVroom</a></li>
 349      <li><a href="#examples-foursquare">Foursquare</a></li>
 350      <li><a href="#examples-wunderkit">Wunderkit</a></li>
 351      <li><a href="#examples-khan-academy">Khan Academy</a></li>
 352      <li><a href="#examples-do">Do</a></li>
 353      <li><a href="#examples-posterous">Posterous Spaces</a></li>
 354      <li><a href="#examples-groupon">Groupon Now!</a></li>
 355      <li><a href="#examples-basecamp">Basecamp Mobile</a></li>
 356      <li><a href="#examples-slavery-footprint">Slavery Footprint</a></li>
 357      <li><a href="#examples-stripe">Stripe</a></li>
 358      <li><a href="#examples-diaspora">Diaspora</a></li>
 359      <li><a href="#examples-soundcloud">SoundCloud Mobile</a></li>
 360      <li><a href="#examples-pandora">Pandora</a></li>
 361      <li><a href="#examples-code-school">Code School</a></li>
 362      <li><a href="#examples-cloudapp">CloudApp</a></li>
 363      <li><a href="#examples-seatgeek">SeatGeek</a></li>
 364      <li><a href="#examples-grove">Grove.io</a></li>
 365      <li><a href="#examples-kicksend">Kicksend</a></li>
 366      <li><a href="#examples-shortmail">Shortmail</a></li>
 367      <li><a href="#examples-battlefield">Battlefield Play4Free</a></li>
 368      <li><a href="#examples-salon">Salon.io</a></li>
 369      <li><a href="#examples-tilemill">TileMill</a></li>
 370      <li><a href="#examples-blossom">Blossom</a></li>
 371      <li><a href="#examples-animoto">Animoto</a></li>
 372      <li><a href="#examples-codiqa">Codiqa</a></li>
 373      <li><a href="#examples-attictv">AtticTV</a></li>
 374      <li><a href="#examples-decide">Decide</a></li>
 375      <li><a href="#examples-trello">Trello</a></li>
 376      <li><a href="#examples-ducksboard">Ducksboard</a></li>
 377      <li><a href="#examples-picklive">Picklive</a></li>
 378      <li><a href="#examples-quietwrite">QuietWrite</a></li>
 379      <li><a href="#examples-tzigla">Tzigla</a></li>
 380    </ul>
 381
 382    <a class="toc_title" href="#faq">
 383      F.A.Q.
 384    </a>
 385    <ul class="toc_section">
 386      <li><a href="#FAQ-events">Catalog of Events</a></li>
 387      <li><a href="#FAQ-tim-toady">More Than One Way To Do It</a></li>
 388      <li><a href="#FAQ-nested">Nested Models &amp; Collections</a></li>
 389      <li><a href="#FAQ-bootstrap">Loading Bootstrapped Models</a></li>
 390      <li><a href="#FAQ-extending">Extending Backbone</a></li>
 391      <li><a href="#FAQ-mvc">Traditional MVC</a></li>
 392      <li><a href="#FAQ-this">Binding "this"</a></li>
 393      <li><a href="#FAQ-rails">Working with Rails</a></li>
 394    </ul>
 395
 396    <a class="toc_title" href="#changelog">
 397      Change Log
 398    </a>
 399
 400  </div>
 401
 402  <div class="container">
 403
 404    <p>
 405      <img style="width: 451px; height: 80px;" src="docs/images/backbone.png" alt="Backbone.js" />
 406    </p>
 407
 408    <p>
 409      Backbone.js gives structure to web applications
 410      by providing <b>models</b> with key-value binding and custom events,
 411      <b>collections</b> with a rich API of enumerable functions,
 412      <b>views</b> with declarative event handling, and connects it all to your
 413      existing API over a RESTful JSON interface.
 414    </p>
 415
 416    <p>
 417      The project is <a href="http://github.com/documentcloud/backbone/">hosted on GitHub</a>,
 418      and the <a href="docs/backbone.html">annotated source code</a> is available,
 419      as well as an online <a href="test/test.html">test suite</a>,
 420      an <a href="examples/todos/index.html">example application</a>,
 421      a <a href="https://github.com/documentcloud/backbone/wiki/Tutorials%2C-blog-posts-and-example-sites">list of tutorials</a>
 422      and a <a href="#examples">long list of real-world projects</a> that use Backbone.
 423      Backbone is available for use under the <a href="http://github.com/documentcloud/backbone/blob/master/LICENSE">MIT software license</a>.
 424    </p>
 425
 426    <p>
 427      You can report bugs and discuss features on the
 428      <a href="http://github.com/documentcloud/backbone/issues">GitHub issues page</a>,
 429      on Freenode IRC in the <tt>#documentcloud</tt> channel, post questions to the
 430      <a href="https://groups.google.com/forum/#!forum/backbonejs">Google Group</a>,
 431      add pages to the <a href="https://github.com/documentcloud/backbone/wiki">wiki</a>
 432      or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>.
 433    </p>
 434
 435    <p>
 436      <i>
 437        Backbone is an open-source component of
 438        <a href="http://documentcloud.org/">DocumentCloud</a>.
 439      </i>
 440    </p>
 441
 442    <h2 id="downloads">
 443      Downloads &amp; Dependencies
 444      <span style="padding-left: 7px; font-size:11px; font-weight: normal;" class="interface">(Right-click, and use "Save As")</span>
 445    </h2>
 446
 447    <table>
 448      <tr>
 449        <td><a class="punch" href="backbone.js">Development Version (0.9.1)</a></td>
 450        <td><i>47kb, Full source, lots of comments</i></td>
 451      </tr>
 452      <tr>
 453        <td><a class="punch" href="backbone-min.js">Production Version (0.9.1)</a></td>
 454        <td><i>5.3kb, Packed and gzipped</i></td>
 455      </tr>
 456    </table>
 457
 458    <p>
 459      Backbone's only hard dependency is
 460      <a href="http://documentcloud.github.com/underscore/">Underscore.js</a> <small>( > 1.3.1)</small>.
 461      For RESTful persistence, history support via <a href="#Router">Backbone.Router</a>
 462      and DOM manipulation with <a href="#View">Backbone.View</a>, include
 463      <a href="https://github.com/douglascrockford/JSON-js">json2.js</a>, and either
 464      <a href="http://jquery.com">jQuery</a> <small>( > 1.4.2)</small> or
 465      <a href="http://zeptojs.com/">Zepto</a>.
 466    </p>
 467
 468    <h2 id="introduction">Introduction</h2>
 469
 470    <p>
 471      When working on a web application that involves a lot of JavaScript, one
 472      of the first things you learn is to stop tying your data to the DOM. It's all
 473      too easy to create JavaScript applications that end up as tangled piles of
 474      jQuery selectors and callbacks, all trying frantically to keep data in
 475      sync between the HTML UI, your JavaScript logic, and the database on your
 476      server. For rich client-side applications, a more structured approach
 477      is often helpful.
 478    </p>
 479
 480    <p>
 481      With Backbone, you represent your data as
 482      <a href="#Model">Models</a>, which can be created, validated, destroyed,
 483      and saved to the server. Whenever a UI action causes an attribute of
 484      a model to change, the model triggers a <i>"change"</i> event; all
 485      the <a href="#View">Views</a> that display the model's state can be notified of the
 486      change, so that they are able to respond accordingly, re-rendering themselves with
 487      the new information. In a finished Backbone app, you don't have to write the glue
 488      code that looks into the DOM to find an element with a specific <i>id</i>,
 489      and update the HTML manually
 490      &mdash; when the model changes, the views simply update themselves.
 491    </p>
 492
 493    <p>
 494      If you're new here, and aren't yet quite sure what Backbone is for, start by
 495      browsing the <a href="#examples">list of Backbone-based projects</a>.
 496    </p>
 497
 498    <p>
 499      Many of the examples that follow are runnable. Click the <i>play</i> button
 500      to execute them.
 501    </p>
 502
 503    <h2 id="upgrading">Upgrading to 0.9</h2>
 504
 505    <p>
 506      Backbone's <b>0.9</b> series should be considered as a release candidate
 507      for an upcoming <b>1.0</b>. Some APIs have changed, and while there is a
 508      <a href="#changelog">change log</a> available, and many new features to
 509      take advantage of, there are a few specific changes where you'll need
 510      to take care:
 511    </p>
 512
 513    <ul>
 514      <li>
 515        If you've ever manually set <tt>this.el</tt> in a Backbone View to be a
 516        particular DOM element, you'll want to use
 517        <a href="#View-setElement">setElement</a> instead.
 518      </li>
 519      <li>
 520        Creating and destroying models is now optimistic. Pass <tt>{wait: true}</tt>
 521        if you need the previous behavior of waiting for the server to acknowledge
 522        success. You can now also pass <tt>{wait: true}</tt> to <a href="#Model-save">save</a> calls.
 523      </li>
 524      <li>
 525        If you have been writing a fair amount of <tt>$(view.el)</tt>, there's now
 526        a cached reference for that jQuery object: <a href="#View-$el">$el</a>.
 527      </li>
 528      <li>
 529        If you're upgrading, make sure you also upgrade your version of Underscore.js
 530        to the latest &mdash; 1.3.1 or greater.
 531      </li>
 532      <li>
 533        <tt>model.set</tt> will no longer trigger change events when setting a value
 534        with <tt>{silent: true}</tt> then setting it back to its original value.
 535        Similarly, after changing an attribute silently, that <tt>change:attribute</tt>
 536        event <i>will</i> fire during the next change.
 537      </li>
 538      <li>
 539        Since <tt>view.$(selector)</tt> is now equivalent to <tt>view.$el.find(selector)</tt>
 540        rather than <tt>$(selector, view.el)</tt> it can no longer be used when
 541        <tt>selector</tt> is an HTML string or DOM element.
 542      </li>
 543    </ul>
 544
 545    <h2 id="Events">Backbone.Events</h2>
 546
 547    <p>
 548      <b>Events</b> is a module that can be mixed in to any object, giving the
 549      object the ability to bind and trigger custom named events. Events do not
 550      have to be declared before they are bound, and may take passed arguments.
 551      For example:
 552    </p>
 553
 554<pre class="runnable">
 555var object = {};
 556
 557_.extend(object, Backbone.Events);
 558
 559object.on("alert", function(msg) {
 560  alert("Triggered " + msg);
 561});
 562
 563object.trigger("alert", "an event");
 564</pre>
 565
 566    <p>
 567      For example, to make a handy event dispatcher that can coordinate events
 568      among different areas of your application: <tt>var dispatcher = _.clone(Backbone.Events)</tt>
 569    </p>
 570
 571    <p id="Events-on">
 572      <b class="header">on</b><code>object.on(event, callback, [context])</code><span class="alias">Alias: bind</span>
 573      <br />
 574      Bind a <b>callback</b> function to an object. The callback will be invoked
 575      whenever the <b>event</b> is fired.
 576      If you have a large number of different events on a page, the convention is to use colons to
 577      namespace them: <tt>"poll:start"</tt>, or <tt>"change:selection"</tt>.
 578      The event string may also be a space-delimited list of several events...
 579    </p>
 580
 581<pre>
 582book.on("change:title change:author", ...);
 583</pre>
 584
 585    <p>
 586      To supply a <b>context</b> value for <tt>this</tt> when the callback is invoked,
 587      pass the optional third argument: <tt>model.on('change', this.render, this)</tt>
 588    </p>
 589
 590    <p>
 591      Callbacks bound to the special
 592      <tt>"all"</tt> event will be triggered when any event occurs, and are passed
 593      the name of the event as the first argument. For example, to proxy all events
 594      from one object to another:
 595    </p>
 596
 597<pre>
 598proxy.on("all", function(eventName) {
 599  object.trigger(eventName);
 600});
 601</pre>
 602
 603    <p id="Events-off">
 604      <b class="header">off</b><code>object.off([event], [callback], [context])</code><span class="alias">Alias: unbind</span>
 605      <br />
 606      Remove a previously-bound <b>callback</b> function from an object. If no
 607      <b>context</b> is specified, all of the versions of the callback with
 608      different contexts will be removed. If no
 609      callback is specified, all callbacks for the <b>event</b> will be
 610      removed. If no event is specified, <i>all</i> event callbacks on the object
 611      will be removed.
 612    </p>
 613
 614<pre>
 615object.off("change", onChange);  // Removes just the onChange callback.
 616
 617object.off("change");            // Removes all "change" callbacks.
 618
 619object.off();                    // Removes all callbacks on object.
 620</pre>
 621
 622    <p id="Events-trigger">
 623      <b class="header">trigger</b><code>object.trigger(event, [*args])</code>
 624      <br />
 625      Trigger callbacks for the given <b>event</b>, or space-delimited list of events.
 626      Subsequent arguments to <b>trigger</b> will be passed along to the
 627      event callbacks.
 628    </p>
 629
 630    <h2 id="Model">Backbone.Model</h2>
 631
 632    <p>
 633      <b>Models</b> are the heart of any JavaScript application, containing
 634      the interactive data as well as a large part of the logic surrounding it:
 635      conversions, validations, computed properties, and access control. You
 636      extend <b>Backbone.Model</b> with your domain-specific methods, and
 637      <b>Model</b> provides a basic set of functionality for managing changes.
 638    </p>
 639
 640    <p>
 641      The following is a contrived example, but it demonstrates defining a model
 642      with a custom method, setting an attribute, and firing an event keyed
 643      to changes in that specific attribute.
 644      After running this code once, <tt>sidebar</tt> will be
 645      available in your browser's console, so you can play around with it.
 646    </p>
 647
 648<pre class="runnable">
 649var Sidebar = Backbone.Model.extend({
 650  promptColor: function() {
 651    var cssColor = prompt("Please enter a CSS color:");
 652    this.set({color: cssColor});
 653  }
 654});
 655
 656window.sidebar = new Sidebar;
 657
 658sidebar.on('change:color', function(model, color) {
 659  $('#sidebar').css({background: color});
 660});
 661
 662sidebar.set({color: 'white'});
 663
 664sidebar.promptColor();
 665</pre>
 666
 667    <p id="Model-extend">
 668      <b class="header">extend</b><code>Backbone.Model.extend(properties, [classProperties])</code>
 669      <br />
 670      To create a <b>Model</b> class of your own, you extend <b>Backbone.Model</b>
 671      and provide instance <b>properties</b>, as well as optional
 672      <b>classProperties</b> to be attached directly to the constructor function.
 673    </p>
 674
 675    <p>
 676      <b>extend</b> correctly sets up the prototype chain, so subclasses created
 677      with <b>extend</b> can be further extended and subclassed as far as you like.
 678    </p>
 679
 680<pre>
 681var Note = Backbone.Model.extend({
 682
 683  initialize: function() { ... },
 684
 685  author: function() { ... },
 686
 687  coordinates: function() { ... },
 688
 689  allowedToEdit: function(account) {
 690    return true;
 691  }
 692
 693});
 694
 695var PrivateNote = Note.extend({
 696
 697  allowedToEdit: function(account) {
 698    return account.owns(this);
 699  }
 700
 701});
 702</pre>
 703
 704    <p class="warning">
 705        Brief aside on <tt>super</tt>: JavaScript does not provide
 706        a simple way to call super &mdash; the function of the same name defined
 707        higher on the prototype chain. If you override a core function like
 708        <tt>set</tt>, or <tt>save</tt>, and you want to invoke the
 709        parent object's implementation, you'll have to explicitly call it, along these lines:
 710    </p>
 711
 712<pre>
 713var Note = Backbone.Model.extend({
 714  set: function(attributes, options) {
 715    Backbone.Model.prototype.set.call(this, attributes, options);
 716    ...
 717  }
 718});
 719</pre>
 720
 721    <p id="Model-constructor">
 722      <b class="header">constructor / initialize</b><code>new Model([attributes])</code>
 723      <br />
 724      When creating an instance of a model, you can pass in the initial values
 725      of the <b>attributes</b>, which will be <a href="#Model-set">set</a> on the
 726      model. If you define an <b>initialize</b> function, it will be invoked when
 727      the model is created.
 728    </p>
 729
 730<pre>
 731new Book({
 732  title: "One Thousand and One Nights",
 733  author: "Scheherazade"
 734});
 735</pre>
 736
 737    <p>
 738      In rare cases, if you're looking to get fancy,
 739      you may want to override <b>constructor</b>, which allows
 740      you to replace the actual constructor function for your model.
 741    </p>
 742
 743    <p id="Model-get">
 744      <b class="header">get</b><code>model.get(attribute)</code>
 745      <br />
 746      Get the current value of an attribute from the model. For example:
 747      <tt>note.get("title")</tt>
 748    </p>
 749
 750    <p id="Model-set">
 751      <b class="header">set</b><code>model.set(attributes, [options])</code>
 752      <br />
 753      Set a hash of attributes (one or many) on the model. If any of the attributes
 754      change the models state, a <tt>"change"</tt> event will be triggered, unless
 755      <tt>{silent: true}</tt> is passed as an option. Change events for specific
 756      attributes are also triggered, and you can bind to those as well, for example:
 757      <tt>change:title</tt>, and <tt>change:content</tt>. You may also pass
 758      individual keys and values.
 759    </p>
 760
 761<pre>
 762note.set({title: "March 20", content: "In his eyes she eclipses..."});
 763
 764book.set("title", "A Scandal in Bohemia");
 765</pre>
 766
 767    <p>
 768      If the model has a <a href="#Model-validate">validate</a> method,
 769      it will be validated before the attributes are set, no changes will
 770      occur if the validation fails, and <b>set</b> will return <tt>false</tt>.
 771      Otherwise, <b>set</b> returns a reference to the model.
 772      You may also pass an <tt>error</tt>
 773      callback in the options, which will be invoked instead of triggering an
 774      <tt>"error"</tt> event, should validation fail.
 775    </p>
 776
 777    <p id="Model-escape">
 778      <b class="header">escape</b><code>model.escape(attribute)</code>
 779      <br />
 780      Similar to <a href="#Model-get">get</a>, but returns the HTML-escaped version
 781      of a model's attribute. If you're interpolating data from the model into
 782      HTML, using <b>escape</b> to retrieve attributes will prevent
 783      <a href="http://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a> attacks.
 784    </p>
 785
 786<pre class="runnable">
 787var hacker = new Backbone.Model({
 788  name: "&lt;script&gt;alert('xss')&lt;/script&gt;"
 789});
 790
 791alert(hacker.escape('name'));
 792</pre>
 793
 794    <p id="Model-has">
 795      <b class="header">has</b><code>model.has(attribute)</code>
 796      <br />
 797      Returns <tt>true</tt> if the attribute is set to a non-null or non-undefined
 798      value.
 799    </p>
 800
 801<pre>
 802if (note.has("title")) {
 803  ...
 804}
 805</pre>
 806
 807    <p id="Model-unset">
 808      <b class="header">unset</b><code>model.unset(attribute, [options])</code>
 809      <br />
 810      Remove an attribute by deleting it from the internal attributes hash.
 811      Fires a <tt>"change"</tt> event unless <tt>silent</tt> is passed as an option.
 812    </p>
 813
 814    <p id="Model-clear">
 815      <b class="header">clear</b><code>model.clear([options])</code>
 816      <br />
 817      Removes all attributes from the model. Fires a <tt>"change"</tt> event unless
 818      <tt>silent</tt> is passed as an option.
 819    </p>
 820
 821    <p id="Model-id">
 822      <b class="header">id</b><code>model.id</code>
 823      <br />
 824      A special property of models, the <b>id</b> is an arbitrary string
 825      (integer id or UUID). If you set the <b>id</b> in the
 826      attributes hash, it will be copied onto the model as a direct property.
 827      Models can be retrieved by id from collections, and the id is used to generate
 828      model URLs by default.
 829    </p>
 830
 831    <p id="Model-idAttribute">
 832      <b class="header">idAttribute</b><code>model.idAttribute</code>
 833      <br />
 834      A model's unique identifier is stored under the <tt>id</tt> attribute.
 835      If you're directly communicating with a backend (CouchDB, MongoDB) that uses
 836      a different unique key, you may set a Model's <tt>idAttribute</tt> to
 837      transparently map from that key to <tt>id</tt>.
 838
 839<pre class="runnable">
 840var Meal = Backbone.Model.extend({
 841  idAttribute: "_id"
 842});
 843
 844var cake = new Meal({ _id: 1, name: "Cake" });
 845alert("Cake id: " + cake.id);
 846</pre>
 847    </p>
 848
 849    <p id="Model-cid">
 850      <b class="header">cid</b><code>model.cid</code>
 851      <br />
 852      A special property of models, the <b>cid</b> or client id is a unique identifier
 853      automatically assigned to all models when they're first created. Client ids
 854      are handy when the model has not yet been saved to the server, and does not
 855      yet have its eventual true <b>id</b>, but already needs to be visible in the UI.
 856      Client ids take the form: <tt>c1, c2, c3 ...</tt>
 857    </p>
 858
 859    <p id="Model-attributes">
 860      <b class="header">attributes</b><code>model.attributes</code>
 861      <br />
 862      The <b>attributes</b> property is the internal hash containing the model's
 863      state. Please use <a href="#Model-set">set</a> to update the attributes instead of modifying
 864      them directly. If you'd like to retrieve and munge a copy of the model's
 865      attributes, use <a href="#Model-toJSON">toJSON</a> instead.
 866    </p>
 867
 868    <p id="Model-changed">
 869      <b class="header">changed</b><code>model.changed</code>
 870      <br />
 871      The <b>changed</b> property is the internal hash containing all the attributes
 872      that have changed since the last <tt>"change"</tt> event was triggered.
 873      Please do not update <b>changed</b> directly.  Its state is maintained internally
 874      by <a href="#Model-set">set</a> and <a href="#Model-change">change</a>.
 875      A copy of <b>changed</b> can be acquired from
 876      <a href="#Model-changedAttributes">changedAttributes</a>.
 877    </p>
 878
 879    <p id="Model-defaults">
 880      <b class="header">defaults</b><code>model.defaults or model.defaults()</code>
 881      <br />
 882      The <b>defaults</b> hash (or function) can be used to specify the default
 883      attributes for your model. When creating an instance of the model,
 884      any unspecified attributes will be set to their default value.
 885    </p>
 886
 887<pre class="runnable">
 888var Meal = Backbone.Model.extend({
 889  defaults: {
 890    "appetizer":  "caesar salad",
 891    "entree":     "ravioli",
 892    "dessert":    "cheesecake"
 893  }
 894});
 895
 896alert("Dessert will be " + (new Meal).get('dessert'));
 897</pre>
 898
 899    <p class="warning">
 900      Remember that in JavaScript, objects are passed by reference, so if you
 901      include an object as a default value, it will be shared among all instances.
 902    </p>
 903
 904    <p id="Model-toJSON">
 905      <b class="header">toJSON</b><code>model.toJSON()</code>
 906      <br />
 907      Return a copy of the model's <a href="#Model-attributes">attributes</a> for JSON stringification.
 908      This can be used for persistence, serialization, or for augmentation before
 909      being handed off to a view. The name of this method is a bit confusing, as
 910      it doesn't actually return a JSON string &mdash; but I'm afraid that it's
 911      the way that the <a href="https://developer.mozilla.org/en/JSON#toJSON()_method">JavaScript API for <b>JSON.stringify</b> works</a>.
 912    </p>
 913
 914<pre class="runnable">
 915var artist = new Backbone.Model({
 916  firstName: "Wassily",
 917  lastName: "Kandinsky"
 918});
 919
 920artist.set({birthday: "December 16, 1866"});
 921
 922alert(JSON.stringify(artist));
 923</pre>
 924
 925    <p id="Model-fetch">
 926      <b class="header">fetch</b><code>model.fetch([options])</code>
 927      <br />
 928      Resets the model's state from the server. Useful if the model has never
 929      been populated with data, or if you'd like to ensure that you have the
 930      latest server state. A <tt>"change"</tt> event will be triggered if the
 931      server's state differs from the current attributes. Accepts
 932      <tt>success</tt> and <tt>error</tt> callbacks in the options hash, which
 933      are passed <tt>(model, response)</tt> as arguments.
 934    </p>
 935
 936<pre>
 937// Poll every 10 seconds to keep the channel model up-to-date.
 938setInterval(function() {
 939  channel.fetch();
 940}, 10000);
 941</pre>
 942
 943    <p id="Model-save">
 944      <b class="header">save</b><code>model.save([attributes], [options])</code>
 945      <br />
 946      Save a model to your database (or alternative persistence layer),
 947      by delegating to <a href="#Sync">Backbone.sync</a>. The <b>attributes</b>
 948      hash (as in <a href="#Model-set">set</a>) should contain the attributes
 949      you'd like to change &mdash; keys that aren't mentioned won't be altered &mdash; but,
 950      a <i>complete representation</i> of the resource will be sent to the server.
 951      As with <tt>set</tt>, you may pass individual keys and values instead of a hash.
 952      If the model has a <a href="#Model-validate">validate</a>
 953      method, and validation fails, the model will not be saved. If the model
 954      <a href="#Model-isNew">isNew</a>, the save will be a <tt>"create"</tt>
 955      (HTTP <tt>POST</tt>), if the model already
 956      exists on the server, the save will be an <tt>"update"</tt> (HTTP <tt>PUT</tt>).
 957    </p>
 958
 959    <p>
 960      Calling <tt>save</tt> with new attributes will cause a <tt>"change"</tt>
 961      event immediately, and a <tt>"sync"</tt> event after the server has acknowledged
 962      the successful change. Pass <tt>{wait: true}</tt> if you'd like to wait
 963      for the server before setting the new attributes on the model.
 964    </p>
 965
 966    <p>
 967      In the following example, notice how our overridden version
 968      of <tt>Backbone.sync</tt> receives a <tt>"create"</tt> request
 969      the first time the model is saved and an <tt>"update"</tt>
 970      request the second time.
 971    </p>
 972
 973<pre class="runnable">
 974Backbone.sync = function(method, model) {
 975  alert(method + ": " + JSON.stringify(model));
 976  model.id = 1;
 977};
 978
 979var book = new Backbone.Model({
 980  title: "The Rough Riders",
 981  author: "Theodore Roosevelt"
 982});
 983
 984book.save();
 985
 986book.save({author: "Teddy"});
 987</pre>
 988
 989    <p>
 990      <b>save</b> accepts <tt>success</tt> and <tt>error</tt> callbacks in the
 991      options hash, which are passed <tt>(model, response)</tt> as arguments.
 992      The <tt>error</tt> callback will also be invoked if the model has a
 993      <tt>validate</tt> method, and validation fails. If a server-side
 994      validation fails, return a non-<tt>200</tt> HTTP response code, along with
 995      an error response in text or JSON.
 996    </p>
 997
 998<pre>
 999book.save("author", "F.D.R.", {error: function(){ ... }});
1000</pre>
1001
1002    <p id="Model-destroy">
1003      <b class="header">destroy</b><code>model.destroy([options])</code>
1004      <br />
1005      Destroys the model on the server by delegating an HTTP <tt>DELETE</tt>
1006      request to <a href="#Sync">Backbone.sync</a>. Accepts
1007      <tt>success</tt> and <tt>error</tt> callbacks in the options hash.
1008      Triggers a <tt>"destroy"</tt> event on the model, which will bubble up
1009      through any collections that contain it, and a <tt>"sync"</tt> event, after
1010      the server has successfully acknowledged the model's deletion. Pass
1011      <tt>{wait: true}</tt> if you'd like to wait for the server to respond
1012      before removing the model from the collection.
1013    </p>
1014
1015<pre>
1016book.destroy({success: function(model, response) {
1017  ...
1018}});
1019</pre>
1020
1021    <p id="Model-validate">
1022      <b class="header">validate</b><code>model.validate(attributes)</code>
1023      <br />
1024      This method is left undefined, and you're encouraged to override it with
1025      your custom validation logic, if you have any that can be performed
1026      in JavaScript. <b>validate</b> is called before <tt>set</tt> and
1027      <tt>save</tt>, and is passed the attributes that are about to be updated.
1028      If the model and attributes are valid, don't return anything from <b>validate</b>;
1029      if the attributes are invalid, return an error of your choosing. It
1030      can be as simple as a string error message to be displayed, or a complete
1031      error object that describes the error programmatically. <tt>set</tt> and
1032      <tt>save</tt> will not continue if <b>validate</b> returns an error.
1033      Failed validations trigger an <tt>"error"</tt> event.
1034    </p>
1035
1036<pre class="runnable">
1037var Chapter = Backbone.Model.extend({
1038  validate: function(attrs) {
1039    if (attrs.end < attrs.start) {
1040      return "can't end before it starts";
1041    }
1042  }
1043});
1044
1045var one = new Chapter({
1046  title : "Chapter One: The Beginning"
1047});
1048
1049one.on("error", function(model, error) {
1050  alert(model.get("title") + " " + error);
1051});
1052
1053one.set({
1054  start: 15,
1055  end:   10
1056});
1057</pre>
1058
1059    <p>
1060      <tt>"error"</tt> events are useful for providing coarse-grained error
1061      messages at the model or collection level, but if you have a specific view
1062      that can better handle the error, you may override and suppress the event
1063      by passing an <tt>error</tt> callback directly:
1064    </p>
1065
1066<pre>
1067account.set({access: "unlimited"}, {
1068  error: function(model, error) {
1069    alert(error);
1070  }
1071});
1072</pre>
1073
1074    <p id="Model-isValid">
1075      <b class="header">isValid</b><code>model.isValid()</code>
1076      <br />
1077      Models may enter an invalid state if you make changes to them silently
1078      ... useful when dealing with form input. Call <tt>model.isValid()</tt>
1079      to check if the model is currently in a valid state, according to your
1080      <tt>validate</tt> function.
1081    </p>
1082
1083    <p id="Model-url">
1084      <b class="header">url</b><code>model.url()</code>
1085      <br />
1086      Returns the relative URL where the model's resource would be located on
1087      the server. If your models are located somewhere else, override this method
1088      with the correct logic. Generates URLs of the form: <tt>"/[collection.url]/[id]"</tt>,
1089      falling back to <tt>"/[urlRoot]/id"</tt> if the model is not part of a collection.
1090    </p>
1091
1092    <p>
1093      Delegates to <a href="#Collection-url">Collection#url</a> to generate the
1094      URL, so make sure that you have it defined, or a <a href="#Model-urlRoot">urlRoot</a>
1095      property, if all models of this class share a common root URL.
1096      A model with an id of <tt>101</tt>, stored in a
1097      <a href="#Collection">Backbone.Collection</a> with a <tt>url</tt> of <tt>"/documents/7/notes"</tt>,
1098      would have this URL: <tt>"/documents/7/notes/101"</tt>
1099    </p>
1100
1101    <p id="Model-urlRoot">
1102      <b class="header">urlRoot</b><code>model.urlRoot or model.urlRoot()</code>
1103      <br />
1104      Specify a <tt>urlRoot</tt> if you're using a model outside of a collection,
1105      to enable the default <a href="#Model-url">url</a> function to generate
1106      URLs based on the model id. <tt>"/[urlRoot]/id"</tt><br />
1107      Note that <tt>urlRoot</tt> may also be defined as a function.
1108    </p>
1109
1110<pre class="runnable">
1111var Book = Backbone.Model.extend({urlRoot : '/books'});
1112
1113var solaris = new Book({id: "1083-lem-solaris"});
1114
1115alert(solaris.url());
1116</pre>
1117
1118    <p id="Model-parse">
1119      <b class="header">parse</b><code>model.parse(response)</code>
1120      <br />
1121      <b>parse</b> is called whenever a model's data is returned by the
1122      server, in <a href="#Model-fetch">fetch</a>, and <a href="#Model-save">save</a>.
1123      The function is passed the raw <tt>response</tt> object, and should return
1124      the attributes hash to be <a href="#Model-set">set</a> on the model. The
1125      default implementation is a no-op, simply passing through the JSON response.
1126      Override this if you need to work with a preexisting API, or better namespace
1127      your responses.
1128    </p>
1129
1130    <p>
1131      If you're working with a Rails backend, you'll notice that Rails' default
1132      <tt>to_json</tt> implementation includes a model's attributes under a
1133      namespace. To disable this behavior for seamless Backbone integration, set:
1134    </p>
1135
1136<pre>
1137ActiveRecord::Base.include_root_in_json = false
1138</pre>
1139
1140    <p id="Model-clone">
1141      <b class="header">clone</b><code>model.clone()</code>
1142      <br />
1143      Returns a new instance of the model with identical attributes.
1144    </p>
1145
1146    <p id="Model-isNew">
1147      <b class="header">isNew</b><code>model.isNew()</code>
1148      <br />
1149      Has this model been saved to the server yet? If the model does not yet have
1150      an <tt>id</tt>, it is considered to be new.
1151    </p>
1152
1153    <p id="Model-change">
1154      <b class="header">change</b><code>model.change()</code>
1155      <br />
1156      Manually trigger the <tt>"change"</tt> event and a <tt>"change:attribute"</tt>
1157      event for each attribute that has changed. If you've been passing
1158      <tt>{silent: true}</tt> to the <a href="#Model-set">set</a> function in order to
1159      aggregate rapid changes to a model, you'll want to call <tt>model.change()</tt>
1160      when you're all finished.
1161    </p>
1162
1163    <p id="Model-hasChanged">
1164      <b class="header">hasChanged</b><code>model.hasChanged([attribute])</code>
1165      <br />
1166      Has the model changed since the last <tt>"change"</tt> event? If an <b>attribute</b>
1167      is passed, returns <tt>true</tt> if that specific attribute has changed.
1168    </p>
1169
1170    <p class="warning">
1171      Note that this method, and the following change-related ones,
1172      are only useful during the course of a <tt>"change"</tt> event.
1173    </p>
1174
1175<pre>
1176book.on("change", function() {
1177  if (book.hasChanged("title")) {
1178    ...
1179  }
1180});
1181</pre>
1182
1183    <p id="Model-changedAttributes">
1184      <b class="header">changedAttributes</b><code>model.changedAttributes([attributes])</code>
1185      <br />
1186      Retrieve a hash of only the model's attributes that have changed. Optionally,
1187      an external <b>attributes</b> hash can be passed in, returning
1188      the attributes in that hash which differ from the model. This can be used
1189      to figure out which portions of a view should be updated, or what calls
1190      need to be made to sync the changes to the server.
1191    </p>
1192
1193    <p id="Model-previous">
1194      <b class="header">previous</b><code>model.previous(attribute)</code>
1195      <br />
1196      During a <tt>"change"</tt> event, this method can be used to get the
1197      previous value of a changed attribute.
1198    </p>
1199
1200<pre class="runnable">
1201var bill = new Backbone.Model({
1202  name: "Bill Smith"
1203});
1204
1205bill.on("change:name", function(model, name) {
1206  alert("Changed name from " + bill.previous("name") + " to " + name);
1207});
1208
1209bill.set({name : "Bill Jones"});
1210</pre>
1211
1212    <p id="Model-previousAttributes">
1213      <b class="header">previousAttributes</b><code>model.previousAttributes()</code>
1214      <br />
1215      Return a copy of the model's previous attributes. Useful for getting a
1216      diff between versions of a model, or getting back to a valid state after
1217      an error occurs.
1218    </p>
1219
1220    <h2 id="Collection">Backbone.Collection</h2>
1221
1222    <p>
1223      Collections are ordered sets of models. You can bind <tt>"change"</tt> events
1224      to be notified when any model in the collection has been modified,
1225      listen for <tt>"add"</tt> and <tt>"remove"</tt> events, <tt>fetch</tt>
1226      the collection from the server, and use a full suite of
1227      <a href="#Collection-Underscore-Methods">Underscore.js methods</a>.
1228    </p>
1229
1230    <p>
1231      Any event that is triggered on a model in a collection will also be
1232      triggered on the collection directly, for convenience.
1233      This allows you to listen for changes to specific attributes in any
1234      model in a collection, for example:
1235      <tt>Documents.on("change:selected", ...)</tt>
1236    </p>
1237
1238    <p id="Collection-extend">
1239      <b class="header">extend</b><code>Backbone.Collection.extend(properties, [classProperties])</code>
1240      <br />
1241      To create a <b>Collection</b> class of your own, extend <b>Backbone.Collection</b>,
1242      providing instance <b>properties</b>, as well as optional <b>classProperties</b> to be attached
1243      directly to the collection's constructor function.
1244    </p>
1245
1246    <p id="Collection-model">
1247      <b class="header">model</b><code>collection.model</code>
1248      <br />
1249      Override this property to specify the model class that the collection
1250      contains. If defined, you can pass raw attributes objects (and arrays) to
1251      <a href="#Collection-add">add</a>, <a href="#Collection-create">create</a>,
1252      and <a href="#Collection-reset">reset</a>, and the attributes will be
1253      converted into a model of the proper type.
1254    </p>
1255
1256<pre>
1257var Library = Backbone.Collection.extend({
1258  model: Book
1259});
1260</pre>
1261
1262    <p id="Collection-constructor">
1263      <b class="header">constructor / initialize</b><code>new Collection([models], [options])</code>
1264      <br />
1265      When creating a Collection, you may choose to pass in the initial array of <b>models</b>.
1266      The collection's <a href="#Collection-comparator">comparator</a> function
1267      may be included as an option. If you define an <b>initialize</b> function, it will be
1268      invoked when the collection is created.
1269    </p>
1270
1271<pre>
1272var tabs = new TabSet([tab1, tab2, tab3]);
1273</pre>
1274
1275    <p id="Collection-models">
1276      <b class="header">models</b><code>collection.models</code>
1277      <br />
1278      Raw access to the JavaScript array of models inside of the collection. Usually you'll
1279      want to use <tt>get</tt>, <tt>at</tt>, or the <b>Underscore methods</b>
1280      to access model objects, but occasionally a direct reference to the array
1281      is desired.
1282    </p>
1283
1284    <p id="Collection-toJSON">
1285      <b class="header">toJSON</b><code>collection.toJSON()</code>
1286      <br />
1287      Return an array containing the attributes hash of each model in the
1288      collection. This can be used to serialize and persist the
1289      collection as a whole. The name of this method is a bit confusing, because
1290      it conforms to
1291      <a href="https://developer.mozilla.org/en/JSON#toJSON()_method">JavaScript's JSON API</a>.
1292    </p>
1293
1294<pre class="runnable">
1295var collection = new Backbone.Collection([
1296  {name: "Tim", age: 5},
1297  {name: "Ida", age: 26},
1298  {name: "Rob", age: 55}
1299]);
1300
1301alert(JSON.stringify(collection));
1302</pre>
1303
1304    <p id="Collection-Underscore-Methods">
1305      <b class="header">Underscore Methods (28)</b>
1306      <br />
1307      Backbone proxies to <b>Underscore.js</b> to provide 28 iteration functions
1308      on <b>Backbone.Collection</b>. They aren't all documented here, but
1309      you can take a look at the Underscore documentation for the full details&hellip;
1310    </p>
1311
1312    <ul class="small">
1313      <li><a href="http://documentcloud.github.com/underscore/#each">forEach (each)</a></li>
1314      <li><a href="http://documentcloud.github.com/underscore/#map">map</a></li>
1315      <li><a href="http://documentcloud.github.com/underscore/#reduce">reduce (foldl, inject)</a></li>
1316      <li><a href="http://documentcloud.github.com/underscore/#reduceRight">reduceRight (foldr)</a></li>
1317      <li><a href="http://documentcloud.github.com/underscore/#detect">find (detect)</a></li>
1318      <li><a href="http://documentcloud.github.com/underscore/#select">filter (select)</a></li>
1319      <li><a href="http://documentcloud.github.com/underscore/#reject">reject</a…

Large files files are truncated, but you can click here to view the full file