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

[docs,refactor][s]: move examples to being tutorials in the docs directory.

Browse Source
This commit is contained in:
Rufus Pollock
2012-06-29 16:40:22 +01:00
parent 12f6afebc9
commit 889fb6afb1
3 changed files with 6 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/index.html
View File

@@ -52,12 +52,12 @@ root: ../
<div class="row">
<div class="span4">
<div class="well">
<h4><a href="example-quickstart.html">Recline Quickstart Guide</a></h4>
<h4><a href="tutorial-views.html">Views Quickstart - Grids, Graphs, Maps and more</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4><a href="example-backends.html">Loading from difference sources: Google Docs, Local CSV, DataHub</a></h4>
<h4><a href="tutorial-backends.html">Loading from difference sources: Google Docs, Local CSV, DataHub</a></h4>
</div>
</div>
<div class="span4">

110
docs/tutorial-backends.markdown Normal file
View File

@@ -0,0 +1,110 @@
---
layout: container
title: Library - Example - Loading data from different sources using Backends
recline-deps: true
root: ../
---
<div class="page-header">
<h1>
Loading data from different sources using Backends
</h1>
</div>
These set of examples will show you how you can load data from different
sources such as Google Docs or the DataHub using Recline.
<div class="alert alert-info">
<p><strong>Note</strong>: 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.</p>
<p>Moreover, Recline is designed so you need <strong>only</strong> include the
backend and its dependencies without needing to include any of the dependencies
for the view portion of the Recline library.</p>
</div>
## 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 use a backend directly e.g.
{% highlight javascript %}
var backend = recline.Backend.ElasticSearch.fetch({url: ...});
{% 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: 'backend-identifier'
});
{% endhighlight %}
<div class="alert alert-info">
<strong>Backend identifiers</strong>
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'.
</div>
### Included Backends
* [elasticsearch: ElasticSearch Backend](docs/backend/elasticsearch.html)
* [dataproxy: DataProxy Backend (CSV and XLS on the Web)](docs/backend/dataproxy.html)
* [gdocs: Google Docs (Spreadsheet) Backend](docs/backend/gdocs.html)
* [csv: Local CSV file backend](docs/backend/csv.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 %}
<!-- 3rd party dependencies -->
<script type="text/javascript" src="vendor/jquery/1.7.1/jquery.js"></script>
<script type="text/javascript" src="vendor/underscore/1.1.6/underscore.js"></script>
<script type="text/javascript" src="vendor/backbone/0.5.1/backbone.js"></script>
<!-- include the backend code you need e.g. here for gdocs -->
<script type="text/javascript" src="src/backend/gdocs.js"></script>
<!-- Or you can just include all of recline. -->
<script type="text/javascript" src="dist/recline.js"></script>
{% 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).
<div class="alert alert-info">
<strong>Want a real world example?</strong> This <a
href="http://okfnlabs.org/opendatacensus">Open Data Census micro-app</a> loads
data from Google Docs and then displays it on a specialist interface combining
a bespoke chooser and a Kartograph (svg-only) map.
</div>
{% highlight javascript %}
{% include example-backends-gdocs.js %}
{% endhighlight %}
### Result
<div id="my-gdocs" class="doc-ex-rendered">&nbsp;</div>
<script type="text/javascript">
{% include example-backends-gdocs.js %}
</script>
## Writing your own backend
Writing your own backend is easy to do. Details of the required API are in the
[Backend documentation](docs/backends.html).

237
docs/tutorial-views.markdown Normal file
View File

