Documentation DrasticTreemap

DrasticTreemap 1.2, by DrasticData.

Overview

DrasticTreemap ia a dynamic treemap in flash. A treemap is a method for displaying tree-structured data using nested rectangles. Most treemaps on the internet are static. DrasticTreemap is dynamic in the sense that it smoothly repositions and resizes its items to display a new state. You can configure it to display the items grouped by variables and to use colors as you like. You can manipulate the treemap from javascript and the treemap supports mouse events to interact with the embedding web page. Examples are contained in the distribution and on the web page of DrasticData: http://www.drasticdata.nl/DDHome.php?m=drastictreemap

Embedding DrasticTreemap in your web page

We advise to use swfobject to include the DrasticTreemap Flash component in your web page. Here we show how to call DrasticTreemap with width 300 and height 250 and default values for the rest:

<html><head>
<script src="js/swfobject.js" type="text/javascript"></script>
<script type="text/javascript">
  var flashvars = {};
  var params = {};
  swfobject.embedSWF("DrasticTreemap.swf", "treemap", "300", "250", "10.0.0", "expressInstall.swf", flashvars, params);
</script>
</head>
<body>
<div id="treemap">
  <a href="http://www.adobe.com/go/getflashplayer">
  <img src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif" 
    alt="Get Adobe Flash player" /></a>
</div>
</body>

Configuration file

By default DrasticTreemap will look for a configuration file named DrasticTreemap.xml in the map from where it was called. You may specify a different file to use in the flashvars section of the calling code.

  var flashvars = {
    configFile: "myDrasticTreemap.xml"
  };

Configuration options:

Configuration options are explained in the file DrasticTreemapAllConfigVariables.xml in the release. For completeness we show it here:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration>
	<!-- THE DATA: -->
	<dataFile>DrasticTreemapExampleData100nodes.txt</dataFile> <!-- if absent: DrasticTreemap.txt -->
	<dataFileDelimiter>	</dataFileDelimiter> <!-- if absent: tab delimited -->
	
	<!-- SIZING: if absent, the component will choose the first numeric column, if present -->
	<sizeColumn>var1</sizeColumn>
	
	<!-- 	GROUPING: any number of groupBy tags. The order specifies the grouping order. If absent no grouping -->
	<groupBy>category1</groupBy>
	<groupBy>category2</groupBy>
	
	<!-- LABELS: 
	labelColumn specifies the column to use as labels for leafs. If absent no labels on leaf lavel
	Each labelFormat specifies the format (size, color, alpha, visible) of labels to display on a level.
	If visible="false" for a level they won't be displayed unless you make them visible with the toggleLabels function.
	level 0 applies to leaf nodes
	level 1 applies to parents of leafs
	level 2 applies to parente of parents of leafs etc.-->
	<labelColumn>label</labelColumn> <!-- if absent, no labels -->
	<labelFormat level="1" size="26" color="0xC0C0C0" alpha="0.7"></labelFormat>
	<labelFormat level="2" size="30" color="0x222222" alpha="0.4" visible="false"></labelFormat>
	
	<!-- COLORS: -->
	<colorColumn>category1</colorColumn> <!-- if absent no colors -->
	<color value="A" color="0xFF0000"></color> <!-- for specific values of colorColumn -->
	<color value="B" color="0x00FF00"></color>
	<color value="C" color="0x0000FF"></color>
	
	<!-- TOOLTIPS -->
	<tipTextTitle>Node: {0}</tipTextTitle> <!-- title; {0} will be replaced with value of labelColumn -->
	<!-- columns to display in tooltip. Maximum 6. If none, the first 6 dataColumns will be displayed-->
	<tipTextContentCol>label</tipTextContentCol>
	<tipTextContentCol>var1</tipTextContentCol>
	<tipTextContentCol>var2</tipTextContentCol>
	<tipTextContentCol>var3</tipTextContentCol>
	<tipTextContentCol>category1</tipTextContentCol>
	<tipTextContentCol>category2</tipTextContentCol>
	
	<!-- Various setting -->
	<speed>0.5</speed> <!-- speed of animation in seconds, default 0.8 -->
	<fixedLayout>true</fixedLayout> <!-- if true, nodes will try to keep their relalive positions on recalculating, default: true-->
	<frameWidth>2</frameWidth> <!-- optionally display frames around parent nodes. Default: 0; Caution: the use of frames may slow down treemap calculations!-->
	<leafBorderWidth>1</leafBorderWidth> <!-- width of border around leaf nodes (integer). Default 1-->
	<gradients>true</gradients> <!-- show gradients in leaf nodes, default: true -->

	<!-- callbacks -->
	<onMouseOver>displayname</onMouseOver>
	<onMouseOverColumn>label</onMouseOverColumn>
	<onMouseOut>displayname</onMouseOut>
	<onMouseOutColumn>label</onMouseOutColumn>
	<onClick>displayname</onClick>
	<onClickColumn>label</onClickColumn>
	<onDblClick>displayname</onDblClick>
	<onDblClickColumn>label</onDblClickColumn>

