From 73767bf6c4eb038fd163b50972f099c8ddc8e7ac Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 18 May 2012 23:21:00 +0100 Subject: [PATCH] [#121,doc/example-backends][m]: reasonable start on a backend tutorial including a live example of loading data from google docs. --- _includes/example-backends-gdocs.js | 27 +++++++ css/site/site.css | 4 + example-backends.markdown | 114 ++++++++++++++++++++++++++++ library.html | 12 +-- 4 files changed, 151 insertions(+), 6 deletions(-) create mode 100644 _includes/example-backends-gdocs.js create mode 100644 example-backends.markdown diff --git a/_includes/example-backends-gdocs.js b/_includes/example-backends-gdocs.js new file mode 100644 index 00000000..55f6c630 --- /dev/null +++ b/_includes/example-backends-gdocs.js @@ -0,0 +1,27 @@ +// Create a dataset with a Google Docs backend and a url to the Google Doc +var dataset = new recline.Model.Dataset({ + url: 'https://docs.google.com/spreadsheet/ccc?key=0Aon3JiuouxLUdGZPaUZsMjBxeGhfOWRlWm85MmV0UUE#gid=0' + }, + backend='gdoc' +); + +// Optional - display the results in a grid +// Note how we can set this up before any data has arrived +// Views will listen for query completion and update themselves automatically +var grid = new recline.View.Grid({ + model: dataset +}); +$('#my-gdocs').append(grid.el); + +// Now do the query to the backend to load data +dataset.fetch().done(function() { + dataset.query().done(function(data) { + // The grid will update automatically + // Log some data as an example + if (console) { + console.log(data); + console.log(dataset.currentDocuments); + } + }); +}); + diff --git a/css/site/site.css b/css/site/site.css index c1a30f1d..a7970f63 100644 --- a/css/site/site.css +++ b/css/site/site.css @@ -267,3 +267,7 @@ section.grey:after { border-radius: 0; } +.doc-ex-rendered { + margin-bottom: 20px; +} + diff --git a/example-backends.markdown b/example-backends.markdown new file mode 100644 index 00000000..c2cc55ee --- /dev/null +++ b/example-backends.markdown @@ -0,0 +1,114 @@ +--- +layout: container +title: Library - Example - Loading data from different sources using Backends +recline-deps: true +--- + +
+

+ Loading data from different sources using Backends +

+
+ +These set of examples will show you how you can load data from different +sources such as Google Docs or the DataHub using Recline. + +
+

Note: often you are loading data from a given source in +order to display it using the various Recline views. However, you can also +happily use this data with your own code and app and this is a very common +use-case.

+

Moreover, Recline is designed so you need only include the +backend and its dependencies without needing to include any of the dependencies +for the view portion of the Recline library.

+
+ +## Overview + +Backends 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. + +You can instantiate a backend directly e.g. + +{% highlight javascript %} +var backend = recline.Backend.ElasticSearch(); +{% endhighlight %} + +But more usually the backend will be created or loaded for you by Recline and all you need is provide the identifier for that Backend e.g. + +{% highlight javascript %} +var dataset = recline.Model.Dataset({ + ... + }, + 'backend-identifier' +); +{% endhighlight %} + +
+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'. +
+ +### Included Backends + +* [memory: Memory Backend (local data)](docs/backend/memory.html) +* [elasticsearch: ElasticSearch Backend](docs/backend/elasticsearch.html) +* [dataproxy: DataProxy Backend (CSV and XLS on the Web)](docs/backend/dataproxy.html) +* [gdoc: Google Docs (Spreadsheet) Backend](docs/backend/gdocs.html) +* [csv: Local CSV file backend](docs/backend/localcsv.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 + +This is as per the [quickstart](example-quickstart.html) but the set of files is much more limited if you are just using a Backend. Specifically: + +{% highlight html %} + + + + + + + + + + + +{% endhighlight %} + + +## Loading Data from Google Docs + +We will be using the [following Google +Doc](https://docs.google.com/spreadsheet/ccc?key=0Aon3JiuouxLUdGZPaUZsMjBxeGhfOWRlWm85MmV0UUE#gid=0). +For Recline to be able to access a Google Spreadsheet it **must** have been +'Published to the Web' (enabled via File -> Publish to the Web menu). + +
+Want a real world example? This 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. +
+ +{% highlight javascript %} +{% include example-backends-gdocs.js %} +{% endhighlight %} + +### Result + +
 
+ + + + +## Writing your own backend + +Writing your own backend is easy to do. Details of the required API are in the +[Backend documentation](docs/backend/base.html). + diff --git a/library.html b/library.html index 7165f566..6742e859 100644 --- a/library.html +++ b/library.html @@ -25,7 +25,7 @@ title: Library - Home

Recline Quickstart Guide

-

Loading from difference sources: Google Docs, Local CSV, DataHub

+

Loading from difference sources: Google Docs, Local CSV, DataHub

Twitter Example

@@ -148,11 +148,11 @@ title: Library - Home

Backends