/index.html
HTML | 2979 lines | 2548 code | 431 blank | 0 comment | 0 complexity | b69705de982d09979ee460e7c7e96db9 MD5 | raw file
- <!DOCTYPE HTML>
- <html>
- <head>
- <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
- <meta http-equiv="X-UA-Compatible" content="chrome=1">
- <title>Backbone.js</title>
- <style>
- body {
- font-size: 14px;
- line-height: 22px;
- font-family: Helvetica Neue, Helvetica, Arial;
- background: #f4f4f4 url(docs/images/background.png);
- }
- .interface {
- font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, sans-serif !important;
- }
- div#sidebar {
- background: #fff;
- position: fixed;
- top: 0; left: 0; bottom: 0;
- width: 200px;
- overflow-y: auto;
- overflow-x: hidden;
- padding: 15px 0 30px 30px;
- border-right: 1px solid #ddd;
- box-shadow: 0 0 20px #ccc; -webkit-box-shadow: 0 0 20px #ccc; -moz-box-shadow: 0 0 20px #ccc;
- }
- a.toc_title, a.toc_title:visited {
- display: block;
- color: black;
- font-weight: bold;
- margin-top: 15px;
- }
- a.toc_title:hover {
- text-decoration: underline;
- }
- #sidebar .version {
- font-size: 10px;
- font-weight: normal;
- }
- ul.toc_section {
- font-size: 11px;
- line-height: 14px;
- margin: 5px 0 0 0;
- padding-left: 0px;
- list-style-type: none;
- font-family: Lucida Grande;
- }
- .toc_section li {
- cursor: pointer;
- margin: 0 0 3px 0;
- }
- .toc_section li a {
- text-decoration: none;
- color: black;
- }
- .toc_section li a:hover {
- text-decoration: underline;
- }
- div.container {
- position: relative;
- width: 550px;
- margin: 40px 0 50px 260px;
- }
- div.run {
- position: absolute;
- right: 15px;
- width: 26px; height: 18px;
- background: url('docs/images/arrows.png') no-repeat -26px 0;
- }
- div.run:active {
- background-position: -51px 0;
- }
- p, div.container ul {
- margin: 20px 0;
- width: 550px;
- }
- p.warning {
- font-size: 12px;
- line-height: 18px;
- font-style: italic;
- }
- div.container ul {
- list-style: circle;
- font-size: 12px;
- padding-left: 15px;
- }
- a, a:visited {
- color: #444;
- }
- a:active, a:hover {
- color: #000;
- }
- a img {
- border: 0;
- }
- h1, h2, h3, h4, h5, h6 {
- padding-top: 20px;
- }
- h2 {
- font-size: 20px;
- }
- b.header {
- font-size: 16px;
- line-height: 30px;
- }
- span.alias {
- font-size: 14px;
- font-style: italic;
- margin-left: 20px;
- }
- table {
- margin: 15px 0 0; padding: 0;
- }
- tr, td {
- margin: 0; padding: 0;
- }
- td {
- padding: 0px 15px 5px 0;
- }
- code, pre, tt {
- font-family: Monaco, Consolas, "Lucida Console", monospace;
- font-size: 12px;
- line-height: 18px;
- font-style: normal;
- }
- tt {
- padding: 0px 3px;
- background: #fff;
- border: 1px solid #ddd;
- zoom: 1;
- }
- code {
- margin-left: 20px;
- }
- pre {
- font-size: 12px;
- padding: 2px 0 2px 15px;
- border: 4px solid #bbb; border-top: 0; border-bottom: 0;
- margin: 0px 0 30px;
- }
- img.example_image {
- margin: 0px auto;
- }
- </style>
- </head>
- <body>
- <div id="sidebar" class="interface">
- <a class="toc_title" href="#">
- Backbone.js <span class="version">(0.5.3)</span>
- </a>
- <a class="toc_title" href="#Introduction">
- Introduction
- </a>
- <a class="toc_title" href="#Events">
- Events
- </a>
- <ul class="toc_section">
- <li>– <a href="#Events-bind">bind</a></li>
- <li>– <a href="#Events-unbind">unbind</a></li>
- <li>– <a href="#Events-trigger">trigger</a></li>
- </ul>
- <a class="toc_title" href="#Model">
- Model
- </a>
- <ul class="toc_section">
- <li>– <a href="#Model-extend">extend</a></li>
- <li>– <a href="#Model-constructor">constructor / initialize</a></li>
- <li>– <a href="#Model-get">get</a></li>
- <li>– <a href="#Model-set">set</a></li>
- <li>– <a href="#Model-escape">escape</a></li>
- <li>– <a href="#Model-has">has</a></li>
- <li>– <a href="#Model-unset">unset</a></li>
- <li>– <a href="#Model-clear">clear</a></li>
- <li>– <a href="#Model-id">id</a></li>
- <li>– <a href="#Model-cid">cid</a></li>
- <li>– <a href="#Model-attributes">attributes</a></li>
- <li>– <a href="#Model-defaults">defaults</a></li>
- <li>- <a href="#Model-toJSON">toJSON</a></li>
- <li>– <a href="#Model-fetch">fetch</a></li>
- <li>– <a href="#Model-save">save</a></li>
- <li>– <a href="#Model-destroy">destroy</a></li>
- <li>– <a href="#Model-validate">validate</a></li>
- <li>– <a href="#Model-url">url</a></li>
- <li>– <a href="#Model-urlRoot">urlRoot</a></li>
- <li>– <a href="#Model-parse">parse</a></li>
- <li>– <a href="#Model-clone">clone</a></li>
- <li>– <a href="#Model-isNew">isNew</a></li>
- <li>– <a href="#Model-change">change</a></li>
- <li>– <a href="#Model-hasChanged">hasChanged</a></li>
- <li>– <a href="#Model-changedAttributes">changedAttributes</a></li>
- <li>– <a href="#Model-previous">previous</a></li>
- <li>– <a href="#Model-previousAttributes">previousAttributes</a></li>
- </ul>
- <a class="toc_title" href="#Collection">
- Collection
- </a>
- <ul class="toc_section">
- <li>– <a href="#Collection-extend">extend</a></li>
- <li>– <a href="#Collection-model">model</a></li>
- <li>– <a href="#Collection-constructor">constructor / initialize</a></li>
- <li>– <a href="#Collection-models">models</a></li>
- <li>– <a href="#Collection-toJSON">toJSON</a></li>
- <li>– <a href="#Collection-Underscore-Methods"><b>Underscore Methods (26)</b></a></li>
- <li>– <a href="#Collection-add">add</a></li>
- <li>– <a href="#Collection-remove">remove</a></li>
- <li>– <a href="#Collection-get">get</a></li>
- <li>– <a href="#Collection-getByCid">getByCid</a></li>
- <li>– <a href="#Collection-at">at</a></li>
- <li>– <a href="#Collection-length">length</a></li>
- <li>– <a href="#Collection-comparator">comparator</a></li>
- <li>– <a href="#Collection-sort">sort</a></li>
- <li>– <a href="#Collection-pluck">pluck</a></li>
- <li>– <a href="#Collection-url">url</a></li>
- <li>– <a href="#Collection-parse">parse</a></li>
- <li>– <a href="#Collection-fetch">fetch</a></li>
- <li>– <a href="#Collection-reset">reset</a></li>
- <li>– <a href="#Collection-create">create</a></li>
- </ul>
- <a class="toc_title" href="#Router">
- Router
- </a>
- <ul class="toc_section">
- <li>– <a href="#Router-extend">extend</a></li>
- <li>– <a href="#Router-routes">routes</a></li>
- <li>– <a href="#Router-constructor">constructor / initialize</a></li>
- <li>– <a href="#Router-route">route</a></li>
- <li>– <a href="#Router-navigate">navigate</a></li>
- </ul>
- <a class="toc_title" href="#History">
- History
- </a>
- <ul class="toc_section">
- <li>– <a href="#History-start">start</a></li>
- </ul>
- <a class="toc_title" href="#Sync">
- Sync
- </a>
- <ul class="toc_section">
- <li>– <a href="#Sync">Backbone.sync</a></li>
- <li>– <a href="#Sync-emulateHTTP">Backbone.emulateHTTP</a></li>
- <li>– <a href="#Sync-emulateJSON">Backbone.emulateJSON</a></li>
- </ul>
- <a class="toc_title" href="#View">
- View
- </a>
- <ul class="toc_section">
- <li>– <a href="#View-extend">extend</a></li>
- <li>– <a href="#View-constructor">constructor / initialize</a></li>
- <li>– <a href="#View-el">el</a></li>
- <li>– <a href="#View-dollar">$ (jQuery or Zepto)</a></li>
- <li>– <a href="#View-render">render</a></li>
- <li>– <a href="#View-remove">remove</a></li>
- <li>– <a href="#View-make">make</a></li>
- <li>– <a href="#View-delegateEvents">delegateEvents</a></li>
- </ul>
- <a class="toc_title" href="#Utility">
- Utility
- </a>
- <ul class="toc_section">
- <li>– <a href="#Utility-noConflict">noConflict</a></li>
- </ul>
- <a class="toc_title" href="#examples">
- Examples
- </a>
- <ul class="toc_section">
- <li>– <a href="#examples-todos">Todos</a></li>
- <li>– <a href="#examples-documentcloud">DocumentCloud</a></li>
- <li>– <a href="#examples-linkedin">LinkedIn Mobile</a></li>
- <li>– <a href="#examples-flow">Flow</a></li>
- <li>– <a href="#examples-basecamp">Basecamp Mobile</a></li>
- <li>– <a href="#examples-groupon">Groupon Now!</a></li>
- <li>– <a href="#examples-trajectory">Trajectory</a></li>
- <li>– <a href="#examples-soundcloud">SoundCloud Mobile</a></li>
- <li>– <a href="#examples-pandora">Pandora</a></li>
- <li>– <a href="#examples-cloudapp">CloudApp</a></li>
- <li>– <a href="#examples-seatgeek">SeatGeek</a></li>
- <li>– <a href="#examples-tpm">Talking Points Memo</a></li>
- <li>– <a href="#examples-kicksend">Kicksend</a></li>
- <li>– <a href="#examples-shortmail">Shortmail</a></li>
- <li>– <a href="#examples-hotel-tonight">Hotel Tonight</a></li>
- <li>– <a href="#examples-salon">Salon.io</a></li>
- <li>– <a href="#examples-quoteroller">Quote Roller</a></li>
- <li>– <a href="#examples-tilemill">TileMill</a></li>
- <li>– <a href="#examples-rround">rround.me</a></li>
- <li>- <a href="#examples-blossom">Blossom</a></li>
- <li>- <a href="#examples-instagreat">Insta-great!</a></li>
- <li>- <a href="#examples-decide">Decide</a></li>
- <li>- <a href="#examples-trello">Trello</a></li>
- <li>- <a href="#examples-bittorrent">BitTorrent</a></li>
- <li>- <a href="#examples-trapit">Trapit</a></li>
- <li>- <a href="#examples-fluxiom">Fluxiom</a></li>
- <li>- <a href="#examples-chop">Chop</a></li>
- <li>- <a href="#examples-blackcomb">Blackcomb</a></li>
- <li>- <a href="#examples-test-kitchen">America’s Test Kitchen</a></li>
- <li>- <a href="#examples-quietwrite">QuietWrite</a></li>
- <li>- <a href="#examples-tzigla">Tzigla</a></li>
- <li>- <a href="#examples-substance">Substance</a></li>
- </ul>
- <a class="toc_title" href="#faq">
- F.A.Q.
- </a>
- <ul class="toc_section">
- <li>– <a href="#FAQ-events">Catalog of Events</a></li>
- <li>– <a href="#FAQ-tim-toady">More Than One Way To Do It</a></li>
- <li>– <a href="#FAQ-nested">Nested Models & Collections</a></li>
- <li>– <a href="#FAQ-bootstrap">Loading Bootstrapped Models</a></li>
- <li>– <a href="#FAQ-mvc">Traditional MVC</a></li>
- <li>– <a href="#FAQ-this">Binding "this"</a></li>
- </ul>
- <a class="toc_title" href="#changelog">
- Change Log
- </a>
- </div>
- <div class="container">
- <p>
- <img style="width: 385px; height: 126px;" src="docs/images/backbone.png" alt="Backbone.js" />
- </p>
- <p>
- <a href="http://github.com/documentcloud/backbone/">Backbone</a>
- supplies structure to JavaScript-heavy applications by providing <b>models</b> with
- key-value binding and custom events, <b>collections</b> with a rich API of enumerable functions,
- <b>views</b> with declarative event handling, and connects it all to your
- existing application over a RESTful JSON interface.
- </p>
- <p>
- The project is <a href="http://github.com/documentcloud/backbone/">hosted on GitHub</a>,
- and the <a href="docs/backbone.html">annotated source code</a> is available,
- as well as an online <a href="test/test.html">test suite</a>, an
- <a href="examples/todos/index.html">example application</a> and a
- <a href="https://github.com/documentcloud/backbone/wiki/Tutorials%2C-blog-posts-and-example-sites">list of tutorials</a>.
- </p>
- <p>
- You can report bugs and discuss features on the
- <a href="http://github.com/documentcloud/backbone/issues">GitHub issues page</a>,
- on Freenode IRC in the <tt>#documentcloud</tt> channel, post questions to the
- <a href="https://groups.google.com/forum/#!forum/backbonejs">Google Group</a>,
- or send tweets to <a href="http://twitter.com/documentcloud">@documentcloud</a>.
- </p>
- <p>
- <i>
- Backbone is an open-source component of
- <a href="http://documentcloud.org/">DocumentCloud</a>.
- </i>
- </p>
- <h2 id="downloads">
- Downloads & Dependencies
- <span style="padding-left: 7px; font-size:11px; font-weight: normal;" class="interface">(Right-click, and use "Save As")</span>
- </h2>
- <table>
- <tr>
- <td><a href="backbone.js">Development Version (0.5.3)</a></td>
- <td><i>41kb, Full Source with Comments</i></td>
- </tr>
- <tr>
- <td><a href="backbone-min.js">Production Version (0.5.3)</a></td>
- <td><i>4.6kb, Packed and Gzipped</i></td>
- </tr>
- </table>
- <p>
- Backbone's only hard dependency is
- <a href="http://documentcloud.github.com/underscore/">Underscore.js</a>.
- For RESTful persistence, history support via <a href="#Router">Backbone.Router</a>
- and DOM manipulation with <a href="#View">Backbone.View</a>, include
- <a href="https://github.com/douglascrockford/JSON-js">json2.js</a>, and either
- <a href="http://jquery.com">jQuery</a> <small>( > 1.4.2)</small> or
- <a href="http://zeptojs.com/">Zepto</a>.
- </p>
-
- <h2 id="Upgrading">Upgrading to 0.5.0+</h2>
- <p>
- We've taken the opportunity to clarify some naming with the <b>0.5.0</b>
- release. <tt>Controller</tt> is now <a href="#Router">Router</a>, and
- <tt>refresh</tt> is now <a href="#Collection-reset">reset</a>.
- The previous <tt>saveLocation</tt> and <tt>setLocation</tt>
- functions have been replaced by <a href="#Router-navigate">navigate</a>.
- <tt>Backbone.sync</tt>'s method signature has changed to allow the passing
- of arbitrary options to <tt>jQuery.ajax</tt>.
- Be sure to <a href="#History-start">opt-in</a> to <tt>pushState</tt> support,
- if you want to use it.
- </p>
- <h2 id="Introduction">Introduction</h2>
- <p>
- When working on a web application that involves a lot of JavaScript, one
- of the first things you learn is to stop tying your data to the DOM. It's all
- too easy to create JavaScript applications that end up as tangled piles of
- jQuery selectors and callbacks, all trying frantically to keep data in
- sync between the HTML UI, your JavaScript logic, and the database on your
- server. For rich client-side applications, a more structured approach
- is often helpful.
- </p>
- <p>
- With Backbone, you represent your data as
- <a href="#Model">Models</a>, which can be created, validated, destroyed,
- and saved to the server. Whenever a UI action causes an attribute of
- a model to change, the model triggers a <i>"change"</i> event; all
- the <a href="#View">Views</a> that display the model's data are notified of the
- event, causing them to re-render. You don't have to write the glue
- code that looks into the DOM to find an element with a specific <i>id</i>,
- and update the HTML manually
- — when the model changes, the views simply update themselves.
- </p>
- <p>
- Many of the examples that follow are runnable. Click the <i>play</i> button
- to execute them.
- </p>
- <h2 id="Events">Backbone.Events</h2>
- <p>
- <b>Events</b> is a module that can be mixed in to any object, giving the
- object the ability to bind and trigger custom named events. Events do not
- have to be declared before they are bound, and may take passed arguments.
- For example:
- </p>
- <pre class="runnable">
- var object = {};
- _.extend(object, Backbone.Events);
- object.bind("alert", function(msg) {
- alert("Triggered " + msg);
- });
- object.trigger("alert", "an event");
- </pre>
- <p id="Events-bind">
- <b class="header">bind</b><code>object.bind(event, callback, [context])</code>
- <br />
- Bind a <b>callback</b> function to an object. The callback will be invoked
- whenever the <b>event</b> (specified by an arbitrary string identifier) is fired.
- If you have a large number of different events on a page, the convention is to use colons to
- namespace them: <tt>"poll:start"</tt>, or <tt>"change:selection"</tt>
- </p>
-
- <p>
- To supply a <b>context</b> value for <tt>this</tt> when the callback is invoked,
- pass the optional third argument: <tt>model.bind('change', this.render, this)</tt>
- </p>
- <p>
- Callbacks bound to the special
- <tt>"all"</tt> event will be triggered when any event occurs, and are passed
- the name of the event as the first argument. For example, to proxy all events
- from one object to another:
- </p>
- <pre>
- proxy.bind("all", function(eventName) {
- object.trigger(eventName);
- });
- </pre>
- <p id="Events-unbind">
- <b class="header">unbind</b><code>object.unbind([event], [callback])</code>
- <br />
- Remove a previously-bound <b>callback</b> function from an object. If no
- callback is specified, all callbacks for the <b>event</b> will be
- removed. If no event is specified, <i>all</i> event callbacks on the object
- will be removed.
- </p>
- <pre>
- object.unbind("change", onChange); // Removes just the onChange callback.
- object.unbind("change"); // Removes all "change" callbacks.
- object.unbind(); // Removes all callbacks on object.
- </pre>
- <p id="Events-trigger">
- <b class="header">trigger</b><code>object.trigger(event, [*args])</code>
- <br />
- Trigger callbacks for the given <b>event</b>. Subsequent arguments to
- <b>trigger</b> will be passed along to the event callbacks.
- </p>
- <h2 id="Model">Backbone.Model</h2>
- <p>
- <b>Models</b> are the heart of any JavaScript application, containing
- the interactive data as well as a large part of the logic surrounding it:
- conversions, validations, computed properties, and access control. You
- extend <b>Backbone.Model</b> with your domain-specific methods, and
- <b>Model</b> provides a basic set of functionality for managing changes.
- </p>
- <p>
- The following is a contrived example, but it demonstrates defining a model
- with a custom method, setting an attribute, and firing an event keyed
- to changes in that specific attribute.
- After running this code once, <tt>sidebar</tt> will be
- available in your browser's console, so you can play around with it.
- </p>
- <pre class="runnable">
- var Sidebar = Backbone.Model.extend({
- promptColor: function() {
- var cssColor = prompt("Please enter a CSS color:");
- this.set({color: cssColor});
- }
- });
- window.sidebar = new Sidebar;
- sidebar.bind('change:color', function(model, color) {
- $('#sidebar').css({background: color});
- });
- sidebar.set({color: 'white'});
- sidebar.promptColor();
- </pre>
- <p id="Model-extend">
- <b class="header">extend</b><code>Backbone.Model.extend(properties, [classProperties])</code>
- <br />
- To create a <b>Model</b> class of your own, you extend <b>Backbone.Model</b>
- and provide instance <b>properties</b>, as well as optional
- <b>classProperties</b> to be attached directly to the constructor function.
- </p>
- <p>
- <b>extend</b> correctly sets up the prototype chain, so subclasses created
- with <b>extend</b> can be further extended and subclassed as far as you like.
- </p>
- <pre>
- var Note = Backbone.Model.extend({
- initialize: function() { ... },
- author: function() { ... },
- coordinates: function() { ... },
- allowedToEdit: function(account) {
- return true;
- }
- });
- var PrivateNote = Note.extend({
- allowedToEdit: function(account) {
- return account.owns(this);
- }
- });
- </pre>
- <p class="warning">
- Brief aside on <tt>super</tt>: JavaScript does not provide
- a simple way to call super — the function of the same name defined
- higher on the prototype chain. If you override a core function like
- <tt>set</tt>, or <tt>save</tt>, and you want to invoke the
- parent object's implementation, you'll have to explicitly call it, along these lines:
- </p>
- <pre>
- var Note = Backbone.Model.extend({
- set: function(attributes, options) {
- Backbone.Model.prototype.set.call(this, attributes, options);
- ...
- }
- });
- </pre>
- <p id="Model-constructor">
- <b class="header">constructor / initialize</b><code>new Model([attributes])</code>
- <br />
- When creating an instance of a model, you can pass in the initial values
- of the <b>attributes</b>, which will be <a href="#Model-set">set</a> on the
- model. If you define an <b>initialize</b> function, it will be invoked when
- the model is created.
- </p>
- <pre>
- new Book({
- title: "One Thousand and One Nights",
- author: "Scheherazade"
- });
- </pre>
- <p id="Model-get">
- <b class="header">get</b><code>model.get(attribute)</code>
- <br />
- Get the current value of an attribute from the model. For example:
- <tt>note.get("title")</tt>
- </p>
- <p id="Model-set">
- <b class="header">set</b><code>model.set(attributes, [options])</code>
- <br />
- Set a hash of attributes (one or many) on the model. If any of the attributes
- change the models state, a <tt>"change"</tt> event will be triggered, unless
- <tt>{silent: true}</tt> is passed as an option. Change events for specific
- attributes are also triggered, and you can bind to those as well, for example:
- <tt>change:title</tt>, and <tt>change:content</tt>.
- </p>
- <pre>
- note.set({title: "October 12", content: "Lorem Ipsum Dolor Sit Amet..."});
- </pre>
- <p>
- If the model has a <a href="#Model-validate">validate</a> method,
- it will be validated before the attributes are set, no changes will
- occur if the validation fails, and <b>set</b> will return <tt>false</tt>.
- You may also pass an <tt>error</tt>
- callback in the options, which will be invoked instead of triggering an
- <tt>"error"</tt> event, should validation fail.
- </p>
- <p id="Model-escape">
- <b class="header">escape</b><code>model.escape(attribute)</code>
- <br />
- Similar to <a href="#Model-get">get</a>, but returns the HTML-escaped version
- of a model's attribute. If you're interpolating data from the model into
- HTML, using <b>escape</b> to retrieve attributes will prevent
- <a href="http://en.wikipedia.org/wiki/Cross-site_scripting">XSS</a> attacks.
- </p>
- <pre class="runnable">
- var hacker = new Backbone.Model({
- name: "<script>alert('xss')</script>"
- });
- alert(hacker.escape('name'));
- </pre>
- <p id="Model-has">
- <b class="header">has</b><code>model.has(attribute)</code>
- <br />
- Returns <tt>true</tt> if the attribute is set to a non-null or non-undefined
- value.
- </p>
- <pre>
- if (note.has("title")) {
- ...
- }
- </pre>
- <p id="Model-unset">
- <b class="header">unset</b><code>model.unset(attribute, [options])</code>
- <br />
- Remove an attribute by deleting it from the internal attributes hash.
- Fires a <tt>"change"</tt> event unless <tt>silent</tt> is passed as an option.
- </p>
- <p id="Model-clear">
- <b class="header">clear</b><code>model.clear([options])</code>
- <br />
- Removes all attributes from the model. Fires a <tt>"change"</tt> event unless
- <tt>silent</tt> is passed as an option.
- </p>
- <p id="Model-id">
- <b class="header">id</b><code>model.id</code>
- <br />
- A special property of models, the <b>id</b> is an arbitrary string
- (integer id or UUID). If you set the <b>id</b> in the
- attributes hash, it will be copied onto the model as a direct property.
- Models can be retrieved by id from collections, and the id is used to generate
- model URLs by default.
- </p>
- <p id="Model-cid">
- <b class="header">cid</b><code>model.cid</code>
- <br />
- A special property of models, the <b>cid</b> or client id is a unique identifier
- automatically assigned to all models when they're first created. Client ids
- are handy when the model has not yet been saved to the server, and does not
- yet have its eventual true <b>id</b>, but already needs to be visible in the UI.
- Client ids take the form: <tt>c1, c2, c3 ...</tt>
- </p>
- <p id="Model-attributes">
- <b class="header">attributes</b><code>model.attributes</code>
- <br />
- The <b>attributes</b> property is the internal hash containing the model's
- state. Please use <a href="#Model-set">set</a> to update the attributes instead of modifying
- them directly. If you'd like to retrieve and munge a copy of the model's
- attributes, use <a href="#Model-toJSON">toJSON</a> instead.
- </p>
- <p id="Model-defaults">
- <b class="header">defaults</b><code>model.defaults or model.defaults()</code>
- <br />
- The <b>defaults</b> hash (or function) can be used to specify the default
- attributes for your model. When creating an instance of the model,
- any unspecified attributes will be set to their default value.
- </p>
- <pre class="runnable">
- var Meal = Backbone.Model.extend({
- defaults: {
- "appetizer": "caesar salad",
- "entree": "ravioli",
- "dessert": "cheesecake"
- }
- });
- alert("Dessert will be " + (new Meal).get('dessert'));
- </pre>
- <p class="warning">
- Remember that in JavaScript, objects are passed by reference, so if you
- include an object as a default value, it will be shared among all instances.
- </p>
- <p id="Model-toJSON">
- <b class="header">toJSON</b><code>model.toJSON()</code>
- <br />
- Return a copy of the model's <a href="#Model-attributes">attributes</a> for JSON stringification.
- This can be used for persistence, serialization, or for augmentation before
- being handed off to a view. The name of this method is a bit confusing, as
- it doesn't actually return a JSON string — but I'm afraid that it's
- the way that the <a href="https://developer.mozilla.org/en/JSON#toJSON()_method">JavaScript API for <b>JSON.stringify</b> works</a>.
- </p>
- <pre class="runnable">
- var artist = new Backbone.Model({
- firstName: "Wassily",
- lastName: "Kandinsky"
- });
- artist.set({birthday: "December 16, 1866"});
- alert(JSON.stringify(artist));
- </pre>
- <p id="Model-fetch">
- <b class="header">fetch</b><code>model.fetch([options])</code>
- <br />
- Resets the model's state from the server. Useful if the model has never
- been populated with data, or if you'd like to ensure that you have the
- latest server state. A <tt>"change"</tt> event will be triggered if the
- server's state differs from the current attributes. Accepts
- <tt>success</tt> and <tt>error</tt> callbacks in the options hash, which
- are passed <tt>(model, response)</tt> as arguments.
- </p>
- <pre>
- // Poll every 10 seconds to keep the channel model up-to-date.
- setInterval(function() {
- channel.fetch();
- }, 10000);
- </pre>
- <p id="Model-save">
- <b class="header">save</b><code>model.save([attributes], [options])</code>
- <br />
- Save a model to your database (or alternative persistence layer),
- by delegating to <a href="#Sync">Backbone.sync</a>. The <b>attributes</b>
- hash (as in <a href="#Model-set">set</a>) should contain the attributes
- you'd like to change -- keys that aren't mentioned won't be altered.
- If the model has a <a href="#Model-validate">validate</a>
- method, and validation fails, the model will not be saved. If the model
- <a href="#Model-isNew">isNew</a>, the save will be a <tt>"create"</tt>
- (HTTP <tt>POST</tt>), if the model already
- exists on the server, the save will be an <tt>"update"</tt> (HTTP <tt>PUT</tt>).
- </p>
- <p>
- In the following example, notice how our overridden version
- of <tt>Backbone.sync</tt> receives a <tt>"create"</tt> request
- the first time the model is saved and an <tt>"update"</tt>
- request the second time.
- </p>
- <pre class="runnable">
- Backbone.sync = function(method, model) {
- alert(method + ": " + JSON.stringify(model));
- model.id = 1;
- };
- var book = new Backbone.Model({
- title: "The Rough Riders",
- author: "Theodore Roosevelt"
- });
- book.save();
- book.save({author: "Teddy"});
- </pre>
- <p>
- <b>save</b> accepts <tt>success</tt> and <tt>error</tt> callbacks in the
- options hash, which are passed <tt>(model, response)</tt> as arguments.
- The <tt>error</tt> callback will also be invoked if the model has a
- <tt>validate</tt> method, and validation fails. If a server-side
- validation fails, return a non-<tt>200</tt> HTTP response code, along with
- an error response in text or JSON.
- </p>
- <pre>
- book.save({author: "F.D.R."}, {error: function(){ ... }});
- </pre>
- <p id="Model-destroy">
- <b class="header">destroy</b><code>model.destroy([options])</code>
- <br />
- Destroys the model on the server by delegating an HTTP <tt>DELETE</tt>
- request to <a href="#Sync">Backbone.sync</a>. Accepts
- <tt>success</tt> and <tt>error</tt> callbacks in the options hash.
- Triggers a <tt>"destroy"</tt> event on the model, which will bubble up
- through any collections that contain it.
- </p>
- <pre>
- book.destroy({success: function(model, response) {
- ...
- }});
- </pre>
- <p id="Model-validate">
- <b class="header">validate</b><code>model.validate(attributes)</code>
- <br />
- This method is left undefined, and you're encouraged to override it with
- your custom validation logic, if you have any that can be performed
- in JavaScript. <b>validate</b> is called before <tt>set</tt> and
- <tt>save</tt>, and is passed the attributes that are about to be updated.
- If the model and attributes are valid, don't return anything from <b>validate</b>;
- if the attributes are invalid, return an error of your choosing. It
- can be as simple as a string error message to be displayed, or a complete
- error object that describes the error programmatically. <tt>set</tt> and
- <tt>save</tt> will not continue if <b>validate</b> returns an error.
- Failed validations trigger an <tt>"error"</tt> event.
- </p>
- <pre class="runnable">
- var Chapter = Backbone.Model.extend({
- validate: function(attrs) {
- if (attrs.end < attrs.start) {
- return "can't end before it starts";
- }
- }
- });
- var one = new Chapter({
- title : "Chapter One: The Beginning"
- });
- one.bind("error", function(model, error) {
- alert(model.get("title") + " " + error);
- });
- one.set({
- start: 15,
- end: 10
- });
- </pre>
- <p>
- <tt>"error"</tt> events are useful for providing coarse-grained error
- messages at the model or collection level, but if you have a specific view
- that can better handle the error, you may override and suppress the event
- by passing an <tt>error</tt> callback directly:
- </p>
- <pre>
- account.set({access: "unlimited"}, {
- error: function(model, error) {
- alert(error);
- }
- });
- </pre>
- <p id="Model-url">
- <b class="header">url</b><code>model.url()</code>
- <br />
- Returns the relative URL where the model's resource would be located on
- the server. If your models are located somewhere else, override this method
- with the correct logic. Generates URLs of the form: <tt>"/[collection.url]/[id]"</tt>,
- falling back to <tt>"/[urlRoot]/id"</tt> if the model is not part of a collection.
- </p>
- <p>
- Delegates to <a href="#Collection-url">Collection#url</a> to generate the
- URL, so make sure that you have it defined, or a <a href="#Model-urlRoot">urlRoot</a>
- property, if all models of this class share a common root URL.
- A model with an id of <tt>101</tt>, stored in a
- <a href="#Collection">Backbone.Collection</a> with a <tt>url</tt> of <tt>"/documents/7/notes"</tt>,
- would have this URL: <tt>"/documents/7/notes/101"</tt>
- </p>
- <p id="Model-urlRoot">
- <b class="header">urlRoot</b><code>model.urlRoot</code>
- <br />
- Specify a <tt>urlRoot</tt> if you're using a model outside of a collection,
- to enable the default <a href="#Model-url">url</a> function to generate
- URLs based on the model id. <tt>"/[urlRoot]/id"</tt>
- </p>
- <pre class="runnable">
- var Book = Backbone.Model.extend({urlRoot : '/books'});
- var solaris = new Book({id: "1083-lem-solaris"});
- alert(solaris.url());
- </pre>
- <p id="Model-parse">
- <b class="header">parse</b><code>model.parse(response)</code>
- <br />
- <b>parse</b> is called whenever a model's data is returned by the
- server, in <a href="#Model-fetch">fetch</a>, and <a href="#Model-save">save</a>.
- The function is passed the raw <tt>response</tt> object, and should return
- the attributes hash to be <a href="#Model-set">set</a> on the model. The
- default implementation is a no-op, simply passing through the JSON response.
- Override this if you need to work with a preexisting API, or better namespace
- your responses.
- </p>
- <p>
- If you're working with a Rails backend, you'll notice that Rails' default
- <tt>to_json</tt> implementation includes a model's attributes under a
- namespace. To disable this behavior for seamless Backbone integration, set:
- </p>
- <pre>
- ActiveRecord::Base.include_root_in_json = false
- </pre>
- <p id="Model-clone">
- <b class="header">clone</b><code>model.clone()</code>
- <br />
- Returns a new instance of the model with identical attributes.
- </p>
- <p id="Model-isNew">
- <b class="header">isNew</b><code>model.isNew()</code>
- <br />
- Has this model been saved to the server yet? If the model does not yet have
- an <tt>id</tt>, it is considered to be new.
- </p>
- <p id="Model-change">
- <b class="header">change</b><code>model.change()</code>
- <br />
- Manually trigger the <tt>"change"</tt> event.
- If you've been passing <tt>{silent: true}</tt> to the <a href="#Model-set">set</a> function in order to
- aggregate rapid changes to a model, you'll want to call <tt>model.change()</tt>
- when you're all finished.
- </p>
- <p id="Model-hasChanged">
- <b class="header">hasChanged</b><code>model.hasChanged([attribute])</code>
- <br />
- Has the model changed since the last <tt>"change"</tt> event? If an <b>attribute</b>
- is passed, returns <tt>true</tt> if that specific attribute has changed.
- </p>
-
- <p class="warning">
- Note that this method, and the following change-related ones,
- are only useful during the course of a <tt>"change"</tt> event.
- </p>
- <pre>
- book.bind("change", function() {
- if (book.hasChanged("title")) {
- ...
- }
- });
- </pre>
- <p id="Model-changedAttributes">
- <b class="header">changedAttributes</b><code>model.changedAttributes([attributes])</code>
- <br />
- Retrieve a hash of only the model's attributes that have changed. Optionally,
- an external <b>attributes</b> hash can be passed in, returning
- the attributes in that hash which differ from the model. This can be used
- to figure out which portions of a view should be updated, or what calls
- need to be made to sync the changes to the server.
- </p>
- <p id="Model-previous">
- <b class="header">previous</b><code>model.previous(attribute)</code>
- <br />
- During a <tt>"change"</tt> event, this method can be used to get the
- previous value of a changed attribute.
- </p>
- <pre class="runnable">
- var bill = new Backbone.Model({
- name: "Bill Smith"
- });
- bill.bind("change:name", function(model, name) {
- alert("Changed name from " + bill.previous("name") + " to " + name);
- });
- bill.set({name : "Bill Jones"});
- </pre>
- <p id="Model-previousAttributes">
- <b class="header">previousAttributes</b><code>model.previousAttributes()</code>
- <br />
- Return a copy of the model's previous attributes. Useful for getting a
- diff between versions of a model, or getting back to a valid state after
- an error occurs.
- </p>
- <h2 id="Collection">Backbone.Collection</h2>
- <p>
- Collections are ordered sets of models. You can to bind <tt>"change"</tt> events
- to be notified when any model in the collection has been modified,
- listen for <tt>"add"</tt> and <tt>"remove"</tt> events, <tt>fetch</tt>
- the collection from the server, and use a full suite of
- <a href="#Collection-Underscore-Methods">Underscore.js methods</a>.
- </p>
- <p>
- Any event that is triggered on a model in a collection will also be
- triggered on the collection directly, for convenience.
- This allows you to listen for changes to specific attributes in any
- model in a collection, for example:
- <tt>Documents.bind("change:selected", ...)</tt>
- </p>
- <p id="Collection-extend">
- <b class="header">extend</b><code>Backbone.Collection.extend(properties, [classProperties])</code>
- <br />
- To create a <b>Collection</b> class of your own, extend <b>Backbone.Collection</b>,
- providing instance <b>properties</b>, as well as optional <b>classProperties</b> to be attached
- directly to the collection's constructor function.
- </p>
- <p id="Collection-model">
- <b class="header">model</b><code>collection.model</code>
- <br />
- Override this property to specify the model class that the collection
- contains. If defined, you can pass raw attributes objects (and arrays) to
- <a href="#Collection-add">add</a>, <a href="#Collection-create">create</a>,
- and <a href="#Collection-reset">reset</a>, and the attributes will be
- converted into a model of the proper type.
- </p>
- <pre>
- var Library = Backbone.Collection.extend({
- model: Book
- });
- </pre>
- <p id="Collection-constructor">
- <b class="header">constructor / initialize</b><code>new Collection([models], [options])</code>
- <br />
- When creating a Collection, you may choose to pass in the initial array of <b>models</b>.
- The collection's <a href="#Collection-comparator">comparator</a> function
- may be included as an option. If you define an <b>initialize</b> function, it will be
- invoked when the collection is created.
- </p>
- <pre>
- var tabs = new TabSet([tab1, tab2, tab3]);
- </pre>
- <p id="Collection-models">
- <b class="header">models</b><code>collection.models</code>
- <br />
- Raw access to the JavaScript array of models inside of the collection. Usually you'll
- want to use <tt>get</tt>, <tt>at</tt>, or the <b>Underscore methods</b>
- to access model objects, but occasionally a direct reference to the array
- is desired.
- </p>
- <p id="Collection-toJSON">
- <b class="header">toJSON</b><code>collection.toJSON()</code>
- <br />
- Return an array containing the attributes hash of each model in the
- collection. This can be used to serialize and persist the
- collection as a whole. The name of this method is a bit confusing, because
- it conforms to
- <a href="https://developer.mozilla.org/en/JSON#toJSON()_method">JavaScript's JSON API</a>.
- </p>
- <pre class="runnable">
- var collection = new Backbone.Collection([
- {name: "Tim", age: 5},
- {name: "Ida", age: 26},
- {name: "Rob", age: 55}
- ]);
- alert(JSON.stringify(collection));
- </pre>
- <p id="Collection-Underscore-Methods">
- <b class="header">Underscore Methods (26)</b>
- <br />
- Backbone proxies to <b>Underscore.js</b> to provide 26 iteration functions
- on <b>Backbone.Collection</b>. They aren't all documented here, but
- you can take a look at the Underscore documentation for the full details…
- </p>
- <ul>
- <li><a href="http://documentcloud.github.com/underscore/#each">forEach (each)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#map">map</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#reduce">reduce (foldl, inject)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#reduceRight">reduceRight (foldr)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#detect">find (detect)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#select">filter (select)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#reject">reject</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#all">every (all)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#any">some (any)</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#include">include</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#invoke">invoke</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#max">max</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#min">min</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#sortBy">sortBy</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#groupBy">groupBy</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#sortedIndex">sortedIndex</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#toArray">toArray</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#size">size</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#first">first</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#rest">rest</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#last">last</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#without">without</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#indexOf">indexOf</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#lastIndexOf">lastIndexOf</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#isEmpty">isEmpty</a></li>
- <li><a href="http://documentcloud.github.com/underscore/#chain">chain</a></li>
- </ul>
- <pre>
- Books.each(function(book) {
- book.publish();
- });
- var titles = Books.map(function(book) {
- return book.get("title");
- });
- var publishedBooks = Books.filter(function(book) {
- return book.get("published") === true;
- });
- var alphabetical = Books.sortBy(function(book) {
- return book.author.get("name").toLowerCase();
- });
- </pre>
- <p id="Collection-add">
- <b class="header">add</b><code>collection.add(models, [options])</code>
- <br />
- Add a model (or an array of models) to the collection. Fires an <tt>"add"</tt>
- event, which you can pass <tt>{silent: true}</tt> to suppress. If a
- <a href="#Collection-model">model</a> property is defined, you may also pass
- raw attributes objects, and have them be vivified as instances of the model.
- Pass <tt>{at: index}</tt> to splice the model into the collection at the
- specified <tt>index</tt>.
- </p>
- <pre class="runnable">
- var ships = new Backbone.Collection;
- ships.bind("add", function(ship) {
- alert("Ahoy " + ship.get("name") + "!");
- });
- ships.add([
- {name: "Flying Dutchman"},
- {name: "Black Pearl"}
- ]);
- </pre>
- <p id="Collection-remove">
- <b class="header">remove</b><code>collection.remove(models, [options])</code>
- <br />
- Remove a model (or an array of models) from the collection. Fires a
- <tt>"remove"</tt> event, which you can use <tt>silent</tt>
- to suppress.
- </p>
- <p id="Collection-get">
- <b class="header">get</b><code>collection.get(id)</code>
- <br />
- Get a model from a collection, specified by <b>id</b>.
- </p>
- <pre>
- var book = Library.get(110);
- </pre>
- <p id="Collection-getByCid">
- <b class="header">getByCid</b><code>collection.getByCid(cid)</code>
- <br />
- Get a model from a collection, specified by client id. The client id
- is the <tt>.cid</tt> property of the model, automatically assigned whenever
- a model is created. Useful for models which have not yet been saved to
- the server, and do not yet have true ids.
- </p>
- <p id="Collection-at">
- <b class="header">at</b><code>collection.at(index)</code>
- <br />
- Get a model from a collection, specified by index. Useful if your collection
- is sorted, and if your collection isn't sorted, <b>at</b> will still
- retrieve models in insertion order.
- </p>
- <p id="Collection-length">
- <b class="header">length</b><code>collection.length</code>
- <br />
- Like an array, a Collection maintains a <tt>length</tt> property, counting
- the number of models it contains.
- </p>
- <p id="Collection-comparator">
- <b class="header">comparator</b><code>collection.comparator</code>
- <br />
- By default there is no <b>comparator</b> function on a collection.
- If you define a comparator, it will be used to maintain
- the collection in sorted order. This means that as models are added,
- they are inserted at the correct index in <tt>collection.models</tt>.
- Comparator functions take a model and return a numeric or string value
- by which the model should be ordered relative to others.
- </p>
- <p>
- Note how even though all of the chapters in this example are added backwards,
- they come out in the proper order:
- </p>
- <pre class="runnable">
- var Chapter = Backbone.Model;
- var chapters = new Backbone.Collection;
- chapters.comparator = function(chapter) {
- return chapter.get("page");
- };
- chapters.add(new Chapter({page: 9, title: "The End"}));
- chapters.add(new Chapter({page: 5, title: "The Middle"}));
- chapters.add(new Chapter({page: 1, title: "The Beginning"}));
- alert(chapters.pluck('title'));
- </pre>
- <p class="warning">
- Brief aside: This comparator function is different than JavaScript's regular
- "sort", which must return <tt>0</tt>, <tt>1</tt>, or <tt>-1</tt>,
- and is more similar to a <tt>sortBy</tt> — a much nicer API.
- </p>
- <p id="Collection-sort">
- <b class="header">sort</b><code>collection.sort([options])</code>
- <br />
- Force a collection to re-sort itself. You don't need to call this under
- normal circumstances, as a collection with a <a href="#Collection-comparator">comparator</a> function
- will maintain itself in proper sort order at all times. Calling <b>sort</b>
- triggers the collection's <tt>"reset"</tt> event, unless silenced by passing
- <tt>{silent: true}</tt>
- </p>
- <p id="Collection-pluck">
- <b class="header">pluck</b><code>collection.pluck(attribute)</code>
- <br />
- Pluck an attribute from each model in the collection. Equivalent to calling
- <tt>map</tt>, and returning a single attribute from the iterator.
- </p>
- <pre class="runnable">
- var stooges = new Backbone.Collection([
- new Backbone.Model({name: "Curly"}),
- new Backbone.Model({name: "Larry"}),
- new Backbone.Model({name: "Moe"})
- ]);
- var names = stooges.pluck("name");
- alert(JSON.stringify(names));
- </pre>
- <p id="Collection-url">
- <b class="header">url</b><code>collection.url or collection.url()</code>
- <br />
- Set the <b>url</b> property (or function) on a collection to reference
- its location on the server. Models within the collection will use <b>url</b>
- to construct URLs of their own.
- </p>
- <pre>
- var Notes = Backbone.Collection.extend({
- url: '/notes'
- });
- // Or, something more sophisticated:
- var Notes = Backbone.Collection.extend({
- url: function() {
- return this.document.url() + '/notes';
- }
- });
- </pre>
- <p id="Collection-parse">
- <b class="header">parse</b><code>collection.parse(response)</code>
- <br />
- <b>parse</b> is called by Backbone whenever a collection's models are
- returned by the server, in <a href="#Collection-fetch">fetch</a>.
- The function is passed the raw <tt>response</tt> object, and should return
- the array of model attributes to be <a href="#Collection-add">added</a>
- to the collection. The default implementation is a no-op, simply passing
- through the JSON response. Override this if you need to work with a
- preexisting API, or better namespace your responses.
- </p>
- <pre>
- var Tweets = Backbone.Collection.extend({
- // The Twitter Search API returns tweets under "results".
- parse: function(response) {
- return response.results;
- }
- });
- </pre>
- <p id="Collection-fetch">
- <b class="header">fetch</b><code>collection.fetch([options])</code>
- <br />
- Fetch the default set of models for this collection from the server,
- resetting the collection when they arrive. The <b>options</b> hash takes
- <tt>success</tt> and <tt>error</tt>
- callbacks which will be passed <tt>(collection, response)</tt> as arguments.
- When the model data returns from the server, the collection will
- <a href="#Collection-reset">reset</a>.
- Delegates to <a href="#Sync">Backbone.sync</a>
- under the covers, for custom persistence strategies.
- The server handler for <b>fetch</b> requests should return a JSON array of
- models.
- </p>
- <pre class="runnable">
- Backbone.sync = function(method, model) {
- alert(method + ": " + model.url);
- };
- var Accounts = new Backbone.Collection;
- Accounts.url = '/accounts';
- Accounts.fetch();
- </pre>
- <p>
- If you'd like to add the incoming models to the current collection, instead
- of replacing the collection's contents, pass <tt>{add: true}</tt> as an
- option to <b>fetch</b>.
- </p>
-
- <p>
- <b>jQuery.ajax</b> options can also be passed directly as <b>fetch</b> options,
- so to fetch a specific page of a paginated collection:
- <tt>Documents.fetch({data: {page: 3}})</tt>
- </p>
- <p>
- Note that <b>fetch</b> should not be used to populate collections on
- page load — all models needed at load time should already be
- <a href="#FAQ-bootstrap">bootstrapped</a> in to place. <b>fetch</b> is
- intended for lazily-loading models for interfaces that are not needed
- immediately: for example, documents with collections of notes that may be
- toggled open and closed.
- </p>
- <p id="Collection-reset">
- <b class="header">reset</b><code>collection.reset(models, [options])</code>
- <br />
- Adding and removing models one at a time is all well and good, but sometimes
- you have so many models to change that you'd rather just update the collection
- in bulk. Use <b>reset</b> to replace a collection with a new list
- of models (or attribute hashes), triggering a single <tt>"reset"</tt> event
- at the end. Pass <tt>{silent: true}</tt> to suppress the <tt>"reset"</tt> event.
- Using reset with no arguments is useful as a way to empty the collection.
- </p>
- <p>
- Here's an example using <b>reset</b> to bootstrap a collection during initial page load,
- in a Rails application.
- </p>
- <pre>
- <script>
- Accounts.reset(<%= @accounts.to_json %>);
- </script>
- </pre>
- <p>
- Calling <tt>collection.reset()</tt> without passing any models as arguments
- will empty the entire collection.
- </p>
- <p id="Collection-create">
- <b class="header">create</b><code>collection.create(attributes, [options])</code>
- <br />
- Convenience to create a new instance of a model within a collection.
- Equivalent to instantiating a model with a hash of attributes,
- saving the model to the server, and adding the model to the set after being
- successfully created. Returns
- the model, or <tt>false</tt> if a validation error prevented the
- model from being created. In order for this to work, you should set the
- <a href="#Collection-model">model</a> property of the collection.
- The <b>create</b> method can accept either an attributes hash or an
- existing, unsaved model object.
- </p>
- <pre>
- var Library = Backbone.Collection.extend({
- model: Book
- });
- var NYPL = new Library;
- var othello = NYPL.create({
- title: "Othello",
- author: "William Shakespeare"
- });
- </pre>
- <h2 id="Router">Backbone.Router</h2>
- <p>
- Web applications often provide linkable, bookmarkable, shareable URLs for
- important locations in the app. Until recently, hash fragments
- (<tt>#page</tt>) were used to provide these permalinks, but with the
- arrival of the History API, it's now possible to use standard URLs (<tt>/page</tt>).
- <b>Backbone.Router</b> provides methods for routing client-side pages, and
- connecting them to actions and events. For browsers which don't yet support
- the History API, the Router handles graceful fallback and transparent
- translation to the fragment version of the URL.
- </p>
- <p>
- During page load, after your application has finished creating all of its routers,
- be sure to call <tt>Backbone.history.start()</tt>, or
- <tt>Backbone.history.start({pushState: true})</tt> to route the initial URL.
- </p>
- <p id="Router-extend">
- <b class="header">extend</b><code>Backbone.Router.extend(properties, [classProperties])</code>
- <br />
- Get started by creating a custom router class. You'll
- want to define actions that are triggered when certain URL fragments are
- matched, and provide a <a href="#Router-routes">routes</a> hash
- that pairs routes to actions.
- </p>
- <pre>
- var Workspace = Backbone.Router.extend({
- routes: {
- "help": "help", // #help
- "search/:query": "search", // #search/kiwis
- "search/:query/p:page": "search" // #search/kiwis/p7
- },
- help: function() {
- ...
- },
- search: function(query, page) {
- ...
- }
- });
- </pre>
- <p id="Router-routes">
- <b class="header">routes</b><code>router.routes</code>
- <br />
- The routes hash maps URLs with parameters to functions on your router,
- similar to the <a href="#View">View</a>'s <a href="#View-delegateEvents">events hash</a>.
- Routes can contain parameter parts, <tt>:param</tt>, which match a single URL
- component between slashes; and splat parts <tt>*splat</tt>, which can match
- any number of URL components.
- </p>
- <p>
- For example, a route of <tt>"search/:query/p:page"</tt> will match
- a fragment of <tt>#search/obama/p2</tt>, passing <tt>"obama"</tt>
- and <tt>"2"</tt> to the action. A route of <tt>"file/*path"</tt> will
- match <tt>#file/nested/folder/file.txt</tt>,
- passing <tt>"nested/folder/file.txt"</tt> to the action.
- </p>
- <p>
- When the visitor presses the back button, or enters a URL, and a particular
- route is matched, the name of the action will be fired as an
- <a href="#Events">event</a>, so that other objects can listen to the router,
- and be notified. In the following example, visiting <tt>#help/uploading</tt>
- will fire a <tt>route:help</tt> event from the router.
- </p>
- <pre>
- routes: {
- "help/:page": "help",
- "download/*path": "download",
- "folder/:name": "openFolder",
- "folder/:name-:mode": "openFolder"
- }
- </pre>
- <pre>
- router.bind("route:help", function(page) {
- ...
- });
- </pre>
- <p id="Router-constructor">
- <b class="header">constructor / initialize</b><code>new Router([options])</code>
- <br />
- When creating a new router, you may pass its
- <a href="#Router-routes">routes</a> hash directly as an option, if you
- choose. All <tt>options</tt> will also be passed to your <tt>initialize</tt>
- function, if defined.
- </p>
- <p id="Router-route">
- <b class="header">route</b><code>router.route(route, name, callback)</code>
- <br />
- Manually create a route for the router, The <tt>route</tt> argument may
- be a <a href="#Router-routes">routing string</a> or regular expression.
- Each matching capture from the route or regular expression will be passed as
- an argument to the callback. The <tt>name</tt> argument will be triggered as
- a <tt>"route:name"</tt> event whenever the route is matched.
- </p>
- <pre>
- initialize: function(options) {
- // Matches #page/10, passing "10"
- this.route("page/:number", "page", function(number){ ... });
- // Matches /117-a/b/c/open, passing "117-a/b/c"
- this.route(/^(.*?)\/open$/, "open", function(id){ ... });
- }
- </pre>
- <p id="Router-navigate">
- <b class="header">navigate</b><code>router.navigate(fragment, [triggerRoute])</code>
- <br />
- Whenever you reach a point in your application that you'd like to save
- as a URL, call <b>navigate</b> in order to update the URL.
- If you wish to also call the route function, pass <b>triggerRoute</b>.
- </p>
- <pre>
- openPage: function(pageNumber) {
- this.document.pages.at(pageNumber).open();
- this.navigate("page/" + pageNumber);
- }
- # Or ...
- app.navigate("help/troubleshooting", true);
- </pre>
- <h2 id="History">Backbone.history</h2>
- <p>
- <b>History</b> serves as a global router (per frame) to handle <tt>hashchange</tt>
- events or <tt>pushState</tt>, match the appropriate route, and trigger callbacks. You shouldn't
- ever have to create one of these yourself — you should use the reference
- to <tt>Backbone.history</tt> that will be created for you automatically if you make use
- of <a href="#Router">Routers</a> with <a href="#Router-routes">routes</a>.
- </p>
-
- <p>
- <b>pushState</b> support exists on a purely opt-in basis in Backbone.
- Older browsers that don't support <tt>pushState</tt> will continue to use
- hash-based URL fragments, and if a hash URL is visited by a
- <tt>pushState</tt>-capable browser, it will be transparently upgraded to
- the true URL. Note that using real URLs requires your web server to be
- able to correctly render those pages, so back-end changes are required
- as well. For example, if you have a route of <tt>/documents/100</tt>,
- your web server must be able to serve that page, if the browser
- visits that URL directly. For full search-engine crawlability, it's best to
- have the server generate the complete HTML for the page ... but if it's a web
- application, just rendering the same content you would have for the root URL,
- and filling in the rest with Backbone Views and JavaScript works fine.
- </p>
- <p id="History-start">
- <b class="header">start</b><code>Backbone.history.start([options])</code>
- <br />
- When all of your <a href="#Router">Routers</a> have been created,
- and all of the routes are set up properly, call <tt>Backbone.history.start()</tt>
- to begin monitoring <tt>hashchange</tt> events, and dispatching routes.
- </p>
-
- <p>
- To indicate that you'd like to use HTML5 <tt>pushState</tt> support in
- your application, use <tt>Backbone.history.start({pushState: true})</tt>.
- </p>
-
- <p>
- If your application is not being served from the root url <tt>/</tt> of your
- domain, be sure to tell History where the root really is, as an option:
- <tt>Backbone.history.start({pushState: true, root: "/public/search/"})</tt>
- </p>
-
- <p>
- When called, if a route succeeds with a match for the current URL,
- <tt>Backbone.history.start()</tt> returns <tt>true</tt>. If no defined
- route matches the current URL, it returns <tt>false</tt>.
- </p>
-
- <p>
- If the server has already rendered the entire page, and you don't want the
- initial route to trigger when starting History, pass <tt>silent: true</tt>.
- </p>
-
- <p>
- Because hash-based history in Internet Explorer relies on an
- <tt><iframe></tt>, be sure to only call <tt>start()</tt> after the DOM
- is ready.
- </p>
- <pre>
- $(function(){
- new WorkspaceRouter();
- new HelpPaneRouter();
- Backbone.history.start({pushState: true});
- });
- </pre>
- <h2 id="Sync">Backbone.sync</h2>
- <p>
- <b>Backbone.sync</b> is the function that Backbone calls every time it
- attempts to read or save a model to the server. By default, it uses
- <tt>(jQuery/Zepto).ajax</tt> to make a RESTful JSON request. You can override
- it in order to use a different persistence strategy, such as WebSockets,
- XML transport, or Local Storage.
- </p>
- <p>
- The method signature of <b>Backbone.sync</b> is <tt>sync(method, model, [options])</tt>
- </p>
- <ul>
- <li><b>method</b> – the CRUD method (<tt>"create"</tt>, <tt>"read"</tt>, <tt>"update"</tt>, or <tt>"delete"</tt>)</li>
- <li><b>model</b> – the model to be saved (or collection to be read)</li>
- <li><b>options</b> – success and error callbacks, and all other jQuery request options</li>
- </ul>
- <p>
- With the default implementation, when <b>Backbone.sync</b> sends up a request to save
- a model, its attributes will be passed, serialized as JSON, and sent in the HTTP body
- with content-type <tt>application/json</tt>. When returning a JSON response,
- send down the attributes of the model that have been changed by the server, and need
- to be updated on the client. When responding to a <tt>"read"</tt> request from a collection
- (<a href="#Collection#fetch">Collection#fetch</a>), send down an array
- of model attribute objects.
- </p>
- <p>
- The default <b>sync</b> handler maps CRUD to REST like so:
- </p>
- <ul>
- <li><b>create → POST </b><tt>/collection</tt></li>
- <li><b>read → GET </b><tt>/collection[/id]</tt></li>
- <li><b>update → PUT </b><tt>/collection/id</tt></li>
- <li><b>delete → DELETE </b><tt>/collection/id</tt></li>
- </ul>
- <p>
- As an example, a Rails handler responding to an <tt>"update"</tt> call from
- <tt>Backbone</tt> might look like this: <i>(In real code, never use
- </i><tt>update_attributes</tt><i> blindly, and always whitelist the attributes
- you allow to be changed.)</i>
- </p>
- <pre>
- def update
- account = Account.find params[:id]
- account.update_attributes params
- render :json => account
- end
- </pre>
- <p>
- One more tip for Rails integration is to disable the default namespacing for
- <tt>to_json</tt> calls on models by setting <tt>ActiveRecord::Base.include_root_in_json = false</tt>
- </p>
- <p id="Sync-emulateHTTP">
- <b class="header">emulateHTTP</b><code>Backbone.emulateHTTP = true</code>
- <br />
- If you want to work with a legacy web server that doesn't support Backbones's
- default REST/HTTP approach, you may choose to turn on <tt>Backbone.emulateHTTP</tt>.
- Setting this option will fake <tt>PUT</tt> and <tt>DELETE</tt> requests with
- a HTTP <tt>POST</tt>, and pass them under the <tt>_method</tt> parameter. Setting this option
- will also set an <tt>X-HTTP-Method-Override</tt> header with the true method.
- </p>
- <pre>
- Backbone.emulateHTTP = true;
- model.save(); // POST to "/collection/id", with "_method=PUT" + header.
- </pre>
- <p id="Sync-emulateJSON">
- <b class="header">emulateJSON</b><code>Backbone.emulateJSON = true</code>
- <br />
- If you're working with a legacy web server that can't handle requests
- encoded as <tt>application/json</tt>, setting <tt>Backbone.emulateJSON = true;</tt>
- will cause the JSON to be serialized under a <tt>model</tt> parameter, and
- the request to be made with a <tt>application/x-www-form-urlencoded</tt>
- mime type, as if from an HTML form.
- </p>
- <h2 id="View">Backbone.View</h2>
- <p>
- Backbone views are almost more convention than they are code — they
- don't determine anything about your HTML or CSS for you, and can be used
- with any JavaScript templating library.
- The general idea is to organize your interface into logical views,
- backed by models, each of which can be updated independently when the
- model changes, without having to redraw the page. Instead of digging into
- a JSON object, looking up an element in the DOM, and updating the HTML by hand,
- you can bind your view's <tt>render</tt> function to the model's <tt>"change"</tt>
- event — and now everywhere that
- model data is displayed in the UI, it is always immediately up to date.
- </p>
- <p id="View-extend">
- <b class="header">extend</b><code>Backbone.View.extend(properties, [classProperties])</code>
- <br />
- Get started with views by creating a custom view class. You'll want to
- override the <a href="#View-render">render</a> function, specify your
- declarative <a href="#View-delegateEvents">events</a>, and perhaps the
- <tt>tagName</tt>, <tt>className</tt>, or <tt>id</tt> of the View's root
- element.
- </p>
- <pre>
- var DocumentRow = Backbone.View.extend({
- tagName: "li",
- className: "document-row",
- events: {
- "click .icon": "open",
- "click .button.edit": "openEditDialog",
- "click .button.delete": "destroy"
- },
- render: function() {
- ...
- }
- });
- </pre>
- <p id="View-constructor">
- <b class="header">constructor / initialize</b><code>new View([options])</code>
- <br />
- When creating a new View, the options you pass are attached to the view
- as <tt>this.options</tt>, for future reference. There are several special
- options that, if passed, will be attached directly to the view:
- <tt>model</tt>, <tt>collection</tt>,
- <tt>el</tt>, <tt>id</tt>, <tt>className</tt>, and <tt>tagName</tt>.
- If the view defines an <b>initialize</b> function, it will be called when
- the view is first created. If you'd like to create a view that references
- an element <i>already</i> in the DOM, pass in the element as an option:
- <tt>new View({el: existingElement})</tt>
- </p>
- <pre>
- var doc = Documents.first();
- new DocumentRow({
- model: doc,
- id: "document-row-" + doc.id
- });
- </pre>
- <p id="View-el">
- <b class="header">el</b><code>view.el</code>
- <br />
- All views have a DOM element at all times (the <b>el</b> property),
- whether they've already been inserted into the page or not. In this
- fashion, views can be rendered at any time, and inserted into the DOM all
- at once, in order to get high-performance UI rendering with as few
- reflows and repaints as possible. <tt>this.el</tt> is created from the
- view's <tt>tagName</tt>, <tt>className</tt>, and <tt>id</tt> properties,
- if specified. If not, <b>el</b> is an empty <tt>div</tt>.
- </p>
- <p>
- You may assign <b>el</b> directly if the view is being
- created for an element that already exists in the DOM. Use either a
- reference to a real DOM element, or a css selector string.
- </p>
- <pre class="runnable">
- var ItemView = Backbone.View.extend({
- tagName: 'li'
- });
- var BodyView = Backbone.View.extend({
- el: 'body'
- });
- var item = new ItemView();
- var body = new BodyView();
- alert(item.el + ' ' + body.el);
- </pre>
- <p id="View-dollar">
- <b class="header">$ (jQuery or Zepto)</b><code>view.$(selector)</code>
- <br />
- If jQuery or Zepto is included on the page, each view has a
- <b>$</b> function that runs queries scoped within the view's element. If you use this
- scoped jQuery function, you don't have to use model ids as part of your query
- to pull out specific elements in a list, and can rely much more on HTML class
- attributes. It's equivalent to running: <tt>$(selector, this.el)</tt>
- </p>
- <pre>
- ui.Chapter = Backbone.View.extend({
- serialize : function() {
- return {
- title: this.$(".title").text(),
- start: this.$(".start-page").text(),
- end: this.$(".end-page").text()
- };
- }
- });
- </pre>
- <p id="View-render">
- <b class="header">render</b><code>view.render()</code>
- <br />
- The default implementation of <b>render</b> is a no-op. Override this
- function with your code that renders the view template from model data,
- and updates <tt>this.el</tt> with the new HTML. A good
- convention is to <tt>return this</tt> at the end of <b>render</b> to
- enable chained calls.
- </p>
- <pre>
- var Bookmark = Backbone.View.extend({
- render: function() {
- $(this.el).html(this.template(this.model.toJSON()));
- return this;
- }
- });
- </pre>
- <p>
- Backbone is agnostic with respect to your preferred method of HTML templating.
- Your <b>render</b> function could even munge together an HTML string, or use
- <tt>document.createElement</tt> to generate a DOM tree. However, we suggest
- choosing a nice JavaScript templating library.
- <a href="http://github.com/janl/mustache.js">Mustache.js</a>,
- <a href="http://github.com/creationix/haml-js">Haml-js</a>, and
- <a href="http://github.com/sstephenson/eco">Eco</a> are all fine alternatives.
- Because <a href="http://documentcloud.github.com/underscore/">Underscore.js</a> is already on the page,
- <a href="http://documentcloud.github.com/underscore/#template">_.template</a>
- is available, and is an excellent choice if you've already XSS-sanitized
- your interpolated data.
- </p>
- <p>
- Whatever templating strategy you end up with, it's nice if you <i>never</i>
- have to put strings of HTML in your JavaScript. At DocumentCloud, we
- use <a href="http://documentcloud.github.com/jammit/">Jammit</a> in order
- to package up JavaScript templates stored in <tt>/app/views</tt> as part
- of our main <tt>core.js</tt> asset package.
- </p>
- <p id="View-remove">
- <b class="header">remove</b><code>view.remove()</code>
- <br />
- Convenience function for removing the view from the DOM. Equivalent to calling
- <tt>$(view.el).remove();</tt>
- </p>
- <p id="View-make">
- <b class="header">make</b><code>view.make(tagName, [attributes], [content])</code>
- <br />
- Convenience function for creating a DOM element of the given type (<b>tagName</b>),
- with optional attributes and HTML content. Used internally to create the
- initial <tt>view.el</tt>.
- </p>
- <pre class="runnable">
- var view = new Backbone.View;
- var el = view.make("b", {className: "bold"}, "Bold! ");
- $("#make-demo").append(el);
- </pre>
- <div id="make-demo"></div>
- <p id="View-delegateEvents">
- <b class="header">delegateEvents</b><code>delegateEvents([events])</code>
- <br />
- Uses jQuery's <tt>delegate</tt> function to provide declarative callbacks
- for DOM events within a view.
- If an <b>events</b> hash is not passed directly, uses <tt>this.events</tt>
- as the source. Events are written in the format <tt>{"event selector": "callback"}</tt>.
- Omitting the <tt>selector</tt> causes the event to be bound to the view's
- root element (<tt>this.el</tt>). By default, <tt>delegateEvents</tt> is called
- within the View's constructor for you, so if you have a simple <tt>events</tt>
- hash, all of your DOM events will always already be connected, and you will
- never have to call this function yourself.
- </p>
-
- <p>
- The <tt>events</tt> property may also be defined as a function that returns
- an <b>events</b> hash, to make it easier to programmatically define your
- events, as well as inherit them from parent views.
- </p>
- <p>
- Using <b>delegateEvents</b> provides a number of advantages over manually
- using jQuery to bind events to child elements during <a href="#View-render">render</a>. All attached
- callbacks are bound to the view before being handed off to jQuery, so when
- the callbacks are invoked, <tt>this</tt> continues to refer to the view object. When
- <b>delegateEvents</b> is run again, perhaps with a different <tt>events</tt>
- hash, all callbacks are removed and delegated afresh — useful for
- views which need to behave differently when in different modes.
- </p>
- <p>
- A view that displays a document in a search result might look
- something like this:
- </p>
- <pre>
- var DocumentView = Backbone.View.extend({
- events: {
- "dblclick" : "open",
- "click .icon.doc" : "select",
- "contextmenu .icon.doc" : "showMenu",
- "click .show_notes" : "toggleNotes",
- "click .title .lock" : "editAccessLevel",
- "mouseover .title .date" : "showTooltip"
- },
- render: function() {
- $(this.el).html(this.template(this.model.toJSON()));
- return this;
- },
- open: function() {
- window.open(this.model.get("viewer_url"));
- },
- select: function() {
- this.model.set({selected: true});
- },
- ...
- });
- </pre>
- <h2 id="Utility">Utility Functions</h2>
- <p>
-
- </p>
- <p id="Utility-noConflict">
- <b class="header">noConflict</b><code>var backbone = Backbone.noConflict();</code>
- <br />
- Returns the <tt>Backbone</tt> object back to its original value. You can
- use the return value of <tt>Backbone.noConflict()</tt> to keep a local
- reference to Backbone. Useful for embedding Backbone on third-party
- websites, where you don't want to clobber the existing Backbone.
- </p>
- <pre>
- var localBackbone = Backbone.noConflict();
- var model = localBackbone.Model.extend(...);
- </pre>
- <h2 id="examples">Examples</h2>
- <p id="examples-todos">
- <a href="http://jgn.me/">Jérôme Gravel-Niquet</a> has contributed a
- <a href="examples/todos/index.html">Todo List application</a>
- that is bundled in the repository as Backbone example. If you're wondering
- where to get started with Backbone in general, take a moment to
- <a href="docs/todos.html">read through the annotated source</a>. The app uses a
- <a href="docs/backbone-localstorage.html">LocalStorage adapter</a>
- to transparently save all of your todos within your browser, instead of
- sending them to a server. Jérôme also has a version hosted at
- <a href="http://localtodos.com/">localtodos.com</a> that uses a
- <a href="http://github.com/jeromegn/backbone-mootools">MooTools-backed version of Backbone</a>
- instead of jQuery.
- </p>
- <div style="text-align: center;">
- <a href="examples/todos/index.html">
- <img src="docs/images/todos.png" alt="Todos" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-documentcloud">DocumentCloud</h2>
-
- <p>
- The <a href="http://www.documentcloud.org/public/#search/">DocumentCloud workspace</a>
- is built on Backbone.js, with <i>Documents</i>, <i>Projects</i>,
- <i>Notes</i>, and <i>Accounts</i> all as Backbone models and collections.
- If you're interested in history — both Underscore.js and Backbone.js
- were originally extracted from the DocumentCloud codebase, and packaged
- into standalone JS libraries.
- </p>
- <div style="text-align: center;">
- <a href="http://www.documentcloud.org/public/#search/">
- <img src="docs/images/dc-workspace.png" alt="DocumentCloud Workspace" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-linkedin">LinkedIn Mobile</h2>
- <p>
- <a href="http://www.linkedin.com/">LinkedIn</a> used Backbone.js to create
- its <a href="http://www.linkedin.com/static?key=mobile">next-generation HTML5 mobile web app</a>.
- Backbone made it easy to keep the app modular, organized and extensible so
- that it was possible to program the complexities of LinkedIn's user experience.
- The app also uses <a href="http://zeptojs.com/">Zepto</a>,
- <a href="http://documentcloud.github.com/underscore/">Underscore.js</a>,
- <a href="http://sass-lang.com/">SASS</a>, <a href="http://cubiq.org/iscroll">iScroll</a>,
- HTML5 LocalStorage and Canvas.
- </p>
- <div style="text-align: center;">
- <a href="http://www.linkedin.com/static?key=mobile">
- <img src="docs/images/linkedin-mobile.png" alt="LinkedIn Mobile" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-flow">Flow</h2>
-
- <p>
- <a href="http://www.metalabdesign.com/">MetaLab</a> used Backbone.js to create
- <a href="http://www.getflow.com/">Flow</a>, a task management app for teams. The
- workspace relies on Backbone.js to construct task views, activities, accounts,
- folders, projects, and tags. You can see the internals under <tt>window.Flow</tt>.
- </p>
- <div style="text-align: center;">
- <a href="http://www.getflow.com/">
- <img src="docs/images/flow.png" alt="Flow" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-basecamp">Basecamp Mobile</h2>
- <p>
- <a href="http://37signals.com/">37Signals</a> used Backbone.js to create
- <a href="http://basecamphq.com/mobile">Basecamp Mobile</a>, the mobile version
- of their popular project management software. You can access all your Basecamp
- projects, post new messages, and comment on milestones (all represented
- internally as Backbone.js models).
- </p>
- <div style="text-align: center;">
- <a href="http://basecamphq.com/mobile">
- <img src="docs/images/basecamp-mobile.png" alt="Basecamp Mobile" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-groupon">Groupon Now!</h2>
-
- <p>
- <a href="http://www.groupon.com/now">Groupon Now!</a> helps you find
- local deals that you can buy and use right now. When first developing
- the product, the team decided it would be AJAX heavy with smooth transitions
- between sections instead of full refreshes, but still needed to be fully
- linkable and shareable. Despite never having used Backbone before, the
- learning curve was incredibly quick — a prototype was hacked out in an
- afternoon, and the team was able to ship the product in two weeks.
- Because the source is minimal and understandable, it was easy to
- add several Backbone extensions for Groupon Now!: changing the router
- to handle URLs with querystring parameters, and adding a simple
- in-memory store for caching repeated requests for the same data.
- </p>
- <div style="text-align: center;">
- <a href="http://www.groupon.com/now">
- <img src="docs/images/groupon.png" alt="Groupon Now!" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-trajectory">Trajectory</h2>
-
- <p>
- <a href="https://www.apptrajectory.com/">Trajectory</a> is an agile
- software planning tool used to discuss wireframes, record decisions made,
- relate user stories and bugs to discussions, and track your progress and
- plan the future. With Rails on the backend, Trajectory uses Backbone.js
- heavily to provide a fluid story planning interface that even updates in
- real-time based on the actions of other users.
- </p>
- <div style="text-align: center;">
- <a href="http://www.apptrajectory.com/">
- <img src="docs/images/trajectory.png" alt="Trajectory" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-soundcloud">SoundCloud Mobile</h2>
- <p>
- <a href="http://soundcloud.com">SoundCloud</a> is the leading sound sharing
- platform on the internet, and Backbone.js provides the foundation for
- <a href="http://m.soundcloud.com">SoundCloud Mobile</a>. The project uses
- the public SoundCloud <a href="http://soundcloud.com/developers">API</a>
- as a data source (channeled through a nginx proxy),
- <a href="http://api.jquery.com/category/plugins/templates/">jQuery templates</a>
- for the rendering, <a href="http://docs.jquery.com/Qunit">Qunit
- </a> and <a href="http://code.google.com/p/phantomjs/">PhantomJS</a> for
- the testing suite. The JS code, templates and CSS are built for the
- production deployment with various Node.js tools like
- <a href="https://github.com/dsimard/ready.js">ready.js</a>,
- <a href="https://github.com/mde/node-jake">Jake</a>,
- <a href="https://github.com/tmpvar/jsdom">jsdom</a>.
- The <b>Backbone.History</b> was modified to support the HTML5 <tt>history.pushState</tt>.
- <b>Backbone.sync</b> was extended with an additional SessionStorage based cache
- layer.
- </p>
- <div style="text-align: center;">
- <a href="http://m.soundcloud.com">
- <img src="docs/images/soundcloud.png" alt="SoundCloud" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-pandora">Pandora</h2>
-
- <p>
- When <a href="http://www.pandora.com/newpandora">Pandora</a> redesigned
- their site in HTML5, they chose Backbone.js to help
- manage the user interface and interactions. For example, there's a model
- that represents the "currently playing track", and multiple views that
- automatically update when the current track changes. The station list is a
- collection, so that when stations are added or changed, the UI stays up to date.
- </p>
- <div style="text-align: center;">
- <a href="http://www.pandora.com/newpandora">
- <img src="docs/images/pandora.png" alt="Pandora" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-cloudapp">CloudApp</h2>
-
- <p>
- <a href="http://getcloudapp.com">CloudApp</a> is simple file and link
- sharing for the Mac. Backbone.js powers the web tools
- which consume the <a href="http://developer.getcloudapp.com">documented API</a>
- to manage Drops. Data is either pulled manually or pushed by
- <a href="http://pusher.com">Pusher</a> and fed to
- <a href="http://github.com/janl/mustache.js">Mustache</a> templates for
- rendering. Check out the <a href="http://cloudapp.github.com/engine">annotated source code</a>
- to see the magic.
- </p>
- <div style="text-align: center;">
- <a href="http://getcloudapp.com">
- <img src="docs/images/cloudapp.png" alt="CloudApp" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-seatgeek">SeatGeek</h2>
-
- <p>
- <a href="http://seatgeek.com">SeatGeek</a>'s stadium ticket maps were originally
- developed with Prototype.js. Moving to Backbone.js and jQuery helped organize
- a lot of the UI code, and the increased structure has made adding features
- a lot easier. SeatGeek is also in the process of building a mobile
- interface that will be Backbone.js from top to bottom.
- </p>
- <div style="text-align: center;">
- <a href="http://seatgeek.com">
- <img src="docs/images/seatgeek.png" alt="SeatGeek" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-tpm">Talking Points Memo: Baroque</h2>
-
- <p>
- <a href="http://labs.talkingpointsmemo.com/2011/08/the-baroque-era.php">Baroque</a>
- is the editor currently powering the homepage of
- <a href="http://talkingpointsmemo.com/">Talking Points Memo</a>.
- With a Sinatra backend for publishing, Baroque uses Backbone.js to provide
- real-time story and asset dropping, complex reordering actions and copy
- editing, making web layout feel much more like print layout.
- </p>
- <div style="text-align: center;">
- <a href="http://labs.talkingpointsmemo.com/2011/08/the-baroque-era.php">
- <img src="docs/images/baroque.jpg" alt="Baroque" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-kicksend">Kicksend</h2>
-
- <p>
- <a href="http://kicksend.com">Kicksend</a> is a real-time file sharing
- platform that helps everyday people send and receive files of any size
- with their friends and family. Kicksend's web application makes extensive
- use of Backbone.js to model files, friends, lists and activity streams.
- </p>
- <div style="text-align: center;">
- <a href="http://kicksend.com">
- <img src="docs/images/kicksend.png" alt="Kicksend" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-shortmail">Shortmail</h2>
-
- <p>
- <a href="http://410labs.com/">410 Labs</a> uses Backbone.js at
- <a href="http://shortmail.com/">Shortmail.com</a> to build a
- fast and responsive inbox, driven by the <a href="#Router">Router</a>.
- Backbone works with a Rails backend to provide inbox rendering, archiving,
- replying, composing, and even a changes feed. Using Backbone's event-driven
- model and pushing the rendering and interaction logic to the front-end
- has not only simplified the view code, it has also drastically reduced the
- load on Shortmail's servers.
- </p>
- <div style="text-align: center;">
- <a href="http://shortmail.com">
- <img src="docs/images/shortmail.png" alt="Shortmail" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-hotel-tonight">Hotel Tonight</h2>
-
- <p>
- <a href="http://www.hoteltonight.com/">Hotel Tonight</a> used Backbone.js,
- <a href="http://coffeescript.org">CoffeeScript</a>,
- <a href="http://documentcloud.github.com/jammit/">Jammit</a> and more to
- create the
- <a href="https://market.android.com/details?id=com.hoteltonight.android.prod">Android version</a>
- of their app; a last-minute, mobile, hotel booking application. The app
- leverages Backbone for the bulk of its architecture, with jQuery Mobile
- coming in for visual presentation.
- </p>
- <div style="text-align: center;">
- <a href="http://www.hoteltonight.com">
- <img src="docs/images/hotel-tonight.png" alt="Hotel Tonight" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-salon">Salon.io</h2>
-
- <p>
- <a href="http://salon.io">Salon.io</a> provides a space where photographers,
- artists and designers freely arrange their visual art on virtual walls.
- <a href="http://salon.io">Salon.io</a> runs on Rails, but does not use
- much of the traditional stack, as the entire frontend is designed as a
- single page web app, using Backbone.js and
- <a href="http://coffeescript.org">CoffeeScript</a>.
- </p>
- <div style="text-align: center;">
- <a href="http://salon.io">
- <img src="docs/images/salon.png" alt="Salon.io" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-quoteroller">Quote Roller</h2>
-
- <p>
- <a href="http://www.codingstaff.com">Coding Staff</a> used Backbone.js to
- create <a href="http://www.quoteroller.com">Quote Roller</a>, an application
- that helps to create, send, organize and track business proposals with ease.
- Backbone.js has been used to implement interactive parts of the
- application like template builder, pricing table, file attachments manager.
- </p>
- <div style="text-align: center;">
- <a href="http://www.quoteroller.com">
- <img src="docs/images/quoteroller.png" alt="Quote Roller" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-tilemill">TileMill</h2>
-
- <p>
- Our fellow
- <a href="http://www.newschallenge.org/">Knight Foundation News Challenge</a>
- winners, <a href="http://mapbox.com/">MapBox</a>, created an open-source
- map design studio with Backbone.js:
- <a href="http://mapbox.github.com/tilemill/">TileMill</a>.
- TileMill lets you manage map layers based on shapefiles and rasters, and
- edit their appearance directly in the browser with the
- <a href="https://github.com/mapbox/carto">Carto styling language</a>.
- Note that the gorgeous <a href="http://mapbox.com/">MapBox</a> homepage
- is also a Backbone.js app.
- </p>
- <div style="text-align: center;">
- <a href="http://mapbox.github.com/tilemill/">
- <img src="docs/images/tilemill.png" alt="TileMill" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-rround">rround.me</h2>
-
- <p>
- <a href="http://rround.me">rround.me</a> uses the HTML
- <a href="http://diveintohtml5.org/geolocation.html">Geolocation API</a>
- to discover tweets, YouTube videos, Instagram photos, Foursquare spots, and other happenings
- posted by people close to you. The site is a single-page app built on Backbone.js,
- with people, locations and events all represented by Backbone Models.
- Backbone Views listen for changes in the underlying data as you adjust
- the range (distance) of your search.
- </p>
- <div style="text-align: center;">
- <a href="http://rround.me/">
- <img src="docs/images/rround.png" alt="rround.me" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-blossom">Blossom</h2>
-
- <p>
- <a href="http://blossom.io">Blossom</a> is a lightweight project management
- tool for lean teams. Backbone.js is heavily used in combination with
- <a href="http://coffeescript.org">CoffeeScript</a> to provide a smooth
- interaction experience. The RESTful backend is built
- with <a href="http://flask.pocoo.org/">Flask</a> on Google App Engine.
- </p>
- <div style="text-align: center;">
- <a href="http://blossom.io">
- <img src="docs/images/blossom.png" alt="Blossom" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-instagreat">Insta-great!</h2>
-
- <p>
- <a href="http://twitter.com/elliottkember">Elliott Kember</a> and
- <a href="http://twitter.com/dizzyup">Hector Simpson</a> built
- <a href="http://instagre.at">Insta-great!</a>
- - a fun way to explore popular photos and interact with
- <a href="http://instagram.com/">Instagram</a> on the web.
- Elliott says, "Backbone.js and Coffeescript were insanely useful for
- writing clean, consistent UI code and keeping everything modular and
- readable, even through several code refactors. I'm in love."
- </p>
- <div style="text-align: center;">
- <a href="http://instagre.at">
- <img src="docs/images/instagreat.png" alt="instagre.at" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-decide">Decide</h2>
-
- <p>
- <a href="http://decide.com">Decide.com</a> helps people decide when to buy
- consumer electronics. It relies heavily on Backbone.js to render and
- update its Search Results Page. An "infinite scroll" feature takes
- advantage of a SearchResults model containing a collection of
- Product models to fetch more results and render them on the fly
- with Mustache. A SearchController keeps everything in sync and
- maintains page state in the URL. Backbone also powers the user
- accounts and settings management.
- </p>
- <div style="text-align: center;">
- <a href="http://decide.com">
- <img src="docs/images/decide.png" alt="Decide" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-trello">Trello</h2>
-
- <p>
- <a href="http://trello.com">Trello</a> is a collaboration tool that
- organizes your projects into boards. A Trello board holds many lists of
- cards, which can contain checklists, files and conversations, and may be
- voted on and organized with labels. Updates on the board happen in
- real time. The site was built ground up using Backbone.js for all the
- models, views, and routes.
- </p>
- <div style="text-align: center;">
- <a href="http://trello.com">
- <img src="docs/images/trello.png" alt="Trello" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-bittorrent">BitTorrent</h2>
-
- <p>
- <a href="http://www.bittorrent.com">BitTorrent</a> used Backbone to
- completely rework an existing Win32 UI. Models normalize access to the
- client's data and views rely heavily on the <tt>change</tt> events to keep
- the UI state current. Using Backbone and SCSS,
- <a href="http://www.bittorrent.com/chrysalis/">our new design</a> and UX
- prototypes are considerably easier to iterate, test and work with than
- the original Win32 UI.
- </p>
- <div style="text-align: center;">
- <a href="http://www.bittorrent.com/chrysalis/">
- <img src="docs/images/bittorrent.jpg" alt="BitTorrent" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-trapit">Trapit</h2>
-
- <p>
- <a href="http://trap.it">Trapit</a> brings the web to you, scouring
- the web on your behalf, 24/7. The product, currently in private beta,
- uses Backbone to organize the best, most relevant content into individual
- "traps" on your favorite topics and interests.
- </p>
- <div style="text-align: center;">
- <a href="http://trap.it">
- <img src="docs/images/trapit.png" alt="Trapit" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-fluxiom">Fluxiom</h2>
-
- <p>
- <a href="http://fluxiom.com">Fluxiom</a> uses Backbone.js and HTML5 to
- deliver a seamless upload experience from the desktop to the cloud,
- including drag and drop, live previews, partial uploads, and one-click sharing.
- <p>
-
- <p>
- The upload queue is a single collection and each file is it’s own model.
- The UI is divided into several views for efficient event handling, and
- uses <a href="http://documentcloud.github.com/underscore/">Underscore.js</a>
- templates for fast rendering, even when handling hundreds of uploads.
- </p>
-
- <div style="text-align: center;">
- <a href="http://fluxiom.com/">
- <img src="docs/images/fluxiom.png" alt="Fluxiom" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-chop">Chop</h2>
-
- <p>
- <a href="http://chopapp.com/">Chop</a> is a little app from
- <a href="http://www.zurb.com/">ZURB</a> that lets people slice up bad code
- and share their feedback to help put it back together.
- Chop was built to demonstrate how easy it is to build pageless apps
- using Backbone.js and Rails. Chop makes extensive use of Backbone <b>Views</b>,
- <b>Controllers</b>, and <b>Models</b>.
- </p>
-
- <div style="text-align: center;">
- <a href="http://chopapp.com/">
- <img src="docs/images/chop.png" alt="Chop" class="example_image" />
- </a>
- </div>
-
-
- <h2 id="examples-blackcomb">Blackcomb</h2>
-
- <p>
- <a href="http://www.opzi.com/">Opzi</a> used Backbone.js to create
- <a href="http://www.opzi.com/">Blackcomb</a>, a web-based platform for collaboration
- applications. Apps can be installed through a simple app store or added in
- custom configurations by editing a simple YAML file. The project relied
- heavily on Backbone.js for the creation of reusable view components.
- </p>
-
- <div style="text-align: center;">
- <a href="http://www.opzi.com/">
- <img src="docs/images/blackcomb.png" alt="Blackcomb" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-test-kitchen">America’s Test Kitchen</h2>
- <p>
- <a href="http://www.testkitchenschool.com/">America’s Test Kitchen</a>,
- an online cooking school, uses Backbone.js to manage quizzes, polls,
- kitchen assignments, recipe tutorials and a hybrid HTML5/Flash video player.
- The whole Backbone codebase is about 5k SLOC, with Mustache.js for
- templating, and Rails on the back end. <a href="http://wir35.com/">Max Lord</a>
- writes: “Working with Backbone made this one of the most pleasurable
- large scale client-side projects I have ever worked on, and I am definitely
- planning on continuing to work with it.”
- </p>
- <div style="text-align: center;">
- <a href="http://www.testkitchenschool.com/">
- <img src="docs/images/test-kitchen.png" alt="America's Test Kitchen" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-quietwrite">QuietWrite</h2>
- <p>
- <a href="http://www.twitter.com/jamesjyu">James Yu</a> used Backbone.js to
- create <a href="http://www.quietwrite.com/">QuietWrite</a>, an app
- that gives writers a clean and quiet interface to concentrate on the text itself.
- The editor relies on Backbone to persist document data to the server. He
- followed up with a Backbone.js + Rails tutorial that describes how to implement
- <a href="http://www.jamesyu.org/2011/01/27/cloudedit-a-backbone-js-tutorial-by-example/">CloudEdit, a simple document editing app</a>.
- </p>
- <div style="text-align: center;">
- <a href="http://www.quietwrite.com/">
- <img src="docs/images/quietwrite.png" alt="QuietWrite" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-tzigla">Tzigla</h2>
- <p>
- <a href="http://twitter.com/evilchelu">Cristi Balan</a> and
- <a href="http://dira.ro">Irina Dumitrascu</a> created
- <a href="http://tzigla.com">Tzigla</a>, a collaborative drawing
- application where artists make tiles that connect to each other to
- create <a href="http://tzigla.com/boards/1">surreal drawings</a>.
- Backbone models help organize the code, routers provide
- <a href="http://tzigla.com/boards/1#!/tiles/2-2">bookmarkable deep links</a>,
- and the views are rendered with
- <a href="https://github.com/creationix/haml-js">haml.js</a> and
- <a href="http://zeptojs.com/">Zepto</a>.
- Tzigla is written in Ruby (Rails) on the backend, and
- <a href="http://coffeescript.org">CoffeeScript</a> on the frontend, with
- <a href="http://documentcloud.github.com/jammit/">Jammit</a>
- prepackaging the static assets.
- </p>
- <div style="text-align: center;">
- <a href="http://www.tzigla.com/">
- <img src="docs/images/tzigla.png" alt="Tzigla" class="example_image" />
- </a>
- </div>
-
- <h2 id="examples-substance">Substance</h2>
-
- <p>
- Michael Aufreiter is building an open source document authoring and
- publishing engine: <a href="http://substance.io">Substance</a>.
- Substance makes use of Backbone.View and Backbone.Router, while
- Backbone plays well together with
- <a href="http://github.com/michael/data">Data.js</a>, which is used for
- data persistence.
- </p>
- <div style="text-align: center;">
- <a href="http://substance.io/">
- <img src="docs/images/substance.png" alt="Substance" class="example_image" />
- </a>
- </div>
- <h2 id="faq">F.A.Q.</h2>
- <p id="FAQ-events">
- <b class="header">Catalog of Events</b>
- <br />
- Here's a list of all of the built-in events that Backbone.js can fire.
- You're also free to trigger your own events on Models and Views as you
- see fit.
- </p>
- <ul>
- <li><b>"add"</b> (model, collection) — when a model is added to a collection. </li>
- <li><b>"remove"</b> (model, collection) — when a model is removed from a collection. </li>
- <li><b>"reset"</b> (collection) — when the collection's entire contents have been replaced. </li>
- <li><b>"change"</b> (model, collection) — when a model's attributes have changed. </li>
- <li><b>"change:[attribute]"</b> (model, collection) — when a specific attribute has been updated. </li>
- <li><b>"destroy"</b> (model, collection) — when a model is <a href="#Model-destroy">destroyed</a>. </li>
- <li><b>"error"</b> (model, collection) — when a model's validation fails, or a <a href="#Model-save">save</a> call fails on the server. </li>
- <li><b>"route:[name]"</b> (router) — when one of a router's routes has matched. </li>
- <li><b>"all"</b> — this special event fires for <i>any</i> triggered event, passing the event name as the first argument. </li>
- </ul>
-
- <p id="FAQ-tim-toady">
- <b class="header">There's More Than One Way To Do It</b>
- <br />
- It's common for folks just getting started to treat the examples listed
- on this page as some sort of gospel truth. In fact, Backbone.js is intended
- to be fairly agnostic about many common patterns in client-side code.
- For example...
- </p>
-
- <p>
- <b>References between Models and Views</b> can be handled several ways.
- Some people like to have direct pointers, where views correspond 1:1 with
- models (<tt>model.view</tt> and <tt>view.model</tt>). Others prefer to have intermediate
- "controller" objects that orchestrate the creation and organization of
- views into a hierarchy. Others still prefer the evented approach, and always
- fire events instead of calling methods directly. All of these styles work well.
- </p>
-
- <p>
- <b>Batch operations</b> on Models are common, but often best handled differently
- depending on your server-side setup. Some folks don't mind making individual
- Ajax requests. Others create explicit resources for RESTful batch operations:
- <tt>/notes/batch/destroy?ids=1,2,3,4</tt>. Others tunnel REST over JSON, with the
- creation of "changeset" requests:
- </p>
-
- <pre>
- {
- "create": [array of models to create]
- "update": [array of models to update]
- "destroy": [array of model ids to destroy]
- }
- </pre>
- <p>
- <b>Feel free to define your own events.</b> <a href="#Events">Backbone.Events</a>
- is designed so that you can mix it in to any JavaScript object or prototype.
- Since you can use any string as an event, it's often handy to bind
- and trigger your own custom events: <tt>model.bind("selected:true")</tt> or
- <tt>model.bind("editing")</tt>
- </p>
-
- <p>
- <b>Render the UI</b> as you see fit. Backbone is agnostic as to whether you
- use <a href="http://documentcloud.github.com/underscore/#template">Underscore templates</a>,
- <a href="https://github.com/janl/mustache.js">Mustache.js</a>, direct DOM
- manipulation, server-side rendered snippets of HTML, or
- <a href="http://jqueryui.com/">jQuery UI</a> in your <tt>render</tt> function.
- Sometimes you'll create a view for each model ... sometimes you'll have a
- view that renders thousands of models at once, in a tight loop. Both can be
- appropriate in the same app, depending on the quantity of data involved,
- and the complexity of the UI.
- </p>
- <p id="FAQ-nested">
- <b class="header">Nested Models & Collections</b>
- <br />
- It's common to nest collections inside of models with Backbone. For example,
- consider a <tt>Mailbox</tt> model that contains many <tt>Message</tt> models.
- One nice pattern for handling this is have a <tt>this.messages</tt> collection
- for each mailbox, enabling the lazy-loading of messages, when the mailbox
- is first opened ... perhaps with <tt>MessageList</tt> views listening for
- <tt>"add"</tt> and <tt>"remove"</tt> events.
- </p>
- <pre>
- var Mailbox = Backbone.Model.extend({
- initialize: function() {
- this.messages = new Messages;
- this.messages.url = '/mailbox/' + this.id + '/messages';
- this.messages.bind("reset", this.updateCounts);
- },
- ...
- });
- var Inbox = new Mailbox;
- // And then, when the Inbox is opened:
- Inbox.messages.fetch();
- </pre>
- <p>
- If you're looking for something more opinionated, there are a number of
- Backbone plugins that add sophisticated associations among models,
- <a href="https://github.com/documentcloud/backbone/wiki/Extensions%2C-Plugins%2C-Resources">available on the wiki</a>.
- </p>
- <p id="FAQ-bootstrap">
- <b class="header">Loading Bootstrapped Models</b>
- <br />
- When your app first loads, it's common to have a set of initial models that
- you know you're going to need, in order to render the page. Instead of
- firing an extra AJAX request to <a href="#Collection-fetch">fetch</a> them,
- a nicer pattern is to have their data already bootstrapped into the page.
- You can then use <a href="#Collection-reset">reset</a> to populate your
- collections with the initial data. At DocumentCloud, in the
- <a href="http://en.wikipedia.org/wiki/ERuby">ERB</a> template for the
- workspace, we do something along these lines:
- </p>
- <pre>
- <script>
- Accounts.reset(<%= @accounts.to_json %>);
- Projects.reset(<%= @projects.to_json(:collaborators => true) %>);
- </script>
- </pre>
- <p id="FAQ-mvc">
- <b class="header">How does Backbone relate to "traditional" MVC?</b>
- <br />
- Different implementations of the
- <a href="http://en.wikipedia.org/wiki/Model–View–Controller">Model-View-Controller</a>
- pattern tend to disagree about the definition of a controller. If it helps any, in
- Backbone, the <a href="#View">View</a> class can also be thought of as a
- kind of controller, dispatching events that originate from the UI, with
- the HTML template serving as the true view. We call it a View because it
- represents a logical chunk of UI, responsible for the contents of a single
- DOM element.
- </p>
-
- <p>
- Comparing the overall structure of Backbone to a server-side MVC framework
- like <b>Rails</b>, the pieces line up like so:
- </p>
-
- <ul>
- <li>
- <b>Backbone.Model</b> – Like a Rails model minus the class
- methods. Wraps a row of data in business logic.
- </li>
- <li>
- <b>Backbone.Collection</b> – A group of models on the client-side,
- with sorting/filtering/aggregation logic.
- </li>
- <li>
- <b>Backbone.Router</b> – Rails <tt>routes.rb</tt> + Rails controller
- actions. Maps URLs to functions.
- </li>
- <li>
- <b>Backbone.View</b> – A logical, re-usable piece of UI. Often,
- but not always, associated with a model.
- </li>
- <li>
- <b>Client-side Templates</b> – Rails <tt>.html.erb</tt> views,
- rendering a chunk of HTML.
- </li>
- </ul>
- <p id="FAQ-this">
- <b class="header">Binding "this"</b>
- <br />
- Perhaps the single most common JavaScript "gotcha" is the fact that when
- you pass a function as a callback, its value for <tt>this</tt> is lost. With
- Backbone, when dealing with <a href="#Events">events</a> and callbacks,
- you'll often find it useful to rely on
- <a href="http://documentcloud.github.com/underscore/#bind">_.bind</a> and
- <a href="http://documentcloud.github.com/underscore/#bindAll">_.bindAll</a>
- from Underscore.js.
- </p>
-
- <p>
- When binding callbacks to Backbone events, you can choose to pass an optional
- third argument to specify the <tt>this</tt> that will be used when the
- callback is later invoked:
- </p>
- <pre>
- var MessageList = Backbone.View.extend({
- initialize: function() {
- var messages = this.collection;
- messages.bind("reset", this.render, this);
- messages.bind("add", this.addMessage, this);
- messages.bind("remove", this.removeMessage, this);
- }
- });
- // Later, in the app...
- Inbox.messages.add(newMessage);
- </pre>
- <h2 id="changelog">Change Log</h2>
-
- <p>
- <b class="header">0.5.3</b> — <small><i>August 9, 2011</i></small><br />
- A View's <tt>events</tt> property may now be defined as a function, as well
- as an object literal, making it easier to programmatically define and inherit
- events. <tt>groupBy</tt> is now proxied from Underscore as a method on Collections.
- If the server has already rendered everything on page load, pass
- <tt>Backbone.history.start({silent: true})</tt> to prevent the initial route
- from triggering. Bugfix for pushState with encoded URLs.
- </p>
-
- <p>
- <b class="header">0.5.2</b> — <small><i>July 26, 2011</i></small><br />
- The <tt>bind</tt> function, can now take an optional third argument, to specify
- the <tt>this</tt> of the callback function.
- Multiple models with the same <tt>id</tt> are now allowed in a collection.
- Fixed a bug where calling <tt>.fetch(jQueryOptions)</tt> could cause an
- incorrect URL to be serialized.
- Fixed a brief extra route fire before redirect, when degrading from
- <tt>pushState</tt>.
- </p>
-
- <p>
- <b class="header">0.5.1</b> — <small><i>July 5, 2011</i></small><br />
- Cleanups from the 0.5.0 release, to wit: improved transparent upgrades from
- hash-based URLs to pushState, and vice-versa. Fixed inconsistency with
- non-modified attributes being passed to <tt>Model#initialize</tt>. Reverted
- a <b>0.5.0</b> change that would strip leading hashbangs from routes.
- Added <tt>contains</tt> as an alias for <tt>includes</tt>.
- </p>
- <p>
- <b class="header">0.5.0</b> — <small><i>July 1, 2011</i></small><br />
- A large number of tiny tweaks and micro bugfixes, best viewed by looking
- at <a href="https://github.com/documentcloud/backbone/compare/0.3.3...0.5.0">the commit diff</a>.
- HTML5 <tt>pushState</tt> support, enabled by opting-in with:
- <tt>Backbone.history.start({pushState: true})</tt>.
- <tt>Controller</tt> was renamed to <tt>Router</tt>, for clarity.
- <tt>Collection#refresh</tt> was renamed to <tt>Collection#reset</tt> to emphasize
- its ability to both reset the collection with new models, as well as empty
- out the collection when used with no parameters.
- <tt>saveLocation</tt> was replaced with <tt>navigate</tt>.
- RESTful persistence methods (save, fetch, etc.) now return the jQuery deferred
- object for further success/error chaining and general convenience.
- Improved XSS escaping for <tt>Model#escape</tt>.
- Added a <tt>urlRoot</tt> option to allow specifying RESTful urls without
- the use of a collection.
- An error is thrown if <tt>Backbone.history.start</tt> is called multiple times.
- <tt>Collection#create</tt> now validates before initializing the new model.
- <tt>view.el</tt> can now be a jQuery string lookup.
- Backbone Views can now also take an <tt>attributes</tt> parameter.
- <tt>Model#defaults</tt> can now be a function as well as a literal attributes
- object.
- </p>
-
- <p>
- <b class="header">0.3.3</b> — <small><i>Dec 1, 2010</i></small><br />
- Backbone.js now supports <a href="http://zeptojs.com">Zepto</a>, alongside
- jQuery, as a framework for DOM manipulation and Ajax support.
- Implemented <a href="#Model-escape">Model#escape</a>, to efficiently handle
- attributes intended for HTML interpolation. When trying to persist a model,
- failed requests will now trigger an <tt>"error"</tt> event. The
- ubiquitous <tt>options</tt> argument is now passed as the final argument
- to all <tt>"change"</tt> events.
- </p>
- <p>
- <b class="header">0.3.2</b> — <small><i>Nov 23, 2010</i></small><br />
- Bugfix for IE7 + iframe-based "hashchange" events. <tt>sync</tt> may now be
- overridden on a per-model, or per-collection basis. Fixed recursion error
- when calling <tt>save</tt> with no changed attributes, within a
- <tt>"change"</tt> event.
- </p>
- <p>
- <b class="header">0.3.1</b> — <small><i>Nov 15, 2010</i></small><br />
- All <tt>"add"</tt> and <tt>"remove"</tt> events are now sent through the
- model, so that views can listen for them without having to know about the
- collection. Added a <tt>remove</tt> method to <a href="#View">Backbone.View</a>.
- <tt>toJSON</tt> is no longer called at all for <tt>'read'</tt> and <tt>'delete'</tt> requests.
- Backbone routes are now able to load empty URL fragments.
- </p>
- <p>
- <b class="header">0.3.0</b> — <small><i>Nov 9, 2010</i></small><br />
- Backbone now has <a href="#Controller">Controllers</a> and
- <a href="#History">History</a>, for doing client-side routing based on
- URL fragments.
- Added <tt>emulateHTTP</tt> to provide support for legacy servers that don't
- do <tt>PUT</tt> and <tt>DELETE</tt>.
- Added <tt>emulateJSON</tt> for servers that can't accept <tt>application/json</tt>
- encoded requests.
- Added <a href="#Model-clear">Model#clear</a>, which removes all attributes
- from a model.
- All Backbone classes may now be seamlessly inherited by CoffeeScript classes.
- </p>
- <p>
- <b class="header">0.2.0</b> — <small><i>Oct 25, 2010</i></small><br />
- Instead of requiring server responses to be namespaced under a <tt>model</tt>
- key, now you can define your own <a href="#Model-parse">parse</a> method
- to convert responses into attributes for Models and Collections.
- The old <tt>handleEvents</tt> function is now named
- <a href="#View-delegateEvents">delegateEvents</a>, and is automatically
- called as part of the View's constructor.
- Added a <a href="#Collection-toJSON">toJSON</a> function to Collections.
- Added <a href="#Collection-chain">Underscore's chain</a> to Collections.
- </p>
- <p>
- <b class="header">0.1.2</b> — <small><i>Oct 19, 2010</i></small><br />
- Added a <a href="#Model-fetch">Model#fetch</a> method for refreshing the
- attributes of single model from the server.
- An <tt>error</tt> callback may now be passed to <tt>set</tt> and <tt>save</tt>
- as an option, which will be invoked if validation fails, overriding the
- <tt>"error"</tt> event.
- You can now tell backbone to use the <tt>_method</tt> hack instead of HTTP
- methods by setting <tt>Backbone.emulateHTTP = true</tt>.
- Existing Model and Collection data is no longer sent up unnecessarily with
- <tt>GET</tt> and <tt>DELETE</tt> requests. Added a <tt>rake lint</tt> task.
- Backbone is now published as an <a href="http://npmjs.org">NPM</a> module.
- </p>
- <p>
- <b class="header">0.1.1</b> — <small><i>Oct 14, 2010</i></small><br />
- Added a convention for <tt>initialize</tt> functions to be called
- upon instance construction, if defined. Documentation tweaks.
- </p>
- <p>
- <b class="header">0.1.0</b> — <small><i>Oct 13, 2010</i></small><br />
- Initial Backbone release.
- </p>
- <p>
- <br />
- <a href="http://documentcloud.org/" title="A DocumentCloud Project" style="background:none;">
- <img src="http://jashkenas.s3.amazonaws.com/images/a_documentcloud_project.png" alt="A DocumentCloud Project" style="position:relative;left:-10px;" />
- </a>
- </p>
- </div>
- <script src="test/vendor/underscore-1.1.6.js"></script>
- <script src="test/vendor/jquery-1.5.js"></script>
- <script src="test/vendor/json2.js"></script>
- <script src="backbone.js"></script>
- <script>
- // Set up the "play" buttons for each runnable code example.
- $(function() {
- $('.runnable').each(function() {
- var code = this;
- var button = $('<div class="run" title="Run"></div>');
- $(button).insertBefore(code).bind('click', function(){
- eval($(code).text());
- });
- });
- });
- </script>
- </body>
- </html>