From 6d32ac2b27f782ad565f21d7a47f31e24c4452a1 Mon Sep 17 00:00:00 2001
From: Rufus Pollock <rufus.pollock@okfn.org>
Date: Fri, 6 Jan 2012 12:08:55 +0000
Subject: [PATCH] [refactor][s]: rename getRows to getDocuments (thereby
 removing outstanding TODO).

---
 src/model.js       | 36 +++++++++++++++++++++---------------
 src/view.js        |  2 +-
 test/model.test.js |  8 ++++----
 3 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/src/model.js b/src/model.js
index 09dac231..e102063b 100644
--- a/src/model.js
+++ b/src/model.js
@@ -18,16 +18,20 @@ my.Dataset = Backbone.Model.extend({
     this.docCount = null;
   },
 
-  // Get rows (documents) from the backend returning a recline.DocumentList
+  // AJAX method with promise API to get rows (documents) from the backend.
   //
-  // TODO: ? rename to getDocuments?
+  // Resulting DocumentList are used to reset this.currentDocuments and are
+  // also returned.
+  //
+  // :param numRows: passed onto backend getDocuments.
+  // :param start: passed onto backend getDocuments.
   //
   // this does not fit very well with Backbone setup. Backbone really expects you to know the ids of objects your are fetching (which you do in classic RESTful ajax-y world). But this paradigm does not fill well with data set up we have here.
   // This also illustrates the limitations of separating the Dataset and the Backend
-  getRows: function(numRows, start) {
+  getDocuments: function(numRows, start) {
     var self = this;
     var dfd = $.Deferred();
-    this.backend.getRows(this.id, numRows, start).then(function(rows) {
+    this.backend.getDocuments(this.id, numRows, start).then(function(rows) {
       var docs = _.map(rows, function(row) {
         return new my.Document(row);
       });
@@ -63,14 +67,16 @@ my.setBackend = function(backend) {
 
 // Backend which just caches in memory
 // 
-// Does not need to be a backbone model but provides some conveience
+// Does not need to be a backbone model but provides some conveniences
 my.BackendMemory = Backbone.Model.extend({
   // Initialize a Backend with a local in-memory dataset.
   // 
   // NB: We can handle one and only one dataset at a time.
   //
   // :param dataset: the data for a dataset on which operations will be
-  // performed. In the form of a hash with metadata and data attributes.
+  // performed. Its form should be a hash with metadata and data
+  // attributes.
+  //
   // - metadata: hash of key/value attributes of any kind (but usually with title attribute)
   // - data: hash with 2 keys:
   //  - headers: list of header names/labels
@@ -78,13 +84,13 @@ my.BackendMemory = Backbone.Model.extend({
   //
   //  Example of data:
   // 
-  //    {
-  //        headers: ['x', 'y', 'z']
-  //      , rows: [
-  //          {id: 0, x: 1, y: 2, z: 3}
-  //        , {id: 1, x: 2, y: 4, z: 6}
-  //      ]
-  //    };
+  //        {
+  //            headers: ['x', 'y', 'z']
+  //          , rows: [
+  //              {id: 0, x: 1, y: 2, z: 3}
+  //            , {id: 1, x: 2, y: 4, z: 6}
+  //          ]
+  //        };
   initialize: function(dataset) {
     // deep copy
     this._datasetAsData = $.extend(true, {}, dataset);
@@ -139,7 +145,7 @@ my.BackendMemory = Backbone.Model.extend({
       alert('Not supported: sync on BackendMemory with method ' + method + ' and model ' + model);
     }
   },
-  getRows: function(datasetId, numRows, start) {
+  getDocuments: function(datasetId, numRows, start) {
     if (start === undefined) {
       start = 0;
     }
@@ -199,7 +205,7 @@ my.BackendWebstore = Backbone.Model.extend({
       }
     }
   },
-  getRows: function(datasetId, numRows, start) {
+  getDocuments: function(datasetId, numRows, start) {
     if (start === undefined) {
       start = 0;
     }
diff --git a/src/view.js b/src/view.js
index 409ceab3..6564b0ce 100644
--- a/src/view.js
+++ b/src/view.js
@@ -65,7 +65,7 @@ my.DataExplorer = Backbone.View.extend({
       self.flotGraph.el.hide();
       self.$dataViewContainer.append(self.dataTable.el)
       self.$dataViewContainer.append(self.flotGraph.el);
-      self.model.getRows(self.config.displayCount);
+      self.model.getDocuments(self.config.displayCount);
     });
   },
 
diff --git a/test/model.test.js b/test/model.test.js
index ca3f2510..9db2517d 100644
--- a/test/model.test.js
+++ b/test/model.test.js
@@ -32,11 +32,11 @@ test('new Dataset', function () {
     equal(dataset.get('name'), metadata.name);
     deepEqual(dataset.get('headers'), indata.headers);
     equal(dataset.docCount, 6);
-    dataset.getRows(4, 2).then(function(documentList) {
+    dataset.getDocuments(4, 2).then(function(documentList) {
       deepEqual(indata.rows[2], documentList.models[0].toJSON());
     });
-    dataset.getRows().then(function(docList) {
-      // Test getRows
+    dataset.getDocuments().then(function(docList) {
+      // Test getDocuments
       equal(docList.length, Math.min(10, indata.rows.length));
       var doc1 = docList.models[0];
       deepEqual(doc1.toJSON(), indata.rows[0]);
@@ -159,7 +159,7 @@ test('Webstore Backend', function() {
   dataset.fetch().then(function(dataset) {
     deepEqual(['__id__', 'date', 'geometry', 'amount'], dataset.get('headers'));
     equal(3, dataset.docCount)
-    dataset.getRows().then(function(docList) {
+    dataset.getDocuments().then(function(docList) {
       equal(3, docList.length)
       equal("2009-01-01", docList.models[0].get('date'));
     });