PageRenderTime 10ms CodeModel.GetById 4ms app.highlight 34ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

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

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