Treemap.js

Author: Nicolas Garcia Belmonte

License: BSD License

Version: 1.0.8a

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the organization nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY Nicolas Garcia Belmonte ``AS IS’’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Nicolas Garcia Belmonte BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Summary

Treemap.js	Author: Nicolas Garcia Belmonte
TreeUtil	An object containing some common tree manipulation methods.
Functions
prune	Clears all tree nodes having depth greater than maxLevel.
getParent	Returns the parent node of the node having id.
getSubtree	Returns the subtree that matches the given id.
getLeaves	Returns the leaves of the tree.
eachLevel	Iterates on tree nodes which relative depth is less or equal than a specified level.
each	A tree iterator.
loadSubtrees	Appends subtrees to leaves by requesting new subtrees.
TM	Abstract Treemap class.
Config	Treemap configuration.
Properties
tips	initial layout orientation “v” or “h” for vertical/horizontal.
tips	Enables tips for the Treemap
titleHeight	The height of the title.
rootId	The id of the main container box.
offset	Offset distance between nodes.
levelsToShow	Depth of the plotted tree.
Color	Configuration object to add some color to the leaves.
allow	Set this to true if you want to add color to the nodes.
minValue	We need to know the minimum value of the property which will be taken in account to color the leaves.
maxValue	We need to know the maximum value of the property which will be taken in account to color the leaves.
minColorValue	The color to be applied when displaying a min value (RGB format).
maxColorValue	The color to be applied when displaying a max value (RGB format).
Functions
initialize	TM.Squarified and TM.SliceAndDice constructor.
Properties
tree	The JSON tree.
showSubtree	The displayed JSON subtree.
tips	This property will hold the a Mootools Tips instance if specified.
controller	A treemap controller http://blog.thejit.org/?p=8
rootId	Id of the Treemap container
Functions
toStyle	Transforms a JSON into a CSS style string.
leaf	Returns a boolean value specifying if the node is a tree leaf or not.
createBox	Constructs the proper DOM layout from a json node.
plot	Plots a Treemap
headBox	Creates the head div dom element that usually contains the name of a parent JSON tree node.
bodyBox	Creates the body div dom element that usually contains a subtree dom element layout.
contentBox	Creates the content div dom element that usually contains a leaf div dom element or head and body div dom elements.
leafBox	Creates the leaf div dom element that usually contains nothing else.
setColor	A JSON tree node has usually a data property containing an Array of key-value objects.
enter	Sets the elem parameter as root and performs the layout.
out	Takes the parent node of the currently shown subtree and performs the layout.
view	Sets the root of the treemap to the specified Id
resetPath	Removes the .in-path className for all tree dom elements and then adds this className to all ancestors of the given subtree.
initializeBehavior	Binds different methods to dom elements like tips, color changing, adding or removing class names on mouseenter and mouseleave, etc.
loadTree	Loads the subtree specified by id and plots it on the layout container.
TM.SliceAndDice	A JavaScript implementation of the Slice and Dice Treemap algorithm.
Functions
loadFromJSON	Loads the specified JSON tree and lays it on the main container.
compute	Called by loadFromJSON to calculate recursively all node positions and lay out the tree.
TM.Area	Abstract Treemap class containing methods that are common to aspect ratio related algorithms.
Functions
loadFromJSON	Loads the specified JSON tree and lays it on the main container.
computeDim	Computes the dimensions and positions of a group of nodes according to a custom layout row condition.
worstAspectRatio	Calculates the worst aspect ratio of a group of rectangles.
avgAspectRatio	Calculates the worst aspect ratio of a group of rectangles.
layoutLast	Performs the layout of the last computed sibling.
TM.Squarified	A JavaScript implementation of the Squarified Treemap algorithm.
Functions
compute	Called by loadFromJSON to calculate recursively all node positions and lay out the tree.
processChildrenLayout	Computes children real areas and other useful parameters for performing the Squarified algorithm.
squarify	Performs a heuristic method to calculate div elements sizes in order to have a good aspect ratio.
layoutRow	Performs the layout of an array of nodes.
TM.Strip	A JavaScript implementation of the Strip Treemap algorithm.
Functions
compute	Called by loadFromJSON to calculate recursively all node positions and lay out the tree.
processChildrenLayout	Computes children real areas and other useful parameters for performing the Squarified algorithm.
stripify	Performs a heuristic method to calculate div elements sizes in order to have a good compromise between aspect ratio and order.
layoutRow	Performs the layout of an array of nodes.

