knight/datahub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[#52,doc,refactor][s]: move instructions re creating a backend into backend/base source docs and tidy doc page a bit.

Browse Source
This commit is contained in:
Rufus Pollock 2012-04-01 11:11:38 +01:00
parent 767f9a23d6
commit e5e24f72de
2 changed files with 43 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
index.html
View File

@ -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-->

30
src/backend/base.js
View File

@ -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) {
},