Graph documentation

Author	Jos de Jong, Almende B.V.
Website	Chap Links Library
License	Apache License, Version 2.0

Overview
Example
Loading
Data Format
Configuration Options
Methods
Events
Styles
Data Policy

Overview

The Graph is an interactive visualization chart to draw (measurement) data in time. You can freely move and zoom in the graph by dragging and scrolling in the window. The time scale on the axis is adjusted automatically, and supports scales ranging from milliseconds to years.

The Graph visualization is designed to display large amouts of data in your browser. Modern browsers can render up to 100.000 (or even a million) datapoints without problems. However, to keep rendering smooth on older browsers too, it is better to keep the number of datapoints below 10.000. Note that rendering is faster when a smaller part of the data is visible, i.e. when zooming in.

The Graph is developed as a Google Visualization Chart in javascript. There is a GWT wrapper available to use the Graph in GWT (Google Web Toolkit). It runs in all browsers without additional requirements. Graph is tested on Firefox 3.6, Safari 5.0, Chrome 6.0, Opera 10.6, Internet Explorer 6 to 9.

Example

Here a graph example. Click and drag to move the graph, scroll to zoom the graph.

More examples can be found in the examples directory.

<!DOCTYPE HTML PUBLIC
    "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>Graph demo</title>

    <style>
      body {font: 10pt arial;}
    </style>

    <script type="text/javascript" src="http://www.google.com/jsapi"></script>
    <script type="text/javascript" src="../graph.js"></script>
    <link rel="stylesheet" type="text/css" href="../graph.css">
    <!--[if IE]><script src="../excanvas.js"></script><![endif]-->

    <script type="text/javascript">
      google.load("visualization", "1");

      // Set callback to run when API is loaded
      google.setOnLoadCallback(drawVisualization);

      // Called when the Visualization API is loaded.
      function drawVisualization() {
        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('datetime', 'time');
        data.addColumn('number', 'Function A');
        data.addColumn('number', 'Function B');

        function functionA(x) {
          return Math.sin(x / 25) * Math.cos(x / 25) * 50 + (Math.random()-0.5) * 10;
        }

        function functionB(x) {
          return Math.sin(x / 50) *50 + Math.cos(x / 7) * 75 + (Math.random()-0.5) * 20 + 20;
        }

        // create data
        var d = new Date(2010, 9, 23, 20, 0, 0);
        for (var i = 0; i < 100; i++) {
          data.addRow([new Date(d), functionA(i), functionB(i)]);
          d.setMinutes(d.getMinutes() + 1);
        }

        // specify options
        var options = {
          "width":  "100%",
          "height": "350px"
        };

        // Instantiate our graph object.
        var graph = new links.Graph(document.getElementById('mygraph'));

        // Draw our graph with the created data and options
        graph.draw(data, options);
      }
   </script>
  </head>

  <body>
    <div id="mygraph"></div>

    <div id="info"></div>
  </body>
</html>

Loading

To load the Graph, download the file graph.zip, and unzip it in your html page such that the files are located in a subfolder graph. When you use a Google DataTable or Events, the Google API must be included too. Note that the Google API is only available online, so it is not possible to use it in an offline application.

<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript" src="graph/graph.js"></script>
<!--[if IE]><script src="../excanvas.js"></script><![endif]-->
<link rel="stylesheet" type="text/css" href="graph/graph.css">

When the Google API is used, the google visualization tools needs to be loaded. This is not needed when using a JSON Array as data type.

google.load("visualization", "1");
google.setOnLoadCallback(drawVisualization);
function drawVisualization() {
  // load data and create the graph here
}

The class name of the Graph is links.Graph

var graph = new links.Graph(container);

After being loaded, the graph can be drawn via the function draw(), provided with data and options.

graph.draw(data, options);

where data is a Google DataTable or a JSON Object, and options is a name-value map in the JSON format.

Data Format

The Graph can be fed with two types of data: a Google DataTable, or a Javascript Array. Using a Google DataTable requires loading the Google JSAPI, which is only available online.

Google DataTable

