From 4b2b8cf29498433499f8c8ef4eeffa9c62bf3ec8 Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Wed, 13 Oct 2010 09:22:27 -0400 Subject: [PATCH] final pass through the documentation --- index.html | 102 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 88 insertions(+), 14 deletions(-) diff --git a/index.html b/index.html index 24a5fcf97..5c6d52077 100644 --- a/index.html +++ b/index.html @@ -789,7 +789,7 @@

Backbone.Collection

 var Ship  = Backbone.Model;
-var ships = new Backbone.Collection();
+var ships = new Backbone.Collection;
 
 ships.bind("add", function(ship) {
   alert("Ahoy " + ship.get("name") + "!");
@@ -854,7 +854,7 @@ 
Backbone.Collection

     
 
 var Chapter  = Backbone.Model;
-var chapters = new Backbone.Collection();
+var chapters = new Backbone.Collection;
 
 chapters.comparator = function(chapter) {
   return chapter.get("page");
@@ -933,16 +933,28 @@ 
Backbone.Collection

       

       Fetch the default set of models for this collection from the server,
       refreshing the collection when they arrive. The options hash takes
-      success(collection, response) and error(collection, response)
-      callbacks. Delegates to Backbone.sync
+      success and error
+      callbacks which will be passed (collection, response) as arguments. 
+      Delegates to Backbone.sync
       under the covers, for custom persistence strategies.
     

 
     

       The server handler for fetch requests should return a JSON list of
-      models, namespaced under "models": {"models": [...]} — and
-      additional information can be returned under different keys.
+      models, namespaced under "models": {"models": [...]} —
+      additional information can be returned with the response under different keys.
     

+    
+
+Backbone.sync = function(method, model) {
+  alert(method + ": " + model.url);
+};
+
+var accounts = new Backbone.Collection;
+accounts.url = '/accounts';
+
+accounts.fetch();
+

 
     

       Note that fetch should not be used to populate collections on
@@ -964,6 +976,19 @@ 
Backbone.Collection

       must have a model property, referencing the type of model that
       the collection contains.
     

+    
+
+var Library = Backbone.Collection.extend({
+  model: Book
+});
+
+var NYPL = new Library;
+
+var othello = NYPL.create({
+  title: "Othello",
+  author: "William Shakespeare"
+});
+

 
     

       toStringcollection.toString()
@@ -992,15 +1017,42 @@ 
Backbone.sync

       
  • success({model: ...}) – a callback that should be fired if the request works
    • 
       
  • error({model: ...}) – a callback that should be fired if the request fails
    • 
     
+    
+    
    
+      When formulating server responses for Backbone.sync requests, 
+      model attributes will be sent up, serialized as JSON, under the model
+      parameter. When returning a JSON response, send down the model's representation
+      under the model key, and other keys can be used for additional out-of-band
+      information. When responding to a "read" request from a collection,
+      send down the array of model attribute hashes under the models key.
+    
    
+    
+    
    
+      For example, a Rails handler responding to an "update" call from
+      Backbone.sync would look like this: (In real code, never use
+      update_attributes blindly, and always whitelist the attributes
+      you allow to be changed.)
+    
    
+    
+
    +def update
+  account = Account.find(params[:id])
+  account.update_attributes JSON.parse params[:model]
+  render :json => {:model => account}
+end
+
    
 
     
    Backbone.View
    
 
     
    
-      Backbone views are almost more convention than they are code.
-      The general idea is to organize your interface into logical sections,
+      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. Instead of digging into a JSON object and looking up an
-      element in the DOM, and updating the HTML by hand, it should look more like:
+      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, 
+      it should look more like:
       model.bind('change', view.render) — and now everywhere that
       model data is displayed in the UI, it is always immediately up to date.
     
    
@@ -1044,13 +1096,15 @@ 
    Backbone.View
    
       function with your code that renders the view template from model data,
       and updates this.el with the new HTML. You can use any flavor of
       JavaScript templating or DOM-building you prefer. Because Underscore.js
-      is already on the page, _.template is already available. A good
+      is already on the page, 
+      _.template 
+      is already available. A good
       convention is to return this at the end of render to
       enable chained calls.
     
    
 
 
    -ui.Chapter = Backbone.View.extend({
+var Bookmark = Backbone.View.extend({
   render: function() {
     $(this.el).html(this.template.render(this.model.toJSON()));
     return this;
@@ -1065,6 +1119,16 @@ 
    Backbone.View
    
       with optional attributes and HTML content. Used internally to create the
       initial view.el.
     
    
+        
+
    +var view = new Backbone.View;
+
+var el = view.make("b", {className: "bold"}, "Bold! ");
+
+$("#make-demo").append(el);
+
    
+
+
    
 
     
    
       handleEventshandleEvents([events])
@@ -1077,7 +1141,7 @@ 
    Backbone.View
    
 
     
    
       Using handleEvents provides a number of advantages over manually
-      binding events to child elements within render. All attached
+      using jQuery to bind events to child elements during render. All attached
       callbacks are bound to the view before being handed off to jQuery, so when
       the callbacks are invoked, this continues to refer to the view object. When
       handleEvents is run again, perhaps with a different events
@@ -1106,7 +1170,17 @@ 
    Backbone.View
    
     $(this.el).html(this.template.render(this.model.toJSON()));
     this.handleEvents();
     return this;
-  }
+  },
+  
+  open: function() {
+    window.open(this.model.get("viewer_url"));
+  },
+  
+  select: function() {
+    this.model.set({selected: true});
+  },
+  
+  ...
 
 });