[docs/tutorials,#113][s]: rework and extend section on records in basics tutorial and start section on filters in query tutorial.

docs/tutorial-basics-query.markdown

@@ -13,7 +13,7 @@ root: ../
 
 ## Preparations
 
-See <a href="{{page.root}}/docs/tutorial-basics.html">first Dataset basics tutorial</a> for getting setup and initializing Dataset.
+See <a href="{{page.root}}/docs/tutorial-basics.html">first Dataset basics tutorial</a> for getting setup and initializing a Dataset.
 
 <script type="text/javascript">
 {% include data.js %}
@@ -24,13 +24,16 @@ var dataset = new recline.Model.Dataset({
 
 ## Querying
 
-The basic thing we want to do with Datasets is query and filter them. This is very easy to do:
+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 records only contains 2 records as we restricted number of returned records using the size attribute.
+This results in the following. Note how recordCount is now 3 (the total number
+of records matched by the query) but that records only contains 2 records as we
+restricted number of returned records using the size attribute.
 
 <div class="ex-2 well">&nbsp;</div>
 
@@ -39,8 +42,29 @@ $('.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>.
+## Filtering
 
-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).
+A simple unstructured query like the one provided above searches all fieldsfor the value provided.
 
+Often you want to "filter" results more precisely, for example by specifying a specific value in a specific field. To do this we use "filters".
+
+{% highlight javascript %}
+var query = new recline.Model.Query();
+query.addFilter({type: 'term', field: 2});
+dataset.query(query);
+{% endhighlight %}
+
+## QueryState
+
+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).
+
+## Full Details of the Query Language
+
+Full details of the <a href="models.html#query">query structure and its options
+can be found in the reference documentation</a>.
 

docs/tutorial-basics.markdown

@@ -58,13 +58,11 @@ var dataset = new recline.Model.Dataset({
 });
 </script>
 
-## Records, Fields and more
+## A Dataset and its Records
 
 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>
+For example, let's display some information about the Dataset and its records using some of the key Dataset attributes: `recordCount` and `records`.
 
 {% highlight javascript %}
 {% include tutorial-basics-ex-1.js %}
@@ -79,9 +77,42 @@ $('.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.
+### Records
 
-### Fields
+`Dataset.records` is a Backbone Collection of `Record`s resutling from latest query. This need not (and usually isn't) **all** the records in this Dataset since the latest query need not have matched all records.
+
+<div class="alert alert-info">
+Note that on initialization, a Dataset automatically queries for the first 100 records so this is what will usually be available in th <code>records</code> attribute. If you did want all records loaded into <code>records</code> at the start just requery after fetch has completed:
+
+{% highlight javascript %}
+// for the async case need to put inside of done
+dataset.fetch().done(function() {
+  dataset.query({size: dataset.recordCount});
+});
+{% endhighlight %}
+</div>
+
+As a Backbone Collection it supports all the standard Backbone collection functionality including methods like `each` and `filter`:
+
+{% highlight javascript %}
+dataset.records.each(function(record) {
+  console.log(record.get('x') * 2);
+});
+
+var filtered = dataset.records.filter(function(record) {
+  return (record.get('z') > 4 && record.get('z') < 18);
+});
+
+// get all the values for a given attribute/field/column
+var xvalues = dataset.records.pluck('x');
+
+// calls toJSON on all records at once
+dataset.records.toJSON();
+{% endhighlight %}
+
+<div class="alert alert-info">Want to know more about Dataset and Records? Check out the <a href="models.html">reference documentation</a></div>
+
+## 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.
 
@@ -100,7 +131,11 @@ $('.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):
+As can be seen all fields have the default type of 'string'.
+
+As you may have noticed above the last geo attribute of the dataset 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.
+
+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 %}
@@ -113,5 +148,5 @@ $('.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>).
+As can be seen the rendering of the field has changed. This is because the `summary` 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>).