The graph requires a data table with at least two columns. The first column must contain dates, and the second (and optionally more columns) contains numeric data values. A table is constructed as:

var data = new google.visualization.DataTable();
data.addColumn('datetime', 'time');
data.addColumn('number', 'Values A');
data.addColumn('number', 'Values B'); // optionally add more than one data column

data.addRow([new Date(2010,7,15), 12.5, 34.6]);
// ...

The columns are defined as:

Name	Type	Description
time	datetime	The date of the data point, for example `new Date(2010,09,23)`.
value	number	The data value.
value	number	Optional: more data columns.

JavaScript Array

The Graph requires a Javascript Array with at least one dataset. A dataset is an Javascript Object containing two parameters: label and data. The label is displayed in the legend of the Graph, and the data parameter contains an Array with Objects. Optionally, a type parameter can be provided to the dataset, denoting the type of the data. Unlike the Google DataTable, a JavaScript dataset can contain different data types: line (default), area, or event.

Data type "line"

The default type of a data set is line. Graph will display the dataset as a line, a dotted line, or dots, depending on the line style. The data consists of an array with objects, each object containing two parameters:

Name	Type	Required	Description
date	Date	yes	The date of the data point.
value	Number	yes	The value of the data point.

Data type "area"

For data type area, data will be displayed as colored, horizontal background ranges. The data consists of an array with ranges, each range containing date parameters start and end, and optionally a string parameter color containing a valid HTML color for an individual range. If an area has no color defined, the color will be read from the configuration parameter lines[].color. Typically, the color for a background area will be an rgba color with transparency, for example rgba(51, 102, 204, 0.1). The data consists of an array with objects, where each object can contain the following parameters:

Name	Type	Required	Description
start	Date	yes	The start date of the background area.
end	Date	yes	The end date of the background area.
text	String	no	Text displayed as a text label top left of the background area.
title	String	no	Text displayed when hovering the top left of the background area.
color	String	no	An HTML color for the line of the background area. If an area has no color defined, the color will be read from the configuration parameter `lines[].color`. Typically, the color for a background area will be an rgba color with transparency, for example `rgba(51, 102, 204, 0.1)`.
textColor	String	no	An HTML color for the text label of the background area. If an area has no textColor defined, the textColor will be read from the configuration parameter `lines[].textColor`.
font	String	no	The font for the text label of the background area, for example '10pt arial'. If an area has no font defined, the font will be read from the configuration parameter `lines[].font`.

Data type "event"

Data sets of type event will be displayed as vertical lines. The data consists of an array with objects, where each object can contain the following parameters:

Name	Type	Required	Description
date	Date	yes	The date of the event.
text	String	no	Text displayed as a text label top right of the event.
title	String	no	Text displayed when hovering the top of the event line.
color	String	no	An HTML color for the line of the event. If an event has no color defined, the color will be read from the configuration parameter `lines[].color`.
textColor	String	no	An HTML color for the text label of the event. If an event has no textColor defined, the textColor will be read from the configuration parameter `lines[].textColor`.
font	String	no	The font for the text label of the event, for example '10pt arial'. If an event has no font defined, the font will be read from the configuration parameter `lines[].font`.

JavaScript Array example

// a line graph
var dataset1 = {
  "label" : "Dataset A",
  "data" : [
    {"date": new Date(2010,7,15), "value" : 12.5},
    {"date": new Date(2010,7,16), "value" : 3.5},
    // ...
  ]
};

// another line graph
var dataset2 = {
  "label" : "Dataset B",
  "data" : [
    {"date": new Date(2010,7,15), "value" : 3.2},
    {"date": new Date(2010,7,17), "value" : 6.1},
    // ...
  ]
};

// background areas
var dataset3 = {
  "type": "area"
  "label" : "Background",
  "data" : [
    {"start": new Date(2010,7,15), "end" : new Date(2010,7,17) },
    {"start": new Date(2010,7,19), "end" : new Date(2010,7,24), "color": "rgba(51, 102, 204, 0.1)"},
    // ...
  ]
};

// put all datasets in one array
var data = [dataset1, dataset2, dataset3];

Configuration Options

