Permalink
Browse files

[#113,docs/tutorial][l]: tutorial-basics written giving introduction …

…to dataset and associated functionality.

* Minor corrections to several other parts of docs.
  • Loading branch information...
rufuspollock committed Jul 1, 2012
1 parent a8b8c1a commit 1dadc1106bd2dbcad4580d3889e15ac44c865f80
View
@@ -1,9 +1,9 @@
var data = [
- {id: 0, date: '2011-01-01', x: 1, y: 2, z: 3, country: 'DE', label: 'first', lat:52.56, lon:13.40},
- {id: 1, date: '2011-02-02', x: 2, y: 4, z: 24, country: 'UK', label: 'second', lat:54.97, lon:-1.60},
- {id: 2, date: '2011-03-03', x: 3, y: 6, z: 9, country: 'US', label: 'third', lat:40.00, lon:-75.5},
- {id: 3, date: '2011-04-04', x: 4, y: 8, z: 6, country: 'UK', label: 'fourth', lat:57.27, lon:-6.20},
- {id: 4, date: '2011-05-04', x: 5, y: 10, z: 15, country: 'UK', label: 'fifth', lat:51.58, lon:0},
- {id: 5, date: '2011-06-02', x: 6, y: 12, z: 18, country: 'DE', label: 'sixth', lat:51.04, lon:7.9}
+ {id: 0, date: '2011-01-01', x: 1, y: 2, z: 3, country: 'DE', geo: {lat:52.56, lon:13.40} },
+ {id: 1, date: '2011-02-02', x: 2, y: 4, z: 24, country: 'UK', geo: {lat:54.97, lon:-1.60}},
+ {id: 2, date: '2011-03-03', x: 3, y: 6, z: 9, country: 'US', geo: {lat:40.00, lon:-75.5}},
+ {id: 3, date: '2011-04-04', x: 4, y: 8, z: 6, country: 'UK', geo: {lat:57.27, lon:-6.20}},
+ {id: 4, date: '2011-05-04', x: 5, y: 10, z: 15, country: 'UK', geo: {lat:51.58, lon:0}},
+ {id: 5, date: '2011-06-02', x: 6, y: 12, z: 18, country: 'DE', geo: {lat:51.04, lon:7.9}}
];
@@ -1,10 +1,8 @@
// 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 name or instance
- 'gdocs'
-);
+ url: 'https://docs.google.com/spreadsheet/ccc?key=0Aon3JiuouxLUdGZPaUZsMjBxeGhfOWRlWm85MmV0UUE#gid=0',
+ backend: 'gdocs'
+});
// Optional - display the results in a grid
// Note how we can set this up before any data has arrived
@@ -15,14 +13,9 @@ var grid = new recline.View.Grid({
$('#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);
- }
- });
+dataset.fetch().done(function(dataset) {
+ if (console) {
+ console.log(dataset.currentDocuments);
+ }
});
@@ -0,0 +1,24 @@
+// (for convenience) assume availability of jquery
+// must have div with class="ex-1"
+var $el = $('.ex-1');
+
+// we will define this function display so we can reuse it below!
+function display(dataset) {
+ // total number of records resulting from latest query
+ $el.append('Total found: ' + dataset.recordCount + '<br />');
+ $el.append('Total returned: ' + dataset.currentRecords.length);
+
+ $el.append('<hr />');
+
+ // dataset.currentRecords is a Backbone Collection of Records that resulted from latest query (hence "current")
+ // Get the first record in the list - it returns an instance of the Record object
+ var record = dataset.currentRecords.at(0);
+
+ // Use the summary helper method which produces proper html
+ // You could also do record.toJSON() to get a hash of the record data
+ $el.append(dataset.recordSummary(record));
+}
+
+// now display our existing dataset ...
+display(dataset);
+
@@ -0,0 +1,13 @@
+// must have a div with class="ex-1"
+var $el = $('.ex-2');
+
+// query with text 'UK' - this will attempt to match any field for UK
+// Also limit the query to return a maximum of 2 results using the size attribute
+
+// query function has asynchronous behaviour and returns a promise object
+// (even for the case of in memory data where querying in fact happens synchronously)
+// On completion the display function will be called
+dataset.query({q: 'UK', size: 2}).done(function() {
+ display(dataset);
+});
+
@@ -0,0 +1,13 @@
+function onChange() {
+ $('.ex-events').append('Queried: ' + dataset.queryState.get('q') + '. Records matching: ' + dataset.recordCount);
+ $('.ex-events').append('<br />');
+}
+
+dataset.currentRecords.bind('reset', onChange);
+
+dataset.query({q: 'DE'});
+dataset.query({q: 'UK'});
+dataset.query({q: 'US'});
+
+dataset.unbind('reset', onChange);
+
@@ -0,0 +1,10 @@
+var $el = $('.ex-fields-2');
+
+dataset.fields.models[6] = new recline.Model.Field({
+ id: 'geo',
+ label: 'Location',
+ type: 'geo_point'
+});
+var rec = dataset.currentRecords.at(0);
+$el.append(dataset.recordSummary(rec));
+
@@ -0,0 +1,20 @@
+var $el = $('.ex-fields');
+
+// Now list the Fields of this Dataset (these will have be automatically extracted from the data)
+$el.append('Fields: ');
+// Dataset.fields is a Backbone collection of Fields (i.e. record attributes)
+dataset.fields.each(function(field) {
+ $el.append(field.id + ' || ');
+});
+
+$el.append('<hr />');
+
+// Show all field info
+var json = dataset.fields.toJSON();
+$el.append(
+ $('<pre />')
+ .append(
+ JSON.stringify(json, null, 2)
+ )
+);
+
View
@@ -52,53 +52,17 @@ <h2>Tutorials</h2>
<div class="row">
<div class="span4">
<div class="well">
- <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="tutorial-backends.html">Loading from difference sources: Google Docs, Local CSV, DataHub</a></h4>
- </div>
- </div>
- <div class="span4">
- <div class="well">
- <h4>Twitter Example</h4>
- </div>
- </div>
- </div>
- <div class="row">
- <div class="span4">
- <div class="well">
- <h4>Customing Display and Import using Fields</h4>
+ <h4><a href="tutorial-basics.html">Dataset Basics - Creating, Querying, Using</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
- <h4>Listening to events</h4>
+ <h4><a href="tutorial-backends.html">Backends and loading data from Google Docs, Local CSV, DataHub and more</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
- <h4>Setting and Getting State</h4>
- </div>
- </div>
- </div>
-
- <h3>Extending Recline</h3>
- <div class="row">
- <div class="span4">
- <div class="well">
- <h4>Create a new View</h4>
- </div>
- </div>
- <div class="span4">
- <div class="well">
- <h4>Create a new Backend</h4>
- </div>
- </div>
- <div class="span4">
- <div class="well">
- <h4>Create a Custom Record Object</h4>
+ <h4><a href="tutorial-views.html">Views Quickstart - Grids, Graphs, Maps and more</a></h4>
</div>
</div>
</div>
View
@@ -21,7 +21,7 @@ holding summary information about a Field (or multiple Fields).
All the models are Backbone models, that is they extend Backbone.Model. Note,
however that they do not 'sync' (load/save) like normal Backbone models.
-## Dataset
+<h2 id="dataset">Dataset</h2>
A Dataset is *the* central object in Recline. Standard usage is:
@@ -159,7 +159,6 @@ field's value (if any) and the current record. It's signature and behaviour is
the same as for renderer.
-
<h2 id="query">Query</h2>
Query instances encapsulate a query to the backend (see <a
@@ -1,27 +1,24 @@
---
layout: container
-title: Library - Example - Loading data from different sources using Backends
+title: Tutorial - Backends - Loading data from different sources using Backends
recline-deps: true
root: ../
---
<div class="page-header">
<h1>
Loading data from different sources using Backends
+ <br />
+ <small>These set of examples will show you how you can load data from different
+sources such as Google Docs or the DataHub using Recline</small>
</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>
+order to load it into a Recline Dataset and display it in a View. However, you can also
+happily use a Backend to load data on its own without using any other part of the Recline library as all the Backends are designed to have no dependency on other parts of Recline.</p>
</div>
## Overview
@@ -61,7 +58,7 @@ Backend not on this list that you would like to see? It's very easy to write a n
## 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:
+This is as per the [quickstart](tutorial-views.html) but the set of files is much more limited if you are just using a Backend. Specifically:
{% highlight html %}
<!-- 3rd party dependencies -->
Oops, something went wrong.

0 comments on commit 1dadc11

Please sign in to comment.