vendor/assets/javascripts/railsy_backbone.sync.js in railsy_backbone-0.0.1 vs vendor/assets/javascripts/railsy_backbone.sync.js in railsy_backbone-0.0.2

@@ -1,12 +1,15 @@
+// __NOTE:__ only overriding Backbone when `railsy_backbone (start) ... (end)` 
+// is explicitly called out.
+// 
+// Overriding Backbone.sync to implement,  
+// - Nested model attributes  
+// - Rails CSFR Integration  
+// 
 ( function($){
   
-  // Backbone.sync
-  // -------------
-
-  // Need to define the methodMap since it's called from within Backbone.sync
-  //
+  // Define `methodMap` since it's called from within Backbone.sync
   var methodMap = {
       'create': 'POST',
       'update': 'PUT',
       'patch':  'PATCH',
       'delete': 'DELETE',
@@ -15,37 +18,10 @@
 
   var urlError = function() {
     throw new Error("A 'url' property or function must be specified");
   };
 
-  // Overriding Backbone.sync to nest model attributes in within the paramRoot
-  // key-value JSON hashmap.
-  // 
-  // For example, when saving a new Model, 
-  //
-  //   var Book = Backbone.Model.extend({ 
-  //     url: '/books',
-  //     paramRoot: 'book'
-  //   });
-  // 
-  //   var book_instance = new Book({ 
-  //     title:  'the illiad', 
-  //     author: 'homer'
-  //   });
-  //
-  //   book_instance.sync();
-  //
-  // This will cause the HTTP POST to look like this, 
-  //
-  // Started POST "/books" for 127.0.0.1 at 2013-08-03 18:08:56 -0600
-  //   Processing by BooksController#create as JSON
-  //   Parameters: { "book" => { "title" => "the illiad", "author" => "homer" }}
-  // 
-  //
-  // Everything that is not explicitly called out as **railys_backbone** code, is
-  // unmodified Backbone code.
-  // 
   Backbone.sync = function(method, model, options) {
     var type = methodMap[method];
 
     // Default options, unless specified.
     _.defaults(options || (options = {}), {
@@ -59,13 +35,14 @@
     // Ensure that we have a URL.
     if (!options.url) {
       params.url = _.result(model, 'url') || urlError();
     }
     
-    // =========================================================================
-    // railsy_backbone
     // -------------------------------------------------------------------------
+    // railsy_backbone (start)  
+    // __Rails CSFR Integration__  
+    // 
     // include the Rails CSRF token on HTTP PUTs/POSTs    
     // 
     if(!options.noCSRF){
       var beforeSend = options.beforeSend;
       
@@ -74,38 +51,57 @@
         var token = $('meta[name="csrf-token"]').attr('content');
         if (token) xhr.setRequestHeader('X-CSRF-Token', token);
         if (beforeSend) return beforeSend.apply(this, arguments);
       };
     }
-    // =========================================================================
+    // railsy_backbone (end)
+    // 
+    // -------------------------------------------------------------------------
 
     // Ensure that we have the appropriate request data.
     if (options.data == null && model && (method === 'create' || method === 'update' || method === 'patch')) {
       params.contentType = 'application/json';
       
-      // =======================================================================
-      // railsy_backbone
       // -----------------------------------------------------------------------
-      // If model defines **paramRoot**, store model attributes within it. IE
+      // railsy_backbone (start)  
+      // __Nested Model Attributes__  
       // 
-      //   HTTP POST Parameters: { "book" => { "title" => "the illiad", "author" => "home" }}
+      // If Backbone.Model defines `paramRoot`, then store model attributes 
+      // within `paramRoot` key-value pair. For example, book attributes 
+      // (`title`, `author`) are nested within `book` key-value pair,
       // 
-      
+      //      var Book = Backbone.Model.extend({ 
+      //        url: '/books',
+      //        paramRoot: 'book' 
+      //      });
+      // 
+      //      var book_instance = new Book({ 
+      //        title:  'the illiad', 
+      //        author: 'homer'
+      //      });
+      // 
+      // The resulting HTTP POST looks like this,
+      // 
+      //      book_instance.sync();
+      // 
+      //      Started POST "/books" for 127.0.0.1
+      //        Processing by BooksController#create as JSON
+      //        { "book" => { "title" => "the illiad", "author" => "home" } }
+      // 
       if(model.paramRoot) {
         var model_attributes = {}
         model_attributes[model.paramRoot] = model.toJSON(options);
         params.data = JSON.stringify(options.attrs || model_attributes );
       } else {
+        // If model does not define a `paramRoot`, use the original Backbone 
+        // implementation
         params.data = JSON.stringify(options.attrs || model.toJSON(options) );
       }
-      
-      // -------------------------------------------------------------------------
-      // original Backbone code
-      //
-      // params.data = JSON.stringify(options.attrs || model.toJSON(options) );
-      //
-      // =========================================================================
+      // railsy_backbone (end)  
+      // 
+      // -----------------------------------------------------------------------
     }
+    
 
     // For older servers, emulate JSON by encoding the request into an HTML-form.
     if (options.emulateJSON) {
       params.contentType = 'application/x-www-form-urlencoded';
       params.data = params.data ? {model: params.data} : {};