From fd4cf6907e7c93d44be7a48cc5ea092bd67419b3 Mon Sep 17 00:00:00 2001 From: josdejong Date: Thu, 20 Jun 2013 15:04:40 +0200 Subject: [PATCH] Added documentation on DataSet and DataView --- HISTORY.md | 12 +- README.md | 8 +- docs/dataset.html | 684 +++++++++++++++++++++++++++- docs/dataview.html | 222 +++++++++ docs/graph.html | 19 +- docs/index.html | 178 +++++++- docs/timeline.html | 19 +- examples/timeline/02_dataset.html | 2 +- examples/timeline/03_much_data.html | 2 +- 9 files changed, 1094 insertions(+), 52 deletions(-) create mode 100644 docs/dataview.html diff --git a/HISTORY.md b/HISTORY.md index 81b689ec..3c6679b6 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -4,15 +4,17 @@ http://visjs.org ## version 0.1.0 -- Graph now uses an id based set of nodes and edges instead of a row based array - internally. +- Added support for DataSet to Graph. Graph now uses an id based set of nodes + and edges instead of a row based array internally. Methods getSelection and + setSelection of Graph now accept a list with ids instead of rows. - Graph is now robust against edges pointing to non-existing nodes, which can occur easily while dynamically adding/removing nodes and edges. -- Added support for DataSet to Graph. -- Methods getSelection and setSelection of Graph now accept a list with ids - instead of rows. - Implemented basic support for groups in the Timeline. +- Added documentation on DataSet and DataView. - Fixed selection of nodes in a Graph when the containing web page is scrolled. +- Improved date conversion. +- Renamed DataSet option `fieldTypes` to `convert`. +- Renamed function `vis.util.cast` to `vis.util.convert`. ## 2013-06-07, version 0.0.9 diff --git a/README.md b/README.md index 8ade6a9c..ea589e3c 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ The library is designed to be easy to use, handle large amounts of dynamic data, and enable manipulation of the data. The library consists of the following components: +- DataSet and DataView. A flexible key/value based data set. + Add, update, and remove items. Subscribe on changes in the data set. + Filter and order items and convert fields of items. - Timeline. Display different types of data on a timeline. The timeline and the items on the timeline can be interactively moved, zoomed, and manipulated. -- Graph. Display a graph of network with nodes and edges. -- DataSet and DataView. A flexible key/value based data set. - Add, update, and remove items. Subscribe on changes in the data set. - Filter, order, and cast items. +- Graph. Display an interactive graph or network with nodes and edges. The vis.js library is developed by [Almende B.V](http://almende.com). diff --git a/docs/dataset.html b/docs/dataset.html index 201d6e5b..b6590ff2 100644 --- a/docs/dataset.html +++ b/docs/dataset.html @@ -11,12 +11,692 @@ - +

DataSet documentation

-

coming soon...

+

Contents

+ + + +

Overview

+ +

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

+ + +

Example

+ +

+ The following example shows how to use a DataSet. +

+ +
+// 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.subscribe('*', function (event, params, senderId) {
+    console.log('event', event, params);
+});
+
+// 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);
+
+ + + +

Construction

+ +

+ A DataSet can be constructed as: +

+ +
+var data = new vis.DataSet(options)
+
+ +

+ After construction, data can be added to the DataSet using the methods + add and update, as described in section + Data Manipulation. +

+ +

+ The parameter options is optional and is an object which can + contain the following properties: +

+ + + + + + + + + + + + + + + + + + + + +
NameTypeDefault valueDescription
fieldIdString"id" + 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 fieldId. + For example CouchDB uses the field + "_id" to identify documents. +
convertObject.<String, String>none + 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 + Data Types. +
+ + +

Data Manipulation

+ +

+ The data in a DataSet can be manipulated using the methods + add, + update, + and remove. + The DataSet can be emptied using the method + clear. +

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

Add

+ +

+ Add a data item or an array with items. +

+ + Syntax: + 
var addedIds = DataSet.add(data [, senderId])
+ + The argument data can contain: + + +

+ After the items are added to the DataSet, the DataSet will + trigger an event add. When a senderId + is provided, this id will be passed with the triggered + event to all subscribers. +

+ +

+ The method will throw an Error when an item with the same id + as any of the added items already exists. +

+ +

Update

+ +

+ Update a data item or an array with items. +

+ + Syntax: + 
var updatedIds = DataSet.update(data [, senderId])
+ + The argument data can contain: + + +

+ The provided properties will be merged in the existing item. + When an item does not exist, it will be created. +

+ +

+ After the items are updated, the DataSet will + trigger an event add for the added items, and + an event update. When a senderId + is provided, this id will be passed with the triggered + event to all subscribers. +

+ +

Remove

+ +

+ Remove a data item or an array with items. +

+ + Syntax: + 
var removedIds = DataSet.remove(id [, senderId])
+ +

+ The argument id can be: +

+ + +

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

+ +