TreeUtil

An object containing some common tree manipulation methods.

Summary

Functions
prune	Clears all tree nodes having depth greater than maxLevel.
getParent	Returns the parent node of the node having id.
getSubtree	Returns the subtree that matches the given id.
getLeaves	Returns the leaves of the tree.
eachLevel	Iterates on tree nodes which relative depth is less or equal than a specified level.
each	A tree iterator.
loadSubtrees	Appends subtrees to leaves by requesting new subtrees.

Functions

prune

prune: function( tree,
maxLevel )

Clears all tree nodes having depth greater than maxLevel.

Parameters

tree	A JSON tree object. http://blog.thejit.org
maxLevel	An integer specifying the maximum level allowed for this tree. All nodes having depth greater than max level will be deleted.

getParent

getParent: function( tree,
id )

Returns the parent node of the node having id.

Parameters

tree	A JSON tree object. http://blog.thejit.org
id	The id of the child node whose parent will be returned.

getSubtree

getSubtree: function( tree,
id )

Returns the subtree that matches the given id.

Parameters

tree	A JSON tree object. http://blog.thejit.org
id	A node unique identifier.

Returns

A subtree having a root node matching the given id. Returns null if no subtree matching the id is found.

getLeaves

getLeaves: function ( node,
maxLevel )

Returns the leaves of the tree.

Parameters

node	A tree node (which is also a JSON tree object of course). http://blog.thejit.org

Returns

An array having objects with two properties. The node property contains the leaf node. The level property specifies the depth of the node.

eachLevel

eachLevel: function( tree,
initLevel,
toLevel,
action )

Iterates on tree nodes which relative depth is less or equal than a specified level.

Parameters

tree	A JSON tree or subtree. http://blog.thejit.org
initLevel	An integer specifying the initial relative level. Usually zero.
toLevel	An integer specifying a top level. This method will iterate only through nodes with depth less than or equal this number.
action	A function that receives a node and an integer specifying the actual level of the node.

each

each: function( tree,
action )

A tree iterator.

Parameters

tree	A JSON tree or subtree. http://blog.thejit.org
action	A function that receives a node.

loadSubtrees

loadSubtrees: function( tree,
controller )

Appends subtrees to leaves by requesting new subtrees. with the controller.request method.

Parameters

tree	A JSON tree or subtree. http://blog.thejit.org
controller	A controller.

TM

Abstract Treemap class. Squarified and Slice and Dice Treemaps will extend this class.

Config

Treemap configuration. Contains properties to enable customization and proper behavior of treemaps.

Summary

Properties
tips	initial layout orientation “v” or “h” for vertical/horizontal.
tips	Enables tips for the Treemap
titleHeight	The height of the title.
rootId	The id of the main container box.
offset	Offset distance between nodes.
levelsToShow	Depth of the plotted tree.
Color	Configuration object to add some color to the leaves.
allow	Set this to true if you want to add color to the nodes.
minValue	We need to know the minimum value of the property which will be taken in account to color the leaves.
maxValue	We need to know the maximum value of the property which will be taken in account to color the leaves.
minColorValue	The color to be applied when displaying a min value (RGB format).
maxColorValue	The color to be applied when displaying a max value (RGB format).
Functions
initialize	TM.Squarified and TM.SliceAndDice constructor.
Properties
tree	The JSON tree.
showSubtree	The displayed JSON subtree.
tips	This property will hold the a Mootools Tips instance if specified.
controller	A treemap controller http://blog.thejit.org/?p=8
rootId	Id of the Treemap container
Functions
toStyle	Transforms a JSON into a CSS style string.
leaf	Returns a boolean value specifying if the node is a tree leaf or not.
createBox	Constructs the proper DOM layout from a json node.
plot	Plots a Treemap
headBox	Creates the head div dom element that usually contains the name of a parent JSON tree node.
bodyBox	Creates the body div dom element that usually contains a subtree dom element layout.
contentBox	Creates the content div dom element that usually contains a leaf div dom element or head and body div dom elements.
leafBox	Creates the leaf div dom element that usually contains nothing else.
setColor	A JSON tree node has usually a data property containing an Array of key-value objects.
enter	Sets the elem parameter as root and performs the layout.
out	Takes the parent node of the currently shown subtree and performs the layout.
view	Sets the root of the treemap to the specified Id
resetPath	Removes the .in-path className for all tree dom elements and then adds this className to all ancestors of the given subtree.
initializeBehavior	Binds different methods to dom elements like tips, color changing, adding or removing class names on mouseenter and mouseleave, etc.
loadTree	Loads the subtree specified by id and plots it on the layout container.

