Preparations

  1. Download ReclineJS and relevant dependencies.

  2. Include the core dependencies for the Dataset model

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

Creating a Dataset

Here’s the example data We are going to work with:

var data = [
  {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}}
];

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:

var dataset = new recline.Model.Dataset({
  records: data
});

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 using some of the key Dataset attributes: recordCount and records.

// (for convenience) assume availability of jquery
// must have div with class="ex-1"
var $el = $('.ex-1');

// total number of records resulting from latest query
$el.append('Total found: ' + dataset.recordCount + '<br />');
$el.append('Total returned: ' + dataset.records.length);

$el.append('<hr />');

// get 2nd record in list (note collection indexes off 0!)
// this is an instance of a Record object
var record = dataset.records.at(1);

// if records have an id you can get by id too ...
// var record = dataset.records.get(record-id);

// To get record attribute we use 'get'
var recdate = record.get('date');

$el.append('Date is: ' + recdate);
$el.append('<hr />');

// We can also convert the Record back to simple JS object
var simple = record.toJSON();

$el.append('<h4>Record as simple object</h4>');
$el.append('<pre>' + JSON.stringify(simple, null, 2) + '</pre>');

Here’s the output:

 

Records

Dataset.records is a Backbone Collection of Records 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.

Note that on initialization, a Dataset automatically queries for the first 100 records so this is what will usually be available in th records attribute. If you did want all records loaded into records at the start just requery after fetch has completed:
// for the async case need to put inside of done
dataset.fetch().done(function() {
  dataset.query({size: dataset.recordCount});
});

As a Backbone Collection it supports all the standard Backbone collection functionality including methods like each and filter:

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();
Want to know more about Dataset and Records? Check out the reference documentation

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:

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

Running this results in the following:

 

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):

var $el = $('.ex-fields-2');

dataset.fields.models[6] = new recline.Model.Field({
  id: 'geo',
  label: 'Location',
  type: 'geo_point'
});
var rec = dataset.records.at(0);
$el.append(record.summary());
 

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 Field documentation).