# DataView documentation

## Contents

- Overview
- Example
- Construction
- Getting Data
- Subscriptions
- Data Policy

## Overview

A DataView offers a filtered and/or formatted view on a DataSet. One can subscribe on changes in a DataView, and easily get filtered or formatted data without having to specify filters and field types all the time.

## Example

The following example shows how to use a DataView.

    // create a DataSet
    var data = new vis.DataSet();
    data.add([
      {id: 1, text: 'item 1', date: new Date(2013, 6, 20), group: 1, first: true},
      {id: 2, text: 'item 2', date: '2013-06-23', group: 2},
      {id: 3, text: 'item 3', date: '2013-06-25', group: 2},
      {id: 4, text: 'item 4'}
    ]);

    // create a DataView
    // the view will only contain items having a property group with value 1,
    // and will only output fields id, text, and date.
    var view = new vis.DataView(data, {
      filter: function (item) {
        return (item.group == 1);
      },
      fields: ['id', 'text', 'date']
    });

    // subscribe to any change in the DataView
    view.on('*', function (event, properties, senderId) {
      console.log('event', event, properties);
    });

    // update an item in the data set
    data.update({id: 2, group: 1});

    // get all ids in the view
    var ids = view.getIds();
    console.log('ids', ids); // will output [1, 2]

    // get all items in the view
    var items = view.get();

## Construction

A DataView can be constructed as:

    var data = new vis.DataView(dataset, options)

where:

- `dataset` is a DataSet or DataView.
- `options` is an object which can contain the following properties. Note that these properties are exactly the same as the properties available in methods `DataSet.get` and `DataView.get`.

  Name | Type | Description
  --- | --- | ---
  convert | Object.<String, String> | An object containing field names as key, and data types as value. By default, the type of the properties of an item are left unchanged. When a field type is specified, this field in the items will be converted to the specified type. This can be used for example to convert ISO strings containing a date to a JavaScript Date object, or convert strings to numbers or vice versa. The available data types are listed in section Data Types.
  fields | String[ ] | An array with field names. By default, all properties of the items are emitted. When `fields` is defined, only the properties whose name is specified in `fields` will be included in the returned items.
  filter | function | Items can be filtered on specific properties by providing a filter function. A filter function is executed for each of the items in the DataSet, and is called with the item as parameter. The function must return a boolean. All items for which the filter function returns true will be emitted. See also section Data Filtering.

## Getting Data

Data of the DataView can be retrieved using the method `get`.

    var items = view.get();

Data of a DataView can be filtered and formatted again, in exactly the same way as in a DataSet. See sections Data Filtering and Data Formatting for more information.

    var items = view.get({
      fields: ['id', 'score'],
      filter: function (item) {
        return (item.score > 50);
      }
    });

## Subscriptions

One can subscribe on changes in the DataView. Subscription works exactly the same as for DataSets. See the documentation on subscriptions in a DataSet for more information.

    // create a DataSet and a view on the data set
    var data = new vis.DataSet();
    var view = new vis.DataView({
      filter: function (item) {
        return (item.group == 2);
      }
    });

    // subscribe to any change in the DataView
    view.on('*', function (event, properties, senderId) {
      console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
    });

    // add, update, and remove data in the DataSet...

## Data Policy

All code and data is processed and rendered in the browser. No data is sent to any server.