By: Jos de Jong, Almende B.V.
Homepage: http://www.almende.com
License: Apache License, Version 2.0
Links Network is an interactive chart to visualize networks. It allows creating nodes, links between the nodes, and interactive packages moving between nodes. Interaction can be real time or can be animated from a set of historical data. The visualization supports custom styles, colors, sizes, images, and more.
The network visualization works smooth on any modern browser for up to a few hundred nodes and connections.
Network is developed as a Google Visualization Chart in javascript, but can also be used without the Google libraries. There is a GWT wrapper available to use the Network in GWT (Google Web Toolkit). It runs on all modern browsers without additional requirements. Network is tested on Firefox 3.6+, Safari 5.0+, Chrome 6.0+, Opera 10.6+, Internet Explorer 9+.
To get started with Network, download network.zip, and unzip the contents in a subfolder network on your site. Examples can be found in the examples directory.
Here a basic network example. 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>Links Network demo</title>
<style>
body {font: 10pt arial;}
</style>
<script type="text/javascript" src="http://www.google.com/jsapi"></script>
<script type="text/javascript" src="../network.js"></script>
<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 a datatable for the nodes.
var nodesTable = new google.visualization.DataTable();
nodesTable.addColumn('number', 'id');
nodesTable.addColumn('string', 'text');
nodesTable.addColumn('string', 'style'); // optional
nodesTable.addRow([1, "Office", "circle"]);
nodesTable.addRow([2, "Main", "circle"]);
nodesTable.addRow([3, "Server 1", "database"]);
nodesTable.addRow([4, "Server 2", "database"]);
nodesTable.addRow([5, "Internet", "circle"]);
nodesTable.addRow([101, "Computer A", undefined]);
nodesTable.addRow([102, "Computer B", undefined]);
nodesTable.addRow([103, "Computer C", undefined]);
nodesTable.addRow([104, "Computer D", undefined]);
nodesTable.addRow([105, "Computer E", undefined]);
// create a datatable for the links between the nodes
var linksTable = new google.visualization.DataTable();
linksTable.addColumn('number', 'from');
linksTable.addColumn('number', 'to');
linksTable.addColumn('number', 'width'); // optional
linksTable.addRow([1, 101, undefined]);
linksTable.addRow([1, 102, 2]);
linksTable.addRow([1, 103, undefined]);
linksTable.addRow([1, 104, undefined]);
linksTable.addRow([1, 105, undefined]);
linksTable.addRow([1, 2, 5]);
linksTable.addRow([2, 3, 3]);
linksTable.addRow([2, 5, 4]);
linksTable.addRow([5, 4, 2]);
// specify options
var options = {
width: "400px",
height: "500px",
stabilize: false, // do not stabilize before displaying
};
// Instantiate our network object.
var network = new links.Network(document.getElementById('mynetwork'));
// Draw our network with the created data and options
network.draw(nodesTable, linksTable, options);
}
</script>
</head>
<body>
<div id="mynetwork"></div>
</body>
</html>
The Network can be used with or without using Google Javascript libraries. The Google libraries provided classes such as DataTable, DataView, and eventlisteners. But the Google libraries cannot be used in an offline environment.
Download the file
network.zip,
and unzip it in your html page such that the files are located in a subfolder network.
Include the google API and the following files in the head of your html code:
<script type="text/javascript" src="http://www.google.com/jsapi"></script> <script type="text/javascript" src="network/network.js"></script>
If you use the google visualization API needs to be loaded in order to use DataTable. If no Google visualization API is used, the network can be drawn after the page has been loaded.
google.load("visualization", "1");
google.setOnLoadCallback(drawVisualization);
function drawVisualization() {
// load data and create the network here
}
The class name of the Network is links.Network
var network = new links.Network(container);After being loaded, the network can be drawn via the function
draw(),
provided with data and options.
network.draw(nodes, links, packages, options);where
nodes, links, and packages are
a DataTable, and options is a name-value map in the
JSON format. Both links and packages are optional.
Network requires two tables with three data tables:
The tables with Links and Packages are optional. The Timeline supports two data types for each of the tables: a Javascript Array or a Google DataTable. Note that the Google API is only available online and cannot be used in an offline environment.
Note that the column labels must match the names listed below, though the order of the columns may differ.
The node table is required for the network visualization.
The table must contain at least a column id.
The table can have extra columns, used to define the type and style of
individual nodes. Values in optional columns can be left undefined
for individual nodes. In that case, the default value will be applied.
A Google DataTable with nodes is constructed as:
var nodesTable = new google.visualization.DataTable();
nodesTable.addColumn('number', 'id');
nodesTable.addColumn('string', 'text'); // optional
// ... optionally add more columns
nodesTable.addRow([1, 'Node 1']);
// ... more data
A JavaScript Array with nodes is constructed as:
var nodesTable = [
];
nodesTable.push({
'id': 1,
'text': 'Node 1'
});
// ... more data
The data columns are defined as:
| Name | Type | Required | Description |
|---|---|---|---|
| group | anytype | no | A group number or name. The type can be number,
string, or an other type. All nodes with the same group get
the same color schema. |
| id | anytype | yes | A unique id for this node. Nodes may not have duplicate id's. Id's do not need to be consecutive. An id is normally a number, but may be any type. |
| image | string | no | Url of an image. Only applicable when the style of the node is
image. |
| radius | number | no | Radius for the node. Applicable for all styles except rect,
circle, and database.
The value of radius will override a value in
column value. |
| style | string | no | Define a drawing style for the node.
Choose from rect (default), circle,
database, image, text,
dot, star, triangle,
triangleDown, and square.
In case of image, a column with name image must
be provided, containing image urls.
The shapes dot, star, triangle,
triangleDown, and square, are scalable.
The size is determined by the columns radius or
value.
When a column text is provided,
this text will be displayed inside the shape in case of styles
rect, circle, and database.
For all other shapes, the text will be displayed right below the shape.
|
| text | string | no | Text to be displayed in the node or under the image of the node.
Multiple lines can be separated by a newline character \n . |
| title | string | no | Title to be displayed when the user hovers over the node. The title can contain HTML code. |
| value | number | no | A value for the node.
The radius of the nodes will be scaled automatically from minimum to
maximum value.
Only applicable when the style of the node is dot.
If a radius is provided for the node too, it will override the
radius calculated from the value. |
| x | number | no | Horizontal position in pixels. The horizontal position of the node will be fixed. The vertical position y may remain undefined. |
| y | number | no | Vertical position in pixels. The vertical position of the node will be fixed. The horizontal position x may remain undefined. |
The table with links must at least contain columns from and
to.
The table can have extra columns, used to define the type and style of
individual links. Values in optional columns can be left undefined
for individual nodes. In that case, the default value will be applied.
A Google DataTable with links is constructed as:
var linksTable = new google.visualization.DataTable();
linksTable.addColumn('number', 'from');
linksTable.addColumn('number', 'to');
// ... optionally add more columns
linksTable.addRow([1, 3]);
// ... more data
A JavaScript Array with links is constructed as:
var linksTable = [];
linksTable.addRow({
'from': 1,
'to': 3
});
// ... more data
The data columns are defined as:
| Name | Type | Required | Description |
|---|---|---|---|
| color | string | no | A HTML color for the link. |
| from | anytype | yes | The id of a node where the link starts. The type must correspond with the type of the node id's. This is normally a number, but can be any type. |
| length | number | no | The length of the link in pixels. |
| style | string | no | Define a drawing style for the link.
Choose from line (default), arrow,
moving-arrows.
|
| title | string | no | Title to be displayed when the user hovers over the link. The title can contain HTML code. |
| to | anytype | yes | The id of a node where the link ends. The type must correspond with the type of the node id's. This is normally a number, but can be any type. |
| value | number | no | A value for the link.
The width of the links will be scaled automatically from minimum to
maximum value.
If a width is provided for the link too, it will override the
width calculated from the value. |
| width | number | no | Width of the line in pixels. The width will
override a specified value, if a value is
specified too. |
The table with packages must at least contain columns from and
to.
The table can have extra columns, used to define the type and style of
individual packages. Values in optional columns can be left undefined
for individual nodes. In that case, the default value will be applied.
There are two types of packages:
progress is provided,
the package is automatically moved from start node to end node, and deleted
once it has reached the end node. The duration can be customized by setting
a value for duration.progress is provided,
the package is positioned at the given progress between start and end node.
The progress can be updated dynamically via the method addPackages,
and can be deleted via the method deletePackage. Manual packages
must have an id specified, in order to be able to update and delete them lateron.
A Google DataTable with automatically animated packages is constructed as:
var packagesTable = new google.visualization.DataTable();
packagesTable.addColumn('number', 'from');
packagesTable.addColumn('number', 'to');
// ... optionally add more columns
packagesTable.addRow([1, 3]);
// ... more data
A Google DataTable with manually animated packages is constructed as:
var packagesTable = new google.visualization.DataTable();
packagesTable.addColumn('number', 'id');
packagesTable.addColumn('number', 'from');
packagesTable.addColumn('number', 'to');
packagesTable.addColumn('number', 'progress');
// ... optionally add more columns
var id = 1;
var progress = 0.2;
packagesTable.addRow([id, 1, 3, progress]);
// ... more data
A JavaScript Array with packages is constructed as:
var packagesTable = [];
packagesTable.addRow({
'from': 1,
'to': 3
});
// ... more data
The data columns are defined as:
| Name | Type | Required | Description |
|---|---|---|---|
| action | string | no | By specifying action, a package can be created or deleted.
Available values are: create (default) or delete.
When a package is created with an id which already exists, the existing
package will be updated. The action property can be used in
combination with timestamp to animate history.
|
| color | string | no | A HTML color for the package. |
| duration | number | no | Duration in seconds the animation of the package moving from start to end node. Only applicable when progress is not provided. |
| from | anytype | yes | The id of a node where the link starts. The type must correspond with the type of the node id's. This is normally a number, but can be any type. |
| id | anytype | yes | A unique id for the package. Packages cannot have duplicate id's. An id is required for packages with manually defined progress, in order to be able to update or delete them lateron. |
| image | string | no | Url of an image. Only applicable when style is image. |
| progress | number | no | A number between 0 and 1 which determines the progress of the package between the start and end node. If progress is defined, the package must also have an id defined. |
| radius | number | no | The radius of the package. Only applicable when style is dot. |
| style | string | no | Define a drawing style for the package.
Choose from dot (default), image,
star, triangle, triangleDown, or
square.
In case of an image, a column with image url must be provided in the table.
|
| title | string | no | Title to be displayed when the user hovers over the package. The title can contain HTML code. |
| to | anytype | yes | The id of a node where the link ends. The type must correspond with the type of the node id's. This is normally a number, but can be any type. |
| timestamp | Date or number | no | The time on which this package is added or removed.
Only applicable in combination with the column action.
When timestamp is provided, a slider with start and stop button is created
to enable playing history.
|
| value | number | no | A value for the package.
The radius of the packages will be scaled automatically from minimum to
maximum value.
Only applicable when the style of the node is dot.
If a parameter radius is provided for the node too,
this will override the radius calculated from the value. |
Options can be used to customize the network. Options are defined as a JSON object. All options are optional.
var options = {
'width': '100%',
'height': '400px',
'links': {
'color': 'red',
'width': 2
}
};
The following options are available.
| Name | Type | Default | Description |
|---|---|---|---|
| backgroundColor | String or Object | "white" | The background color for the main area of the chart. Can be either a simple HTML color string, for example: 'red' or '#00cc00', or an object with the following properties. |
| backgroundColor.stroke | String | "#666" | The color of the chart border, as an HTML color string. |
| backgroundColor.strokeWidth | Number | 1 | The border width, in pixels. |
| backgroundColor.fill | String | "white" | The chart fill color, as an HTML color string. |
| groups | Object | none | It is possible to specify custom styles for groups. Each node assigned a group gets the specified style. See Groups for an overview of the available styles and an example. |
| height | String | "400px" | The height of the network in pixels or as a percentage. |
| links.color | String | "#2B7CE9" | The default color of a link. |
| links.length | Number | 100 | The default length of a link. |
| links.style | String | "line" | The default style of a link.
Choose from line (default), arrow,
moving-arrows. |
| links.width | Number | 1 | The default width of a link. |
| nodes.borderColor | String | "#2B7CE9" | Default border color of the nodes |
| nodes.backgroundColor | String | "#97C2FC" | Default background color of the nodes |
| nodes.highlightColor | String | "#D2E5FF" | Default background color of the node when the node is selected. |
| nodes.fontColor | String | "black" | Default font color for text in the nodes. |
| nodes.fontFace | String | "sans" | Default font face for text in the nodes, for example "verdana" or "arial". |
| nodes.fontSize | Number | 14 | Default font size in pixels for text in the nodes. |
| nodes.group | String | none | Default group for the nodes. |
| nodes.image | String | none | Default image url for the nodes. only applicable with style image. |
| nodes.widthMin | Number | 16 | The minimum width for a scaled image. Only applicable with style image. |
| nodes.widthMax | Number | 64 | The maximum width for a scaled image. Only applicable with style image. |
| nodes.style | String | "rect" | The default style for all nodes.
Choose from rect (default), circle,
database, image, text, dot.
This style can be overridden by a group style, or by a style of an individual node. |
| nodes.radius | Number | 5 | The default radius for a node. Only applicable with style dot. |
| nodes.radiusMin | Number | 5 | The minimum radius for a scaled node. Only applicable with style dot. |
| nodes.radiusMax | Number | 20 | The maximum radius for a scaled node. Only applicable with style dot. |
| packages.color | String | "#2B7CE9" | Default color for all packages |
| packages.duration | Number | 1.0 | Default duration of animated packages in seconds. |
| packages.image | String | none | Default image for all packages.
Style of the packages must be set to image |
| packages.widthMin | Number | 16 | The minimum width for a scaled package. Only applicable with style image. |
| packages.widthMax | Number | 64 | The maximum width for a scaled package. Only applicable with style image. |
| packages.radius | Number | 5 | Default radius for all packages. |
| packages.radiusMin | Number | 5 | The minimum radius for a scaled package. Only applicable with style dot. |
| packages.radiusMax | Number | 20 | The maximum radius for a scaled package. Only applicable with style dot. |
| packages.style | String | "dot" | Default style for all packages.
Choose from dot (default) or image.
In case of an image, a column with image url must be provided in the table. |
| selectable | Boolean | true | If true, nodes in the network can be selected by clicking them, or
by keeping the Shift key down and dragging a selection area around them.
When the Ctrl key is down, the new selection is appended to the
previous selection. If not, the new selection replaces the previous selection. |
| stabilize | Boolean | true | If true, the network is stabilized before displaying it. If false, the nodes move to a stabe position visibly in an animated way. |
| width | String | "400px" | The width of the network in pixels or as a percentage. |
It is possible to specify custom styles for groups of nodes.
Each node having assigned to this group gets the specified style.
The options groups is an object containing one or multiple groups,
identified by a unique string, the groupname.
A group can have the following styles:
var options = {
// ...
'groups': {
'mygroup': {
'style': 'circle',
'borderColor': 'black',
'backgroundColor': 'white',
'fontColor': 'red',
'fontSize': 18,
'highlightColor': 'yellow'
}
// add more groups here
}
};
var nodesTable = new google.visualization.DataTable();
nodesTable.addColumn('number', 'id');
nodesTable.addColumn('string', 'text');
nodesTable.addColumn('string', 'group');
// ... optionally add more columns
nodesTable.addRow([1, 'Node 1', undefined]); // will get the default style
nodesTable.addRow([2, 'Node 2', 'mygroup']); // will get the style from 'mygroup'
// ... more data
The following styles are available for groups:
| Name | Type | Default | Description |
|---|---|---|---|
| borderColor | String | "#2B7CE9" | Border color of the node |
| backgroundColor | String | "#97C2FC" | Background color of the node |
| highlightColor | String | "#D2E5FF" | Background color of the node when the node is selected. |
| image | String | none | Default image for the nodes. Only applicable in combination with
style image. |
| fontColor | String | "black" | Font color of the node. |
| fontFace | String | "sans" | Font name of the node, for example "verdana" or "arial". |
| fontSize | Number | 14 | Font size for the node in pixels. |
| style | String | "rect" | Choose from rect (default), circle,
database, image, text,
dot.
In case of image, a column with name image must be provided, containing
image urls. |
| radius | Number | 5 | Default radius for the node. Only applicable in combination with
styles rect and dot. |
Network supports the following methods.
| Method | Return Type | Description |
|---|---|---|
| addPackages(packages) | none | Dynamically appends packages to the network. Parameter packages contains
a DataTable. Packages can be removed by specifying a value "delete" in
the action column. |
| animationSetAcceleration(acceleration) | none | Set the time acceleration for animation of history. Only applicable when packages with a timestamp are available. When acceleration is 1, history is played in real time. And for example acceleration of 10 will play history then times the speed of real time. |
| animationSetDuration(duration) | none | Duration of the animation in seconds. Only applicable when packages with a timestamp are available. The animation speed is scaled such that the total duration of playing the history equals the set duration. |
| animationSetFramerate(framerate) | none | Set the framerate in frames per second for animation of history. Only applicable when packages with a timestamp are available. |
| animationStart() | none | Start animation of history. Only applicable when packages with a timestamp are available. |
| animationStop() | none | Stop animation of history. Only applicable when packages with a timestamp are available. |
| draw(nodes, links, packages, options) | none | Loads data, sets the provided options, and draws the network. Parameters nodes, links, and packages are a DataTable, and options is a name-value map in the JSON format. Both links and packages are optional and can be left undefined. |
| getSelection() | Array of selection elements | Standard getSelection() implementation.
Returns an array with one or multiple selections. Each selection contains
the property row. The selections are not ordered.
|
| redraw() | none | Redraw the network. Useful after the camera position is changed externally, when data is changed, or when the layout of the webpage changed. |
| setSelection(selection) | none | Standard setSelection(selection) implementation.
selection is an array with selection elements. The visualization
accepts one or multiple selection elements, which must have the property row.
Example usage: network.setSelection([{"row": 3}]);.
|
| setSize(width, height) | none | Parameters width and height are strings,
containing a new size for the visualization. Size can be provided in pixels
or in percentages. |
| start() | none | Start animation. Only applicable when there are animated links or nodes, or when the nodes are not yet moved to a stable position. |
| stop() | none | Stop animation. Only applicable when there are animated links or nodes. |
Network fires events after one or multiple nodes are selected. The event 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 select event.
function onselect() {
var sel = network.getSelection();
var info = 'selected row(s): ';
for (var i = 0; i < sel.length; i++) {
info += sel[i].row + ' ';
}
alert(info);
}
google.visualization.events.addListener(network, 'select', onselect);
// Or, when not using the Google API:
// links.events.addListener(network, 'select', onselect);
The following events are available.
| name | Description | Properties |
|---|---|---|
| select | Fired after the user selects or unselects a node by clicking it,
or when selecting a number of nodes by dragging a selection area
around them. Not fired when the method setSelection
is executed. The corresponding rows in the data table are selected.
The selected rows can be retrieved via the method getSelection.
|
none |
| ready | The network is loaded and ready for external method calls. If you want to interact with the network, 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 |
All code and data are processed and rendered in the browser. No data is sent to any server.