Options can be used to customize the graph. Options are defined as a JSON object. All options are optional.

var options = {
  "width":  "100%",
  "height": "400px",
  "line": {
    "width": 1  // width applied to all lines
  },
  "lines": [
    {
      "style": "dot-line",
      "radius": 2,
      "color": "cornflowerblue".
      "legend": false
    },
    {
      "style": "line",
      "color": "navy"
    }
  ]
};

The following options are available.

Name	Type	Default	Description
autoDataStep	boolean	true	If true, intermediate data points will be skipped in case of much data. This makes drawing large amounts of data much faster. For example, when the data contains 10000 points, and the width of the graph is 1000 pixels, every tenth datapoint will be drawn and the rest will be skipped.
end	Date	none	The initial start date for the axis of the graph. If not provided, the latest date present in the events is taken as end date.
height	string	"300px"	The height of the graph in pixels or as a percentage.
legend.toggleVisibility	boolean	false	Enable toggling the visibility of individual lines in the graph. When `legend.toggleVisibility` is true, checkboxes are added in the legend to show or hide a line. A line can initially be set invisible by setting `visible` to false for the specified line (see next table).
legend.visible	boolean	true	If true, the legend is shown. If false, the legend is hidden.
legend.width	String	"auto"	Set a width for the legend, for example "200px" or "15%". This can be useful when the function names are very long.
line	Object	{ }	An object with styles applied to all lines: color, width, radius, style, legend. See the table Line.
lines	Array with objects	[ ]	An array with specific styles for the individual lines: color, width, radius, style, legend. These styles override the styles set in the option `line`. See the table Line.
max	Date	none	Set a maximum Date for the visible range. It will not be possible to move beyond this maximum.
min	Date	none	Set a minimum Date for the visible range. It will not be possible to move beyond this minimum.
moveable	boolean	true	If true, the graph is movable. When the graph moved, the `rangechange` events are fired.
scale	links.StepDate.SCALE	none	Set a custom scale. Automatic scaling will be disabled. Both options `scale` and `step` must be set. For example scale=SCALE.MINUTES and step=5 will result in minor steps of 5 minutes, and major steps of an hour. Available scales: `MILLISECOND`, `SECOND`, `MINUTE`, `HOUR`, `WEEKDAY`, `DAY`, `MONTH`, `YEAR`. As step size, choose for example 1, 2, 5, or 10.
start	Date	none	The initial start date for the axis of the graph. If not provided, the earliest date present in the events is taken as start date.
step	number	none	See option `scale`.
tooltip	boolean \| function	true	Show a tooltip containing date and value when hovering over a function. The contents of the tooltip can be customized by providing a callback function as `tooltip`. In this case the function is called with an object containing parameters `date`, `text`, `line`, `color`, `radius` as argument, and must return a string which may contain HTML.
vAreas	Array with objects	none	Create vertical colored background areas. The areas fill the full width of the graph, and are vertically limited between a provided start and end. See table Background Area.
vEnd	number	none	The initial end value of the vertical axis.
vStart	number	none	The initial start value of the vertical axis.
vMin	number	none	The minium value for the vertical axis. If undefined, vMin is taken as the minimum value in the data minus 5% of the data range.
vMax	number	none	The start value of the vertical axis. If undefined, vMax is taken as the maximum value in the data plus 5% of the data range.
vStep	number	none	The step size of the vertical axis. This must be a positive value.
width	string	"100%"	The width of the graph in pixels or as a percentage.
zoomable	boolean	true	If true, the graph is zoomable. When the graph is zoomed, the `rangechange` event is fired.
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.

Line

With the options line and lines, styles can be specified for respectively all lines and individual lines. The following styles are available:

