PageRenderTime 11ms CodeModel.GetById 2ms app.highlight 45ms RepoModel.GetById 1ms app.codeStats 1ms

/index.html

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

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