From 0e50e99c5981a6968001c86d1c34916d2ded9f45 Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 29 Jun 2012 15:41:10 +0100 Subject: [PATCH 01/10] [be/dataproxy][xs]: dataproxy timeout is now configurable (defaults to 5s). --- src/backend.dataproxy.js | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/backend.dataproxy.js b/src/backend.dataproxy.js index ac3eeab3..58f537d7 100644 --- a/src/backend.dataproxy.js +++ b/src/backend.dataproxy.js @@ -6,6 +6,9 @@ this.recline.Backend.DataProxy = this.recline.Backend.DataProxy || {}; my.__type__ = 'dataproxy'; // URL for the dataproxy my.dataproxy_url = 'http://jsonpdataproxy.appspot.com'; + // Timeout for dataproxy (after this time if no response we error) + // Needed because use JSONP so do not receive e.g. 500 errors + my.timeout = 5000; // ## load // @@ -48,12 +51,11 @@ this.recline.Backend.DataProxy = this.recline.Backend.DataProxy || {}; // a crude way to catch those errors. var _wrapInTimeout = function(ourFunction) { var dfd = $.Deferred(); - var timeout = 5000; var timer = setTimeout(function() { dfd.reject({ - message: 'Request Error: Backend did not respond after ' + (timeout / 1000) + ' seconds' + message: 'Request Error: Backend did not respond after ' + (my.timeout / 1000) + ' seconds' }); - }, timeout); + }, my.timeout); ourFunction.done(function(arguments) { clearTimeout(timer); dfd.resolve(arguments); From 12f6afebc90f9b54f5fe2e916b3ff7f6d1842523 Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 29 Jun 2012 15:49:43 +0100 Subject: [PATCH 02/10] [#168,docs/backend][s]: bring backend example up to date. --- docs/backends.markdown | 8 ++++++++ example-backends.markdown | 15 +++++---------- 2 files changed, 13 insertions(+), 10 deletions(-) diff --git a/docs/backends.markdown b/docs/backends.markdown index a7af4a04..72e22069 100644 --- a/docs/backends.markdown +++ b/docs/backends.markdown @@ -11,11 +11,19 @@ root: ../ +Backends connect Dataset and Documents to data from a specific 'Backend' data +source. They provide methods for loading and saving Datasets and individuals +Documents as well as for bulk loading via a query API and doing bulk transforms +on the backend. + Backends come in 2 flavours: 1. Loader backends - only implement fetch method. The data is then cached in a Memory.Store on the Dataset and interacted with there. This is best for sources which just allow you to load data or where you want to load the data once and work with it locally. 2. Store backends - these support fetch, query and, if write-enabled, save. These are suitable where the backend contains a lot of data (infeasible to load locally - for examples a million rows) or where the backend has capabilities you want to take advantage of. + +# Backend API + Backend modules must implement the following API: {% highlight javascript %} diff --git a/example-backends.markdown b/example-backends.markdown index 918156ba..cf754c1c 100644 --- a/example-backends.markdown +++ b/example-backends.markdown @@ -30,20 +30,18 @@ source. They provide methods for loading and saving Datasets and individuals Documents as well as for bulk loading via a query API and doing bulk transforms on the backend. -You can instantiate a backend directly e.g. +You can use a backend directly e.g. {% highlight javascript %} -var backend = recline.Backend.ElasticSearch(); +var backend = recline.Backend.ElasticSearch.fetch({url: ...}); {% endhighlight %} But more usually the backend will be created or loaded for you by Recline and all you need is provide the identifier for that Backend e.g. {% highlight javascript %} var dataset = recline.Model.Dataset({ - ... - }, - 'backend-identifier' -); + backend: 'backend-identifier' +}); {% endhighlight %}
@@ -53,7 +51,6 @@ How do you know the backend identifier for a given Backend? It's just the name o ### Included Backends -* [memory: Memory Backend (local data)](docs/backend/memory.html) * [elasticsearch: ElasticSearch Backend](docs/backend/elasticsearch.html) * [dataproxy: DataProxy Backend (CSV and XLS on the Web)](docs/backend/dataproxy.html) * [gdocs: Google Docs (Spreadsheet) Backend](docs/backend/gdocs.html) @@ -71,8 +68,6 @@ This is as per the [quickstart](example-quickstart.html) but the set of files is - - @@ -110,5 +105,5 @@ a bespoke chooser and a Kartograph (svg-only) map. ## Writing your own backend Writing your own backend is easy to do. Details of the required API are in the -[Backend documentation](docs/backend/base.html). +[Backend documentation](docs/backends.html). From 889fb6afb130618202bef4c78137433d25629a14 Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 29 Jun 2012 16:40:22 +0100 Subject: [PATCH 03/10] [docs,refactor][s]: move examples to being tutorials in the docs directory. --- docs/index.html | 4 ++-- example-backends.markdown => docs/tutorial-backends.markdown | 1 + example-quickstart.markdown => docs/tutorial-views.markdown | 5 +++-- 3 files changed, 6 insertions(+), 4 deletions(-) rename example-backends.markdown => docs/tutorial-backends.markdown (99%) rename example-quickstart.markdown => docs/tutorial-views.markdown (96%) diff --git a/docs/index.html b/docs/index.html index caadbff8..7f7f7ece 100644 --- a/docs/index.html +++ b/docs/index.html @@ -52,12 +52,12 @@ root: ../
-