Properties

tips

initial layout orientation “v” or “h” for vertical/horizontal.

tips

Enables tips for the Treemap

titleHeight

The height of the title. Set this to zero and remove all styles for node classes if you just want to show leaf nodes.

rootId

The id of the main container box. That is, the div that will contain this visualization. This div has to be explicitly added on your page.

offset

Offset distance between nodes. Works better with even numbers. Set this to zero if you only want to show leaf nodes.

levelsToShow

Depth of the plotted tree. The plotted tree will be pruned in order to fit with the specified depth. Useful when using the “request” method on the controller.

Color

Configuration object to add some color to the leaves.

allow

Set this to true if you want to add color to the nodes. Color will be based upon the second “data” JSON object passed to the node. If your node has a “data” property which has at least two key-value objects, color will be based on your second key-value object value.

minValue

We need to know the minimum value of the property which will be taken in account to color the leaves.

maxValue

We need to know the maximum value of the property which will be taken in account to color the leaves.

minColorValue

The color to be applied when displaying a min value (RGB format).

maxColorValue

The color to be applied when displaying a max value (RGB format).

Functions

initialize

initialize: function( controller )

TM.Squarified and TM.SliceAndDice constructor.

Parameters

controller

A treemap controller. http://blog.thejit.org/?p=8

Returns

A new TM.Squarified or TM.SliceAndDice instance.

Properties

tree

The JSON tree. http://blog.thejit.org

showSubtree

The displayed JSON subtree. http://blog.thejit.org

tips

This property will hold the a Mootools Tips instance if specified.

controller

A treemap controller http://blog.thejit.org/?p=8

rootId

Id of the Treemap container

Functions

toStyle

toStyle: function( obj )

Transforms a JSON into a CSS style string.

leaf

leaf: function( tree )

Returns a boolean value specifying if the node is a tree leaf or not.

Parameters

tree	A tree node (which is also a JSON tree object of course). http://blog.thejit.org

Returns

A boolean value specifying if the node is a tree leaf or not.

createBox

createBox: function( json,
coord,
html )

Constructs the proper DOM layout from a json node.

If this node is a leaf, then it creates a leaf div dom element by calling <TM.newLeaf>. Otherwise it creates a content div dom element that contains <TM.newHead> and <TM.newBody> elements.

Parameters

injectTo	A DOM element where this new DOM element will be injected.
json	A JSON subtree. http://blog.thejit.org
coord	A coordinates object specifying width, height, left and top style properties.

plot

plot: function( json )

Plots a Treemap

headBox

headBox: function( json,
coord )

Creates the head div dom element that usually contains the name of a parent JSON tree node.

Parameters

json	A JSON subtree. http://blog.thejit.org
coord	width and height base coordinates

Returns

A new head div dom element that has head as class name.

bodyBox

bodyBox: function( html,
coord )

Creates the body div dom element that usually contains a subtree dom element layout.

Parameters

html	html that should be contained in the body html.

Returns

A new body div dom element that has body as class name.

contentBox

contentBox: function( json,
coord,
html )

Creates the content div dom element that usually contains a leaf div dom element or head and body div dom elements.

Parameters

json	A JSON node. http://blog.thejit.org
coord	An object containing width, height, left and top coordinates.
html	input html wrapped by this tag.

Returns

A new content div dom element that has content as class name.

leafBox

leafBox: function( json,
coord )

Creates the leaf div dom element that usually contains nothing else.

