PageRenderTime 49ms CodeModel.GetById 4ms app.highlight 30ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

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

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