# DataView documentation

## Contents

- Overview
- Example
- Construction
- Methods
- Properties
- 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.

## Methods

DataView contains the following methods.

Method | Return Type | Description
--- | --- | ---
get([options] [, data]) get(id [,options] [, data]) get(ids [, options] [, data]) | Object | Array | DataTable | Get a single item, multiple items, or all items from the DataView. Usage examples can be found in section Getting Data, and the available `options` are described in section Data Selection. If parameter `data` is provided, items will be appended to this array or table, which is required in case of Google DataTable.
getDataSet() | DataSet | Get the DataSet to which the DataView is connected.
getIds([options]) | Number[] | Get ids of all items or of a filtered set of items. Available `options` are described in section Data Selection, except that options `fields` and `type` are not applicable in case of `getIds`.
off(event, callback) | none | Unsubscribe from an event, remove an event listener. See section Subscriptions.
on(event, callback) | none | Subscribe to an event, add an event listener. See section Subscriptions.
refresh() | none | Refresh the filter results of a DataView. Useful when the filter function contains dynamic properties, like:
    var data = new vis.DataSet(...);
    var view = new vis.DataView(data, {
      filter: function (item) {
        return item.value > threshold;
      }
    });
In this example, `threshold` is an external parameter. When the value of `threshold` changes, the DataView must be notified that the filter results may have changed by calling `DataView.refresh()`.
setDataSet(data) | none | Replace the DataSet of the DataView. Parameter `data` can be a DataSet or a DataView.

## Properties

DataView contains the following properties.

Property | Type | Description
--- | --- | ---
length | Number | The number of items in the DataView.

## 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 Manipulation and Data Selection 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.