mirror of
https://github.com/jashkenas/backbone.git
synced 2026-01-17 02:47:58 -05:00
3666 lines
144 KiB
HTML
3666 lines
144 KiB
HTML
<!DOCTYPE HTML>
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="content-type" content="text/html;charset=UTF-8" />
|
||
<meta http-equiv="X-UA-Compatible" content="chrome=1" />
|
||
<link rel="icon" href="docs/images/favicon.ico" />
|
||
<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 #bbb;
|
||
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: 25px 0;
|
||
width: 550px;
|
||
}
|
||
p.warning {
|
||
font-size: 12px;
|
||
line-height: 18px;
|
||
font-style: italic;
|
||
}
|
||
div.container ul {
|
||
list-style: circle;
|
||
padding-left: 15px;
|
||
font-size: 13px;
|
||
line-height: 18px;
|
||
}
|
||
div.container ul li {
|
||
margin-bottom: 10px;
|
||
}
|
||
div.container ul.small {
|
||
font-size: 12px;
|
||
}
|
||
a, a:visited {
|
||
color: #444;
|
||
}
|
||
a:active, a:hover {
|
||
color: #000;
|
||
}
|
||
a.punch {
|
||
display: inline-block;
|
||
background: #4162a8;
|
||
border-top: 1px solid #38538c;
|
||
border-right: 1px solid #1f2d4d;
|
||
border-bottom: 1px solid #151e33;
|
||
border-left: 1px solid #1f2d4d;
|
||
-webkit-border-radius: 4px;
|
||
-moz-border-radius: 4px;
|
||
-ms-border-radius: 4px;
|
||
-o-border-radius: 4px;
|
||
border-radius: 4px;
|
||
-webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
-moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
-ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
-o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
box-shadow: inset 0 1px 10px 1px #5c8bee, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
color: #fff;
|
||
font: bold 14px "helvetica neue", helvetica, arial, sans-serif;
|
||
line-height: 1;
|
||
margin-bottom: 15px;
|
||
padding: 8px 0 10px 0;
|
||
text-align: center;
|
||
text-shadow: 0px -1px 1px #1e2d4d;
|
||
text-decoration: none;
|
||
width: 225px;
|
||
-webkit-background-clip: padding-box; }
|
||
a.punch:hover {
|
||
-webkit-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
-moz-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
-ms-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
-o-box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
box-shadow: inset 0 0px 20px 1px #87adff, 0px 1px 0 #1d2c4d, 0 6px 0px #1f3053, 0 8px 4px 1px #111111;
|
||
cursor: pointer; }
|
||
a.punch:active {
|
||
-webkit-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
|
||
-moz-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
|
||
-ms-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
|
||
-o-box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
|
||
box-shadow: inset 0 1px 10px 1px #5c8bee, 0 1px 0 #1d2c4d, 0 2px 0 #1f3053, 0 4px 3px 0 #111111;
|
||
margin-top: 5px; margin-bottom: 10px }
|
||
a img {
|
||
border: 0;
|
||
}
|
||
h1, h2, h3, h4, h5, h6 {
|
||
padding-top: 20px;
|
||
}
|
||
h2 {
|
||
font-size: 22px;
|
||
}
|
||
b.header {
|
||
font-size: 18px;
|
||
line-height: 35px;
|
||
}
|
||
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 25px;
|
||
}
|
||
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.9.2)</span>
|
||
</a>
|
||
<ul class="toc_section">
|
||
<li>» <a href="http://github.com/documentcloud/backbone">GitHub Repository</a></li>
|
||
<li>» <a href="docs/backbone.html">Annotated Source</a></li>
|
||
</ul>
|
||
|
||
<a class="toc_title" href="#introduction">
|
||
Introduction
|
||
</a>
|
||
|
||
<a class="toc_title" href="#upgrading">
|
||
Upgrading
|
||
</a>
|
||
|
||
<a class="toc_title" href="#Events">
|
||
Events
|
||
</a>
|
||
<ul class="toc_section">
|
||
<li>– <a href="#Events-on">on</a></li>
|
||
<li>– <a href="#Events-off">off</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-idAttribute">idAttribute</a></li>
|
||
<li>– <a href="#Model-cid">cid</a></li>
|
||
<li>– <a href="#Model-attributes">attributes</a></li>
|
||
<li>– <a href="#Model-changed">changed</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-isValid">isValid</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 (28)</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-push">push</a></li>
|
||
<li>– <a href="#Collection-pop">pop</a></li>
|
||
<li>– <a href="#Collection-unshift">unshift</a></li>
|
||
<li>– <a href="#Collection-shift">shift</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-where">where</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-$el">$el</a></li>
|
||
<li>– <a href="#View-setElement">setElement</a></li>
|
||
<li>– <a href="#View-attributes">attributes</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>
|
||
<li>– <a href="#View-undelegateEvents">undelegateEvents</a></li>
|
||
</ul>
|
||
|
||
<a class="toc_title" href="#Utility">
|
||
Utility
|
||
</a>
|
||
<ul class="toc_section">
|
||
<li>– <a href="#Utility-noConflict">noConflict</a></li>
|
||
<li>– <a href="#Utility-setDomLibrary">setDomLibrary</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-audiovroom">AudioVroom</a></li>
|
||
<li>– <a href="#examples-foursquare">Foursquare</a></li>
|
||
<li>– <a href="#examples-wunderkit">Wunderkit</a></li>
|
||
<li>– <a href="#examples-khan-academy">Khan Academy</a></li>
|
||
<li>– <a href="#examples-do">Do</a></li>
|
||
<li>– <a href="#examples-posterous">Posterous Spaces</a></li>
|
||
<li>– <a href="#examples-groupon">Groupon Now!</a></li>
|
||
<li>– <a href="#examples-basecamp">Basecamp Mobile</a></li>
|
||
<li>– <a href="#examples-slavery-footprint">Slavery Footprint</a></li>
|
||
<li>– <a href="#examples-stripe">Stripe</a></li>
|
||
<li>– <a href="#examples-airbnb">Airbnb Mobile</a></li>
|
||
<li>– <a href="#examples-diaspora">Diaspora</a></li>
|
||
<li>– <a href="#examples-soundcloud">SoundCloud Mobile</a></li>
|
||
<li>– <a href="#examples-pandora">Pandora</a></li>
|
||
<li>– <a href="#examples-code-school">Code School</a></li>
|
||
<li>– <a href="#examples-cloudapp">CloudApp</a></li>
|
||
<li>– <a href="#examples-seatgeek">SeatGeek</a></li>
|
||
<li>– <a href="#examples-grove">Grove.io</a></li>
|
||
<li>– <a href="#examples-kicksend">Kicksend</a></li>
|
||
<li>– <a href="#examples-shortmail">Shortmail</a></li>
|
||
<li>– <a href="#examples-battlefield">Battlefield Play4Free</a></li>
|
||
<li>– <a href="#examples-salon">Salon.io</a></li>
|
||
<li>– <a href="#examples-tilemill">TileMill</a></li>
|
||
<li>– <a href="#examples-blossom">Blossom</a></li>
|
||
<li>– <a href="#examples-animoto">Animoto</a></li>
|
||
<li>– <a href="#examples-chaincal">ChainCal</a></li>
|
||
<li>– <a href="#examples-attictv">AtticTV</a></li>
|
||
<li>– <a href="#examples-decide">Decide</a></li>
|
||
<li>– <a href="#examples-trello">Trello</a></li>
|
||
<li>– <a href="#examples-ducksboard">Ducksboard</a></li>
|
||
<li>– <a href="#examples-picklive">Picklive</a></li>
|
||
<li>– <a href="#examples-quietwrite">QuietWrite</a></li>
|
||
<li>– <a href="#examples-tzigla">Tzigla</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-extending">Extending Backbone</a></li>
|
||
<li>– <a href="#FAQ-mvc">Traditional MVC</a></li>
|
||
<li>– <a href="#FAQ-this">Binding "this"</a></li>
|
||
<li>– <a href="#FAQ-rails">Working with Rails</a></li>
|
||
</ul>
|
||
|
||
<a class="toc_title" href="#changelog">
|
||
Change Log
|
||
</a>
|
||
|
||
</div>
|
||
|
||
<div class="container">
|
||
|
||
<p>
|
||
<img style="width: 451px; height: 80px;" src="docs/images/backbone.png" alt="Backbone.js" />
|
||
</p>
|
||
|
||
<p>
|
||
Backbone.js gives structure to web 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 API 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>,
|
||
a <a href="https://github.com/documentcloud/backbone/wiki/Tutorials%2C-blog-posts-and-example-sites">list of tutorials</a>
|
||
and a <a href="#examples">long list of real-world projects</a> that use Backbone.
|
||
Backbone is available for use under the <a href="http://github.com/documentcloud/backbone/blob/master/LICENSE">MIT software license</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>,
|
||
add pages to the <a href="https://github.com/documentcloud/backbone/wiki">wiki</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 class="punch" href="backbone.js">Development Version (0.9.2)</a></td>
|
||
<td><i>52kb, Full source, lots of comments</i></td>
|
||
</tr>
|
||
<tr>
|
||
<td><a class="punch" href="backbone-min.js">Production Version (0.9.2)</a></td>
|
||
<td><i>5.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> <small>( > 1.3.1)</small>.
|
||
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="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 state can be notified of the
|
||
change, so that they are able to respond accordingly, re-rendering themselves with
|
||
the new information. In a finished Backbone app, 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>
|
||
If you're new here, and aren't yet quite sure what Backbone is for, start by
|
||
browsing the <a href="#examples">list of Backbone-based projects</a>.
|
||
</p>
|
||
|
||
<p>
|
||
Many of the examples that follow are runnable. Click the <i>play</i> button
|
||
to execute them.
|
||
</p>
|
||
|
||
<h2 id="upgrading">Upgrading to 0.9</h2>
|
||
|
||
<p>
|
||
Backbone's <b>0.9</b> series should be considered as a release candidate
|
||
for an upcoming <b>1.0</b>. Some APIs have changed, and while there is a
|
||
<a href="#changelog">change log</a> available, and many new features to
|
||
take advantage of, there are a few specific changes where you'll need
|
||
to take care:
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
If you've ever manually set <tt>this.el</tt> in a Backbone View to be a
|
||
particular DOM element, you'll want to use
|
||
<a href="#View-setElement">setElement</a> instead.
|
||
</li>
|
||
<li>
|
||
Creating and destroying models is now optimistic. Pass <tt>{wait: true}</tt>
|
||
if you need the previous behavior of waiting for the server to acknowledge
|
||
success. You can now also pass <tt>{wait: true}</tt> to <a href="#Model-save">save</a> calls.
|
||
</li>
|
||
<li>
|
||
If you have been writing a fair amount of <tt>$(view.el)</tt>, there's now
|
||
a cached reference for that jQuery object: <a href="#View-$el">$el</a>.
|
||
</li>
|
||
<li>
|
||
If you're upgrading, make sure you also upgrade your version of Underscore.js
|
||
to the latest — 1.3.1 or greater.
|
||
</li>
|
||
<li>
|
||
<tt>model.set</tt> will no longer trigger change events when setting a value
|
||
with <tt>{silent: true}</tt> then setting it back to its original value.
|
||
Similarly, after changing an attribute silently, that <tt>change:attribute</tt>
|
||
event <i>will</i> fire during the next change.
|
||
</li>
|
||
<li>
|
||
Since <tt>view.$(selector)</tt> is now equivalent to <tt>view.$el.find(selector)</tt>
|
||
rather than <tt>$(selector, view.el)</tt> it can no longer be used when
|
||
<tt>selector</tt> is an HTML string or DOM element.
|
||
</li>
|
||
</ul>
|
||
|
||
<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.on("alert", function(msg) {
|
||
alert("Triggered " + msg);
|
||
});
|
||
|
||
object.trigger("alert", "an event");
|
||
</pre>
|
||
|
||
<p>
|
||
For example, to make a handy event dispatcher that can coordinate events
|
||
among different areas of your application: <tt>var dispatcher = _.clone(Backbone.Events)</tt>
|
||
</p>
|
||
|
||
<p id="Events-on">
|
||
<b class="header">on</b><code>object.on(event, callback, [context])</code><span class="alias">Alias: bind</span>
|
||
<br />
|
||
Bind a <b>callback</b> function to an object. The callback will be invoked
|
||
whenever the <b>event</b> 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>.
|
||
The event string may also be a space-delimited list of several events...
|
||
</p>
|
||
|
||
<pre>
|
||
book.on("change:title change:author", ...);
|
||
</pre>
|
||
|
||
<p>
|
||
To supply a <b>context</b> value for <tt>this</tt> when the callback is invoked,
|
||
pass the optional third argument: <tt>model.on('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.on("all", function(eventName) {
|
||
object.trigger(eventName);
|
||
});
|
||
</pre>
|
||
|
||
<p id="Events-off">
|
||
<b class="header">off</b><code>object.off([event], [callback], [context])</code><span class="alias">Alias: unbind</span>
|
||
<br />
|
||
Remove a previously-bound <b>callback</b> function from an object. If no
|
||
<b>context</b> is specified, all of the versions of the callback with
|
||
different contexts will be removed. 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>
|
||
// Removes just the `onChange` callback.
|
||
object.off("change", onChange);
|
||
|
||
// Removes all "change" callbacks.
|
||
object.off("change");
|
||
|
||
// Removes the `onChange` callback for all events.
|
||
object.off(null, onChange);
|
||
|
||
// Removes all callbacks for `context` for all events.
|
||
object.off(null, null, context);
|
||
|
||
// Removes all callbacks on `object`.
|
||
object.off();
|
||
</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>, or space-delimited list of events.
|
||
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.on('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>
|
||
In rare cases, if you're looking to get fancy,
|
||
you may want to override <b>constructor</b>, which allows
|
||
you to replace the actual constructor function for your model.
|
||
</p>
|
||
|
||
<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>. You may also pass
|
||
individual keys and values.
|
||
</p>
|
||
|
||
<pre>
|
||
note.set({title: "March 20", content: "In his eyes she eclipses..."});
|
||
|
||
book.set("title", "A Scandal in Bohemia");
|
||
</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>.
|
||
Otherwise, <b>set</b> returns a reference to the model.
|
||
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.
|
||
If <tt>{silent: true}</tt> is passed as an option, the validation is deferred
|
||
until the next change.
|
||
</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-idAttribute">
|
||
<b class="header">idAttribute</b><code>model.idAttribute</code>
|
||
<br />
|
||
A model's unique identifier is stored under the <tt>id</tt> attribute.
|
||
If you're directly communicating with a backend (CouchDB, MongoDB) that uses
|
||
a different unique key, you may set a Model's <tt>idAttribute</tt> to
|
||
transparently map from that key to <tt>id</tt>.
|
||
|
||
<pre class="runnable">
|
||
var Meal = Backbone.Model.extend({
|
||
idAttribute: "_id"
|
||
});
|
||
|
||
var cake = new Meal({ _id: 1, name: "Cake" });
|
||
alert("Cake id: " + cake.id);
|
||
</pre>
|
||
</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-changed">
|
||
<b class="header">changed</b><code>model.changed</code>
|
||
<br />
|
||
The <b>changed</b> property is the internal hash containing all the attributes
|
||
that have changed since the last <tt>"change"</tt> event was triggered.
|
||
Please do not update <b>changed</b> directly. Its state is maintained internally
|
||
by <a href="#Model-set">set</a> and <a href="#Model-change">change</a>.
|
||
A copy of <b>changed</b> can be acquired from
|
||
<a href="#Model-changedAttributes">changedAttributes</a>.
|
||
</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 by delegating to
|
||
<a href="#Sync">Backbone.sync</a>. Returns a
|
||
<a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a>.
|
||
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>. Returns a
|
||
<a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a> if
|
||
validation is successful and <tt>false</tt> otherwise. 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 — but,
|
||
a <i>complete representation</i> of the resource will be sent to the server.
|
||
As with <tt>set</tt>, you may pass individual keys and values instead of a hash.
|
||
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>
|
||
Calling <tt>save</tt> with new attributes will cause a <tt>"change"</tt>
|
||
event immediately, and a <tt>"sync"</tt> event after the server has acknowledged
|
||
the successful change. Pass <tt>{wait: true}</tt> if you'd like to wait
|
||
for the server before setting the new attributes on the model.
|
||
</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>. Returns a
|
||
<a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a> object, or
|
||
<tt>false</tt> if the model <a href="#Model-isNew">isNew</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, and a <tt>"sync"</tt> event, after
|
||
the server has successfully acknowledged the model's deletion. Pass
|
||
<tt>{wait: true}</tt> if you'd like to wait for the server to respond
|
||
before removing the model from the collection.
|
||
</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 model attributes updated with the values
|
||
from <tt>set</tt> or <tt>save</tt>.
|
||
If the attributes are valid, don't return anything from <b>validate</b>;
|
||
if they 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. If <b>validate</b>
|
||
returns an error, <tt>set</tt> and <tt>save</tt> will not continue, and the
|
||
model attributes will not be modified.
|
||
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.on("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-isValid">
|
||
<b class="header">isValid</b><code>model.isValid()</code>
|
||
<br />
|
||
Models may enter an invalid state if you make changes to them silently
|
||
... useful when dealing with form input. Call <tt>model.isValid()</tt>
|
||
to check if the model is currently in a valid state, according to your
|
||
<tt>validate</tt> function.
|
||
</p>
|
||
|
||
<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 or 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><br />
|
||
Note that <tt>urlRoot</tt> may also be defined as a function.
|
||
</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 and a <tt>"change:attribute"</tt>
|
||
event for each attribute that has changed. 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.on("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.on("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 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.on("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 (28)</b>
|
||
<br />
|
||
Backbone proxies to <b>Underscore.js</b> to provide 28 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 class="small">
|
||
<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/#shuffle">shuffle</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/#initial">initial</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>. Likewise, if you're a callback listening to a
|
||
collection's <tt>"add"</tt> event, <tt>options.index</tt> will tell you the
|
||
index at which the model is being added to the collection.
|
||
</p>
|
||
|
||
<pre class="runnable">
|
||
var ships = new Backbone.Collection;
|
||
|
||
ships.on("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. If you're a callback listening to the <tt>"remove"</tt> event,
|
||
the index at which the model is being removed from the collection is available
|
||
as <tt>options.index</tt>.
|
||
</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-push">
|
||
<b class="header">push</b><code>collection.push(model, [options])</code>
|
||
<br />
|
||
Add a model at the end of a collection. Takes the same options as
|
||
<a href="#Collection-add">add</a>.
|
||
</p>
|
||
|
||
<p id="Collection-pop">
|
||
<b class="header">pop</b><code>collection.pop([options])</code>
|
||
<br />
|
||
Remove and return the last model from a collection. Takes the same options as
|
||
<a href="#Collection-remove">remove</a>.
|
||
</p>
|
||
|
||
<p id="Collection-unshift">
|
||
<b class="header">unshift</b><code>collection.unshift(model, [options])</code>
|
||
<br />
|
||
Add a model at the beginning of a collection. Takes the same options as
|
||
<a href="#Collection-add">add</a>.
|
||
</p>
|
||
|
||
<p id="Collection-shift">
|
||
<b class="header">shift</b><code>collection.shift([options])</code>
|
||
<br />
|
||
Remove and return the first model from a collection. Takes the same options as
|
||
<a href="#Collection-remove">remove</a>.
|
||
</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 function can be defined as either a
|
||
<a href="http://underscorejs.org/#sortBy">sortBy</a>
|
||
(pass a function that takes a single argument),
|
||
or as a
|
||
<a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
|
||
(pass a comparator function that expects two arguments).
|
||
</p>
|
||
|
||
<p>
|
||
"sortBy" comparator functions take a model and return a numeric or string
|
||
value by which the model should be ordered relative to others.
|
||
"sort" comparator functions take two models, and return <tt>-1</tt> if
|
||
the first model should come before the second, <tt>0</tt> if they are of
|
||
the same rank and <tt>1</tt> if the first model should come after.
|
||
</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">
|
||
Collections with comparator functions will not automatically re-sort if you
|
||
later change model attributes, so you may wish to call <tt>sort</tt> after
|
||
changing model attributes that would affect the order.
|
||
</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([
|
||
{name: "Curly"},
|
||
{name: "Larry"},
|
||
{name: "Moe"}
|
||
]);
|
||
|
||
var names = stooges.pluck("name");
|
||
|
||
alert(JSON.stringify(names));
|
||
</pre>
|
||
|
||
<p id="Collection-where">
|
||
<b class="header">where</b><code>collection.where(attributes)</code>
|
||
<br />
|
||
Return an array of all the models in a collection that match the
|
||
passed <b>attributes</b>. Useful for simple cases of <tt>filter</tt>.
|
||
</p>
|
||
|
||
<pre class="runnable">
|
||
var friends = new Backbone.Collection([
|
||
{name: "Athos", job: "Musketeer"},
|
||
{name: "Porthos", job: "Musketeer"},
|
||
{name: "Aramis", job: "Musketeer"},
|
||
{name: "d'Artagnan", job: "Guard"},
|
||
]);
|
||
|
||
var musketeers = friends.where({job: "Musketeer"});
|
||
|
||
alert(musketeers.length);
|
||
</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. Note that afterwards,
|
||
if your model class already has a <tt>parse</tt> function, it will be
|
||
run against each fetched model.
|
||
</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 and returns a
|
||
<a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a>.
|
||
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>
|
||
var Accounts = new Backbone.Collection;
|
||
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.
|
||
Delegates to <a href="#Sync">Backbone.sync</a> and returns a
|
||
<a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a> if validation
|
||
is successful, and <tt>false</tt> otherwise.
|
||
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>
|
||
|
||
<p>
|
||
Creating a model will cause an immediate <tt>"add"</tt> event to be
|
||
triggered on the collection, as well as a <tt>"sync"</tt> event, once the
|
||
model has been successfully created on the server. Pass <tt>{wait: true}</tt>
|
||
if you'd like to wait for the server before adding the new model to the collection.
|
||
</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. 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. Note that you'll want to avoid using a
|
||
leading slash in your route definitions:
|
||
</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.on("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. If the
|
||
<tt>callback</tt> argument is omitted <tt>router[name]</tt> will be used
|
||
instead.
|
||
</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" to this.open
|
||
this.route(/^(.*?)\/open$/, "open");
|
||
|
||
},
|
||
|
||
open: function(id) { ... }
|
||
</pre>
|
||
|
||
<p id="Router-navigate">
|
||
<b class="header">navigate</b><code>router.navigate(fragment, [options])</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, set the <b>trigger</b>
|
||
option to <tt>true</tt>.
|
||
To update the URL without creating an entry in the browser's history,
|
||
set the <b>replace</b> option to <tt>true</tt>.
|
||
</p>
|
||
|
||
<pre>
|
||
openPage: function(pageNumber) {
|
||
this.document.pages.at(pageNumber).open();
|
||
this.navigate("page/" + pageNumber);
|
||
}
|
||
|
||
# Or ...
|
||
|
||
app.navigate("help/troubleshooting", {trigger: true});
|
||
|
||
# Or ...
|
||
|
||
app.navigate("help/troubleshooting", {trigger: true, replace: 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 and returns a
|
||
<a href="http://api.jquery.com/jQuery.ajax/#jqXHR">jqXHR</a>. 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 <b>sync</b> function may be overriden globally as <tt>Backbone.sync</tt>,
|
||
or at a finer-grained level, by adding a <tt>sync</tt> function to a Backbone
|
||
collection or to an individual model.
|
||
</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>, setting the <tt>X-HTTP-Method-Override</tt> header
|
||
with the true method. If <tt>emulateJSON</tt> is also on, the true method
|
||
will be passed as an additional <tt>_method</tt> parameter.
|
||
</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>, <tt>tagName</tt> and <tt>attributes</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>, <tt>id</tt> and <tt>attributes</tt> properties,
|
||
if specified. If not, <b>el</b> is an empty <tt>div</tt>.
|
||
</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-$el">
|
||
<b class="header">$el</b><code>view.$el</code>
|
||
<br />
|
||
A cached jQuery (or Zepto) object for the view's element. A handy
|
||
reference instead of re-wrapping the DOM element all the time.
|
||
</p>
|
||
|
||
<pre>
|
||
view.$el.show();
|
||
|
||
listView.$el.append(itemView.el);
|
||
</pre>
|
||
|
||
<p id="View-setElement">
|
||
<b class="header">setElement</b><code>view.setElement(element)</code>
|
||
<br />
|
||
If you'd like to apply a Backbone view to a different DOM element, use
|
||
<b>setElement</b>, which will also create the cached <tt>$el</tt> reference
|
||
and move the view's delegated events from the old element to the new one.
|
||
</p>
|
||
|
||
<p id="View-attributes">
|
||
<b class="header">attributes</b><code>view.attributes</code>
|
||
<br />
|
||
A hash of attributes that will be set as HTML DOM element attributes on the
|
||
view's <tt>el</tt> (id, class, data-properties, etc.), or a function that
|
||
returns such a hash.
|
||
</p>
|
||
|
||
<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>view.$el.find(selector)</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", {"class": "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>.
|
||
The callback may be either the name of a method on the view, or a direct
|
||
function body.
|
||
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>
|
||
|
||
<p id="View-undelegateEvents">
|
||
<b class="header">undelegateEvents</b><code>undelegateEvents()</code>
|
||
<br />
|
||
Removes all of the view's delegated events. Useful if you want to disable
|
||
or remove a view from the DOM temporarily.
|
||
</p>
|
||
|
||
<h2 id="Utility">Utility Functions</h2>
|
||
|
||
<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>
|
||
|
||
<p id="Utility-setDomLibrary">
|
||
<b class="header">setDomLibrary</b><code>Backbone.setDomLibrary(jQueryNew);</code>
|
||
<br />
|
||
If you have multiple copies of <tt>jQuery</tt> on the page, or simply want
|
||
to tell Backbone to use a particular object as its DOM / Ajax library,
|
||
this is the function for you.
|
||
</p>
|
||
|
||
<h2 id="examples">Examples</h2>
|
||
|
||
<p>
|
||
The list of examples that follows, while long, is not exhaustive. If you've
|
||
worked on an app that uses Backbone, please add it to the
|
||
<a href="https://github.com/documentcloud/backbone/wiki/Projects-and-Companies-using-Backbone">wiki page of Backbone apps</a>.
|
||
</p>
|
||
|
||
<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-audiovroom">AudioVroom</h2>
|
||
|
||
<p>
|
||
<a href="http://www.audiovroom.com/">AudioVroom</a> is a free music
|
||
streaming app that allows you to listen to your Facebook friends like
|
||
radio stations. It relies heavily on Backbone (views and song management)
|
||
and also features a responsive grid-based design (using CSS3 media-queries)
|
||
to deliver a unified user experience on desktops, mobiles, and tablets alike.
|
||
Being a pure Backbone app, AudioVroom is only 60kb compressed, and can be
|
||
entirely hosted on the CDN.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://www.audiovroom.com/">
|
||
<img src="docs/images/audiovroom.png" alt="AudioVroom" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-foursquare">Foursquare</h2>
|
||
|
||
<p>
|
||
Foursquare is a fun little startup that helps you meet up with friends,
|
||
discover new places, and save money. Backbone Models are heavily used in
|
||
the core JavaScript API layer and Views power many popular features like
|
||
the <a href="https://foursquare.com">homepage map</a> and
|
||
<a href="https://foursquare.com/seriouseats/list/the-best-doughnuts-in-ny">lists</a>.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://foursquare.com">
|
||
<img src="docs/images/foursquare.png" alt="Foursquare" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-wunderkit">Wunderkit</h2>
|
||
|
||
<p>
|
||
<a href="http://get.wunderkit.com/">Wunderkit</a> is a productivity and
|
||
social collaboration platform. It
|
||
uses Backbone.js as the foundation for the single-page application,
|
||
which is backed by a RESTful Rails API.
|
||
The freedom and agility that Backbone gives to developers
|
||
made it possible to build Wunderkit in a very short time and
|
||
extend it with custom features: a write-through cache using HTML5
|
||
localStorage, and a view hierarchy extension to easily manage trees of
|
||
sub-views. Aside from Backbone, Wunderkit also
|
||
depends on <a href="http://jquery.com/">jQuery</a>, <a href="http://underscorejs.org/">Underscore</a>, <a href="http://requirejs.org/">Require.js</a>, <a href="http://lesscss.org/">LESS</a> and doT.js templates.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://get.wunderkit.com/">
|
||
<img src="docs/images/wunderkit.png" alt="Wunderkit" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-khan-academy">Khan Academy</h2>
|
||
|
||
<p>
|
||
<a href="http://www.khanacademy.org">Khan Academy</a> is on a mission to
|
||
provide a free world-class education to anyone anywhere. With thousands of
|
||
videos, hundreds of JavaScript-driven exercises, and big plans for the
|
||
future, Khan Academy uses Backbone to keep frontend code modular and organized.
|
||
<a href="https://khanacademy.kilnhg.com/Code/Website/Group/stable/Files/javascript/profile-package?rev=tip">User profiles</a>
|
||
and <a href="https://khanacademy.kilnhg.com/Code/Website/Group/stable/File/javascript/shared-package/goals.js?rev=tip">goal setting</a>
|
||
are implemented with Backbone, <a href="http://jquery.com/">jQuery</a> and <a href="http://handlebarsjs.com/">Handlebars</a>, and most new feature
|
||
work is being pushed to the client side, greatly increasing the quality of
|
||
<a href="https://github.com/Khan/khan-api/">the API</a>.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://www.khanacademy.org">
|
||
<img src="docs/images/khan-academy.png" alt="Khan Academy" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-do">Do</h2>
|
||
|
||
<p>
|
||
<a href="http://do.com">Do</a> is a social productivity app that makes it
|
||
easy to work on tasks, track projects, and take notes with your team.
|
||
The <a href="http://do.com">Do.com</a> web application was built from the
|
||
ground up to work seamlessly on your smartphone, tablet and computer. The
|
||
team used Backbone, <a href="http://coffeescript.org/">CoffeeScript</a> and <a href="http://handlebarsjs.com/">Handlebars</a> to build a full-featured
|
||
app in record time and rolled their own extensions for complex navigation
|
||
and model sync support.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://do.com">
|
||
<img src="docs/images/do.png" alt="Do" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-posterous">Posterous</h2>
|
||
|
||
<p>
|
||
<a href="https://posterous.com/">Posterous Spaces</a> is
|
||
<a href="http://technology.posterous.com/posterous-spaces-is-built-on-backbonejs">built on Backbone</a>.
|
||
The models and collections mirror the public
|
||
<a href="http://posterous.com/api">Posterous API</a>. Backbone made it easy
|
||
for the team to create a JavaScript-heavy application with complex
|
||
interactions and state maintenance. Spaces also uses <a href="http://coffeescript.org/">CoffeeScript</a>,
|
||
<a href="http://underscorejs.org/">Underscore.js</a>, <a href="https://github.com/creationix/haml-js">Haml.js</a>, <a href="http://sass-lang.com/">Sass</a>, <a href="http://compass-style.org/">Compass</a>, and of course <a href="http://jquery.com">jQuery</a>.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="https://posterous.com/">
|
||
<img src="docs/images/posterous-spaces.png" alt="Posterous Spaces" 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-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-slavery-footprint">Slavery Footprint</h2>
|
||
|
||
<p>
|
||
<a href="http://slaveryfootprint.org/survey">Slavery Footprint</a>
|
||
allows consumers to visualize how their consumption habits are
|
||
connected to modern-day slavery and provides them with an opportunity
|
||
to have a deeper conversation with the companies that manufacture the
|
||
goods they purchased.
|
||
Based in Oakland, California, the Slavery Footprint team works to engage
|
||
individuals, groups, and businesses to build awareness for and create
|
||
deployable action against forced labor, human trafficking, and modern-day
|
||
slavery through online tools, as well as off-line community education and
|
||
mobilization programs.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://slaveryfootprint.org/survey">
|
||
<img src="docs/images/slavery-footprint.png" alt="Slavery Footprint" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-stripe">Stripe</h2>
|
||
|
||
<p>
|
||
<a href="https://stripe.com">Stripe</a> provides an API for accepting
|
||
credit cards on the web. Stripe's
|
||
<a href="https://manage.stripe.com">management interface</a> was recently
|
||
rewritten from scratch in Coffeescript using Backbone.js as the primary
|
||
framework, <a href="https://github.com/sstephenson/eco">Eco</a> for templates, <a href="http://sass-lang.com/">Sass</a> for stylesheets, and <a href="https://github.com/sstephenson/stitch">Stitch</a> to package
|
||
everything together as <a href="http://commonjs.org/">CommonJS</a> modulas. The new app uses
|
||
<a href="https://stripe.com/docs/api">Stripe's API</a> directly for the
|
||
majority of its actions; Backbone.js models made it simple to map
|
||
client-side models to their corresponding RESTful resources.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="https://stripe.com">
|
||
<img src="docs/images/stripe.png" alt="Stripe" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-airbnb">Airbnb Mobile</h2>
|
||
|
||
<p>
|
||
<a href="http://airbnb.com">Airbnb</a> used Backbone.js and
|
||
<a href="http://coffeescript.org">CoffeeScript</a> to quickly build
|
||
<a href="http://m.airbnb.com">Airbnb Mobile</a>
|
||
in six weeks with a team of three. The mobile version of Airbnb lets you
|
||
discover and book rental spaces directly from your phone: from a private
|
||
apartment to a private island...
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://m.airbnb.com/">
|
||
<img src="docs/images/airbnb-mobile.png" alt="Airbnb-Mobile" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-diaspora">Diaspora</h2>
|
||
|
||
<p>
|
||
<a href="http://www.joindiaspora.com/">Diaspora</a> is a distributed social
|
||
network, formed from a number of independently operated <i>pods</i>.
|
||
You own your personal data, and control with whom you share.
|
||
All of Diaspora is <a href="https://github.com/diaspora/diaspora">open-source</a>
|
||
code, built with <a href="http://rubyonrails.org/">Rails</a> and Backbone.js.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://www.joindiaspora.com/">
|
||
<img src="docs/images/diaspora.png" alt="Diaspora" 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://www.phantomjs.org/">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/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-code-school">Code School</h2>
|
||
|
||
<p>
|
||
<a href="http://www.codeschool.com">Code School</a> courses teach people
|
||
about various programming topics like <a href="http://coffeescript.org">CoffeeScript</a>, CSS, Ruby on Rails,
|
||
and more. The new Code School course
|
||
<a href="http://coffeescript.codeschool.com/levels/1/challenges/1">challenge page</a>
|
||
is built from the ground up on Backbone.js, using
|
||
everything it has to offer: the router, collections, models, and complex
|
||
event handling. Before, the page was a mess of <a href="http://jquery.com/">jQuery</a> DOM manipulation
|
||
and manual Ajax calls. Backbone.js helped introduce a new way to
|
||
think about developing an organized front-end application in Javascript.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://www.codeschool.com">
|
||
<img src="docs/images/code-school.png" alt="Code School" 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 <a href="http://prototypejs.org/">Prototype.js</a>. Moving to Backbone.js and <a href="http://jquery.com/">jQuery</a> 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-grove">Grove.io</h2>
|
||
|
||
<p>
|
||
<a href="http://grove.io">Grove.io</a> provides hosted IRC for teams.
|
||
Backbone.js powers Grove's web client together with <a href="http://handlebarsjs.com/">Handlebars.js templating</a>.
|
||
Updates to chat stream are pulled in realtime using long-polling.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://grove.io">
|
||
<img src="docs/images/grove.png" alt="Grove.io" 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 <a href="http://rubyonrails.org/">Rails</a> 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-battlefield">Battlefield Play4Free</h2>
|
||
|
||
<p>
|
||
<a href="http://battlefield.play4free.com/">Battlefield Play4Free</a> is
|
||
the latest free-to-play first person shooter from the same team that
|
||
created Battlefield Heroes. The in-game HTML5 front-end for makes heavy use of
|
||
Backbone's views, models and collections to help keep the code modular
|
||
and structured.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://battlefield.play4free.com/">
|
||
<img src="docs/images/battlefield.png" alt="Battlefield Play4Free" 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 <a href="http://rubyonrails.org/">Rails</a>, 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-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-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-animoto">Animoto</h2>
|
||
|
||
<p>
|
||
<a href="http://animoto.com">Animoto</a> is a web-based video creation
|
||
platform, where users can upload their own photos, video clips and music
|
||
and create beautifully orchestrated slideshows. The video editor app is
|
||
built with Backbone.js and <a href="http://jquery.com">jQuery</a> and interfaces with a <a href="http://rubyonrails.org/">Ruby on Rails</a>
|
||
backend. Backbone has provided structure which helps the Animoto team
|
||
iterate quickly on the codebase while reducing the risk of regressions.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://www.animoto.com/">
|
||
<img src="docs/images/animoto.png" alt="Tzigla" class="Animoto Video Editor" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-chaincal">ChainCal</h2>
|
||
|
||
<p>
|
||
<a href="http://chaincalapp.com/">ChainCal</a>
|
||
is an iPhone app that helps you to track your daily goals in a
|
||
minimalist, visual way. The app is written almost entirely in <a href="http://coffeescript.org/">CoffeeScript</a>,
|
||
Backbone handles the models, collections and views, and persistence is
|
||
done with a Backbone.sync localStorage adapter. Templates are written in
|
||
<a href="https://github.com/sstephenson/eco">Eco</a> and the app is packaged with <a href="http://brunch.io/">Brunch</a> and deployed with <a href="http://phonegap.com/">Phonegap</a>.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://chaincalapp.com/">
|
||
<img src="docs/images/chaincal.png" alt="ChainCal" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-attictv">AtticTV</h2>
|
||
|
||
<p>
|
||
<a href="http://attictv.com/">AtticTV</a> is MTV for the Youtube Generation:
|
||
kick back and relax while watching the best
|
||
music videos of your favorite genre. The videos are synced across the
|
||
world, so, you're never watching alone on AtticTV. AtticTV is served by
|
||
<a href="http://nodejs.org/">NodeJS</a> written in <a href="http://coffeescript.org/">CoffeeScript</a> with <a href="http://socket.io/">Socket.IO</a> as data transport. The
|
||
frontend is built with Backbone.js with pushstate support, <a href="http://jquery.com/">jQuery</a>, and
|
||
<a href="http://jade-lang.com/">Jade templates</a>.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://attictv.com/">
|
||
<img src="docs/images/attictv.png" alt="AtticTV" 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 <a href="http://mustache.github.com">Mustache</a>. 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-ducksboard">Ducksboard</h2>
|
||
|
||
<p>
|
||
<a href="http://ducksboard.com/">Ducksboard</a> is an online dashboard
|
||
for your SaaS and business metrics, built with
|
||
<a href="http://twistedmatrix.com/">Twisted</a> and
|
||
<a href="http://www.djangoproject.com/">Django</a> and using WebSockets.
|
||
It can fetch data from popular providers or accept input through
|
||
a simple API.
|
||
Backbone is used throughout Ducksboard's interface, every widget,
|
||
dashboard and SaaS account is a Backbone model with several views
|
||
(data display, configuration view). A
|
||
<a href="https://public.ducksboard.com/BFVzKVPeOoWRsL0VZ8MZ/">live demo</a>
|
||
is available.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="http://ducksboard.com/">
|
||
<img src="docs/images/ducksboard.png" alt="Ducksboard" class="example_image" />
|
||
</a>
|
||
</div>
|
||
|
||
<h2 id="examples-picklive">Picklive</h2>
|
||
|
||
<p>
|
||
<a href="http://twitter.com/timruffles">Tim Ruffles</a> and <a href="http://twitter.com/timparker">Tim Parker</a>
|
||
created the game client for <a href="https://free.picklive.com">Picklive</a>, a real-time fantasy-soccer game.
|
||
The client is written in <a href="http://coffeescript.org">CoffeeScript</a>, organised into
|
||
modules via <a href="http://requirejs.org">require.js</a>, tested with
|
||
<a href="http://code.google.com/p/js-test-driver">jsTestDriver</a> and uses
|
||
<a href="http://mustache.github.com">Mustache.js</a> for templating. Backbone's model and sync layer separation
|
||
manages the complexity of mixed polling and web-sockets based synchronisation.
|
||
</p>
|
||
|
||
<div style="text-align: center;">
|
||
<a href="https://free.picklive.com/">
|
||
<img src="docs/images/picklive.png" alt="picklive" 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 + <a href="http://rubyonrails.org/">Rails</a> 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 (<a href="http://rubyonrails.org/">Rails</a>) 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="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 class="small">
|
||
<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, options) — when a model's attributes have changed. </li>
|
||
<li><b>"change:[attribute]"</b> (model, value, options) — 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>"sync"</b> (model, collection) — triggers whenever a model has been successfully synced to the server. </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.on("selected:true")</tt> or
|
||
<tt>model.on("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.on("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>
|
||
Backbone doesn't include direct support for nested models and collections
|
||
or "has many" associations because there are a number
|
||
of good patterns for modeling structured data on the client side, and
|
||
<i>Backbone should provide the foundation for implementing any of them.</i>
|
||
You may want to…
|
||
</p>
|
||
|
||
<ul>
|
||
<li>
|
||
Mirror an SQL database's structure, or the structure of a NoSQL database.
|
||
</li>
|
||
<li>
|
||
Use models with arrays of "foreign key" ids, and join to top level
|
||
collections (a-la tables).
|
||
</li>
|
||
<li>
|
||
For associations that are numerous, use a range of ids instead of an
|
||
explicit list.
|
||
</li>
|
||
<li>
|
||
Avoid ids, and use direct references, creating a partial object graph
|
||
representing your data set.
|
||
</li>
|
||
<li>
|
||
Lazily load joined models from the server, or lazily deserialize nested
|
||
models from JSON documents.
|
||
</li>
|
||
</ul>
|
||
|
||
<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>
|
||
var Accounts = new Backbone.Collection;
|
||
Accounts.reset(<%= @accounts.to_json %>);
|
||
var Projects = new Backbone.Collection;
|
||
Projects.reset(<%= @projects.to_json(:collaborators => true) %>);
|
||
</script>
|
||
</pre>
|
||
|
||
<p>You have to <a href="http://mathiasbynens.be/notes/etago">escape</a>
|
||
<tt></</tt> within the JSON string, to prevent javascript injection
|
||
attacks.
|
||
|
||
<p id="FAQ-extending">
|
||
<b class="header">Extending Backbone</b>
|
||
<br />
|
||
Many JavaScript libraries are meant to be insular and self-enclosed,
|
||
where you interact with them by calling their public API, but never peek
|
||
inside at the guts. Backbone.js is <i>not</i> that kind of library.
|
||
</p>
|
||
|
||
<p>
|
||
Because it serves as a foundation for your application, you're meant to
|
||
extend and enhance it in the ways you see fit — the entire source
|
||
code is <a href="docs/backbone.html">annotated</a> to make this easier
|
||
for you. You'll find that there's very little there apart from core
|
||
functions, and most of those can be overriden or augmented should you find
|
||
the need. If you catch yourself adding methods to <tt>Backbone.Model.prototype</tt>,
|
||
or creating your own base subclass, don't worry — that's how things are
|
||
supposed to work.
|
||
</p>
|
||
|
||
<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.on("reset", this.render, this);
|
||
messages.on("add", this.addMessage, this);
|
||
messages.on("remove", this.removeMessage, this);
|
||
}
|
||
|
||
});
|
||
|
||
// Later, in the app...
|
||
|
||
Inbox.messages.add(newMessage);
|
||
</pre>
|
||
|
||
<p id="FAQ-rails">
|
||
<b class="header">Working with Rails</b>
|
||
<br />
|
||
Backbone.js was originally extracted from
|
||
<a href="http://www.documentcloud.org">a Rails application</a>; getting
|
||
your client-side (Backbone) Models to sync correctly with your server-side
|
||
(Rails) Models is painless, but there are still a few things to be aware of.
|
||
</p>
|
||
|
||
<p>
|
||
By default, Rails adds an extra layer of wrapping around the JSON representation
|
||
of models. You can disable this wrapping by setting:
|
||
</p>
|
||
|
||
<pre>
|
||
ActiveRecord::Base.include_root_in_json = false
|
||
</pre>
|
||
|
||
<p>
|
||
... in your configuration. Otherwise, override
|
||
<a href="#Model-parse">parse</a> to pull model attributes out of the
|
||
wrapper. Similarly, Backbone PUTs and POSTs direct JSON representations
|
||
of models, where by default Rails expects namespaced attributes. You can
|
||
have your controllers filter attributes directly from <tt>params</tt>, or
|
||
you can override <a href="#Model-toJSON">toJSON</a> in Backbone to add
|
||
the extra wrapping Rails expects.
|
||
</p>
|
||
|
||
<h2 id="changelog">Change Log</h2>
|
||
|
||
<b class="header">0.9.2</b> — <small><i>March 21, 2012</i></small> — <a href="https://github.com/documentcloud/backbone/compare/0.9.1...0.9.2">Diff</a><br />
|
||
<ul style="margin-top: 5px;">
|
||
<li>
|
||
Instead of throwing an error when adding duplicate models to a collection,
|
||
Backbone will now silently skip them instead.
|
||
</li>
|
||
<li>
|
||
Added <a href="#Collection-push">push</a>,
|
||
<a href="#Collection-pop">pop</a>,
|
||
<a href="#Collection-unshift">unshift</a>, and
|
||
<a href="#Collection-shift">shift</a> to collections.
|
||
</li>
|
||
<li>
|
||
A model's <a href="#Model-changed">changed</a> hash is now exposed for
|
||
easy reading of the changed attribute delta, since the model's last
|
||
<tt>"change"</tt> event.
|
||
</li>
|
||
<li>
|
||
Added <a href="#Collection-where">where</a> to collections for simple
|
||
filtering.
|
||
</li>
|
||
<li>
|
||
You can now use a single <a href="#Events-off">off</a> call
|
||
to remove all callbacks bound to a specific object.
|
||
</li>
|
||
<li>
|
||
Bug fixes for nested individual change events, some of which may be
|
||
"silent".
|
||
</li>
|
||
<li>
|
||
Bug fixes for URL encoding in <tt>location.hash</tt> fragments.
|
||
</li>
|
||
<li>
|
||
Bug fix for client-side validation in advance of a <tt>save</tt> call
|
||
with <tt>{wait: true}</tt>.
|
||
</li>
|
||
<li>
|
||
Updated / refreshed the example
|
||
<a href="examples/todos/index.html">Todo List</a> app.
|
||
</li>
|
||
</ul>
|
||
|
||
<b class="header">0.9.1</b> — <small><i>Feb. 2, 2012</i></small> — <a href="https://github.com/documentcloud/backbone/compare/0.9.0...0.9.1">Diff</a><br />
|
||
<ul style="margin-top: 5px;">
|
||
<li>
|
||
Reverted to 0.5.3-esque behavior for validating models. Silent changes
|
||
no longer trigger validation (making it easier to work with forms).
|
||
Added an <tt>isValid</tt> function that you can use to check if a model
|
||
is currently in a valid state.
|
||
</li>
|
||
<li>
|
||
If you have multiple versions of jQuery on the page, you can now tell
|
||
Backbone which one to use with <tt>Backbone.setDomLibrary</tt>.
|
||
</li>
|
||
<li>
|
||
Fixes regressions in <b>0.9.0</b> for routing with "root", saving with
|
||
both "wait" and "validate", and the order of nested "change" events.
|
||
</li>
|
||
</ul>
|
||
|
||
<b class="header">0.9.0</b> — <small><i>Jan. 30, 2012</i></small> — <a href="https://github.com/documentcloud/backbone/compare/0.5.3...0.9.0">Diff</a><br />
|
||
<ul style="margin-top: 5px;">
|
||
<li>
|
||
Creating and destroying models with <tt>create</tt> and <tt>destroy</tt>
|
||
are now optimistic by default. Pass <tt>{wait: true}</tt> as an option
|
||
if you'd like them to wait for a successful server response to proceed.
|
||
</li>
|
||
<li>
|
||
Two new properties on views: <tt>$el</tt> — a cached jQuery (or Zepto)
|
||
reference to the view's element, and <tt>setElement</tt>, which should
|
||
be used instead of manually setting a view's <tt>el</tt>. It will
|
||
both set <tt>view.el</tt> and <tt>view.$el</tt> correctly, as well as
|
||
re-delegating events on the new DOM element.
|
||
</li>
|
||
<li>
|
||
You can now bind and trigger multiple spaced-delimited events at once.
|
||
For example: <tt>model.on("change:name change:age", ...)</tt>
|
||
</li>
|
||
<li>
|
||
When you don't know the key in advance, you may now call
|
||
<tt>model.set(key, value)</tt> as well as <tt>save</tt>.
|
||
</li>
|
||
<li>
|
||
Multiple models with the same <tt>id</tt> are no longer allowed in a
|
||
single collection.
|
||
</li>
|
||
<li>
|
||
Added a <tt>"sync"</tt> event, which triggers whenever a model's state
|
||
has been successfully synced with the server (create, save, destroy).
|
||
</li>
|
||
<li>
|
||
<tt>bind</tt> and <tt>unbind</tt> have been renamed to <tt>on</tt>
|
||
and <tt>off</tt> for clarity, following jQuery's lead.
|
||
The old names are also still supported.
|
||
</li>
|
||
<li>
|
||
A Backbone collection's <tt>comparator</tt> function may now behave
|
||
either like a <a href="http://underscorejs.org/#sortBy">sortBy</a>
|
||
(pass a function that takes a single argument),
|
||
or like a <a href="https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/sort">sort</a>
|
||
(pass a comparator function that expects two arguments). The comparator
|
||
function is also now bound by default to the collection — so you
|
||
can refer to <tt>this</tt> within it.
|
||
</li>
|
||
<li>
|
||
A view's <tt>events</tt> hash may now also contain direct function
|
||
values as well as the string names of existing view methods.
|
||
</li>
|
||
<li>
|
||
Validation has gotten an overhaul — a model's <tt>validate</tt> function
|
||
will now be run even for silent changes, and you can no longer create
|
||
a model in an initially invalid state.
|
||
</li>
|
||
<li>
|
||
Added <tt>shuffle</tt> and <tt>initial</tt> to collections, proxied
|
||
from Underscore.
|
||
</li>
|
||
<li>
|
||
<tt>Model#urlRoot</tt> may now be defined as a function as well as a
|
||
value.
|
||
</li>
|
||
<li>
|
||
<tt>View#attributes</tt> may now be defined as a function as well as a
|
||
value.
|
||
</li>
|
||
<li>
|
||
Calling <tt>fetch</tt> on a collection will now cause all fetched JSON
|
||
to be run through the collection's model's <tt>parse</tt> function, if
|
||
one is defined.
|
||
</li>
|
||
<li>
|
||
You may now tell a router to <tt>navigate(fragment, {replace: true})</tt>,
|
||
which will either use <tt>history.replaceState</tt> or
|
||
<tt>location.hash.replace</tt>, in order to change the URL without adding
|
||
a history entry.
|
||
</li>
|
||
<li>
|
||
Within a collection's <tt>add</tt> and <tt>remove</tt> events, the index
|
||
of the model being added or removed is now available as <tt>options.index</tt>.
|
||
</li>
|
||
<li>
|
||
Added an <tt>undelegateEvents</tt> to views, allowing you to manually
|
||
remove all configured event delegations.
|
||
</li>
|
||
<li>
|
||
Although you shouldn't be writing your routes with them in any case —
|
||
leading slashes (<tt>/</tt>) are now stripped from routes.
|
||
</li>
|
||
<li>
|
||
Calling <tt>clone</tt> on a model now only passes the attributes
|
||
for duplication, not a reference to the model itself.
|
||
</li>
|
||
</ul>
|
||
|
||
<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.3.1.js"></script>
|
||
<script src="test/vendor/jquery-1.7.1.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>
|