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 @@ -
+coming soon...
++ 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. +
+ + ++ 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); ++ + + +
+ 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:
+
Name | +Type | +Default value | +Description | +
---|---|---|---|
fieldId | +String | +"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.
+ |
+
convert | +Object.<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. + | +
+ 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 a data item or an array with items. +
+ + Syntax: +var addedIds = DataSet.add(data [, senderId])+ + The argument
data
can contain:
+ Object
containing a single item to be
+ added. The item must contain an id.
+ Array
or
+ google.visualization.DataTable
containing
+ a list with items to be added. Each item must contain
+ an id.
+
+ 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 a data item or an array with items. +
+ + Syntax: +var updatedIds = DataSet.update(data [, senderId])+ + The argument
data
can contain:
+ Object
containing a single item to be
+ updated. The item must contain an id.
+ Array
or
+ google.visualization.DataTable
containing
+ a list with items to be updated. Each item must contain
+ an id.
+ + 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 a data item or an array with items. +
+ + Syntax: +var removedIds = DataSet.remove(id [, senderId])+ +
+ The argument id
can be:
+
Number
or String
containing the id
+ of a single item to be removed.
+ Object
containing the item to be deleted.
+ The item will be deleted by its id.
+ + 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 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 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); + } +}); + ++ + +
+ 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:
+
Name | +Type | +Description | +
---|---|---|
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.
+ |
+
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. + | +
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 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 + } +}); ++ + + +
+ DataSet supports the following data types: +
+ +Name | +Description | +Examples | +
---|---|---|
Boolean | +A JavaScript Boolean | +
+ true + false
+ |
+
Number | +A JavaScript Number | +
+ 32 + 2.4
+ |
+
String | +A JavaScript String | +
+ "hello world" + "2013-06-28"
+ |
+
Date | +A JavaScript Date object | +
+ new Date() + new Date(2013, 5, 28) + new Date(1372370400000)
+ |
+
Moment | +A Moment object, created with + moment.js | +
+ moment() + moment('2013-06-28')
+ |
+
ISODate | +A string containing an ISO Date | +
+ new Date().toISOString() + "2013-06-27T22:00:00.000Z"
+ |
+
ASPDate | +A string containing an ASP Date | +
+ "/Date(1372370400000)/" + "/Date(1198908717056-0700)/"
+ |
+
+ 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 to an event. +
+ + Syntax: +DataSet.subscribe(event, callback)+ + Where: +
event
is a String containing any of the events listed
+ in section Events.
+ callback
is a callback function which will be called
+ each time the event occurs. The callback function is described in
+ section Callback.
+ + Unsubscribe from an event. +
+ + Syntax: +DataSet.unsubscribe(event, callback)+ + Where
event
and callback
correspond with the
+ parameters used to subscribe to the event.
+
+ + The following events are available for subscription: +
+ +Event | +Description | +
---|---|
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.
+ |
+
+ The callback functions of subscribers are called with the following + parameters: +
+ ++function (event, params, senderId) { + // handle the event +}); ++ +
+ where the parameters are defined as +
+ +Parameter | +Type | +Description | +
---|---|---|
event | +String | +
+ Any of the available events: add ,
+ update , or remove .
+ |
+
params | +Object | 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.
+ |
+
senderId | +String | Number | +
+ An senderId, optionally provided by the application code
+ which triggered the event. If senderId is not provided, the
+ argument will be null .
+ |
+
+ All code and data is processed and rendered in the browser. + No data is sent to any server. +
+ 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. +
+ ++ 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(); ++ +
+ 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. | +
+ 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); + } +}); ++ + + +
+ 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... ++ + + +
+ All code and data is processed and rendered in the browser. + No data is sent to any server. +
+ +Author | -Jos de Jong, Almende B.V. | -
Webpage | -http://visjs.org | -
License | -Apache License, Version 2.0 | -
- All code and data are processed and rendered in the browser. No data is sent to any server. + All code and data is processed and rendered in the browser. + No data is sent to any server.
diff --git a/docs/index.html b/docs/index.html index c5b6d327..fbd7bd60 100644 --- a/docs/index.html +++ b/docs/index.html @@ -11,19 +11,187 @@ - +Vis.js contains the following components:
++ Vis.js is a dynamic, browser based visualization library. + The library is designed to be easy to use, handle large amounts + of dynamic data, and enable manipulation of the data. +
+ ++ The library is developed by + Almende B.V. +
+ ++ Vis.js contains of the following components: +
+npm install vis ++ +
+bower install vis ++ +
+ To use a component, include the javascript file of vis in your web page: +
+ +<!DOCTYPE HTML> +<html> +<head> + <script src="components/vis/vis.js"></script> +</head> +<body> +<script type="text/javascript"> + // ... load a visualization +</script> +</body> +</html> ++ +
+ or load vis.js using require.js: +
+ ++require.config({ + paths: { + vis: 'path/to/vis', + } +}); + +require(['vis'], function (math) { + // ... load a visualization +}); ++ +
+ A timeline can be instantiated as follows. Other components can be + created in a similar way. +
+ ++var timeline = new vis.Timeline(container, data, options); ++ +
+ Where container
is an HTML element, data
is
+ an Array with data or a DataSet, and options
is an optional
+ object with configuration options for the component.
+
+ A basic example on using a Timeline is shown below. More examples can be + found in the examples directory of the project. +
+ ++<!DOCTYPE HTML> +<html> +<head> + <title>Timeline basic demo</title> + <script src="components/vis/vis.js"></script> + + <style type="text/css"> + body, html { + font-family: sans-serif; + } + </style> +</head> +<body> +<div id="visualization"></div> + +<script type="text/javascript"> + var container = document.getElementById('visualization'); + var data = [ + {id: 1, content: 'item 1', start: '2013-04-20'}, + {id: 2, content: 'item 2', start: '2013-04-14'}, + {id: 3, content: 'item 3', start: '2013-04-18'}, + {id: 4, content: 'item 4', start: '2013-04-16', end: '2013-04-19'}, + {id: 5, content: 'item 5', start: '2013-04-25'}, + {id: 6, content: 'item 6', start: '2013-04-27'} + ]; + var options = {}; + var timeline = new vis.Timeline(container, data, options); +</script> +</body> +</html> ++ + +
+ Copyright (C) 2010-2013 Almende B.V. +
+ ++ Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at +
+ ++ http://www.apache.org/licenses/LICENSE-2.0 +
+ ++ Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +
+Author | -Jos de Jong, Almende B.V. | -
Webpage | -http://visjs.org | -
License | -Apache License, Version 2.0 | -
- All code and data are processed and rendered in the browser. No data is sent to any server. + All code and data is processed and rendered in the browser. + No data is sent to any server.
diff --git a/examples/timeline/02_dataset.html b/examples/timeline/02_dataset.html index 049eb79d..c1987abd 100644 --- a/examples/timeline/02_dataset.html +++ b/examples/timeline/02_dataset.html @@ -29,7 +29,7 @@ // create a dataset with items var items = new vis.DataSet({ - fieldTypes: { + convert: { start: 'Date', end: 'Date' } diff --git a/examples/timeline/03_much_data.html b/examples/timeline/03_much_data.html index 36221ad7..5d778975 100644 --- a/examples/timeline/03_much_data.html +++ b/examples/timeline/03_much_data.html @@ -27,7 +27,7 @@ // create a dataset with items var now = moment().minutes(0).seconds(0).milliseconds(0); var items = new vis.DataSet({ - fieldTypes: { + convert: { start: 'Date', end: 'Date' }