PageRenderTime 62ms CodeModel.GetById 3ms app.highlight 34ms RepoModel.GetById 13ms app.codeStats 0ms

/index.html

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

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