From e5e24f72debaabfc4551fd489d574677f2b18b50 Mon Sep 17 00:00:00 2001
From: Rufus Pollock <rufus.pollock@okfn.org>
Date: Sun, 1 Apr 2012 11:11:38 +0100
Subject: [PATCH] [#52,doc,refactor][s]: move instructions re creating a
 backend into backend/base source docs and tidy doc page a bit.

---
 index.html          | 67 ++++++++++-----------------------------------
 src/backend/base.js | 30 +++++++++++++++++++-
 2 files changed, 43 insertions(+), 54 deletions(-)

diff --git a/index.html b/index.html
index 1f1c298a..c43582b4 100644
--- a/index.html
+++ b/index.html
@@ -9,9 +9,9 @@
     <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
   <![endif]-->
 
-  <link rel="stylesheet" href="vendor/bootstrap/2.0.0/css/bootstrap.css" />
+  <link rel="stylesheet" href="vendor/bootstrap/2.0.2/css/bootstrap.css" />
   <link rel="stylesheet" href="http://opendatahandbook.org/en/_static/bootstrap-sphinx.css" />
-  <link rel="stylesheet" href="vendor/bootstrap/2.0.0/css/bootstrap-responsive.css" />
+  <link rel="stylesheet" href="vendor/bootstrap/2.0.2/css/bootstrap-responsive.css" />
   
   <style type="text/css">
     html, body {
@@ -65,7 +65,6 @@
       <ul class="nav">
         <li><a href="demo/">Demo</a></li>
         <li><a href="#docs">Docs</a></li>
-        <li><a href="#downloads">Download</a></li>
         <li><a href="http://github.com/okfn/recline/">Code on GitHub</a></li>
       </ul>
       <a class="nav-logo pull-right" href="http://okfn.org/" title="An Open Knowledge Foundation Project">
@@ -140,7 +139,7 @@ Backbone.history.start();
       href="demo/">Demo</a> -- just hit view source (NB: the javascript for the
     demo is in: <a href="demo/js/app.js">app.js</a>).</p>
 
-    <h3 id="doc-concepts">Structure</h3>
+    <h3 id="docs-concepts">Concepts and Structure</h3>
     <p>Recline has a simple structure layered on top of the basic Model/View
     distinction inherent in Backbone.</p>
     
@@ -154,9 +153,13 @@ Backbone.history.start();
     <p><strong>Backends</strong> connect Dataset and Documents to data
     from a specific 'Backend' data source. They provide methods for loading and
     saving Datasets and individuals Documents as well as for bulk loading via a
-    query API and doing bulk transforms on the backend. More <a
-      href="#doc-backends">info on backends can be found below</a>.</p>
-
+    query API and doing bulk transforms on the backend.</p>
+    <p>A template Base class can be found <a href="docs/backend/base.html">in
+      the Backend base module of the source docs</a>. It documents both the
+    relevant methods a Backend must have and (optionally) provides a base
+    'class' for inheritance. You can also find detailed examples of backend
+    implementations in the source documentation below.</p>
+    
     <p><strong>Views</strong>: complementing the model are various Views (you can also easily write your own). Each view holds a pointer to a Dataset:</p>
     <ul>
       <li>DataExplorer: the parent view which manages the overall app and sets up sub views.</li>
@@ -164,58 +167,16 @@ Backbone.history.start();
       <li>FlotGraph: a simple graphing view using <a href="http://code.google.com/p/flot/">Flot</a>.</li>
     </ul>
 
-<h3 id="doc-backends">Backends</h3>
-<p>Backends are implemented as Backbone models but this is just a convenience
-(they do not save or load themselves from any remote source). You can see
-detailed examples of backend implementation in the source documentation
-below.</p>
-
-<p>A backend <em>must</em> implement two methods:</p>
-<pre>
-sync(method, model, options)
-query(dataset, queryObj)
-</pre>
-
-<h4>sync(method, model, options)</h4>
-
-<p>This is an implemntation of Backbone.sync and is used to override
-Backbone.sync on operations for Datasets and Documents which are using this
-backend.</p>
-
-<p>For read-only implementations you will need only to implement read method
-for Dataset models (and even this can be a null operation). The read method
-should return relevant metadata for the Dataset. We do not require read support
-for Documents because they are loaded in bulk by the query method.</p>
-
-<p>For backends supporting write operations you must implement update and
-delete support for Document objects.</p>
-
-<p>All code paths should return an object conforming to the jquery promise
-API.</p>
-
-<h4>query(dataset, queryObj)</h4>
-
-<p>Query the backend for documents returning them in bulk. This method will be
-used by the Dataset.query method to search the backend for documents,
-retrieving the results in bulk. This method should also set the docCount
-attribute on the dataset.</p>
-
-<p><code>queryObj</code> should be either a recline.Model.Query object or a
-Hash. The structure of data in the Query object or Hash should follow that
-defined in <a href="http://github.com/okfn/recline/issues/34">issue 34</a>. (Of
-course, if you are writing your own backend, and hence have control over the
-interpretation of the query object, you can use whatever structure you
-like).</p>
-
-    <h3>Source Docs (via Docco)</h3>
+    <h3 id="docs-source">Source Docs (via Docco)</h3>
     <ul>
       <li><a href="docs/model.html">Models</a></li>
       <li><a href="docs/view.html">DataExplorer View (plus common view code)</a></li>
       <li><a href="docs/view-grid.html">DataGrid View</a></li>
       <li><a href="docs/view-flot-graph.html">Graph View (based on Flot)</a></li>
+      <li><a href="docs/backend/base.html">Backend: Base (base class providing a template for backends)</a></li>
       <li><a href="docs/backend/memory.html">Backend: Memory (local data)</a></li>
       <li><a href="docs/backend/elasticsearch.html">Backend: ElasticSearch</a></li>
-      <li><a href="docs/backend/dataproxy.html">Backend: DataProxy</a></li>
+      <li><a href="docs/backend/dataproxy.html">Backend: DataProxy (CSV and XLS on the Web)</a></li>
       <li><a href="docs/backend/gdocs.html">Backend: Google Docs (Spreadsheet)</a></li>
     </ul>
 
@@ -258,7 +219,7 @@ like).</p>
       <ul class="nav nav-list">
         <li><a href="#docs-using">Using it</a></li>
         <li><a href="#docs-concepts">Concepts and Structure</a></li>
-        <li><a href="#docs-backends">Backends</a></li>
+        <li><a href="#docs-source">Source Docs (Docco)</a></li>
       </ul>
     </div><!--/.well -->
   </div><!--/span-->
diff --git a/src/backend/base.js b/src/backend/base.js
index 94ab7fb1..49eda889 100644
--- a/src/backend/base.js
+++ b/src/backend/base.js
@@ -2,7 +2,7 @@
 //
 // Backends are connectors to backend data sources and stores
 //
-// This is just the base module containing various convenience methods.
+// This is just the base module containing a template Base class and convenience methods.
 this.recline = this.recline || {};
 this.recline.Backend = this.recline.Backend || {};
 
@@ -18,9 +18,37 @@ this.recline.Backend = this.recline.Backend || {};
   //
   // Base class for backends providing a template and convenience functions.
   // You do not have to inherit from this class but even when not it does provide guidance on the functions you must implement.
+  //
+  // Note also that while this (and other Backends) are implemented as Backbone models this is just a convenience.
   my.Base = Backbone.Model.extend({
+
+    // ### sync
+    //
+    // An implementation of Backbone.sync that will be used to override
+    // Backbone.sync on operations for Datasets and Documents which are using this backend.
+    //
+    // For read-only implementations you will need only to implement read method
+    // for Dataset models (and even this can be a null operation). The read method
+    // should return relevant metadata for the Dataset. We do not require read support
+    // for Documents because they are loaded in bulk by the query method.
+    //
+    // For backends supporting write operations you must implement update and delete support for Document objects.
+    //
+    // All code paths should return an object conforming to the jquery promise API.
     sync: function(method, model, options) {
     },
+    
+    // ### query
+    //
+    // Query the backend for documents returning them in bulk. This method will be used by the Dataset.query method to search the backend for documents, retrieving the results in bulk. This method should also set the docCount attribute on the dataset.
+    //
+    // <code>queryObj</code> should be either a recline.Model.Query
+    // object or a Hash. The structure of data in the Query object or
+    // Hash should follow that defined in <a
+    // href="http://github.com/okfn/recline/issues/34">issue 34</a>.
+    // (Of course, if you are writing your own backend, and hence
+    // have control over the interpretation of the query object, you
+    // can use whatever structure you like).
     query: function(model, queryObj) {
     },