Graph2d documentation

Overview

Graph2d is an interactive visualization chart to draw data in a 2D graph. You can freely move and zoom in the graph by dragging and scrolling in the window.

Graph2d uses HTML DOM and SVG for rendering. This allows for flexible customization using css styling.

Overview
Loading
Data Format
- Items
- Groups
Configuration Options
- Graph2d options
- Timeline options
Methods
Events
Localization
Styles
Data Policy

Example

The following code shows how to create a Graph2d and provide it with data. More examples can be found in the examples directory.

<!DOCTYPE HTML>
<html>
<head>
  <title>Graph2d | Basic Example</title>

  <style type="text/css">
    body, html {
      font-family: sans-serif;
    }
  </style>

  <script src="../../dist/vis.js"></script>
  <link href="../../dist/vis.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="visualization"></div>

<script type="text/javascript">
  var container = document.getElementById('visualization');
  var items = [
      {x: '2014-06-11', y: 10},
      {x: '2014-06-12', y: 25},
      {x: '2014-06-13', y: 30},
      {x: '2014-06-14', y: 10},
      {x: '2014-06-15', y: 15},
      {x: '2014-06-16', y: 30}
  ];

  var dataset = new vis.DataSet(items);
  var options = {
      start: '2014-06-10',
      end: '2014-06-18'
  };
  var Graph2d = new vis.Graph2d(container, dataset, options);
</script>
</body>
</html>

Loading

The class name of the Graph2d is vis.Graph2d. When constructing a Graph2d, an HTML DOM container must be provided to attach the graph to. Optionally, data an options can be provided. Data is a vis DataSet or an Array, described in section Data Format. Options is a name-value map in the JSON format. The available options are described in section Configuration Options. Groups is a vis DataSet containing groups. The available options and the method of construction are described in section Data Format.

var graph = new vis.Graph2d(container [, data] [, options] [,groups]);

Data, options and groups can be set or changed later on using the functions Graph2d.setData(data), Graph2d.setOptions(options) and Graph2d.setGroups(groups).

Data Format

Graph2d can load data from an Array, a DataSet or a DataView. JSON objects are added to this DataSet by using the add() function. Data points must have properties x, y, and z, and can optionally have a property style and filter.

Graph2d can be provided with two types of data:

Items containing a set of points to be displayed.
Groups containing a set of groups used to group items together. All items belonging to a group will be drawn as a single graph.

Items

var items = [
    {x: '2014-06-13', y: 30, group: 0},
    {x: '2014-06-14', y: 10, group: 0},
    {x: '2014-06-15', y: 15, group: 1},
    {x: '2014-06-16', y: 30, group: 1},
    {x: '2014-06-17', y: 10, group: 1},
    {x: '2014-06-18', y: 15, group: 1}
];

Name	Type	Required	Description
x	number	yes	Location on the x-axis.
y	number	yes	Location on the y-axis.
group	number \| string	no	The ID of the group this point belongs to.

Groups

Like the items, groups are regular JavaScript Arrays and Objects. Using groups, items can be grouped together. Items are filtered per group, and displayed as individual graphs. Groups can contain the properties id, content, className (optional) and options (optional).

Groups can be applied to a timeline using the method setGroups. A table with groups can be created like:

var groups = new vis.DataSet();
groups.add({
    id: 1,
    content: 'Group 1',
    // Optional: a field 'visible'
    // Optional: a field 'className'
    // Optional: options
  })
groups.add({
  // more groups...
});

Groups can have the following properties:

Name	Type	Required	Description
id	String \| Number	yes	An id for the group. The group will display all items having a property `group` which matches the `id` of the group.
content	String	yes	The contents of the group. This can be plain text or html code.
className	String	no	This field is optional. A className can be used to give groups an individual css style.
options	JSON object	no	This field is optional. The options can be used to give a group a specific draw style. Any options that are colored green in the Configuration Options can be used as options here.
visible	Boolean	true	This field is optional. If false, this group will not be drawn.

Configuration Options

