From 831090329f21ed2e7e33fda92b232cd244314b6f Mon Sep 17 00:00:00 2001 From: Jeremy Ashkenas Date: Thu, 14 Oct 2010 10:29:18 -0400 Subject: [PATCH] Issue #8 -- a number of improvements to the documentation. --- backbone.js | 35 ++++++++++++--------- index.html | 77 +++++++++++++++++++++++++++++++++------------- test/collection.js | 33 +++++++++++--------- 3 files changed, 94 insertions(+), 51 deletions(-) diff --git a/backbone.js b/backbone.js index bc08d58b8..832dc8f46 100644 --- a/backbone.js +++ b/backbone.js @@ -322,17 +322,27 @@ // Add a model, or list of models to the set. Pass **silent** to avoid // firing the `added` event for every new model. add : function(models, options) { - if (!_.isArray(models)) return this._add(models, options); - for (var i=0; i– sort
  • – pluck
  • – url
    • -
  • – refresh
  • – fetch
    • +
  • – refresh
  • – create
    • @@ -975,16 +975,6 @@

    Backbone.Collection

    }); -

    - refreshcollection.refresh(models, [options]) -
    - 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 refresh to replace a collection with a new list - of models (or attribute hashes), triggering a single "refresh" event - at the end. Pass {silent: true} to suppress the "refresh" event. -

    -

    fetchcollection.fetch([options])
    @@ -992,6 +982,8 @@

    Backbone.Collection

    refreshing the collection when they arrive. The options hash takes success and error callbacks which will be passed (collection, response) as arguments. + When the model data returns from the server, the collection will +     refresh. Delegates to Backbone.sync under the covers, for custom persistence strategies.

    @@ -1007,10 +999,10 @@

    Backbone.Collection

    alert(method + ": " + model.url); }; -var accounts = new Backbone.Collection; -accounts.url = '/accounts'; +var Accounts = new Backbone.Collection; +Accounts.url = '/accounts'; -accounts.fetch(); +Accounts.fetch();

    @@ -1020,6 +1012,27 @@

    Backbone.Collection

    for interfaces that are not needed immediately: for example, documents with collections of notes that may be toggled open and closed.

    + +

    + refreshcollection.refresh(models, [options]) +
    + 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 refresh to replace a collection with a new list + of models (or attribute hashes), triggering a single "refresh" event + at the end. Pass {silent: true} to suppress the "refresh" event. +

    + +

    + Here's an example using refresh to bootstrap a collection during initial page load, + in a Rails application. +

    + +
    +<script>
+  Accounts.refresh(<%= @accounts.to_json %>);
+</script>
+

    createcollection.create(attributes, [options]) @@ -1150,7 +1163,9 @@

    Backbone.View

    model, collection, el, id, className, and tagName. If the view defines an initialize function, it will be called when - the view is first created. + the view is first created. If you'd like to create a view that references + an element already in the DOM, pass in the element as an option: + new View({el: existingElement}) 

    @@ -1204,11 +1219,7 @@ 
    Backbone.View
    
       
    
       The default implementation of render is a no-op. Override this
       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
+      and updates this.el with the new HTML. A good
       convention is to return this at the end of render to
       enable chained calls.
     
    
@@ -1216,12 +1227,34 @@ 
    Backbone.View
    
 
     var Bookmark = Backbone.View.extend({
   render: function() {
-    $(this.el).html(this.template.render(this.model.toJSON()));
+    $(this.el).html(this.template(this.model.toJSON()));
     return this;
   }
 });
 
    
 
+    
    
+      Backbone is agnostic with respect to your preferred method of HTML templating.
+      Your render function could even munge together an HTML string, or use
+      document.createElement to generate a DOM tree. However, we suggest
+      choosing a nice JavaScript templating library. 
+      Mustache.js, 
+      Haml-js, and
+      Eco are all fine alternatives. 
+      Because Underscore.js is already on the page,
+      _.template
+      is available, and is an excellent choice if you've already XSS-sanitized
+      your interpolated data.
+    
    
+    
+    
    
+      Whatever templating strategy you end up with, it's nice if you never 
+      have to put strings of HTML in your JavaScript. At DocumentCloud, we
+      use Jammit in order
+      to package up JavaScript templates stored in /app/views as part
+      of our main core.js asset package.
+    
    
+
     
    
       makeview.make(tagName, [attributes], [content])
       
    
@@ -1279,7 +1312,7 @@ 
    Backbone.View
    
   },
 
   render: function() {
-    $(this.el).html(this.template.render(this.model.toJSON()));
+    $(this.el).html(this.template(this.model.toJSON()));
     this.handleEvents();
     return this;
   },
diff --git a/test/collection.js b/test/collection.js
index 1499b0950..fb9cec857 100644
--- a/test/collection.js
+++ b/test/collection.js
@@ -58,20 +58,6 @@ $(document).ready(function() {
     equals(col.first(), d);
   });
 
-  test("collections: refresh", function() {
-    var refreshed = 0;
-    var models = col.models;
-    col.bind('refresh', function() { refreshed += 1; });
-    col.refresh([]);
-    equals(refreshed, 1);
-    equals(col.length, 0);
-    equals(col.last(), null);
-    col.refresh(models);
-    equals(refreshed, 2);
-    equals(col.length, 4);
-    equals(col.last(), a);
-  });
-
   test("collections: fetch", function() {
     col.fetch();
     equals(lastRequest[0], 'read');
@@ -111,4 +97,23 @@ $(document).ready(function() {
     equals(col.min(function(model){ return model.id; }).id, 1);
   });
 
+  test("collections: refresh", function() {
+    var refreshed = 0;
+    var models = col.models;
+    col.bind('refresh', function() { refreshed += 1; });
+    col.refresh([]);
+    equals(refreshed, 1);
+    equals(col.length, 0);
+    equals(col.last(), null);
+    col.refresh(models);
+    equals(refreshed, 2);
+    equals(col.length, 4);
+    equals(col.last(), a);
+    col.refresh(_.map(models, function(m){ return m.attributes; }));
+    equals(refreshed, 3);
+    equals(col.length, 4);
+    ok(col.last() !== a);
+    ok(_.isEqual(col.last().attributes, a.attributes));
+  });
+
 });