Recline Quickstart Guide

+

Views Quickstart - Grids, Graphs, Maps and more

-

Loading from difference sources: Google Docs, Local CSV, DataHub

+

Loading from difference sources: Google Docs, Local CSV, DataHub

diff --git a/example-backends.markdown b/docs/tutorial-backends.markdown similarity index 99% rename from example-backends.markdown rename to docs/tutorial-backends.markdown index cf754c1c..189970dd 100644 --- a/example-backends.markdown +++ b/docs/tutorial-backends.markdown @@ -2,6 +2,7 @@ layout: container title: Library - Example - Loading data from different sources using Backends recline-deps: true +root: ../ ---
diff --git a/example-quickstart.markdown b/docs/tutorial-views.markdown similarity index 96% rename from example-quickstart.markdown rename to docs/tutorial-views.markdown index 2e470e50..88fbf561 100644 --- a/example-quickstart.markdown +++ b/docs/tutorial-views.markdown @@ -2,13 +2,14 @@ layout: container title: Library - Example - Quickstart recline-deps: true +root: ../ ---

- Recline Quickstart Guide + Views Tutorial
- This step-by-step guide will quickly get you started with Recline basics, including creating a dataset from local data and setting up a grid, graph and map to display it. + This step-by-step tutorial will quickly get you started with Recline basics, including creating a dataset from local data and setting up a grid, graph and map to display it.

From d3c9f30e74fd1c33402320ac05a1e2cece28964a Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 29 Jun 2012 20:27:01 +0100 Subject: [PATCH 04/10] [view/slickgrid][xs]: set recline-slickgrid on view element so that we can pass element in to the view (neede for non-multiview usage e.g. in tutorial). --- src/view.slickgrid.js | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/view.slickgrid.js b/src/view.slickgrid.js index 0c506760..556ddf6f 100644 --- a/src/view.slickgrid.js +++ b/src/view.slickgrid.js @@ -11,6 +11,8 @@ this.recline.View = this.recline.View || {}; // https://github.com/mleibman/SlickGrid // // Initialize it with a `recline.Model.Dataset`. +// +// NB: you need an explicit height on the element for slickgrid to work my.SlickGrid = Backbone.View.extend({ tagName: "div", className: "recline-slickgrid", @@ -18,6 +20,7 @@ my.SlickGrid = Backbone.View.extend({ initialize: function(modelEtc) { var self = this; this.el = $(this.el); + this.el.addClass('recline-slickgrid'); _.bindAll(this, 'render'); this.model.currentRecords.bind('add', this.render); this.model.currentRecords.bind('reset', this.render); @@ -56,7 +59,6 @@ my.SlickGrid = Backbone.View.extend({ render: function() { var self = this; - this.el = $(this.el); var options = { enableCellNavigation: true, From 19f14c950708aa50b71600d19f40a0b2c0c1056b Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 29 Jun 2012 20:29:10 +0100 Subject: [PATCH 05/10] [tutorial/views][s]: bring the tutorial up to date and switch to slickgrid for the grid. --- docs/tutorial-views.markdown | 107 ++++++++++++++++------------------- 1 file changed, 50 insertions(+), 57 deletions(-) diff --git a/docs/tutorial-views.markdown b/docs/tutorial-views.markdown index 88fbf561..750bb065 100644 --- a/docs/tutorial-views.markdown +++ b/docs/tutorial-views.markdown @@ -40,10 +40,6 @@ Before writing any code with Recline, you need to do the following preparation s --> {% endhighlight %} -4. Create a div to hold the Recline view(s): - {% highlight html %} -
{% endhighlight %} - You're now ready to start working with Recline. ### Creating a Dataset @@ -61,37 +57,62 @@ no reason you cannot have objects as values allowing you to nest data. We can now create a recline Dataset object (and memory backend) from this raw data: {% highlight javascript %} -var dataset = recline.Backend.Memory.createDataset(data); +var dataset = new recline.Model.Dataset({ + records: data +}); {% endhighlight %} -Note that behind the scenes Recline will create a Memory backend for this dataset as in Recline every dataset object must have a backend from which it can push and pull data. In the case of in-memory data this is a little artificial since all the data is available locally but this makes more sense for situations where one is connecting to a remote data source (and one which may contain a lot of data). - ### Setting up the Grid -Let's create a data grid view to display the dataset we have just created, binding the view to the `
` we created earlier: + +Let's create a data grid view to display the dataset we have just created. We're going to use the SlickGrid-based grid so we need the following: + +{% highlight html %} + + + + + + + + + +{% endhighlight %} + +Now, let's create an HTML element to for the Grid: + +{% highlight html %} +
+{% endhighlight %} + +Now let's set up the Grid: {% highlight javascript %} var $el = $('#mygrid'); -var grid = new recline.View.Grid({ - model: dataset +var grid = new recline.View.SlickGrid({ + model: dataset, + el: $el }); -$el.append(grid.el); +grid.visible = true; grid.render(); {% endhighlight %} And hey presto: -
 
