Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
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...
commit 1dadc1106bd2dbcad4580d3889e15ac44c865f80 1 parent a8b8c1a
@rgrp rgrp authored
View
12 _includes/data.js
@@ -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}}
];
View
21 _includes/example-backends-gdocs.js
@@ -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);
+ }
});
View
24 _includes/tutorial-basics-ex-1.js
@@ -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);
+
View
13 _includes/tutorial-basics-ex-2.js
@@ -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);
+});
+
View
13 _includes/tutorial-basics-ex-events.js
@@ -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);
+
View
10 _includes/tutorial-basics-ex-fields-2.js
@@ -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));
+
View
20 _includes/tutorial-basics-ex-fields.js
@@ -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
42 docs/index.html
@@ -52,53 +52,17 @@ <h2 id="concepts">Concepts and Structure</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
3  docs/models.markdown
@@ -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
View
17 docs/tutorial-backends.markdown
@@ -1,6 +1,6 @@
---
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: ../
---
@@ -8,20 +8,17 @@ 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 -->
View
170 docs/tutorial-basics.markdown
@@ -0,0 +1,170 @@
+---
+layout: container
+title: Tutorial - Dataset Basics
+recline-deps: true
+root: ../
+---
+
+<div class="page-header">
+ <h1>
+ Getting Started with Datasets
+ <br />
+ <small>This step-by-step tutorial will quickly get you started withthe central Recline object: a Dataset</small>
+ </h1>
+</div>
+
+## Preparations
+
+1. [Download ReclineJS]({{page.root}}download.html) and relevant dependencies.
+
+2. Include the core dependencies for the Dataset model
+
+ {% 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>
+<!-- Recline -->
+<script type="text/javascript" src="dist/recline.js"></script>{% endhighlight %}
+
+## Creating a Dataset
+
+Here's the example data We are going to work with:
+
+{% highlight javascript %}
+{% include data.js %}
+{% endhighlight %}
+
+In this data we have 6 records / rows. Each record is a javascript object
+containing keys and values (values can be 'simple' e.g. a string or float or arrays or hashes - e.g. the geo value here).
+
+<div class="alert alert-info">In this tutorial we are creating datasets with
+"local" JS data. However, Recline has a variety of Backends that make it easy
+to create Datasets from a variety of online sources and local sources including
+Google Spreadsheets, CSV files, etc. See the <a
+href="tutorial-backends.html">Backend tutorial</a> for more.</div>
+
+We can now create a recline Dataset object from this raw data:
+
+{% highlight javascript %}
+var dataset = new recline.Model.Dataset({
+ records: data
+});
+{% endhighlight %}
+
+<script type="text/javascript">
+{% include data.js %}
+var dataset = new recline.Model.Dataset({
+ records: data
+});
+</script>
+
+## Records, Fields and more
+
+Now that we have created a Dataset, we can use it.
+
+For example, let's display some information about the Dataset and its records:
+
+<div class="alert alert-info">You can find out more about Dataset and Records in the <a href="models.html">reference documentation</a></div>
+
+{% highlight javascript %}
+{% include tutorial-basics-ex-1.js %}
+{% endhighlight %}
+
+Here's the output:
+
+<div class="ex-1 well">&nbsp;</div>
+
+<script type="text/javascript">
+$('.ex-1').html('');
+{% include tutorial-basics-ex-1.js %}
+</script>
+
+Note how the last geo attribute just rendered as `[object Object]`. This is because the Dataset is treating that field value as a string. Let's now take a look at the Dataset fields in more detail.
+
+### Fields
+
+In addition to Records, a Dataset has <a href="models.html#field">Fields</a> stored in the `fields` attribute. Fields provide information about the fields/columns in the Dataset, for example their id (key name in record), label, type etc.
+
+The Dataset's fields will be automatically computed from records or provided by the backend but they can also be explicitly provided and configured. Let's take a look at the fields on the dataset at present using the following code:
+
+{% highlight javascript %}
+{% include tutorial-basics-ex-fields.js %}
+{% endhighlight %}
+
+Running this results in the following:
+
+<div class="ex-fields well">&nbsp;</div>
+
+<script type="text/javascript">
+$('.ex-fields').html('');
+{% include tutorial-basics-ex-fields.js %}
+</script>
+
+As can be seen all fields have the default type of 'string'. Let's change the geo field to have type geo\_point and see what affect that has on displaying of the dataset (for good measure we'll also set the label):
+
+{% highlight javascript %}
+{% include tutorial-basics-ex-fields-2.js %}
+{% endhighlight %}
+
+<div class="ex-fields-2 well">&nbsp;</div>
+
+<script type="text/javascript">
+$('.ex-fields-2').html('');
+{% include tutorial-basics-ex-fields-2.js %}
+</script>
+
+As can be seen the rendering of the field has changed. This is because the `recordSummary` method uses the Record.getFieldValue function which in turn renders a record field using the Field's renderer function. This function varies depending on the type and can also be customized (see the <a href="models.html#field">Field documentation</a>).
+
+
+## Querying
+
+The basic thing we want to do with Datasets is query and filter them. This is very easy to do:
+
+{% highlight javascript %}
+{% include tutorial-basics-ex-2.js %}
+{% endhighlight %}
+
+This results in the following. Note how recordCount is now 3 (the total number of records matched by the query) but that currentRecords only contains 2 records as we restricted number of returned records using the size attribute.
+
+<div class="ex-2 well">&nbsp;</div>
+
+<script type="text/javascript">
+$('.ex-2').html('');
+{% include tutorial-basics-ex-2.js %}
+</script>
+
+Full details of the <a href="models.html#query">query structure and its options can be found in the reference documentation</a>.
+
+Also worth noting is that the last run query is stored as a <a href="models.html#query">Query instance</a> in the `queryState` attribute of the Dataset object. Modifying `queryState` will also resulting in a query being run. This is useful when building views that want to display or manage the query state (see, for example, <a href="src/widget.queryeditor.html">Query Editor</a> or <a href="src/widget.filtereditor.html">Filter Editor</a> widgets).
+
+
+## Listening for Events
+
+Often you'll want to listen to events on Datasets and its associated objects rather than have to explicitly notify. This is easy to do thanks to the use of Backbone model objects which have a [standard set of events](http://backbonejs.org/#FAQ-events).
+
+Here's an example to illustrate:
+
+{% highlight javascript %}
+{% include tutorial-basics-ex-events.js %}
+{% endhighlight %}
+
+<div class="ex-events well">&nbsp;</div>
+
+<script type="text/javascript">
+$('.ex-events').html('');
+{% include tutorial-basics-ex-events.js %}
+</script>
+
+Here's a summary of the main objects and their events:
+
+* Dataset:
+
+ * Standard Backbone events for changes to attributes (note that this will **not** include changes to records)
+ * *query:start / query:end* called at start and completion of a query
+
+* Dataset.currentRecords: Backbone.Collection of "current" records (i.e. those resulting from latest query) with standard Backbone set of events: *add, reset, remove*
+
+* Dataset.queryState: queryState is a Query object with standard Backbone Model set of events
+
+* Dataset.fields: Backbone Collection of Fields.
+
View
3  docs/tutorial-views.markdown
@@ -17,7 +17,7 @@ root: ../
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.
+1. [Download ReclineJS]({{page.root}}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 -->
@@ -34,7 +34,6 @@ Before writing any code with Recline, you need to do the following preparation s
<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>
-->
View
7 download.markdown
@@ -9,9 +9,10 @@ title: Download
</h1>
</div>
-Besides the library itself, the download package contains full source code,
-unit tests, files for debugging and a build system. The production files
-(included the same way as in the code above) are in the dist folder.
+Besides the library itself, the download package contains full source
+code, unit tests, external vendor libraries and documentation. The
+production files (included the same way as in the code above) are in the
+dist folder.
<p><a href="https://github.com/okfn/recline/zipball/master" class="btn">Download Recline v0.5 (master)</a> (in-progress version)</p>
View
25 src/model.js
@@ -225,6 +225,8 @@ my.Dataset = Backbone.Model.extend({
return data;
},
+ // ### getFieldsSummary
+ //
// Get a summary for each field in the form of a `Facet`.
//
// @return null as this is async function. Provides deferred/promise interface.
@@ -250,6 +252,19 @@ my.Dataset = Backbone.Model.extend({
return dfd.promise();
},
+ // ### recordSummary
+ //
+ // Get a simple html summary of a Dataset record in form of key/value list
+ recordSummary: function(record) {
+ var html = '';
+ this.fields.each(function(field) {
+ if (field.id != 'id') {
+ html += '<div><strong span="key">' + field.get('label') + '</strong>: ' + record.getFieldValue(field) + '</div>';
+ }
+ });
+ return html;
+ },
+
// ### _backendFromString(backendString)
//
// See backend argument to initialize for details
@@ -344,16 +359,6 @@ my.Record = Backbone.Model.extend({
return val;
},
- summary: function(fields) {
- var html = '';
- for (key in this.attributes) {
- if (key != 'id') {
- html += '<div><strong>' + key + '</strong>: '+ this.attributes[key] + '</div>';
- }
- }
- return html;
- },
-
// Override Backbone save, fetch and destroy so they do nothing
// Instead, Dataset object that created this Record should take care of
// handling these changes (discovery will occur via event notifications)
Please sign in to comment.
Something went wrong with that request. Please try again.