Graph2d Options

Options can be used to customize the Graph2d to your purposes. These options can be passed to the Graph2d object either in the constructor, or by the setOptions function.

var options = {
    width:  '100%',
    height: '400px',
    style: 'surface'
};

The options colored in green can also be used as options for the groups. All options are optional.

Name	Type	Default	Description
yAxisOrientation	String	'left'	This defines with which axis, left or right, the graph is coupled. Example 5 shows groups with different Y axis. If no groups are coupled with an axis, it will not be shown.
defaultGroup	String	'default'	This is the label for the default, ungrouped items when shown in a legend.
sort	Boolean	true	This determines if the items are sorted automatically. They are sorted by the x value. If sort is enabled, more optimizations are possible, increasing the performance.
sampling	Boolean	true	If sampling is enabled, Graph2d will automatically determine the amount of points per pixel. If there are more than 1 point per pixel, not all points will be drawn. Disabling sampling will cause a decrease in performance.
graphHeight	Number \| String	'400px'	This is the height of the graph SVG canvas. If it is larger than the height of the outer frame, you can drag up and down the vertical direction as well as the usual horizontal direction.
shaded	Boolean \| Object	false	Toggle a shaded area with the default settings.
shaded.enabled	Boolean	false	This toggles the shading.
shaded.orientation	String	'bottom'	This determines if the shaded area is at the bottom or at the top of the curve. The options are 'bottom' or 'top'.
style	String	'line'	This allows the user to define if this should be a linegraph or a barchart. The options are: 'line' or 'bar'.
barChart.width	Number	50	The width of the bars.
barChart.align	String	'center'	The alignment of the bars with regards to the coordinate. The options are 'left', 'right' or 'center'.
barChart.handleOverlap	String	'overlap'	You can choose how graph2d handles the case where barcharts are occupying the same datapoint. The possible options are: `overlap, sideBySide, stack`. See example 10 for more information. When using groups, see example 11.
catmullRom	Boolean \| Object	true	Toggle the interpolation with the default settings. For more customization use the JSON format.
catmullRom.enabled	Boolean	true	Toggle the interpolation.
catmullRom.parametrization	String	'centripetal'	Define the type of parametrizaion. Example 7 shows the different methods. The options are 'centripetal' (best results), 'chordal' and 'uniform'. Uniform is the computationally cheapest variant. If catmullRom is disabled, linear interpolation is used.
drawPoints	Boolean \| Object	true	Toggle the drawing of the datapoints with the default settings.
drawPoints.enabled	Boolean	true	Toggle the drawing of the datapoints.
drawPoints.size	Number	6	Determine the size at which the data points are drawn.
drawPoints.style	String	'square'	Determine the shape of the data points. The options are 'square' or 'circle'.
dataAxis.showMinorLabels	Boolean	true	Toggle the drawing of the minor labels on the Y axis.
dataAxis.showMajorLabels	Boolean	true	Toggle the drawing of the major labels on the Y axis.
dataAxis.icons	Boolean	false	Toggle the drawing of automatically generated icons the Y axis.
dataAxis.width	Number \| String	'40px'	Set the (minimal) width of the yAxis. The axis will resize to accomodate the labels of the Y values.
dataAxis.visible	Boolean	true	Show or hide the data axis.
legend	Boolean	false	Toggle the legend with the default settings.
legend.enabled	Boolean	false	Toggle the legend.
legend.icons	Boolean	true	Show automatically generated icons on the legend.
legend.left.visible	Boolean	true	Both axis, left and right, have a corresponding legend. This toggles the visibility of the legend that is coupled with the left axis.
legend.left.position	String	'top-left'	Determine the position of the legend coupled to the left axis. Options are 'top-left', 'top-right', 'bottom-left' or 'bottom-right'.
legend.right.visible	Boolean	true	This toggles the visibility of the legend that is coupled with the right axis.
legend.right.position	String	'top-right'	Determine the position of the legend coupled to the right axis. Options are 'top-left', 'top-right', 'bottom-left' or 'bottom-right'.

