Treant.js - javascript library for drawing tree diagrams

Quick Start Demos

These examples show the Treant.js in use. With the possibilities and combination of CSS and SVG, opportunities are infinite.

Simple company chart

Organizational chart of the company structure along with pictures and basic information about each member.

View Example

Sport results tree

Tennis results are displayed in a classic tree structure. Tree structure is an adequate method of representation for any type of bracketed events.

View Example

Collapsable structure

Every chart may be created collapsible if needed. All animations can be customized to fit the clients desires.

View Example

Evolution tree chart

This is a very simple and effective representation of an evolution branch. It shows the use of scroller.

View Example

Custom colored items

This is a demo displaying how the use of colors can represent each department in the company structure.

View Example

Introduction

About

Treant.js is a Javascript library for createing tree structure charts with the power of HTML, CSS and SVG...

File Structure

Within the download package fo you will find a folder called Treant with the following file stucture. This folder contains all components of the framework needed to get you started.

	
	Treant/
	  ├── Treant.min.js
	  ├── Treant.css
	  ├── vendor/raphael.js
	  ├── perfect-scrollbar/
	  |  ├── jquery.min.js
	  |  ├── jquery.mousewheel.js
	  |  ├── perfect-scrollbar.js
	  |  └── perfect-scrollbar.css
	  ├── examples/
	  |  └── ...
	  └── api-manual/
	     └── ...

Basic HTML Template

Here's a template of an empty HTML5 file containing the integration of Treant's core stylesheet and javascript files:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <title></title>

    <!-- stylesheets -->
    <link rel="stylesheet" href="Treant.css" type="text/css"/>

</head>
<body>
    ...

    <!-- javascript -->
    <script src="vendor/raphael.js"></script>
    <script src="Treant.min.js"></script>
</body>
</html>

Construction & Initialization

Setting up

Treant provides two different standard methods for configuration and constructing of organizational charts.

It is up to you to choose which fits your needs the best!

In the following article, a simple example is given for presentation purposes. The initialization of the Treant library is performed by inserting a simple HTML and JavaScript snippet on your website:

<!-- HTML -->
<div id="tree-simple" style="width:335px; height: 160px"> </div>

/* javascript */
var my_chart = new Treant(simple_chart_config);

The constructor of Treant can take 3 possible parameter. The first is the configuration object (required), which is later described in detail. The second is an optional callback function that is executed as soon as the tree is rendered and ready to be used. The last parameter is also optional and should be the jQuery instance ($) if available. Providing jQuery to Treant extends the functionality and internal efficiencies of the library. The documentation details where jQuery comes into play.
An example of the complete constructor with a test callback and jQuery.

var chart = new Treant(simple_chart_config, function() { alert( 'Tree Loaded' ) }, $ );

The only unknown part of the shown snippet is the variable called simple_chart_config. That variable contains all the information necessary to reneder and visualize the required chart. Luckily, two ways are used for defining this variable. It can either be defined as an Javascript Array or as a Javascript Object known as a JSON structure.

Array approach [ ]

The Array approach is characterized by the need to individually define every node, along with the global config for the Chart object (called config in the example)

Default Markup

config = {
    container: "#tree-simple"
};

parent_node = {
    text: { name: "Parent node" }
};

first_child = {
    parent: parent_node,
    text: { name: "First child" }
};

second_child = {
    parent: parent_node,
    text: { name: "Second child" }
};

simple_chart_config = [
    config, parent_node,
    first_child, second_child
];

Result

Parent node

First child

Second child

JSON approach { }

JSON approach is slightly different. The whole chart config is made as a single Javascript Object with chart and nodeStructure properties.

Default Markup

simple_chart_config = {
    chart: {
        container: "#tree-simple"
    },
    
    nodeStructure: {
        text: { name: "Parent node" },
        children: [
            {
                text: { name: "First child" }
            },
            {
                text: { name: "Second child" }
            }
        ]
    }
};




/**/

Result

Parent node

First child

Second child

As seen from the above example the two approaches are not that much different. The outcome of Treant initialization is the same no matter which approach is used. It is your choice which method you consider best for your needs. A few differences to keep in mind are:

Array

Each node except the root node and config node must have a parent property which references the parent node.
The order of node variables in the final array matters, since the node layout is determined from the given order.

JSON

Two main properties are required: chart and nodeStructure
Nodes are defined in nodeStructure. Each node can have children which are then defined in children property. Property children is an Array which contains other nodes who can also have a children property.
Order of nodes also matters, like in the Array approach.

Performance Hint: JSON approach is known to be a bit faster, since using the Array approach genereates the JSON config before procedeing to chart initalization.

API documentation

The documentation may be divided into two mayor parts.

One part explains the general chart configuration possibilities, and the other focuses on the configuration possibilities available for each individual node.

Treant contructor

Before stating a wider explanation of all the possible chart configurations, it is first required to briefly describe the Treant Javascript constructor which accepts the configuration object with all the data necessary to draw the wanted chart.