@@ -0,0 +1,237 @@
---
layout: container
title: Library - Example - Quickstart
recline-deps: true
root: ../
---
<div class="page-header">
<h1>
Views Tutorial
<br />
<small>This step-by-step tutorial will quickly get you started with Recline basics, including creating a dataset from local data and setting up a grid, graph and map to display it.</small>
</h1>
</div>
### Preparing your page
Before writing any code with Recline, you need to do the following preparation steps on your page:
1. [Download ReclineJS](download.html) and relevant dependencies.
2. Include the relevant CSS in the head section of your document:
{% highlight html %}
<!-- you do not have to use bootstrap but we use it by default -->
<link rel="stylesheet" href="vendor/bootstrap/2.0.2/css/bootstrap.css" />
<!-- CSS for relevant view components - here we just have grid -->
<link rel="stylesheet" href="css/grid.css" />{% endhighlight %}
3. Include the relevant Javascript files somewhere on the page (preferably before body close tag):
{% highlight html %}<!-- 3rd party dependencies -->
<script type="text/javascript" src="vendor/jquery/1.7.1/jquery.js"></script>
<script type="text/javascript" src="vendor/underscore/1.1.6/underscore.js"></script>
<script type="text/javascript" src="vendor/backbone/0.5.1/backbone.js"></script>
<script type="text/javascript" src="vendor/jquery.mustache.js"></script>
<script type="text/javascript" src="vendor/bootstrap/2.0.2/bootstrap.js"></script>
<!-- note that we could include individual components rather than whole of recline e.g.
<script type="text/javascript" src="src/model.js"></script>
<script type="text/javascript" src="src/backend/base.js"></script>
<script type="text/javascript" src="src/backend/memory.js"></script>
<script type="text/javascript" src="src/view-grid.js"></script>
-->
<script type="text/javascript" src="dist/recline.js"></script>{% endhighlight %}
4. Create a div to hold the Recline view(s):
{% highlight html %}
<div id="mygrid"></div>{% endhighlight %}
You're now ready to start working with Recline.
### Creating a Dataset
Here's some example data We are going to work with:
{% highlight javascript %}
{% include data.js %}
{% endhighlight %}
In this data we have 6 documents / rows. Each document is a javascript object
containing keys and values (note that all values here are 'simple' but there is
no reason you cannot have objects as values allowing you to nest data.
We can now create a recline Dataset object (and memory backend) from this raw data:
{% highlight javascript %}
var dataset = recline.Backend.Memory.createDataset(data);
{% endhighlight %}
Note that behind the scenes Recline will create a Memory backend for this dataset as in Recline every dataset object must have a backend from which it can push and pull data. In the case of in-memory data this is a little artificial since all the data is available locally but this makes more sense for situations where one is connecting to a remote data source (and one which may contain a lot of data).
### Setting up the Grid
Let's create a data grid view to display the dataset we have just created, binding the view to the `<div id="mygrid"></div>` we created earlier:
{% highlight javascript %}
var $el = $('#mygrid');
var grid = new recline.View.Grid({
model: dataset
});
$el.append(grid.el);
grid.render();
{% endhighlight %}
And hey presto:
<div id="mygrid" class="recline-read-only" style="margin-bottom: 30px; margin-top: -20px;">&nbsp;</div>
<script type="text/javascript">
{% include data.js %}
var dataset = recline.Backend.Memory.createDataset(data);
var $el = $('#mygrid');
var grid = new recline.View.Grid({
model: dataset,
});
$el.append(grid.el);
grid.render();
</script>
### Creating a Graph
Let's create a graph view to display a line graph for this dataset.
First, add the additional dependencies for this view. These are the Flot
library and the Recline Graph view:
{% highlight html %}
<link rel="stylesheet" href="css/graph.css">
<!-- javascript -->
<script type="text/javascript" src="vendor/jquery.flot/0.7/jquery.flot.js"></script>
<script type="text/javascript" src="src/view-graph.js"></script>
{% endhighlight %}
Next, create a new div for the graph:
{% highlight html %}
<div id="mygraph"></div>
{% endhighlight %}
Now let's create the graph, we will use the same dataset we had earlier:
{% highlight javascript %}
var $el = $('#mygraph');
var graph = new recline.View.Graph({
model: dataset
});
$el.append(grid.el);
graph.render();
{% endhighlight %}
And ... we have a graph view -- with instructions on how to use the controls to
create a graph -- but no graph. Go ahead and play around with the controls to
create a graph of your choosing:
<div id="mygraph" style="margin-bottom: 30px;">&nbsp;</div>
<script type="text/javascript">
var $el = $('#mygraph');
var graph = new recline.View.Graph({
model: dataset
});
$el.append(graph.el);
graph.render();
</script>
But suppose you wanted to create a graph not a graph editor. This is
straightforward to do -- all we need to do is set the 'state' of the graph
view:
{% highlight javascript %}
var $el = $('#mygraph');
var graph = new recline.View.Graph({
model: dataset,
state: {
group: "date",
series: ["x", "z"]
}
});
$el.append(graph.el);
graph.redraw();
{% endhighlight %}
We would get this rendered graph:
<div id="mygraph2" style="margin-bottom: 30px;">&nbsp;</div>
<script type="text/javascript">
var $el = $('#mygraph2');
var graph = new recline.View.Graph({
model: dataset,
state: {
graphType: "lines-and-points",
group: "x",
series: ["y", "z"]
}
});
$el.append(graph.el);
graph.redraw();
</script>
<div class="alert alert-info">
<strong>State</strong>: The concept of a state is a common feature of Recline views being an object
which stores information about the state and configuration of a given view. You
can read more about it in the general <a href="../docs/view.html">Views
documentation</a> as well as the documentation of individual views such as the
<a href="../docs/view-graph.html">Graph View</a>.
</div>
### Creating a Map
Now, let's create a map of this dataset using the lon/lat information which is
present on these data points.
First, add the additional dependencies for the map view. These are the Leaflet
library and the Recline Map view:
{% highlight html %}
<!-- css -->
<link rel="stylesheet" href="vendor/leaflet/0.3.1/leaflet.css">
<!--[if lte IE 8]>
<link rel="stylesheet" href="vendor/leaflet/0.3.1/leaflet.ie.css" />
<![endif]-->
<link rel="stylesheet" href="css/map.css">
<!-- javascript -->
<script type="text/javascript" src="vendor/leaflet/0.3.1/leaflet.js"></script>
<script type="text/javascript" src="src/view-map.js"></script>
{% endhighlight %}
Now, create a new div for the map:
{% highlight html %}
<div id="mymap"></div>
{% endhighlight %}
Now let's create the map, we will use the existing dataset object created
previously:
{% highlight javascript %}
var $el = $('#mymap');
var map = new recline.View.Map({
model: dataset
});
$el.append(map.el);
map.redraw();
{% endhighlight %}
<div id="mymap">&nbsp;</div>
<script type="text/javascript">
var $el = $('#mymap');
var map = new recline.View.Map({
model: dataset
});
$el.append(map.el);
map.redraw();
</script>