PageRenderTime 209ms CodeModel.GetById 100ms app.highlight 74ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

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

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