A newer version of this page is available. Switch to the current version.

jQuery TreeMap - Methods

Methods used to control the treemap node.

customize(options)

Customizes the node.

Parameters:
options:

Object

A tile or a group.

Use this method to customize a specific node. Depending on whether the node is a tile or a group, this method accepts either a tile object or a group object.

NOTE
You can specify any fields of the tile or group objects, except the headerHeight field. This restriction exists because the layout of tiles and groups is calculated long before any customization can be applied.

You can call the customize(options) method at any point of the application flow, for example, when the nodes are being rendered. The following code paints the label of a child node in blue or red depending on the node's value.

JavaScript
var treeMapOptions = {
    // ...
    onNodesRendering: function (e) {
        var children = e.node.getAllChildren();
        $.each(children, function(_, node) {
            node.customize({
                label: {
                    font: {
                        color: node.value() > 100 ? 'blue' : 'red'
                    }
                }
            })
        })
    }
};
NOTE
When a node is being drilled down/up, its visual representation is converted from tile to group and back. However, the customizations made in that node by the customize(options) method remain. If you need to revert the appearance of the node to the initial state, call the node's resetCustomization() method.

drillDown()

Drills down into the node.

When the data source has several hierarchical levels, you may need to enable the user to navigate between them. The movement from the higher to the lower hierarchical level is called "drilling down". The movement backwards is called "drilling up". Although not provided out-of-the-box, this capability is easy to implement using the drillDown() and drillUp() methods.

Usually, drilling down is performed when the user clicks a group of tiles in the UI component. For example, the following code shows the onClick event handler where the drillDown() method is called of the clicked node.

JavaScript
var treeMapOptions = {
    // ...
    onClick: function (e) {
        e.node.drillDown();
    }    
};

To implement drilling up, bind another UI component to TreeMap, e.g., Button. When the user clicks the button, the treemap navigates one level up using its drillUp() method. Alternatively, a click on the button may navigate the user straight to the root node using the resetDrillDown() method of the treemap. Note that the following code configures the onClick handler of the button, not of the treemap.

JavaScript
var buttonOptions = {
    // ...
    onClick: function (e) {
        treeMapInstance.drillUp();
        // treeMapInstance.resetDrillDown();
    }    
};

When the user drills up or down, the drill event fires. To handle it, implement the onDrill event handler.

getAllChildren()

Returns all nodes nested in the current node.

Return Value:

Array<TreeMap Node>

Nodes nested in the current node. Each member of this array has fields and methods described in the Node section.

This method allows you to obtain only direct descendants of the current node. To get all its descendants, call the getAllNodes() method.

getAllNodes()

Returns all descendant nodes.

Return Value:

Array<TreeMap Node>

Descendant nodes. Each member of this array has fields and methods described in the Node section.

This method allows you to obtain all descendant nodes without tree traversal. If you need to obtain the direct descendants only, use the getAllChildren() method.

getChild(index)

Gets a specific node from a collection of direct descendants.

Parameters:
index:

Number

The index of the desired node in the array of child nodes.

Return Value:

TreeMap Node

The specific node.

getChildrenCount()

Indicates how many direct descendants the current node has.

Return Value:

Number

The number of direct descendants of the current node. 0 if there are none.

getParent()

Returns the parent node of the current node.

Return Value:

TreeMap Node

The parent node of the current node. null if the parent is the root node.

isActive()

Indicates whether the current node is active.

Return Value:

Boolean

true if the node belongs to the currently displayed collection of nodes; false otherwise.

NOTE
In most cases, you can consider that the isActive() method returns true when the node is visible, and false otherwise. However, there is an exception for the nodes with zero value. Such nodes are invisible, yet their isActive() method returns true.

isHovered()

Indicates whether the node is in the hover state or not.

Return Value:

Boolean

true if the node is in the hover state; false otherwise.

NOTE
When the user pauses on a group, the group changes its style. The tiles belonging to that group also change their style. However, the isHovered() method of the tiles will return false, although visually they have entered the hover state.

isLeaf()

Indicates whether the node is visualized by a tile or a group of tiles.

Return Value:

Boolean

If true, the node is a tile; if false, the node is a group of tiles.

NOTE
When a node is being drilled down/up, its visual representation is converted from tile to group and back. Thus, the isLeaf() method may return different values for the same node at different stages of the application flow.

isSelected()

Indicates whether the node is selected or not.

Return Value:

Boolean

true if the node is selected; false otherwise.

label()

Returns the label of the node.

Return Value:

String

The label of the node.

label(label)

Sets the label to the node.

Parameters:
label:

String

A new label.

Usually, labels are provided by a data source field. To change the label of a specific node, call the label method passing the new text for the label as its parameter.

resetCustomization()

Reverts the appearance of the node to the initial state.

Use this method if you need to revert the initial appearance after customizing it using the customize(options) method.

select(state)

Sets the selection state of a node.

Parameters:
state:

Boolean

Pass true to select the node; false to deselect.

NOTE
If the selectionMode property is set to "single", calling this method with true as the argument selects one node and deselects all the others.

To deselect all nodes at once, call the clearSelection() method.

showTooltip()

Shows the tooltip.

Use this and hideTooltip() methods to change the visibility of the tooltip programmatically.

value()

Gets the raw value of the node.

Return Value:

Number

The raw value of the node.

NOTE
If the node is a group, this method returns the sum total of values of all nested nodes.