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