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

[#113,docs/tutorials][s]: split tutorials up more.

Browse Source
This commit is contained in:
Rufus Pollock 2012-07-04 14:52:12 +01:00
parent 811604d409
commit 03fe9a5a6a
6 changed files with 156 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
_includes/tutorial-basics-ex-2.js
View File

@ -8,6 +8,12 @@ var $el = $('.ex-2');
// (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);
$('.ex-2').append('Total found: ' + dataset.recordCount);
$('.ex-2').append(' Total returned: ' + dataset.currentRecords.length);
$('.ex-2').append(
$('<pre />').html(
JSON.stringify(dataset.currentRecords.toJSON(), null, 2)
)
);
});

4
css/site/site.css
View File

@ -164,8 +164,8 @@ section.grey:after {
height: 60px;
}
.tutorials {
margin-bottom: 300px;
.tutorials:last-child {
margin-bottom: 200px;
}
/** Code / Pre **/

55
docs/tutorial-basics-events.markdown Normal file
View File

@ -0,0 +1,55 @@
---
layout: container
title: Tutorial - Dataset Basics - Events
recline-deps: true
root: ../
---
<div class="page-header">
<h1>
Dataset Basics - Events
</h1>
</div>
## Preparations
See <a href="{{page.root}}/docs/tutorial-basics.html">first Dataset basics tutorial</a> for getting setup and initializing Dataset.
<script type="text/javascript">
{% include data.js %}
var dataset = new recline.Model.Dataset({
records: data
});
</script>
## Listening for Events
Often you'll want to listen to events on a Dataset and its associated objects. 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.

46
docs/tutorial-basics-query.markdown Normal file
View File

@ -0,0 +1,46 @@
---
layout: container
title: Tutorial - Dataset Basics
recline-deps: true
root: ../
---
<div class="page-header">
<h1>
Dataset Basics - Querying
</h1>
</div>
## Preparations
See <a href="{{page.root}}/docs/tutorial-basics.html">first Dataset basics tutorial</a> for getting setup and initializing Dataset.
<script type="text/javascript">
{% include data.js %}
var dataset = new recline.Model.Dataset({
records: data
});
</script>
## 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).

53
docs/tutorial-basics.markdown
View File

@ -115,56 +115,3 @@ $('.ex-fields-2').html('');
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.

46
docs/tutorials.html Normal file
View File

@ -0,0 +1,46 @@
---
layout: container
title: Tutorials
root: ../
---
<div class="page-header">
<h1>
Tutorials
</h1>
</div>
<div id="tutorials" class="tutorials">
<div class="row">
<div class="span4">
<div class="well">
<h4><a href="tutorial-basics.html">Dataset Basics</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4><a href="tutorial-basics-query.html">Dataset Querying</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4><a href="tutorial-basics-events.html">Datasets and Events</a></h4>
</div>
</div>
</div>
</div>
<div id="tutorials" class="tutorials">
<div class="row">
<div class="span4">
<div class="well">
<h4><a href="tutorial-backends.html">Backends: loading data from Google Docs, Local CSV, DataHub &amp; more ...</a></h4>
</div>
</div>
<div class="span4">
<div class="well">
<h4><a href="tutorial-views.html">Views Quickstart - Grids, Graphs and Maps</a></h4>
</div>
</div>
</div>
</div>