PageRenderTime 67ms CodeModel.GetById 3ms app.highlight 50ms RepoModel.GetById 1ms app.codeStats 1ms

/ch12/index.html

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

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