Hi! I'm Nicolas and I'm interested in information visualization, JavaScript and web standards. I currently work as a Data Visualization Scientist at Twitter. I wrote PhiloGL, the JavaScript InfoVis Toolkit and V8-GL.

« Feeding JSON tree structures to the JIT

On controllers

Posted in: javascript infovis toolkit

Controllers are a straightforward way to customize the JavaScript infovis toolkit (JIT) visualizations. A controller is a JavaScript object that "implements" an interface. The interface methods will then be called at different stages of the visualization, allowing you to, for example, place labels and add event handlers to them, performing actions before and after the animation, making ajax - calls to load data dynamically to the tree, etc. The controller interface is defined as:

var ControllerInterface = {
 
       onCreateLabel: function (domElement, node) {},

       onPlaceLabel: function (domElement, node) {},

       onBeforePlotLine: function(adj) {},

       onAfterPlotLine: function(adj) {},

       onBeforeCompute: function (node) {},

       onAfterCompute: function () {}

       request: function(nodeId, level, onComplete) {},

 };

where:

onCreateLabel(domElement, node) is a method that receives the label dom element as first parameter, and the homologue JSON tree node as second parameter. This method will only be called on label creation. Note that a JSON tree node is a node from the input tree you provided to the visualization. If you don't know what kind of JSON tree format is used to feed the visualizations, you should take a look at my other post first, feeding JSON tree structures to the JIT. This method proves useful when adding events to the labels used by the JIT.
onPlaceLabel(domElement, node) is a method that receives the label dom element as first parameter and the homologue JSON tree node as second parameter. This method is called each time a label has been placed on the visualization, and thus it allows you to update the labels properties, such as size or position. Note that onPlaceLabel will be triggered after updating positions to the labels. That means that, for example, the left and top css properties are allready updated to match the nodes positions.
onBeforePlotLine(adj) is called right before plotting an edge. It provides an adjacence object adj. This object contains two important properties, adj.nodeFrom and adj.nodeTo which contain the graph nodes connected by this edge. You can also assign extra information in an adjacency object, by using the data property. This can be done when assigning weighted graph JSON structures to the visualizations. To know more about weighted nodes and edges please check this post.
onAfterPlotLine(adj) behaves exactly like onBeforePlotLine except that this method is called right after plotting the adj edge. This method can be useful to restore a lineWidth state you've previously changed onBeforePlotLine.
onBeforeCompute(node) is a method called right before performing all computation and animations to the JIT visualization. In the case of treemaps this method will be called after entering or exiting a tree level. In the case of Hyperbolic trees, RGraphs and Spacetrees, this method will be triggered right before perfoming an animation. For Treemap visualizations, the node parameter corresponds to the root node of the subtree which will be laid out. For the Spacetree, Hypertree and RGraph visualizations, the node parameter corresponds to the actual node being clicked or centered on the canvas.
onAfterCompute() is a method triggered right after all animations or computations for the JIT visualizations ended.
request(nodeId, level, onComplete) is a method only used by the Treemap and Spacetree visualizations. You can use this method to "bufferize" information, so that not all the JSON tree structure is loaded at once. The nodeId parameter is the node actually being requested, the level parameter is the level of the subtree being requested, and the onComplete handler is a function you must call after performing your request. A common structure for the request method could be
```
request: function(nodeId, level, onComplete) {
    var data; 
                //make a request call to fill the data object and on complete do:
    onComplete(nodeId, data);
  },
```

Note that you should not declare any of these methods on your controller object if you are not going to use them. Note also that is not mandatory to provide a controller object to the main classes. You can find some example uses for the controller object at the spacetree, hypertree, treemap and rgraph tutorials. Be sure to know what JSON structure feeds the JIT visualizations before you read the tutorials. Hope it was helpful.

« Feeding JSON tree structures to the JIT

Hypertree quick tutorial »

Comments