Parameters

json	A JSON subtree. http://blog.thejit.org
coord	base with and height coordinates

Returns

A new leaf div dom element having leaf as class name.

setColor

setColor: function( json )

A JSON tree node has usually a data property containing an Array of key-value objects. This method takes the second key-value object from that array, returning a string specifying a color relative to the value property of that object.

Parameters

json	A JSON subtree. http://blog.thejit.org

Returns

A String that represents a color in hex value.

enter

enter: function( elem )

Sets the elem parameter as root and performs the layout.

Parameters

elem	A JSON subtree. http://blog.thejit.org

out

out: function()

Takes the parent node of the currently shown subtree and performs the layout.

view

view: function( id )

Sets the root of the treemap to the specified Id

Parameters

id	A node identifier

resetPath

resetPath: function( tree )

Removes the .in-path className for all tree dom elements and then adds this className to all ancestors of the given subtree.

Parameters

tree	A tree node (which is also a JSON tree object of course). http://blog.thejit.org

initializeBehavior

initializeBehavior: function ()

Binds different methods to dom elements like tips, color changing, adding or removing class names on mouseenter and mouseleave, etc.

Parameters

_self

A TM.Squarified or TM.SliceAndDice instance.

loadTree

loadTree: function( id )

Loads the subtree specified by id and plots it on the layout container.

Parameters

id	A subtree id.

TM.SliceAndDice

A JavaScript implementation of the Slice and Dice Treemap algorithm.

Go to http://blog.thejit.org to know what kind of JSON structure feeds this object.

Go to http://blog.thejit.org/?p=8 to know what kind of controller this class accepts.

Refer to the Config object to know what properties can be modified in order to customize this object.

The simplest way to create and layout a slice and dice treemap from a JSON object is

var tm = new TM.SliceAndDice();
tm.loadFromJSON(json);

Summary

Functions
loadFromJSON	Loads the specified JSON tree and lays it on the main container.
compute	Called by loadFromJSON to calculate recursively all node positions and lay out the tree.

Functions

loadFromJSON

loadFromJSON: function ( json )

Loads the specified JSON tree and lays it on the main container.

Parameters

json	A JSON subtree. http://blog.thejit.org

compute

compute: function( par,
json,
orientation )

Called by loadFromJSON to calculate recursively all node positions and lay out the tree.

Parameters

par	The parent node of the json subtree.
json	A JSON subtree. http://blog.thejit.org
orientation	The current <Layout> orientation. This value is switched recursively.

TM.Area

Abstract Treemap class containing methods that are common to aspect ratio related algorithms.

Summary

Functions
loadFromJSON	Loads the specified JSON tree and lays it on the main container.
computeDim	Computes the dimensions and positions of a group of nodes according to a custom layout row condition.
worstAspectRatio	Calculates the worst aspect ratio of a group of rectangles.
avgAspectRatio	Calculates the worst aspect ratio of a group of rectangles.
layoutLast	Performs the layout of the last computed sibling.

Functions

loadFromJSON

loadFromJSON: function ( json )

Loads the specified JSON tree and lays it on the main container.

Parameters

json	A JSON subtree. http://blog.thejit.org

computeDim

computeDim: function( tail,
initElem,
w,
coord,
comp )

Computes the dimensions and positions of a group of nodes according to a custom layout row condition.

Parameters

tail	An array of nodes.
initElem	An array of nodes
w	A fixed dimension where nodes will be layed out.
coord	A coordinates object specifying width, height, left and top style properties.
comp	A custom comparison function

worstAspectRatio

worstAspectRatio: function( ch,
w )

Calculates the worst aspect ratio of a group of rectangles. http://en.wikipedia.org/wiki/Aspect_ratio

Parameters

children	An array of nodes.
w	The fixed dimension where rectangles are being laid out.

Returns

The worst aspect ratio.

avgAspectRatio

avgAspectRatio: function( ch,
w )

Calculates the worst aspect ratio of a group of rectangles. http://en.wikipedia.org/wiki/Aspect_ratio

Parameters

children	An array of nodes.
w	The fixed dimension where rectangles are being laid out.

Returns

The worst aspect ratio.

