You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
714 lines
17 KiB
714 lines
17 KiB
<!doctype html>
|
|
<html>
|
|
|
|
<head>
|
|
<title>vis.js | DataSet documentation</title>
|
|
|
|
<link href="css/prettify.css" type="text/css" rel="stylesheet" />
|
|
<link href='css/style.css' type='text/css' rel='stylesheet'>
|
|
|
|
<script type="text/javascript" src="lib/prettify/prettify.js"></script>
|
|
</head>
|
|
|
|
<body onload="prettyPrint();">
|
|
<div id="container">
|
|
|
|
<h1>DataSet documentation</h1>
|
|
|
|
<h2 id="Contents">Contents</h2>
|
|
<ul>
|
|
<li><a href="#Overview">Overview</a></li>
|
|
<li><a href="#Example">Example</a></li>
|
|
<li><a href="#Construction">Construction</a></li>
|
|
<li><a href="#Data_Manipulation">Data Manipulation</a></li>
|
|
<li><a href="#Data_Filtering">Data Filtering</a></li>
|
|
<li><a href="#Data_Formatting">Data Formatting</a></li>
|
|
<li><a href="#Subscriptions">Subscriptions</a></li>
|
|
<li><a href="#Data_Policy">Data Policy</a></li>
|
|
</ul>
|
|
|
|
|
|
<h2 id="Overview">Overview</h2>
|
|
|
|
<p>
|
|
Vis.js comes with a flexible DataSet, which can be used to hold and
|
|
manipulate unstructured data and listen for changes in the data.
|
|
The DataSet is key/value based. Data items can be added, updated and
|
|
removed from the DatSet, and one can subscribe to changes in the DataSet.
|
|
The data in the DataSet can be filtered and ordered, and fields (like
|
|
dates) can be converted to a specific type. Data can be normalized when
|
|
appending it to the DataSet as well.
|
|
</p>
|
|
|
|
|
|
<h2 id="Example">Example</h2>
|
|
|
|
<p>
|
|
The following example shows how to use a DataSet.
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
// create a DataSet
|
|
var options = {};
|
|
var data = new vis.DataSet(options);
|
|
|
|
// add items
|
|
// note that the data items can contain different properties and data formats
|
|
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'}
|
|
]);
|
|
|
|
// subscribe to any change in the DataSet
|
|
data.on('*', function (event, properties, senderId) {
|
|
console.log('event', event, properties);
|
|
});
|
|
|
|
// update an existing item
|
|
data.update({id: 2, group: 1});
|
|
|
|
// remove an item
|
|
data.remove(4);
|
|
|
|
// get all ids
|
|
var ids = data.getIds();
|
|
console.log('ids', ids);
|
|
|
|
// get a specific item
|
|
var item1 = data.get(1);
|
|
console.log('item1', item1);
|
|
|
|
// retrieve a filtered subset of the data
|
|
var items = data.get({
|
|
filter: function (item) {
|
|
return item.group == 1;
|
|
}
|
|
});
|
|
console.log('filtered items', items);
|
|
|
|
// retrieve formatted items
|
|
var items = data.get({
|
|
fields: ['id', 'date'],
|
|
convert: {
|
|
date: 'ISODate'
|
|
}
|
|
});
|
|
console.log('formatted items', items);
|
|
</pre>
|
|
|
|
|
|
|
|
<h2 id="Construction">Construction</h2>
|
|
|
|
<p>
|
|
A DataSet can be constructed as:
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
var data = new vis.DataSet([data] [, options])
|
|
</pre>
|
|
|
|
<p>
|
|
After construction, data can be added to the DataSet using the methods
|
|
<code>add</code> and <code>update</code>, as described in section
|
|
<a href="#Data_Manipulation">Data Manipulation</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The parameter <code>data</code>code> is optional and can be an Array or
|
|
Google DataTable with items.
|
|
</p>
|
|
|
|
<p>
|
|
The parameter <code>options</code> is optional and is an object which can
|
|
contain the following properties:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Default value</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>fieldId</td>
|
|
<td>String</td>
|
|
<td>"id"</td>
|
|
<td>
|
|
The name of the field containing the id of the items.
|
|
|
|
When data is fetched from a server which uses some specific
|
|
field to identify items, this field name can be specified
|
|
in the DataSet using the option <code>fieldId</code>.
|
|
For example <a href="http://couchdb.apache.org/"
|
|
target="_blank">CouchDB</a> uses the field
|
|
<code>"_id"</code> to identify documents.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>convert</td>
|
|
<td>Object.<String, String></td>
|
|
<td>none</td>
|
|
<td>
|
|
An object containing field names as key, and data types as
|
|
value. By default, the type of the properties of items are left
|
|
unchanged. Item properties can be normalized by specifying a
|
|
field type. This is useful for example to automatically convert
|
|
stringified dates coming from a server into JavaScript Date
|
|
objects. The available data types are listed in section
|
|
<a href="#Data_Types">Data Types</a>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h2 id="Data_Manipulation">Data Manipulation</h2>
|
|
|
|
<p>
|
|
The data in a DataSet can be manipulated using the methods
|
|
<a href="#Add"><code>add</code></a>,
|
|
<a href="#Update"><code>update</code></a>,
|
|
and <a href="#Remove"><code>remove</code></a>.
|
|
The DataSet can be emptied using the method
|
|
<a href="#Clear"><code>clear</code></a>.
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
// create a DataSet
|
|
var data = new vis.DataSet();
|
|
|
|
// add items
|
|
data.add([
|
|
{id: 1, text: 'item 1'},
|
|
{id: 2, text: 'item 2'},
|
|
{id: 3, text: 'item 3'}
|
|
]);
|
|
|
|
// update an item
|
|
data.update({id: 2, text: 'item 2 (updated)'});
|
|
|
|
// remove an item
|
|
data.remove(3);
|
|
</pre>
|
|
|
|
<h3 id="Add">Add</h3>
|
|
|
|
<p>
|
|
Add a data item or an array with items.
|
|
</p>
|
|
|
|
Syntax:
|
|
<pre class="prettyprint lang-js">var addedIds = DataSet.add(data [, senderId])</pre>
|
|
|
|
The argument <code>data</code> can contain:
|
|
<ul>
|
|
<li>
|
|
An <code>Object</code> containing a single item to be
|
|
added. The item must contain an id.
|
|
</li>
|
|
<li>
|
|
An <code>Array</code> or
|
|
<code>google.visualization.DataTable</code> containing
|
|
a list with items to be added. Each item must contain
|
|
an id.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
After the items are added to the DataSet, the DataSet will
|
|
trigger an event <code>add</code>. When a <code>senderId</code>
|
|
is provided, this id will be passed with the triggered
|
|
event to all subscribers.
|
|
</p>
|
|
|
|
<p>
|
|
The method will throw an Error when an item with the same id
|
|
as any of the added items already exists.
|
|
</p>
|
|
|
|
<h3 id="Update">Update</h3>
|
|
|
|
<p>
|
|
Update a data item or an array with items.
|
|
</p>
|
|
|
|
Syntax:
|
|
<pre class="prettyprint lang-js">var updatedIds = DataSet.update(data [, senderId])</pre>
|
|
|
|
The argument <code>data</code> can contain:
|
|
<ul>
|
|
<li>
|
|
An <code>Object</code> containing a single item to be
|
|
updated. The item must contain an id.
|
|
</li>
|
|
<li>
|
|
An <code>Array</code> or
|
|
<code>google.visualization.DataTable</code> containing
|
|
a list with items to be updated. Each item must contain
|
|
an id.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The provided properties will be merged in the existing item.
|
|
When an item does not exist, it will be created.
|
|
</p>
|
|
|
|
<p>
|
|
After the items are updated, the DataSet will
|
|
trigger an event <code>add</code> for the added items, and
|
|
an event <code>update</code>. When a <code>senderId</code>
|
|
is provided, this id will be passed with the triggered
|
|
event to all subscribers.
|
|
</p>
|
|
|
|
<h3 id="Remove">Remove</h3>
|
|
|
|
<p>
|
|
Remove a data item or an array with items.
|
|
</p>
|
|
|
|
Syntax:
|
|
<pre class="prettyprint lang-js">var removedIds = DataSet.remove(id [, senderId])</pre>
|
|
|
|
<p>
|
|
The argument <code>id</code> can be:
|
|
</p>
|
|
<ul>
|
|
<li>
|
|
A <code>Number</code> or <code>String</code> containing the id
|
|
of a single item to be removed.
|
|
</li>
|
|
<li>
|
|
An <code>Object</code> containing the item to be deleted.
|
|
The item will be deleted by its id.
|
|
</li>
|
|
<li>
|
|
An Array containing ids or items to be removed.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
The method ignores removal of non-existing items, and returns an array
|
|
containing the ids of the items which are actually removed from the
|
|
DataSet.
|
|
</p>
|
|
|
|
<p>
|
|
After the items are removed, the DataSet will
|
|
trigger an event <code>remove</code> for the removed items.
|
|
When a <code>senderId</code> is provided, this id will be passed with
|
|
the triggered event to all subscribers.
|
|
</p>
|
|
|
|
|
|
<h3 id="Clear">Clear</h3>
|
|
|
|
<p>
|
|
Clear the complete DataSet.
|
|
</p>
|
|
|
|
Syntax:
|
|
<pre class="prettyprint lang-js">var removedIds = DataSet.clear([senderId])</pre>
|
|
|
|
<p>
|
|
After the items are removed, the DataSet will
|
|
trigger an event <code>remove</code> for all removed items.
|
|
When a <code>senderId</code> is provided, this id will be passed with
|
|
the triggered event to all subscribers.
|
|
</p>
|
|
|
|
|
|
<h2 id="Data_Filtering">Data Filtering</h2>
|
|
|
|
<p>
|
|
Data can be retrieved from the DataSet using the method <code>get</code>.
|
|
This method can return a single item or a list with items.
|
|
</p>
|
|
|
|
<p>A single item can be retrieved by its id:</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
var item1 = dataset.get(1);
|
|
</pre>
|
|
|
|
<p>A selection of items can be retrieved by providing an array with ids:</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
var items = dataset.get([1, 3, 4]); // retrieve items 1, 3, and 4
|
|
</pre>
|
|
|
|
<p>All items can be retrieved by simply calling <code>get</code> without
|
|
specifying an id:</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
var items = dataset.get(); // retrieve all items
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
// retrieve all items having a property group with value 2
|
|
var group2 = dataset.get({
|
|
filter: function (item) {
|
|
return (item.group == 2);
|
|
}
|
|
});
|
|
|
|
// retrieve all items having a property balance with a value above zero
|
|
var positiveBalance = dataset.get({
|
|
filter: function (item) {
|
|
return (item.balance > 0);
|
|
}
|
|
});
|
|
|
|
</pre>
|
|
|
|
|
|
<h2 id="Data_Formatting">Data Formatting</h2>
|
|
|
|
<p>
|
|
The DataSet contains functionality to format data retrieved via the
|
|
method <code>get</code>. The method <code>get</code> has the following
|
|
syntax:
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
var item = DataSet.get(id, options); // retrieve a single item
|
|
var items = DataSet.get(ids, options); // retrieve a selection of items
|
|
var items = DataSet.get(options); // retrieve all items or a filtered set
|
|
</pre>
|
|
|
|
<p>
|
|
Where <code>options</code> is an Object which can have the following
|
|
properties:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>fields</td>
|
|
<td>String[ ]</td>
|
|
<td>
|
|
An array with field names.
|
|
By default, all properties of the items are emitted.
|
|
When <code>fields</code> is defined, only the properties
|
|
whose name is specified in <code>fields</code> will be included
|
|
in the returned items.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>convert</td>
|
|
<td>Object.<String, String></td>
|
|
<td>
|
|
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
|
|
<a href="#Data_Types">Data Types</a>.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>filter</td>
|
|
<td>Function</td>
|
|
<td>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 section <a href="#Data_Filtering">Data Filtering</a>.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>order</td>
|
|
<td>String | Function</td>
|
|
<td>Order the items by a field name or custom sort function.</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<p>
|
|
The following example demonstrates formatting properties and filtering
|
|
properties from items.
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
// create a DataSet
|
|
var data = new vis.DataSet();
|
|
data.add([
|
|
{id: 1, text: 'item 1', date: '2013-06-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'}
|
|
]);
|
|
|
|
// retrieve formatted items
|
|
var items = data.get({
|
|
fields: ['id', 'date', 'group'], // output the specified fields only
|
|
convert: {
|
|
date: 'Date', // convert the date fields to Date objects
|
|
group: 'String' // convert the group fields to Strings
|
|
}
|
|
});
|
|
</pre>
|
|
|
|
|
|
|
|
<h3 id="Data_Types">Data Types</h3>
|
|
|
|
<p>
|
|
DataSet supports the following data types:
|
|
</p>
|
|
|
|
<table style="width: 100%">
|
|
<tr>
|
|
<th>Name</th>
|
|
<th>Description</th>
|
|
<th>Examples</th>
|
|
</tr>
|
|
<tr>
|
|
<td>Boolean</td>
|
|
<td>A JavaScript Boolean</td>
|
|
<td>
|
|
<code>true</code><br>
|
|
<code>false</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Number</td>
|
|
<td>A JavaScript Number</td>
|
|
<td>
|
|
<code>32</code><br>
|
|
<code>2.4</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>String</td>
|
|
<td>A JavaScript String</td>
|
|
<td>
|
|
<code>"hello world"</code><br>
|
|
<code>"2013-06-28"</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Date</td>
|
|
<td>A JavaScript Date object</td>
|
|
<td>
|
|
<code>new Date()</code><br>
|
|
<code>new Date(2013, 5, 28)</code><br>
|
|
<code>new Date(1372370400000)</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>Moment</td>
|
|
<td>A Moment object, created with
|
|
<a href="http://momentjs.com/" target="_blank">moment.js</a></td>
|
|
<td>
|
|
<code>moment()</code><br>
|
|
<code>moment('2013-06-28')</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ISODate</td>
|
|
<td>A string containing an ISO Date</td>
|
|
<td>
|
|
<code>new Date().toISOString()</code><br>
|
|
<code>"2013-06-27T22:00:00.000Z"</code>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ASPDate</td>
|
|
<td>A string containing an ASP Date</td>
|
|
<td>
|
|
<code>"/Date(1372370400000)/"</code><br>
|
|
<code>"/Date(1198908717056-0700)/"</code>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
<h2 id="Subscriptions">Subscriptions</h2>
|
|
|
|
<p>
|
|
One can subscribe on changes in a DataSet.
|
|
A subscription can be created using the method <code>on</code>,
|
|
and removed with <code>off</code>.
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
// create a DataSet
|
|
var data = new vis.DataSet();
|
|
|
|
// subscribe to any change in the DataSet
|
|
data.on('*', function (event, properties, senderId) {
|
|
console.log('event:', event, 'properties:', properties, 'senderId:', senderId);
|
|
});
|
|
|
|
// add an item
|
|
data.add({id: 1, text: 'item 1'}); // triggers an 'add' event
|
|
data.update({id: 1, text: 'item 1 (updated)'}); // triggers an 'update' event
|
|
data.remove(1); // triggers an 'remove' event
|
|
</pre>
|
|
|
|
|
|
<h3 id="On">On</h3>
|
|
|
|
<p>
|
|
Subscribe to an event.
|
|
</p>
|
|
|
|
Syntax:
|
|
<pre class="prettyprint lang-js">DataSet.on(event, callback)</pre>
|
|
|
|
Where:
|
|
<ul>
|
|
<li>
|
|
<code>event</code> is a String containing any of the events listed
|
|
in section <a href="#Events">Events</a>.
|
|
</li>
|
|
<li>
|
|
<code>callback</code> is a callback function which will be called
|
|
each time the event occurs. The callback function is described in
|
|
section <a href="#Callback">Callback</a>.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3 id="Off">Off</h3>
|
|
|
|
<p>
|
|
Unsubscribe from an event.
|
|
</p>
|
|
|
|
Syntax:
|
|
<pre class="prettyprint lang-js">DataSet.off(event, callback)</pre>
|
|
|
|
Where <code>event</code> and <code>callback</code> correspond with the
|
|
parameters used to <a href="#On">subscribe</a> to the event.
|
|
|
|
<h3 id="Events">Events</h3>
|
|
|
|
<p>
|
|
The following events are available for subscription:
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Event</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>add</td>
|
|
<td>
|
|
The <code>add</code> event is triggered when an item
|
|
or a set of items is added, or when an item is updated while
|
|
not yet existing.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>update</td>
|
|
<td>
|
|
The <code>update</code> event is triggered when an existing item
|
|
or a set of existing items is updated.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>remove</td>
|
|
<td>
|
|
The <code>remove</code> event is triggered when an item
|
|
or a set of items is removed.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>*</td>
|
|
<td>
|
|
The <code>*</code> event is triggered when any of the events
|
|
<code>add</code>, <code>update</code>, and <code>remove</code>
|
|
occurs.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3 id="Callback">Callback</h3>
|
|
|
|
<p>
|
|
The callback functions of subscribers are called with the following
|
|
parameters:
|
|
</p>
|
|
|
|
<pre class="prettyprint lang-js">
|
|
function (event, properties, senderId) {
|
|
// handle the event
|
|
});
|
|
</pre>
|
|
|
|
<p>
|
|
where the parameters are defined as
|
|
</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Type</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td>event</td>
|
|
<td>String</td>
|
|
<td>
|
|
Any of the available events: <code>add</code>,
|
|
<code>update</code>, or <code>remove</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>properties</td>
|
|
<td>Object | null</td>
|
|
<td>
|
|
Optional properties providing more information on the event.
|
|
In case of the events <code>add</code>,
|
|
<code>update</code>, and <code>remove</code>,
|
|
<code>properties</code> is always an object containing a property
|
|
items, which contains an array with the ids of the affected
|
|
items.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>senderId</td>
|
|
<td>String | Number</td>
|
|
<td>
|
|
An senderId, optionally provided by the application code
|
|
which triggered the event. If senderId is not provided, the
|
|
argument will be <code>null</code>.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
|
|
|
|
<h2 id="Data_Policy">Data Policy</h2>
|
|
<p>
|
|
All code and data is processed and rendered in the browser.
|
|
No data is sent to any server.
|
|
</p>
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|