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>
</pre>
<p><ahref="http://visjs.org/examples/graph2d/01_basic.html"target="_blank">The result of the code above will be the basic example which is shown here.</a></p>
<h2id="Loading">Loading</h2>
<p>
The class name of the Graph2d is <code>vis.Graph2d</code>.
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 <code>DataSet</code> or an <code>Array</code>, described in
section <ahref="#Data_Format">Data Format</a>.
Options is a name-value map in the JSON format. The available options
are described in section <ahref="#Configuration_Options">Configuration Options</a>.
Groups is a vis <code>DataSet</code> containing groups. The available options and the method of construction
Graph2d can load data from an <code>Array</code>, a <code>DataSet</code> (offering 2 way data binding), or a <code>DataView</code> (offering one way data binding).
Objects are added to this DataSet by using the <code>add()</code> function.
<p>
Graph2d can be provided with two types of data:
</p>
<ul>
<li><ahref="#items">Items</a> containing a set of points to be displayed.</li>
<li><ahref="#groups">Groups</a> containing a set of groups used to group items
together. All items belonging to a group will be drawn as a single graph.</li>
</ul>
<h3id="items">Items</h3>
<preclass="prettyprint lang-js options">
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}
];
</pre>
<tableclass="properties">
<tr>
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td>x</td>
<td>Date</td>
<td>yes</td>
<td>Location on the x-axis.</td>
</tr>
<tr>
<td>y</td>
<td>Number</td>
<td>yes</td>
<td>Location on the y-axis.</td>
</tr>
<tr>
<td>group</td>
<td>Number or string</td>
<td>no</td>
<td>The ID of the group this point belongs to.</td>
</tr>
<tr>
<td>label</td>
<td>Object</td>
<td>no</td>
<td>A label object which will be displayed near to the item. A label object has one requirement - a <b> content </b> property. In addition you can set the <b> xOffset, yOffset and className </b> for further appearance customisations </td>
</tr>
</table>
<h3id="groups">Groups</h3>
<p>
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 <code>id</code>,
<code>content</code>, <code>className</code> (optional) and <code>options</code> (optional).
</p>
<p>
Groups can be applied to a timeline using the method <code>setGroups</code>.
A table with groups can be created like:
</p>
<preclass="prettyprint lang-js options">
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...
});
</pre>
<p>
Groups can have the following properties:
</p>
<tableclass="properties">
<tr>
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
<tr>
<td>id</td>
<td>String or Number</td>
<td>yes</td>
<td>An id for the group. The group will display all items having a
property <code>group</code> which matches the <code>id</code>
of the group.</td>
</tr>
<tr>
<td>content</td>
<td>String</td>
<td>yes</td>
<td>The contents of the group. This can be plain text or html code.</td>
</tr>
<tr>
<td>className</td>
<td>String</td>
<td>no</td>
<td>This field is optional. A className can be used to give groups
an individual css style.
</td>
</tr>
<tr>
<td>style</td>
<td>String</td>
<td>no</td>
<td>This field is optional. A style can be used to give groups
an individual css style, and any style tags specified in style will
override the definition in the className style defined in css.
</td>
</tr>
<tr>
<td>options</td>
<td>Object</td>
<td>no</td>
<td>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.
<td>If two datapoints of a barchart overlap, they are drawn over eachother by default. If sideBySide is set to true, they will be drawn side by side, within the same width as a single bar..
<td>The minimum width of the bars in pixels: by default the bars get smaller while zooming out to prevent overlap, this value is the minimum width of the bar. Default behavior (when minWidth is not set) is 10% of the bar width.</td>
Three different types of objects can be assigned to this property. See <ahref="../../examples/graph2d/19_labels.html">Example 19</a> for an illustration.<br/>
1. <code>Boolean</code>: When true is provided every datapoint will be drawn, false otherwise.<br/>
<preclass="prettyprint lang-js">
drawPoints: true // or false
</pre>
2. <code>Object</code> (the 'rendering' options): If an object is provided it may contain following properties which all can be optional: <code>onRender</code>, <code>className</code><code>size</code> and/or <code>style</code>. For more information check the property's documentation.<br/>
<preclass="prettyprint lang-js">
drawPoints: {
size: 3,
style: 'square'
}
</pre>
3. <code>Function</code>: If a function is provided it will be used as a callback. The function may return values from listing 1 or 2.<br/>
<td>Define the type of parametrizaion for the catmullRom interpolation. <ahref="../../examples/graph2d/07_scrollingAndSorting.html">Example 7</a> shows the different parametrizations. The options are 'centripetal' (best results), 'chordal' and 'uniform'. Uniform is the computationally cheapest variant.
If interpolation is disabled, linear interpolation is used.</td>
<td>A constructor for creating a moment.js Date. Allows for applying a custom time zone. See section <ahref="#Time_zone">Time zone</a> for more information.</td>
<td>If stack is enabled, the graphs will be stacked upon each-other when applicable. A group can opt-out of stacking through the "excludeFromStacking" option.</td>
<td>Set the style for the shading. This is a css string and it will override the attributes set in the class.</td>
</tr>
<trparent="shaded"class="hidden">
<tdclass="greenField indent">style</td>
<td>String</td>
<td>'line'</td>
<td>This allows the user to define if this should be a linegraph, barchart or pointcloud. The options are: 'line', 'bar', 'points'.</td>
</tr>
<tr>
<tdclass="greenField">yAxisOrientation</td>
<td>String</td>
<td>'left'</td>
<td>This defines with which axis, left or right, the graph is coupled. <ahref="../../examples/graph2d/05_bothAxis.html">Example 5</a> shows groups with different Y axis. If no groups are coupled
Graph2d is built upon the framework of the timeline. These options from the timeline can be used with graph2D.
All options are optional.
</p>
<tableclass="options"id="optionTable">
<tr>
<th>Name</th>
<th>Type</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>autoResize</td>
<td>Boolean</td>
<td>true</td>
<td>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 <code>redraw()</code>.</td>
</tr>
<tr>
<td>configure</td>
<td>boolean or function</td>
<td><code>false</code></td>
<td>When true, a configurator is loaded where all configuration options of the Graph2d can be changed live.
The displayed options can be filtered by providing a filter function. This function is invoked with two arguments: the current <code>option</code> and the <code>path</code> (an Array) of the option within the options object. The option will be displayed when the filter function returns true. For example to only display format options:
<td>When a Graph2d is configured to be <code>clickToUse</code>, 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.</td>
</tr>
<tr>
<td>end</td>
<td>Date or Number or String</td>
<td>none</td>
<td>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.</td>
</tr>
<tr>
<td>format</td>
<td>Object</td>
<td>none</td>
<td>
Apply custom date formatting of the labels on the time axis. The default value of <code>format</code> is:
<preclass="prettyprint lang-js">{
minorLabels: {
millisecond:'SSS',
second: 's',
minute: 'HH:mm',
hour: 'HH:mm',
weekday: 'ddd D',
day: 'D',
month: 'MMM',
year: 'YYYY'
},
majorLabels: {
millisecond:'HH:mm:ss',
second: 'D MMMM HH:mm',
minute: 'ddd D MMMM',
hour: 'ddd D MMMM',
weekday: 'MMMM YYYY',
day: 'MMMM YYYY',
month: 'YYYY',
year: ''
}
}</pre>
For values which not provided in the customized <code>options.format</code>, the default values will be used.
All available formatting syntax is described in the <ahref="http://momentjs.com/docs/#/displaying/format/">docs of moment.js</a>.
</td>
</tr>
<tr>
<td>height</td>
<td>Number or String</td>
<td>none</td>
<td>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 <code>maxHeight</code>
to prevent the timeline from getting too high in case of automatically
calculated height.
</td>
</tr>
<tr>
<td>hiddenDates</td>
<td>Object</td>
<td>none</td>
<td>This option allows you to hide specific timespans from the time axis. The dates can be supplied as an object:
<code>{start: '2014-03-21 00:00:00', end: '2014-03-28 00:00:00', [repeat:'daily']}</code> or as an Array of these objects. The repeat argument is optional.
The possible values are (case-sensitive): <code>daily, weekly, monthly, yearly</code>. To hide a weekend, pick any Saturday as start and the following Monday as end
It will not be possible to move beyond this minimum.
</td>
</tr>
<tr>
<td>minHeight</td>
<td>Number or String</td>
<td>none</td>
<td>Specifies the minimum height for the Timeline. Can be a number in pixels or a string like "300px".</td>
</tr>
<tr>
<td>moveable</td>
<td>boolean</td>
<td><code>true</code></td>
<td>
Specifies whether the Timeline can be moved and zoomed by dragging the window.
See also option <code>zoomable</code>.
</td>
</tr>
<tr>
<td>orientation</td>
<td>String</td>
<td>'bottom'</td>
<td>Orientation of the timeline: 'top', 'bottom' (default), or 'both'. If orientation is 'bottom', the time axis is drawn at the bottom. When 'top', the axis is drawn on top. When 'both', two axes are drawn, both on top and at the bottom.</td>
</tr>
<tr>
<td>showCurrentTime</td>
<td>Boolean</td>
<td>true</td>
<td>Show a vertical bar at the current time.</td>
</tr>
<tr>
<td>showCustomTime</td>
<td>Boolean</td>
<td>false</td>
<td>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 <code>timechange</code> is fired repeatedly. After the bar is dragged, the event <code>timechanged</code> is fired once.</td>
</tr>
<tr>
<td>showMajorLabels</td>
<td>Boolean</td>
<td>true</td>
<td>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 <code>showMajorLabels</code> is <code>false</code>, no major labels
are shown.</td>
</tr>
<tr>
<td>showMinorLabels</td>
<td>Boolean</td>
<td>true</td>
<td>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 <code>showMinorLabels</code> is <code>false</code>, no minor labels
are shown. When both <code>showMajorLabels</code> and
<code>showMinorLabels</code> are false, no horizontal axis will be
visible.</td>
</tr>
<tr>
<td>start</td>
<td>Date or Number or String</td>
<td>none</td>
<td>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.</td>
<td>Specify a fixed scale and step size for the time axis.</td>
</tr>
<trparent="timeAxis"class="hidden">
<tdclass="indent">timeAxis.scale</td>
<td>String</td>
<td>none</td>
<td>Set a fixed scale for the time axis of the Timeline. Choose from <code>'millisecond'</code>, <code>'second'</code>, <code>'minute'</code>, <code>'hour'</code>, <code>'weekday'</code>, <code>'day'</code>, <code>'month'</code>, <code>'year'</code>. Example usage:
Returns an Object with relevant properties from an event:
<ul>
<li><code>pageX</code> (Number): absolute horizontal position of the click event.</li>
<li><code>pageY</code> (Number): absolute vertical position of the click event.</li>
<li><code>x</code> (Number): relative horizontal position of the click event.</li>
<li><code>y</code> (Number): relative vertical position of the click event.</li>
<li><code>time</code> (Date): Date of the clicked event.</li>
<li><code>value</code> (Number[]): The data value of the click event. The array contains one value when there is one data axis visible, and two values when there are two visible data axes.</li>
<li><code>what</code> (String or null): name of the clicked thing: <code>background</code>, <code>axis</code>, <code>dat-axis</code>, <code>custom-time</code>, or <code>current-time</code>, <code>legend</code>.</li>
<li><code>event</code> (Object): the original click event.</li>
<td>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).
</td>
</tr>
<tr>
<td>getWindow()</td>
<td>Object</td>
<td>Get the current visible window. Returns an object with properties <code>start: Date</code> and <code>end: Date</code>.</td>
</tr>
<tr>
<td>isGroupVisible(groupId)</td>
<td>Boolean</td>
<td>This checks if the visible option of the supplied group (by ID) is true or false.
</td>
</tr>
<tr>
<td>moveTo(time [, options])</td>
<td>none</td>
<td>Move the window such that given time is centered on screen. Parameter <code>time</code> can be a <code>Date</code>, <code>Number</code>, or <code>String</code>. Available options:
<ul>
<li><code>animate: boolean or number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>
</ul>
</td>
</tr>
<tr>
<td>on(event, callback)</td>
<td>none</td>
<td>Create an event listener. The callback function is invoked every time the event is triggered. Avialable events: <code>rangechange</code>, <code>rangechanged</code>, <code>select</code>. The callback function is invoked as <code>callback(properties)</code>, where <code>properties</code> is an object containing event specific properties. See section <ahref="#Events">Events for more information</a>.</td>
</tr>
<tr>
<td>off(event, callback)</td>
<td>none</td>
<td>Remove an event listener created before via function <code>on(event, callback)</code>. See section <ahref="#Events">Events for more information</a>.</td>
</tr>
<tr>
<td>redraw()</td>
<td>none</td>
<td>Force a redraw of the Graph2d. Can be useful to manually redraw when option autoResize=false.
</td>
</tr>
<tr>
<td>setCurrentTime(time)</td>
<td>none</td>
<td>Set a current time. This can be used for example to ensure that a client's time is synchronized with a shared server time.
<code>time</code> can be a Date object, numeric timestamp, or ISO date string.
Only applicable when option <code>showCurrentTime</code> is true.</td>
</tr>
<tr>
<td>setCustomTime(time)</td>
<td>none</td>
<td>Adjust the custom time bar. Only applicable when the option <code>showCustomTime</code> is true. <code>time</code> can be a Date object, numeric timestamp, or ISO date string.
</td>
</tr>
<tr>
<td>setGroups(groups)</td>
<td>none</td>
<td>Set a data set with groups for the Graph2d.
<code>groups</code> 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 <code>group</code>, which
must correspond with the id of the group.
</td>
</tr>
<tr>
<td>setItems(items)</td>
<td>none</td>
<td>Set a data set with items for the Graph2d.
<code>items</code> can be an Array with Objects,
a DataSet, or a DataView.
</td>
</tr>
<tr>
<td>setOptions(options)</td>
<td>none</td>
<td>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.
</td>
</tr>
<tr>
<td>setWindow(start, end)</td>
<td>none</td>
<td>Set the current visible window. The parameters <code>start</code> and <code>end</code> can be a <code>Date</code>, <code>Number</code>, or <code>String</code>. If the parameter value of <code>start</code> or <code>end</code> is null, the parameter will be left unchanged.</td>
</tr>
</table>
<h2id="Events">Events</h2>
<p>
Graph2d fires events when changing the visible window by dragging, when
selecting items, and when dragging the custom time bar.
</p>
<p>
Here an example on how to listen for a <code>rangeChanged</code> event. A listener can be removed via the function <code>off</code>:
Passes a properties object as returned by the method <ahref="#getEventProperties"><code>Graph2d.getEventProperties(event)</code></a>.
</td>
<td>Fired when clicked inside the Graph2d.
</td>
</tr>
<tr>
<td>contextmenu</td>
<td>
Passes a properties object as returned by the method <ahref="#getEventProperties"><code>Graph2d.getEventProperties(event)</code></a>.
</td>
<td>Fired when right-clicked inside the Graph2d. Note that in order to prevent the context menu from showing up, default behavior of the event must be stopped:
<preclass="prettyprint lang-js options">graph2d.on('contextmenu', function (props) {
alert('Right click!');
props.event.preventDefault();
});
</pre>
</td>
</tr>
<tr>
<td>doubleClick</td>
<td>
Passes a properties object as returned by the method <ahref="#getEventProperties"><code>Graph2d.getEventProperties(event)</code></a>.
<li><code>time</code> (Date): the current time.</li>
</ul>
</td>
<td>Fired repeatedly when the user is dragging the custom time bar.
Only available when the custom time bar is enabled.
</td>
</tr>
<tr>
<td>timechanged</td>
<td>
<ul>
<li><code>time</code> (Date): the current time.</li>
</ul>
</td>
<td>Fired once after the user has dragged the custom time bar.
Only available when the custom time bar is enabled.
</td>
</tr>
</table>
<h2id="Localization">Localization</h2>
<p>
Graph2d can be localized. For localization, Graph2d depends largely on the localization of <ahref="http://momentjs.com">moment.js</a>. 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.
</p>
<p>
To set a locale for the Graph2d, specify the option <code>locale</code>:
</p>
<preclass="prettyprint lang-js">var options = {
locale: 'nl'
};
</pre>
<h3>Create a new locale</h3>
To load a locale into the Graph2d not supported by default, one can add a new locale to the option <code>locales</code>:
<preclass="prettyprint lang-js">var options = {
locales: {
// create a new locale
mylocale: {
current: 'current',
time: 'time',
}
},
// use the new locale
locale: 'mylocale'
};
</pre>
<h3id="available-locales">Available locales</h3>
Graph2d comes with support for the following locales:
By default, the Timeline displays time in local time. To display a Timeline in an other time zone or in UTC, the date constructor can be overloaded via the configuration option <code>moment</code>, which by default is the constructor function of moment.js. More information about UTC with moment.js can be found in the docs: <ahref="http://momentjs.com/docs/#/parsing/utc/">http://momentjs.com/docs/#/parsing/utc/</a>.
