From 68d2f66f66ca09d5e3ba99958b7f4bb5e378dc3c Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Mon, 22 Oct 2012 16:30:15 +0100 Subject: [PATCH] [docs/backend][s]: tidy up and factor out backend list to include file. --- _includes/backend-list.html | 8 ++++++ _includes/example-backends-online-csv.js | 6 ++--- docs/backends.markdown | 10 +++++++ docs/index.html | 9 +------ docs/tutorial-backends.markdown | 33 ++++++++---------------- 5 files changed, 33 insertions(+), 33 deletions(-) create mode 100644 _includes/backend-list.html diff --git a/_includes/backend-list.html b/_includes/backend-list.html new file mode 100644 index 00000000..8e5eaddb --- /dev/null +++ b/_includes/backend-list.html @@ -0,0 +1,8 @@ + diff --git a/_includes/example-backends-online-csv.js b/_includes/example-backends-online-csv.js index 60a57d93..284998c9 100644 --- a/_includes/example-backends-online-csv.js +++ b/_includes/example-backends-online-csv.js @@ -3,8 +3,8 @@ var dataset = new recline.Model.Dataset({ url: '{{page.root}}/demos/data/sample.csv', backend: 'csv', - // separator: ',', - // delimiter: '"', + // delimiter: ',', + // quotechar: '"', // encoding: 'utf8' }); @@ -13,7 +13,7 @@ var dataset = new recline.Model.Dataset({ dataset.fetch(); // show the data for illustrations sake -var grid = new recline.View.Grid({ +var grid = new recline.View.SlickGrid({ model: dataset }); $('#my-online-csv').append(grid.el); diff --git a/docs/backends.markdown b/docs/backends.markdown index 72e22069..527f9014 100644 --- a/docs/backends.markdown +++ b/docs/backends.markdown @@ -16,11 +16,21 @@ 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. +
Looking for quickstart tutorial rather than reference documentation? See the Backends Tutorial.
+ Backends come in 2 flavours: 1. Loader backends - only implement fetch method. The data is then cached in a Memory.Store on the Dataset and interacted with there. This is best for sources which just allow you to load data or where you want to load the data once and work with it locally. 2. Store backends - these support fetch, query and, if write-enabled, save. These are suitable where the backend contains a lot of data (infeasible to load locally - for examples a million rows) or where the backend has capabilities you want to take advantage of. +# List of Backends Shipped with Recline + +{% include backend-list.html %} + +NB: examples of the 2 types of backends are provided by the Google docs backend (a "Loader" backend) and the ElasticSearch backend (a Store backend). + +It's easy to write your own backend - you just need to implement the API as described below. + # Backend API diff --git a/docs/index.html b/docs/index.html index 37f90f55..a76db5e8 100644 --- a/docs/index.html +++ b/docs/index.html @@ -54,14 +54,7 @@ root: ../

Backends

- + {% include backend-list.html %}

Dataset Views and Widgets

diff --git a/docs/tutorial-backends.markdown b/docs/tutorial-backends.markdown index fad3b026..2f8c3594 100644 --- a/docs/tutorial-backends.markdown +++ b/docs/tutorial-backends.markdown @@ -1,6 +1,6 @@ --- layout: container -title: Tutorial - Backends - Loading data from different sources using Backends +title: Loading data from different sources using Backends - Tutorial recline-deps: true root: ../ --- @@ -53,23 +53,18 @@ var dataset = recline.Model.Dataset({ {% endhighlight %}
-Backend identifiers +

Backend identifiers How do you know the backend identifier for a given Backend? It's just the name of the 'class' in recline.Backend module (but case-insensitive). E.g. recline.Backend.ElasticSearch can be identified as 'ElasticSearch' or -'elasticsearch'. +'elasticsearch'.

+

What Backends are available from Recline? +{% include backend-list.html %} +

+

Backend you'd like to see not available? It's easy to write your own – see the Backend reference docs for details of the required API. +

-### Included Backends - -* [gdocs: Google Docs (Spreadsheet)](src/backend.gdocs.html) -* [csv: CSV files](src/backend.csv.html) -* [elasticsearch: ElasticSearch](src/backend.elasticsearch.html) - this also covers the DataHub as it has an ElasticSearch compatible API -* [dataproxy: DataProxy (CSV and XLS on the Web)](src/backend.dataproxy.html) -* [couchdb: CouchDB](src/backend.couchdb.html) - -Backend not on this list that you would like to see? It's very easy to write a -new backend -- see below for more details. ## Preparing your app @@ -82,7 +77,7 @@ much more limited if you are just using a Backend. Specifically: - + @@ -98,7 +93,7 @@ For Recline to be able to access a Google Spreadsheet it **must** have been
Want a real world example? This Open Data Census micro-app loads +href="http://dashboard.opengovernmentdata.org/census/">Open Data Census micro-app loads data from Google Docs and then displays it on a specialist interface combining a bespoke chooser and a Kartograph (svg-only) map.
@@ -137,7 +132,7 @@ Recline supports ElasticSearch as a full read/write/query backend. It also means For loading data from CSV files there are 3 cases: -1. CSV is online but on same domain -- we can then load using AJAX (as no problems with same origin policy) +1. CSV is online but on same domain or supporting CORS (S3 and Google Storage support CORS!) -- we can then load using AJAX (as no problems with same origin policy) 2. CSV is on local disk -- if your browser supports HTML5 File API we can load the CSV file off disk 3. CSV is online but not on same domain -- use DataProxy (see below) @@ -211,9 +206,3 @@ You can customize the length of this timeout by setting the following constant: recline.Backend.DataProxy.timeout = 10000; {% endhighlight %} - -## Writing your own backend - -Writing your own backend is easy to do. Details of the required API are in the -[Backend documentation](backends.html). -