Name	Type	Default	Description
style	string	"line"	A line style. Available styles are: `line`, `dot`, or `dot-line`. Dots are drawn at each data point. Lines are drawn between the data points.
color	string	black	A string with an HTML color, for example `red` or `#FF0000`. If color is not specified, a color is chosen from an array with default colors.
width	number	1.0	The width of the line in pixels. Only applicable when the line style is `line` or `dot-line`.
radius	number	1.0	The radius of dots in pixels. Only applicable when the line style is `dot` or `dot-line`.
legend	boolean	true	Show or hide the legend for this line. If true, the legend is visible.
visible	boolean	true	Show or hide this line. If false, the line is hidden. See also the option `legend.toggleVisibility`, which creates checkboxes to toggle the visibility of a line in the legend.
textColor	string	#4D4D4D	A string with an HTML color for text labels. Only applicable for data sets of type `area` and `event`.
font	string	10pt arial	The font for text labels. Only applicable for data sets of type `area` and `event`.

Background areas

With the option vAreas, vertical colored background areas can be created. The areas fill the full width of the graph, and are vertically limited between a provided start and end. The following styles are available:

Name	Type	Default	Description
className	string	none	A class name which can be used to give a background area custom css styling.
color	string	none	A string with an HTML color, for example `red`, `#FF0000`, or `rgba(255,0,0,0.1)`.
start	number	null	The start of the background area on the vertical axis. If null (default), the background area will be drawn from the bottom of the graph to the end of the background area.
end	number	null	The end of the background area on the vertical axis. If null (default), the background area will be drawn from the start of the background area to the top of the graph.

Methods

The Graph supports the following methods.

Method	Return Type	Description
draw(data, options)	none	Loads data, sets the provided options, and draws the graph.
getValueRange()	An object with `start` and `end` properties	Returns an object with `start` and `end` properties, which each one of them is a Number object, representing the current value range (vertical axis).
getVisibleChartRange()	An object with `start` and `end` properties	Returns an object with `start` and `end` properties, which each one of them is a Date object, representing the currently visible time range.
redraw()	none	Redraw the graph. Useful after the visible range is changed externally, when data is changed, or when the layout of the webpage changed.
setAutoScale(enable)	none	Enable or disable autoscaling. If `enable` true or not defined, autoscaling is enabled. If false, autoscaling is disabled.
setSize(width, height)	none	Parameters `width` and `height` are strings, containing a new size for the graph. Size can be provided in pixels or in percentages.
setScale(scale, step)	none	Set a custom scale. Automatic scaling will be disabled. For example setScale(SCALE.MINUTES, 5) will result in minor steps of 5 minutes, and major steps of an hour. Available scales: `MILLISECOND`, `SECOND`, `MINUTE`, `HOUR`, `WEEKDAY`, `DAY`, `MONTH`, `YEAR`. As step size, choose for example 1, 2, 5, or 10.
setValueRange (start, end)	none	Sets the (vertical) value range. Accepts two parameters of type Number that represent the start and the end of the range. Set start to null to set the start of the range to the lowest data value; set end to null to set the end of the range to the highest data value. The values must lie within the the range between lowest and highest data value.
setValueRangeAuto()	none	Adjust the (vertical) value range to fit all data.
setVisibleChartRange (start, end)	none	Sets the visible range (zoom) to the specified range. Accepts two parameters of type Date that represent the first and last time of the desired selected visible range. Set start to null to include everything from the earliest date to end; set end to null to include everything from start to the last date.
setVisibleChartRangeNow()	none	Move the visible range such that the current time is located in the center of the graph. This method does not trigger a `rangechange` event.
setVisibleChartRangeAuto()	none	Adjust the visible time range to fit all data. This method does not trigger a `rangechange` event.

Events

The Graph fires events after the visible range changed. The events can be catched by creating a listener. Listeners can be registered using the event messages from the Google API or event messages from the CHAP Links library.

Here an example on how to catch a rangechange event.

function onrangechange(event) {
  alert("The range changed to:\n" +
        "Start: " + event.start + "\n" +
        "End: " + event.end);
}

google.visualization.events.addListener(mygraph, 'rangechange', onrangechange);
// Or, when using the Links Events instead of the Google API:
//   links.events.addListener(mygraph, 'rangechange', onrangechange);

The following events are available.