+ After the items are removed, the DataSet will + trigger an event remove for the removed items. + When a senderId is provided, this id will be passed with + the triggered event to all subscribers. +

+ + +

Clear

+ +

+ Clear the complete DataSet. +

+ + Syntax: + 
var removedIds = DataSet.clear([senderId])
+ +

+ After the items are removed, the DataSet will + trigger an event remove for all removed items. + When a senderId is provided, this id will be passed with + the triggered event to all subscribers. +

+ + +

Data Filtering

+ +

+ Data can be retrieved from the DataSet using the method get. + This method can return a single item or a list with items. +

+ +

A single item can be retrieved by its id:

+ +
+var item1 = dataset.get(1);
+
+ +

A selection of items can be retrieved by providing an array with ids:

+ +
+var items = dataset.get([1, 3, 4]); // retrieve items 1, 3, and 4
+
+ +

All items can be retrieved by simply calling get without + specifying an id:

+ +
+var items = dataset.get();          // retrieve all items
+
+ +

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

+ +
+// 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);
+    }
+});
+
+
+ + +

Data Formatting

+ +

+ The DataSet contains functionality to format data retrieved via the + method get. The method get has the following + syntax: +

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

+ Where options is an Object which can have the following + properties: +

+ + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescription
fieldsString[ ] + 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. +
convertObject.<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. +
filterfunctionItems 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 Data Filtering.
+ +

+ The following example demonstrates formatting properties and filtering + properties from items. +

+ +
+// 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
+    }
+});
+
+ + + +

Data Types

+ +

+ DataSet supports the following data types: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionExamples
BooleanA JavaScript Boolean + true
+ false +
NumberA JavaScript Number + 32
+ 2.4 +
StringA JavaScript String + "hello world"
+ "2013-06-28" +
DateA JavaScript Date object + new Date()
+ new Date(2013, 5, 28)
+ new Date(1372370400000) +
MomentA Moment object, created with + moment.js + moment()
+ moment('2013-06-28') +
ISODateA string containing an ISO Date + new Date().toISOString()
+ "2013-06-27T22:00:00.000Z" +
ASPDateA string containing an ASP Date + "/Date(1372370400000)/"
+ "/Date(1198908717056-0700)/" +
+ + +

Subscriptions

+ +

+ One can subscribe on changes in a DataSet. + A subscription can be created using the method subscribe, + and removed with unsubscribe. +

+ +
+// create a DataSet
+var data = new vis.DataSet();
+
+// subscribe to any change in the DataSet
+data.subscribe('*', function (event, params, senderId) {
+    console.log('event:', event, 'params:', params, '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
+
+ + +

Subscribe

+ +

+ Subscribe to an event. +

+ + Syntax: + 
DataSet.subscribe(event, callback)
+ + Where: + + +

Unsubscribe

+ +

+ Unsubscribe from an event. +

+ + Syntax: + 
DataSet.unsubscribe(event, callback)
+ + Where event and callback correspond with the + parameters used to subscribe to the event. + +

Events

+ +

+ The following events are available for subscription: +

+ + + + + + + + + + + + + + + + + + + + + + +
EventDescription
add + The add event is triggered when an item + or a set of items is added, or when an item is updated while + not yet existing. +
update + The update event is triggered when an existing item + or a set of existing items is updated. +
remove + The remove event is triggered when an item + or a set of items is removed. +
* + The * event is triggered when any of the events + add, update, and remove + occurs. +
+ +

Callback

+ +

+ The callback functions of subscribers are called with the following + parameters: +

+ + 
+function (event, params, senderId) {
+    // handle the event
+});
+
+ +

+ where the parameters are defined as +

+ + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
eventString + Any of the available events: add, + update, or remove. +
paramsObject | null + Optional parameters providing more information on the event. + In case of the events add, + update, and remove, + params is always an object containing a property + items, which contains an array with the ids of the affected + items. +
senderIdString | Number + An senderId, optionally provided by the application code + which triggered the event. If senderId is not provided, the + argument will be null. +
+ + + +

Data Policy

+

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

diff --git a/docs/dataview.html b/docs/dataview.html new file mode 100644 index 00000000..e637a2e0 --- /dev/null +++ b/docs/dataview.html @@ -0,0 +1,222 @@ + + + + + vis.js | DataView documentation + + + + + + + + + +
+ +

DataView documentation

+ +

Contents

+ + + +

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.subscribe('*', function (event, params, senderId) {
+    console.log('event', event, params);
+});
+
+// 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: +

+ + + +

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.subscribe('*', function (event, params, senderId) {
+    console.log('event:', event, 'params:', params, '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. +

+ +
+ + \ No newline at end of file diff --git a/docs/graph.html b/docs/graph.html index 5d3a41c4..0ccc5e4e 100644 --- a/docs/graph.html +++ b/docs/graph.html @@ -15,22 +15,6 @@

Graph documentation

- - - - - - - - - - - - - -
AuthorJos de Jong, Almende B.V.
Webpagehttp://visjs.org
License Apache License, Version 2.0
- -

Contents