The tree explorer API encompasses the TExpl and TNode interfaces. The library provides TExpl implementations, which are instantiated by the library user to display a tree explorer widget on the page. The TNode interface is implemented by node objects provided by the library user, which describe the data the tree displays.
The tree explorer displays navigable visualizations of trees, which are directed acyclic graphs with a single root. A tree is defined by a root node, provided by the library user, which may have child nodes, which may in turn have children, etc. The root node provided by the caller must be a JavaScript object implementing the TNode interface. Nodes have short textual labels and may also have attributes associated with them that affect the visualization in various ways.
Arbitrarily large, even infinite, trees may be navigated, but only part of the tree is visible at any given instant. The widget creates UI elements called panels for each node in the visible part of the tree. The user of the widget navigates by hovering over, clicking, or otherwise activating the panels. As the user navigates the widget, the TExpl implementation will create further panels as necessary, calling the TNode interface methods to learn about the shape of the graph and the relevant attributes of the nodes.
As the user navigates the tree or activates panels, the widget generates events which may be handled by providing callback functions. Event handler callbacks may be provided on node objects to handle things like mouse clicks, or on the tree explorer object to handle events generated by a user's navigation of the tree.
Trees may be visualized in any number of ways, and various visualizations are available as plugins. Visualizations may expose any number of options (colors, sizes, speeds, etc) for the library user to adjust.
Each TNode object provided by the caller must implement getLabel() and must either implement getChildren() or set isLeaf to true.
TNode.getLabel()
TNode.isLeaf
true if this node object represents a leaf node.
If isLeaf is true, getChildren() will never be called.
Note that a leaf node is not necessarily the same as a node with zero children.
For example, in a filesystem browser, leaf nodes might represent files, while an empty directory would be a non-leaf node with zero children.
Leaf nodes may be visualized differently from other nodes.
TNode.getChildren()
The following properties and methods will be added by the implementation to each TNode as the tree is constructed.
TNode.children
TNode.parent
TNode.refresh()
Each visualization implements the TExpl interface. Each visualization provides a constructor which requires two arguments: a visualization options object which specifies any options appropriate to the visualization, and an object implementing the TNode interface representing the root node of the tree. The options object may be empty, in which case default values will be used.
To change between visualizations, only the name of the constructor (and possibly any options) need be changed. Every visualization supports the same TNode node object interface.
Examples:
var options = { /* ... options specific to the ElasticRow visualization ... */ }
var tree = new ElasticRowTree(options, root);
var tree2 = new RadialTree({}, root); /* use an empty options object for the defaults */
See the visualization documentation [which doesn't yet exist] for the options supported by each visualization.
After instantiating the tree explorer object, the user may provide callback functions (event handlers) which will be called as the widget is navigated.
TExpl.onhoverpathchange()
Visualizations must provide the methods and properties shown below, and may provide additional methods.
TExpl.show()
TExpl.hide()
TExpl.hoverPath