`Treant` constructor
parameters	`chart_structure {Array or JSON}` `callback {function} optional` `jQuery {jQuery object} optional`	`chart_structure` is a required parameter. Its detailed definition is explained further down in the API documentation. `callback` (deprecated) is an optional parameter. Function passed as callback will be executed after chart initialization. It is now preferred to use the onTreeLoaded callback which is now part of the chart configuration. `jQuery` is an optional parameter. If jQuery is available simply pass `$` for this parameter. This will provide animation support, ability to get TreeNode class instances directly from the DOM using `.data( 'treenode' );`, and many more features. Usage var my_chart = new Treant( chart_structure, callback, $ );

Treant constructor

parameters

chart_structure {Array or JSON}

callback {function} optional

jQuery {jQuery object} optional

chart_structure is a required parameter. Its detailed definition is explained further down in the API documentation.
callback (deprecated) is an optional parameter. Function passed as callback will be executed after chart initialization. It is now preferred to use the onTreeLoaded callback which is now part of the chart configuration.
jQuery is an optional parameter. If jQuery is available simply pass $ for this parameter. This will provide animation support, ability to get TreeNode class instances directly from the DOM using .data( 'treenode' );, and many more features.

Usage

 var my_chart = new Treant( chart_structure, callback, $ );

As seen above, the chart_structure parameter should be provided for the Treant constructor. Further documentation explains the possible solutions for generating the chart_structure which will eventually give the desired result.

Part 1: General chart API

The first part of the API explains all the properties that can be passed to chart config variable.

What is a chart config variable?

Example: Below is a simple example in Construction & Initialization. In the Array example the config variable and in the JSON example the simple_chart_config.chart property are editable withe the properties listed bellow.

List of properties

Property	Values	Short Description
container {string}	`-` (required)	A string that identifies a HTML element that will contain the organizational chart (nodes and connections). A string should be specified as a jQuery ID selector (ex: `"#some-element-id"`)
callback {object}	onCreateNode {function} `null` onCreateNodeCollapseSwitch {function} `null` onAfterAddNode {function} `null` onBeforeAddNode {function} `null` onAfterPositionNode {function} `null` onBeforePositionNode {function} `null` onToggleCollapseFinished {function} `null` onAfterClickCollapseSwitch {function} `null` onBeforeClickCollapseSwitch {function} `null` onTreeLoaded {function} `null`	Detailed usage and examples coming soon.
rootOrientation {string}	`NORTH` `EAST` `WEST` `SOUTH`	This property specifies the position of the root node, and the orientation of its children which depend on it.
nodeAlign {string}	`CENTER` `TOP` `BOTTOM`	Specifies the vertical alignment of nodes on the same level. Is one node has a bigger height than the others, the ones with the smaller height should be properly vertical aligned.
levelSeparation {number}	`30(px)`	The levelSeparation property defines the separation between chart levels.
siblingSeparation {number}	`30(px)`	The siblingSeparation property defines the separation between two sibling on the same level.
subTeeSeparation {number}	`30(px)`	The siblingSeparation property defines the separation between two neighbor branches of the organizational chart.
hideRootNode {boolean}	`false` `true`	The root node can be hidden by defining this as `true`. Root node should still be defined in the chart structure but it won't be shown.
animateOnInit {boolean}	`false`	Every chart can be animated uppon initialization if this option is set to `true`. For more animation options see chart config animation. (jQuery required)
animateOnInitDelay {number}	`500(ms)`	This option indicates a number of miliseconds before an init animation is triggered.
scrollbar {string}	`native` `fancy` `None`	If the chart container is smaller than the chart content a scrollbar will be shown. There are tree possibilities. Use a native browser scrollbar, use a fancy jquery powered scrollbar or don't use scrollbar at all with the `"None"` property. Usage <!-- include this files if "fancy" is set --> <link href="[path]/perfect-scrollbar.css" rel="stylesheet" type="text/css"/> <script src="[path]/jquery.min.js"></script> <script src="[path]/jquery.mousewheel.js"></script> <script src="[path]/perfect-scrollbar.js"></script>
padding {number}	`15(px)`	If the scrollbar is shown, this defines the padding between the chart structure and the chart container.
connectors {object}	type {string} `curve` `bCurve` `step` `straight` style {object} `stroke: 'black'` `arrow-end: {string}` `cursor: {string}` `fill: {string}` `fill-opacity: {number}` `opacity: {number}` `stroke: {string}` `stroke-dasharray: {string}` `stroke-linecap: {string}` `stroke-opacity: {number}` `stroke-width: {number}` stackIndent {number} `15(px)`	`type` defines which type of connector line should be drawn between a parent node and its children.Several possibilities are available, their appearance is the following: `style` parameter requires you to define an object. Its definition can be found at RaphaelJS documentation under possible parameters section. `stackIndent` is the property which will be applied to stacked children. See `stackChildren` under part 2 of the API.
node {object}	HTMLclass {string} `-` drawLineThrough {boolean} `false` collapsable {boolean} `false` link {object} `target: '_self'`	A string can be entered under `HTMLclass`. That class will be given to each node in the cart along with the default `.node` class. `drawLineThrough` accepts a boolean. If set to `true`, each node will have a connector line drawn through it. A `collapsable` option enables the node to interactively collapse its children. A collapse switch is added to the node. (jQuery required) If you are planning of making a lot of `<a>` nodes then here is the possibility to assign `target="_blank"` to each of those nodes in one blow.
animation {object}	nodeSpeed {number} `450(ms)` nodeAnimation {string} `linear` connectorsSpeed {number} `450(ms)` connectorsAnimation {string} `linear`	How the chart animates can be fully customised. Here, animation speed and animation functions can be set. jQuery is required in oreder for animations to work. `nodeAnimation` accepts one of jquery.easing functions . jquery.easing plugin needs to be included. `connectorsAnimation` accepts one of Raphael.easing_formulas or CSS format: cubic‐bezier(XX, XX, XX, XX) Performance Hint: In order to animate nodes with hardware-accelerated transitions use jquery.transition.js plugin