name	Description	Properties
rangechange	Visible range is changing. Fired repeatedly while the user is modifying the visible time by moving (dragging) the graph, or by zooming (scrolling), but not after a call to `setVisibleChartRange` method. The new range can be retrieved by calling `getVisibleChartRange` method.	`start`: Date. The start time of the visible range. `end`: Date. The end time of the visible range.
rangechanged	Visible range has been changed. Fired once after the user has modified the visible time by moving (dragging) the timeline, or by zooming (scrolling), but not after a call to `setVisibleChartRange` or `setRangeToCurrentTime` methods. The new range can be retrieved by calling `getVisibleChartRange` method.	`start`: Date. The start time of the visible range. `end`: Date. The end time of the visible range.
ready	The chart is ready for external method calls. If you want to interact with the chart, and call methods after you draw it, you should set up a listener for this event before you call the draw method, and call them only after the event was fired.	none

Styles

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

For example, to change the background color of the graph, include the following code inside the head of your html code or in a separate stylesheet.

<style>
div.graph-canvas {
  background-color: yellow;
}
</style>

Class name	Description	Default style
div.graph-frame	The frame contains the canvas. It determines the size and the border of the Graph.	border: 1px solid lightgray;
div.graph-canvas	The canvas is located inside the frame and can be moved and zoomed. All elements (data, axis) are drawn on the canvas. Use this css class for example to give the Graph a background color.
div.graph-axis	The horizontal axis.	border-color: #bfbfbf; border-width: 1px;
div.graph-axis-vertical	The vertical axis.
div.graph-axis-grid	Both horizontal and vertical axis have grid lines.	border-width: 1px;
div.graph-axis-grid-minor	The axis has two grid lines: minor and major. When the scale is in days, each day gets a minor grid line, and each month a major grid line.	border-color: #999999; filter: alpha(opacity=25); opacity: 0.25;
div.graph-axis-grid-major	See `div.graph-axis-grid-major`	border-color: black; filter: alpha(opacity=25); opacity: 0.25;
div.graph-axis-grid-vertical	The grid lines on the vertical axis.	border-color: black; filter: alpha(opacity=25); opacity: 0.25;
div.graph-axis-button-menu	The menu around the zoom buttons on the top left.	left: 10px; top: 10px;
div.graph-axis-button	The zoom buttons on the top left.	color: white; background-color: lightgray; width: 16px; height: 16px; text-align: center; font-size: 13px; border-radius: 2px; margin-right: 5px; margin-bottom: 5px; cursor: pointer;
div.graph-axis-button:hover	The zoom buttons when hovered	background-color: gray;
div.graph-background-area	A vertical background area, created using option `vAreas`.	position: absolute; left: 0; top: 0; width: 100%; height: 0;
div.graph-axis-text	Both `div.graph-axis-text-minor` and `div.graph-axis-text-major` have also the class `div.graph-axis-text`. Use this class to set font styles for both classes at once	padding: 3px; color: #4d4d4d;
div.graph-axis-text-minor	The horizontal axis has two grid types: minor and major. When the scale is in days, each day gets a minor text, and each month a major text
div.graph-axis-text-major	See `div.graph-axis-text-minor`
div.graph-axis-text-vertical	The text on the vertical axis.	padding-right: 10px;
div.graph-legend	The legend. The legend contains oen or multiple items, one for each data line in the graph.	border: 1px solid #bfbfbf;
div.graph-legend-item	Each line has an legend item.	color: #4d4d4d; margin: 5px;
div.graph-legend-item	Each line has an legend item.	color: #4d4d4d; margin: 5px;
div.graph-tooltip-dot	When hovering over a function in the graph, a tooltip is shown. The dot is displayed on datapoint currently hovered.	position: absolute; width: 0; height: 0; margin-left: -4px; margin-top: -4px; border: 4px solid #4d4d4d; border-radius: 4px;
div.graph-tooltip-label	When hovering over a function in the graph, a tooltip is shown. The tooltip	position: absolute; width: 200px; background-color: white; background-color: rgba(255, 255, 255, 0.8); border: 1px solid #bfbfbf; border-radius: 1px; box-shadow: 0 0 15px rgba(128, 128, 128, 0.2); padding: 5px; color: #4d4d4d;
div.graph-tooltip-label td	The label contents use a table for the layout.	vertical-align: top;

Data Policy

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