Timeline Options

Graph2d is built upon the framework of the timeline. These options from the timeline can be used with graph2D. All options are optional.

Name	Type	Default	Description
autoResize	boolean	true	If true, the Timeline will automatically detect when its container is resized, and redraw itself accordingly. If false, the Timeline can be forced to repaint after its container has been resized using the function `redraw()`.
clickToUse	boolean	false	When a Graph2d is configured to be `clickToUse`, it will react to mouse and touch events only when active. When active, a blue shadow border is displayed around the Graph2d. The Graph2d is set active by clicking on it, and is changed to inactive again by clicking outside the Graph2d or by pressing the ESC key.
end	Date \| Number \| String	none	The initial end date for the axis of the timeline. If not provided, the latest date present in the items set is taken as end date.
height	Number \| String	none	The height of the timeline in pixels or as a percentage. When height is undefined or null, the height of the timeline is automatically adjusted to fit the contents. It is possible to set a maximum height using option `maxHeight` to prevent the timeline from getting too high in case of automatically calculated height.
locale	String	none	Select a locale for the Graph2d. See section Localization for more information.
locales	Object	none	A map with i18n locales. See section Localization for more information.
max	Date \| Number \| String	none	Set a maximum Date for the visible range. It will not be possible to move beyond this maximum.
maxHeight	Number \| String	none	Specifies the maximum height for the Timeline. Can be a number in pixels or a string like "300px".
min	Date \| Number \| String	none	Set a minimum Date for the visible range. It will not be possible to move beyond this minimum.
minHeight	Number \| String	none	Specifies the minimum height for the Timeline. Can be a number in pixels or a string like "300px".
orientation	String	'bottom'	Orientation of the timeline: 'top' or 'bottom' (default). If orientation is 'bottom', the time axis is drawn at the bottom, and if 'top', the axis is drawn on top.
showCurrentTime	boolean	true	Show a vertical bar at the current time.
showCustomTime	boolean	false	Show a vertical bar displaying a custom time. This line can be dragged by the user. The custom time can be utilized to show a state in the past or in the future. When the custom time bar is dragged by the user, the event `timechange` is fired repeatedly. After the bar is dragged, the event `timechanged` is fired once.
showMajorLabels	boolean	true	By default, the timeline shows both minor and major date labels on the time axis. For example the minor labels show minutes and the major labels show hours. When `showMajorLabels` is `false`, no major labels are shown.
showMinorLabels	boolean	true	By default, the timeline shows both minor and major date labels on the time axis. For example the minor labels show minutes and the major labels show hours. When `showMinorLabels` is `false`, no minor labels are shown. When both `showMajorLabels` and `showMinorLabels` are false, no horizontal axis will be visible.
start	Date \| Number \| String	none	The initial start date for the axis of the timeline. If not provided, the earliest date present in the events is taken as start date.
width	String	'100%'	The width of the timeline in pixels or as a percentage.
zoomMax	Number	315360000000000	Set a maximum zoom interval for the visible range in milliseconds. It will not be possible to zoom out further than this maximum. Default value equals about 10000 years.
zoomMin	Number	10	Set a minimum zoom interval for the visible range in milliseconds. It will not be possible to zoom in further than this minimum.

Methods

The Graph2d supports the following methods.