+
 
@@ -107,7 +128,7 @@ library and the Recline Graph view: - + {% endhighlight %} Next, create a new div for the graph: @@ -116,35 +137,15 @@ Next, create a new div for the graph:
{% endhighlight %} -Now let's create the graph, we will use the same dataset we had earlier: +Now let's create the graph, we will use the same dataset we had earlier, and we will need to set the view 'state' in order to configure the graph with the column to use for the x-axis ("group") and the columns to use for the series to show ("series"). -{% highlight javascript %} -var $el = $('#mygraph'); -var graph = new recline.View.Graph({ - model: dataset -}); -$el.append(grid.el); -graph.render(); -{% endhighlight %} - -And ... we have a graph view -- with instructions on how to use the controls to -create a graph -- but no graph. Go ahead and play around with the controls to -create a graph of your choosing: - -
 
- - - -But suppose you wanted to create a graph not a graph editor. This is -straightforward to do -- all we need to do is set the 'state' of the graph -view: +
+State: The concept of a state is a common feature of Recline views being an object +which stores information about the state and configuration of a given view. You +can read more about it in the general Views +documentation as well as the documentation of individual views such as the +Graph View. +
{% highlight javascript %} var $el = $('#mygraph'); @@ -159,12 +160,12 @@ $el.append(graph.el); graph.redraw(); {% endhighlight %} -We would get this rendered graph: +The result is the following graph: -
 
+
 
