[#113,docs/tutorial][l]: tutorial-basics written giving introduction to dataset and associated functionality.

* Minor corrections to several other parts of docs.

_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}}
 ];
 

_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);
+  }
 });
 

_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);
+

_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);
+});
+

_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);
+

_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));
+

_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)
+    )
+);
+