</Configuration>

Data file:

The dataFile contains records. Fields are delimited by a character, by default a tab. The first line of the data file must contains the names of the columns. Numbers should use dots for decimals. An example data file is shown below. More extensive examples are included in the DrasticTreemap release in the Examples map and are also available on the website www.drasticdata.nl

Example data file:

name gender 2006 2007 2008 2009
John	1	300	350	600	700
Jim	1	200	100	50	100
Julie	0	200	400	500	350

Communication between browser and DrasticTreemap Component

Events

The treemap supports mouseover, mouseout, click and doubleclick events. You can specify a javascript function to be called when one of these events fire. This function will be called with a parameter, the value of the column (usually an id) you indicate to be used in the configuration file. Here is how it works:

In the xml configuration file:
  <onclick>displayname</onclick>
  <onClickColumn>label</onClickColumn>
  
In the calling html file:
  <script type="text/javascript">
    function displayname(s) {alert("you clicked on the item with label: " + s);}
  </script>

A more extensive example of the use of events is included in the examples map in the release.

Manipulating the treemap from Javascript

You can manipulate the treemap from the embedding javascript by calling the following functions. All these functions will return true in case of success.

sizeColumn(<columnname>): this function takes one parameter, the name of the column to be used for sizing items.
labelColumn(<columnname>): this function takes one parameter, the name of the column to be used for labeling items.
toggleLabels(<level>): this function takes one parameter, the level for which the labels will be toggled on/off.
colorColumn(<columnname>): this function takes one parameter, the name of the column to be used for coloring items. Coloring will be performed automatically, unless you specify a number of dedicated color values (see above under configuration options).
groupByCols([<columnname1>,<columnname2>,..,<columnnamen>]): this function takes one parameter, which is an array of column names to use for grouping. The order matters. With multiple column names, you can create deeper hierarchies. An empty array indicates no grouping at all, which is the default behaviour for the treemap.

Example of the use of the colorColumn and groupByCols functions:

<html><head>
<script src="js/swfobject.js" type="text/javascript"></script>
<script type="text/javascript">
    var flashvars = {};
    var params = {;
    swfobject.embedSWF("DrasticTreemap.swf", "treemap", "300", "250", "10.0.0", "expressInstall.swf", flashvars, params);
</script>
</head>
<body>
<div id="treemap">
  <a href="http://www.adobe.com/go/getflashplayer">
  <img src="http://www.adobe.com/images/shared/download_buttons/get_flash_player.gif" 
    alt="Get Adobe Flash player" /></a>
</div>
	<a href="javascript:{}" onclick="treemap.colorColumn('category1')">Color by cat1</a><br/>
	<a href="javascript:{}" onclick="treemap.colorColumn('category2')">Color by cat2</a><br/>
	<br/>
	<a href="javascript:{}" onclick="treemap.groupByCols(['category1'])">Group by cat1</a><br/>
	<a href="javascript:{}" onclick="treemap.groupByCols(['category2'])">Group by cat2</a><br/>
	<a href="javascript:{}" onclick="treemap.groupByCols([])">No grouping</a><br/>
</div>
</body>
</html>

Notes

The license applicable to this component and the licenses of the libraries used in the component are included in the file license.txt in the distribution.

Version History

Version 1.2:

Specify width of border of leaf nodes
Gradients on or off

Version 1.1:

Ability to specify the alpha value of labels per level
Ability to toggle labels on/off from javascript per level
Some minor bug fixes

Version 1.0:

First public release