-
-State: The concept of a state is a common feature of Recline views being an object -which stores information about the state and configuration of a given view. You -can read more about it in the general Views -documentation as well as the documentation of individual views such as the -Graph View. -
- ### Creating a Map Now, let's create a map of this dataset using the lon/lat information which is From f06b9ad1b1c6ebe007276179123178aadac38d7a Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Fri, 29 Jun 2012 20:40:15 +0100 Subject: [PATCH 06/10] [field][xs]: formatter for geo_point type (like an object). --- src/model.js | 3 +++ test/model.test.js | 8 +++++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/src/model.js b/src/model.js index 50721278..630a38ba 100644 --- a/src/model.js +++ b/src/model.js @@ -404,6 +404,9 @@ my.Field = Backbone.Model.extend({ object: function(val, field, doc) { return JSON.stringify(val); }, + geo_point: function(val, field, doc) { + return JSON.stringify(val); + }, 'float': function(val, field, doc) { var format = field.get('format'); if (format === 'percentage') { diff --git a/test/model.test.js b/test/model.test.js index 9300c274..0740c1b4 100644 --- a/test/model.test.js +++ b/test/model.test.js @@ -44,13 +44,19 @@ test('Field: default renderers', function () { myobject: {a: 1, b: 2}, link: 'http://abc.com/', link2: 'Some text then https://abc.com/', - markdown: '### ABC' + markdown: '### ABC', + geopoint: [18.7, -122] }); var field = new recline.Model.Field({id: 'myobject', type: 'object'}); var out = doc.getFieldValue(field); var exp = '{"a":1,"b":2}'; equal(out, exp); + var field = new recline.Model.Field({id: 'geopoint', type: 'geo_point'}); + var out = doc.getFieldValue(field); + var exp = '[18.7,-122]'; + equal(out, exp); + var field = new recline.Model.Field({id: 'x', type: 'float', format: 'percentage'}); var out = doc.getFieldValue(field); var exp = '12.3%'; From b9555cce6a7c3eb4942e0131baaa5329904606b1 Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Sun, 1 Jul 2012 09:01:21 +0100 Subject: [PATCH 07/10] [refactor][xs]: rename docCount to recordCount. --- src/model.js | 6 +++--- src/view.multiview.js | 4 ++-- test/backend.dataproxy.test.js | 4 ++-- test/backend.elasticsearch.test.js | 2 +- test/backend.memory.test.js | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/model.js b/src/model.js index 630a38ba..495020a9 100644 --- a/src/model.js +++ b/src/model.js @@ -27,7 +27,7 @@ my.Dataset = Backbone.Model.extend({ creates: [] }; this.facets = new my.FacetList(); - this.docCount = null; + this.recordCount = null; this.queryState = new my.Query(); this.queryState.bind('change', this.query); this.queryState.bind('facet:add', this.query); @@ -197,7 +197,7 @@ my.Dataset = Backbone.Model.extend({ _handleQueryResult: function(queryResult) { var self = this; - self.docCount = queryResult.total; + self.recordCount = queryResult.total; var docs = _.map(queryResult.hits, function(hit) { var _doc = new my.Record(hit); _doc.bind('change', function(doc) { @@ -220,7 +220,7 @@ my.Dataset = Backbone.Model.extend({ toTemplateJSON: function() { var data = this.toJSON(); - data.docCount = this.docCount; + data.recordCount = this.recordCount; data.fields = this.fields.toJSON(); return data; }, diff --git a/src/view.multiview.js b/src/view.multiview.js index ccadc046..3168689b 100644 --- a/src/view.multiview.js +++ b/src/view.multiview.js @@ -83,7 +83,7 @@ my.MultiView = Backbone.View.extend({
\
\
\ - {{docCount}} records\ + {{recordCount}} records\
\
\
\ @@ -166,7 +166,7 @@ my.MultiView = Backbone.View.extend({ }); this.model.bind('query:done', function() { self.clearNotifications(); - self.el.find('.doc-count').text(self.model.docCount || 'Unknown'); + self.el.find('.doc-count').text(self.model.recordCount || 'Unknown'); }); this.model.bind('query:fail', function(error) { self.clearNotifications(); diff --git a/test/backend.dataproxy.test.js b/test/backend.dataproxy.test.js index 2c873ab1..d9ed4131 100644 --- a/test/backend.dataproxy.test.js +++ b/test/backend.dataproxy.test.js @@ -94,14 +94,14 @@ test('DataProxy Backend', function() { expect(6); dataset.fetch().then(function() { deepEqual(['__id__', 'date', 'price'], _.pluck(dataset.fields.toJSON(), 'id')); - equal(10, dataset.docCount) + equal(10, dataset.recordCount) equal(dataset.currentRecords.models[0].get('date'), "1950-01"); // needed only if not stubbing // start(); }); dataset.query({q: '1950-01'}).then(function() { - equal(dataset.docCount, 1); + equal(dataset.recordCount, 1); equal(dataset.currentRecords.models[0].get('price'), '34.73'); }); $.ajax.restore(); diff --git a/test/backend.elasticsearch.test.js b/test/backend.elasticsearch.test.js index a4434961..c9a9d027 100644 --- a/test/backend.elasticsearch.test.js +++ b/test/backend.elasticsearch.test.js @@ -280,7 +280,7 @@ test("query", function() { dataset.fetch().done(function(dataset) { deepEqual(['_created', '_last_modified', 'end', 'owner', 'start', 'title'], _.pluck(dataset.fields.toJSON(), 'id')); dataset.query().then(function(recList) { - equal(3, dataset.docCount); + equal(3, dataset.recordCount); equal(3, recList.length); equal('Note 1', recList.models[0].get('title')); start(); diff --git a/test/backend.memory.test.js b/test/backend.memory.test.js index 81ec8f80..abeb6273 100644 --- a/test/backend.memory.test.js +++ b/test/backend.memory.test.js @@ -178,7 +178,7 @@ test('basics', function () { dataset.fetch().then(function(datasetAgain) { equal(dataset.get('name'), memoryData.metadata.name); deepEqual(_.pluck(dataset.fields.toJSON(), 'id'), _.pluck(data.fields, 'id')); - equal(dataset.docCount, 6); + equal(dataset.recordCount, 6); }); }); From 568eb1e0341a422834d00327321912d1b6631aab Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Sun, 1 Jul 2012 13:54:00 +0100 Subject: [PATCH 08/10] [model,bugfix][xs]: prevent query function triggering a second query by using silent: true when setting queryState. --- src/model.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/model.js b/src/model.js index 495020a9..9453ce5c 100644 --- a/src/model.js +++ b/src/model.js @@ -178,7 +178,7 @@ my.Dataset = Backbone.Model.extend({ this.trigger('query:start'); if (queryObj) { - this.queryState.set(queryObj); + this.queryState.set(queryObj, {silent: true}); } var actualQuery = this.queryState.toJSON(); From a8b8c1a59a842cc2c8e6c6aec98082080a9ef14f Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Sun, 1 Jul 2012 14:26:53 +0100 Subject: [PATCH 09/10] [view/map][xs]: additional name for geo column ('geo', 'lonlat'). --- src/view.map.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/view.map.js b/src/view.map.js index daa27f96..143a935f 100644 --- a/src/view.map.js +++ b/src/view.map.js @@ -35,7 +35,7 @@ my.Map = Backbone.View.extend({ // If not found, the user will need to define the fields via the editor. latitudeFieldNames: ['lat','latitude'], longitudeFieldNames: ['lon','longitude'], - geometryFieldNames: ['geojson', 'geom','the_geom','geometry','spatial','location'], + geometryFieldNames: ['geojson', 'geom','the_geom','geometry','spatial','location', 'geo', 'lonlat'], initialize: function(options) { var self = this; From 1dadc1106bd2dbcad4580d3889e15ac44c865f80 Mon Sep 17 00:00:00 2001 From: Rufus Pollock Date: Sun, 1 Jul 2012 15:40:04 +0100 Subject: [PATCH 10/10] [#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 | 12 +- _includes/example-backends-gdocs.js | 21 +-- _includes/tutorial-basics-ex-1.js | 24 ++++ _includes/tutorial-basics-ex-2.js | 13 ++ _includes/tutorial-basics-ex-events.js | 13 ++ _includes/tutorial-basics-ex-fields-2.js | 10 ++ _includes/tutorial-basics-ex-fields.js | 20 +++ docs/index.html | 56 ++------ docs/models.markdown | 3 +- docs/tutorial-backends.markdown | 17 +-- docs/tutorial-basics.markdown | 170 +++++++++++++++++++++++ docs/tutorial-views.markdown | 3 +- download.markdown | 7 +- src/model.js | 25 ++-- 14 files changed, 301 insertions(+), 93 deletions(-) create mode 100644 _includes/tutorial-basics-ex-1.js create mode 100644 _includes/tutorial-basics-ex-2.js create mode 100644 _includes/tutorial-basics-ex-events.js create mode 100644 _includes/tutorial-basics-ex-fields-2.js create mode 100644 _includes/tutorial-basics-ex-fields.js create mode 100644 docs/tutorial-basics.markdown diff --git a/_includes/data.js b/_includes/data.js index 44015ffd..57065512 100644 --- a/_includes/data.js +++ b/_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}} ]; diff --git a/_includes/example-backends-gdocs.js b/_includes/example-backends-gdocs.js index 72fa38fd..555d6a2c 100644 --- a/_includes/example-backends-gdocs.js +++ b/_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); + } }); diff --git a/_includes/tutorial-basics-ex-1.js b/_includes/tutorial-basics-ex-1.js new file mode 100644 index 00000000..067a1f1b --- /dev/null +++ b/_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 + '
'); + $el.append('Total returned: ' + dataset.currentRecords.length); + + $el.append('
'); + + // 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); + diff --git a/_includes/tutorial-basics-ex-2.js b/_includes/tutorial-basics-ex-2.js new file mode 100644 index 00000000..79b937ae --- /dev/null +++ b/_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); +}); + diff --git a/_includes/tutorial-basics-ex-events.js b/_includes/tutorial-basics-ex-events.js new file mode 100644 index 00000000..a9a78ebe --- /dev/null +++ b/_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('
'); +} + +dataset.currentRecords.bind('reset', onChange); + +dataset.query({q: 'DE'}); +dataset.query({q: 'UK'}); +dataset.query({q: 'US'}); + +dataset.unbind('reset', onChange); + diff --git a/_includes/tutorial-basics-ex-fields-2.js b/_includes/tutorial-basics-ex-fields-2.js new file mode 100644 index 00000000..0559abc8 --- /dev/null +++ b/_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)); + diff --git a/_includes/tutorial-basics-ex-fields.js b/_includes/tutorial-basics-ex-fields.js new file mode 100644 index 00000000..d6cc38eb --- /dev/null +++ b/_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('
'); + +// Show all field info +var json = dataset.fields.toJSON(); +$el.append( + $('
')
+    .append(
+      JSON.stringify(json, null, 2)
+    )
+);
+
diff --git a/docs/index.html b/docs/index.html
index 7f7f7ece..432e7b54 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -50,57 +50,21 @@ root: ../
   likely be useful in understanding the details of these tutorials.
+
+
+

Dataset Basics - Creating, Querying, Using

+
+
+
+
+

Backends and loading data from Google Docs, Local CSV, DataHub and more

+
+

Views Quickstart - Grids, Graphs, Maps and more

-
-
-

Loading from difference sources: Google Docs, Local CSV, DataHub

-
-
-
-
-

Twitter Example

-
-
-
-
-
-
-

Customing Display and Import using Fields

-
-
-
-
-

Listening to events

-
-
-
-
-

Setting and Getting State

-
-
-
- -

Extending Recline

-
-
-
-

Create a new View

-
-
-
-
-

Create a new Backend

-
-
-
-
-

Create a Custom Record Object

-
-
diff --git a/docs/models.markdown b/docs/models.markdown index 05ec1976..676dbcb2 100644 --- a/docs/models.markdown +++ b/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 +

Dataset

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. -

Query

Query instances encapsulate a query to the backend (see

Loading data from different sources using Backends +
+ These set of examples will show you how you can load data from different +sources such as Google Docs or the DataHub using Recline

-These set of examples will show you how you can load data from different -sources such as Google Docs or the DataHub using Recline.

Note: 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.

-

Moreover, Recline is designed so you need only include the -backend and its dependencies without needing to include any of the dependencies -for the view portion of the Recline library.

+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.

## 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 %} diff --git a/docs/tutorial-basics.markdown b/docs/tutorial-basics.markdown new file mode 100644 index 00000000..2705c814 --- /dev/null +++ b/docs/tutorial-basics.markdown @@ -0,0 +1,170 @@ +--- +layout: container +title: Tutorial - Dataset Basics +recline-deps: true +root: ../ +--- + +
+

+ Getting Started with Datasets +
+ This step-by-step tutorial will quickly get you started withthe central Recline object: a Dataset +

+
+ +## Preparations + +1. [Download ReclineJS]({{page.root}}download.html) and relevant dependencies. + +2. Include the core dependencies for the Dataset model + + {% highlight html %} + + + + +{% 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). + +
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 Backend tutorial for more.
+ +We can now create a recline Dataset object from this raw data: + +{% highlight javascript %} +var dataset = new recline.Model.Dataset({ + records: data +}); +{% endhighlight %} + + + +## 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: + +
You can find out more about Dataset and Records in the reference documentation
+ +{% highlight javascript %} +{% include tutorial-basics-ex-1.js %} +{% endhighlight %} + +Here's the output: + +
 
+ + + +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 Fields 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: + +
 
+ + + +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 %} + +
 
+ + + +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 Field documentation). + + +## 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. + +
 
+ + + +Full details of the query structure and its options can be found in the reference documentation. + +Also worth noting is that the last run query is stored as a Query instance 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, Query Editor or Filter Editor 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 %} + +
 
+ + + +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. + diff --git a/docs/tutorial-views.markdown b/docs/tutorial-views.markdown index 750bb065..7e22f018 100644 --- a/docs/tutorial-views.markdown +++ b/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 %} @@ -34,7 +34,6 @@ Before writing any code with Recline, you need to do the following preparation s diff --git a/download.markdown b/download.markdown index fd8d381c..412715b5 100644 --- a/download.markdown +++ b/download.markdown @@ -9,9 +9,10 @@ title: Download
-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.

Download Recline v0.5 (master) (in-progress version)

diff --git a/src/model.js b/src/model.js index 9453ce5c..1651559d 100644 --- a/src/model.js +++ b/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 += '
' + field.get('label') + ': ' + record.getFieldValue(field) + '
'; + } + }); + 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 += '
' + key + ': '+ this.attributes[key] + '
'; - } - } - 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)