layoutLast

layoutLast: function( ch,
w,
coord )

Performs the layout of the last computed sibling.

Parameters

ch	An array of nodes.
w	A fixed dimension where nodes will be layed out.
coord	A coordinates object specifying width, height, left and top style properties.

TM.Squarified

A JavaScript implementation of the Squarified Treemap algorithm.

Go to http://blog.thejit.org to know what kind of JSON structure feeds this object.

Go to http://blog.thejit.org/?p=8 to know what kind of controller this class accepts.

Refer to the Config object to know what properties can be modified in order to customize this object.

The simplest way to create and layout a Squarified treemap from a JSON object is

var tm = new TM.Squarified();
tm.loadFromJSON(json);

Summary

Functions
compute	Called by loadFromJSON to calculate recursively all node positions and lay out the tree.
processChildrenLayout	Computes children real areas and other useful parameters for performing the Squarified algorithm.
squarify	Performs a heuristic method to calculate div elements sizes in order to have a good aspect ratio.
layoutRow	Performs the layout of an array of nodes.

Functions

compute

compute: function( json,
coord )

Called by loadFromJSON to calculate recursively all node positions and lay out the tree.

Parameters

parent	The parent node of the json subtree.
json	A JSON subtree. http://blog.thejit.org
coord	A coordinates object specifying width, height, left and top style properties.

processChildrenLayout

processChildrenLayout: function( par,
ch,
coord )

Computes children real areas and other useful parameters for performing the Squarified algorithm.

Parameters

parent	The parent node of the json subtree.
ch	An Array of nodes
coord	A coordinates object specifying width, height, left and top style properties.

squarify

squarify: function( tail,
initElem,
w,
coord )

Performs a heuristic method to calculate div elements sizes in order to have a good aspect ratio.

Parameters

tail	An array of nodes.
initElem	An array of nodes
w	A fixed dimension where nodes will be layed out.
coord	A coordinates object specifying width, height, left and top style properties.

layoutRow

layoutRow: function( ch,
w,
coord )

Performs the layout of an array of nodes.

Parameters

ch	An array of nodes.
w	A fixed dimension where nodes will be layed out.
coord	A coordinates object specifying width, height, left and top style properties.

TM.Strip

A JavaScript implementation of the Strip Treemap algorithm.

Go to http://blog.thejit.org to know what kind of JSON structure feeds this object.

Go to http://blog.thejit.org/?p=8 to know what kind of controller this class accepts.

Refer to the Config object to know what properties can be modified in order to customize this object.

The simplest way to create and layout a Strip treemap from a JSON object is

var tm = new TM.Strip();
tm.loadFromJSON(json);

Summary

Functions
compute	Called by loadFromJSON to calculate recursively all node positions and lay out the tree.
processChildrenLayout	Computes children real areas and other useful parameters for performing the Squarified algorithm.
stripify	Performs a heuristic method to calculate div elements sizes in order to have a good compromise between aspect ratio and order.
layoutRow	Performs the layout of an array of nodes.

Functions

compute

compute: function( json,
coord )

Called by loadFromJSON to calculate recursively all node positions and lay out the tree.

Parameters

parent	The parent node of the json subtree.
json	A JSON subtree. http://blog.thejit.org
coord	A coordinates object specifying width, height, left and top style properties.

processChildrenLayout

processChildrenLayout: function( par,
ch,
coord )

Computes children real areas and other useful parameters for performing the Squarified algorithm.

Parameters

parent	The parent node of the json subtree.
ch	An Array of nodes
coord	A coordinates object specifying width, height, left and top style properties.

stripify

stripify: function( tail,
initElem,
w,
coord )

Performs a heuristic method to calculate div elements sizes in order to have a good compromise between aspect ratio and order.

Parameters

tail	An array of nodes.
initElem	An array of nodes
w	A fixed dimension where nodes will be layed out.
coord	A coordinates object specifying width, height, left and top style properties.

layoutRow

layoutRow: function( ch,
w,
coord )

Performs the layout of an array of nodes.

Parameters

ch	An array of nodes.
w	A fixed dimension where nodes will be layed out.
coord	A coordinates object specifying width, height, left and top style properties.