Part 2: Individual node configuration

The second part explains the properties which can be passed to every single node.

Where do I define node configuration?

Example: Look at the simple example in Construction & Initialization. In the Array example the parent_node, first_child, second_child variables, and in the JSON example, each node in the simple_chart_config.nodeStructure property are editable withe the properties listed bellow.

List of properties

Property	Values	Short Description
text {object}	name {string} or {object} `class: .node-name` `-` title {string} or {object} `class: .node-title` `-` desc {string} or {object} `class: .node-desc` `-` contact {string} or {object} `class: .node-contact` `-` data-* {string} `class: -` `-`	A `text` property can be given to each node. Here you can describe the content of a node in detail. For each `text` property a `<p>` tag will be created inside the node container. Corresponding HTML classes will be given to each created tag so they can be styled what ever way you like. If you pass an object instead off a string, an `<a>` tag will be created instead of `<p>` tag. Usage node = { parent: some_parent, text: { name: "Simple node", title: "One of kind", desc: "A basic example", data-foo: " data Attribute for node", contact: { val: "contact me", href: "http://twitter.com/", target: "_self" } } }
link {object}	href {string} `-` target {string} `-`	By default, each node is created as an absolute positioned `<div>` element. By defining a `link` property, a node is rendered as an `<a>` element instead.
image {string}	`-`	An image can be inserted into a node container. A relative or absolute path to target image needs to be set as `image` parameter. The `<img>` is inserted before the text properties.
innerHTML {string}	`-`	A custom HTML structure can be inserted into a node container. A HTML string needs to be specified in order for this to work. Another usage of this property is to pass a jQuery ID selector. In that case, an element with a given id is found and its copy is used as node structure. Suffix "-copy" is added to the id of the node element.
childrenDropLevel {number}	`-`	If a certain node has children, a `childrenDropLevel` can be defined on it. That property specifies how many levels deeper than normal should children be positioned.
pseudo {boolean}	`-`	A `pseudo` property allows the creation of invisible nodes with no content. Such nodes can have children and all the other desired properties, the only thing to keep in mind is that such nodes have NO content.
connectors {object}	`inherits from chart config.connectors`	Although all the nodes inherit the `connectors` property from the chart config, it can be overridden for a single node by redefining it under node config. See chart config `connectors` for more documentation.
collapsable {boolean}	`inherits from chart config.node.collapsable`	Each node can be meade collapsable. (jQuery required) See chart config `node.collapsable` for more documentation.
collapsed {boolean}	`false`	This option can be set to `true`, if so, effected node is initially collapsed. That node is also considered as `collapsable`. (jQuery required)
HTMLclass {string}	`inherits from chart config.node.HTMLclass`	If specified, all the nodes inherit the HTMLclass from `config.node.HTMLclass`. But with this property, it is possible to give extra classes to individual nodes. See chart config `node.HTMLclass` for more documentation.
HTMLid {string}	`-`	A custom HTML id attribute can be given to each node element by defineing an `id` property.
stackChildren {boolean}	`-`	`stackChildren` property can be set to `true`. If so the children of the target node will be positioned one beneath the other instead of side by side. This propery won't take affect if the node has grandchildren. When set, the appearance is the following:
drawLineThrough {boolean}	`inherits from chart config.node .drawLineThrough`	The inherited property can be overridden or set by defining this property. See chart config `node.drawLineThrough` for more documentation.

Examples

An extra simple example. Just to get you started.

This is a demo displaying how the use of colors can represent each department in the company structure. It is simple and easy to understand. Anyone could easily visualize their departments in this type of chart.

Root nodes are optional and can easily be omitted.

Here is an example that shows how to make an interactive, collapsible chart.

Organizational chart of the company structure along with pictures and basic information about each member.

Tennis results are displayed in a classic tree structure. Tree structure is an adequate method of representation for any type of bracketed events.

Using vendor/raphael.js as a SVG drawing library, all types and styles for connectors are possible.

When having trouble with a big and more complex chart, a good looking scrollbar can be used to access hidden content.

Root node can be positioned in all four mayor directions. A scrollbar is only displayed where needed.

Treant can be SEO friendly. This example shows how a static HTML can be used for node content.

This is a very simple and effective representation of an evolution branch. It shows the use of scroller.

An interactive timeline can be made.

Download

Download Or you can fork the project from Github.