Method	Return Type	Description
clear([what])	none	Clear the Graph2d. An object can be passed specifying which sections to clear: items, groups, and/or options. By Default, items, groups and options are cleared, i.e. `what = {items: true, groups: true, options: true}`. Example usage: Graph2d.clear(); // clear items, groups, and options Graph2d.clear({options: true}); // clear options only
destroy()	none	Destroy the Graph2d. The Graph2d is removed from memory. all DOM elements and event listeners are cleaned up.
getCustomTime()	Date	Retrieve the custom time. Only applicable when the option `showCustomTime` is true.
setCustomTime(time)	none	Adjust the custom time bar. Only applicable when the option `showCustomTime` is true. `time` is a Date object.
getLegend(groupId, iconWidth, iconHeight)	SVGelement, String, String	Returns an object containing an SVG element with the icon of the group (size determined by iconWidth and iconHeight), the label of the group (content) and the yAxisOrientation of the group (left or right).
getWindow()	Object	Get the current visible window. Returns an object with properties `start: Date` and `end: Date`.
getItemRange()	Object	Get the range of all the items as an object containing `min: Date` and `max: Date`.
fit()	none	Adjust the visible window such that it fits all items.
on(event, callback)	none	Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: `rangechange`, `rangechanged`, `select`. The callback function is invoked as `callback(properties)`, where `properties` is an object containing event specific properties. See section Events for more information.
off(event, callback)	none	Remove an event listener created before via function `on(event, callback)`. See section Events for more information.
redraw()	none	Force a redraw of the Graph2d. Can be useful to manually redraw when option autoResize=false.
isGroupVisible(groupId)	Boolean	This checks if the visible option of the supplied group (by ID) is true or false.
setGroups(groups)	none	Set a data set with groups for the Graph2d. `groups` can be an Array with Objects, a DataSet, or a DataView. For each of the groups, the items of the Graph2d are filtered on the property `group`, which must correspond with the id of the group.
setItems(items)	none	Set a data set with items for the Graph2d. `items` can be an Array with Objects, a DataSet, or a DataView.
setOptions(options)	none	Set or update options. It is possible to change any option of the Graph2d at any time. You can for example switch orientation on the fly.
setWindow(start, end)	none	Set the current visible window. The parameters `start` and `end` can be a `Date`, `Number`, or `String`. If the parameter value of `start` or `end` is null, the parameter will be left unchanged.

Events

Graph2d fires events when changing the visible window by dragging, when selecting items, and when dragging the custom time bar.

Here an example on how to listen for a rangeChanged event.

Graph2d.on('select', function (properties) {
  alert('selected items: ' + properties.nodes);
});

A listener can be removed via the function off:

function onChange (properties) {
  alert('changed!');
}

// add event listener
Graph2d.on('rangechanged', onChange);

// do stuff...

// remove event listener
Graph2d.off('rangechanged', onChange);

The following events are available.

name	Description	Properties
rangechange	Fired repeatedly when the user is dragging the Graph2d window.	`start` (Number): timestamp of the current start of the window. `end` (Number): timestamp of the current end of the window.
rangechanged	Fired once after the user has dragged the Graph2d window.	`start` (Number): timestamp of the current start of the window. `end` (Number): timestamp of the current end of the window.
timechange	Fired repeatedly when the user is dragging the custom time bar. Only available when the custom time bar is enabled.	`time` (Date): the current time.
timechanged	Fired once after the user has dragged the custom time bar. Only available when the custom time bar is enabled.	`time` (Date): the current time.

Localization

Graph2d can be localized. For localization, Graph2d depends largely on the localization of moment.js. Locales are not included in vis.js by default. To enable localization, moment.js must be loaded with locales. Moment.js offers a bundle named "moment-with-locales.min.js" for this and there are various alternative ways to load locales.

To set a locale for the Graph2d, specify the option locale:

var options = {
  locale: 'nl'
};

Create a new locale

To load a locale into the Graph2d not supported by default, one can add a new locale to the option locales:

var options = {
  locales: {
    // create a new locale
    mylocale: {
      current: 'current',
      time: 'time',
    }
  },

  // use the new locale
  locale: 'mylocale'
};

Available locales

Graph2d comes with support for the following locales:

Language	Code
English	`en` `en_EN` `en_US`
Dutch	`nl` `nl_NL` `nl_BE`

Styles

All parts of the Graph2d have a class name and a default css style just like the Graph2d. The styles can be overwritten, which enables full customization of the layout of the Graph2d.

Additionally, Graph2d has 10 preset styles for graphs, which are cycled through when loading groups. These styles can be overwritten as well, along with defining your own classes to style the graphs! Example 4 and example 5 show the usage of custom styles.

Data Policy

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