Events

This section describes events fired by this widget.

click

Fires when the user clicks a node.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
jQueryEvent: jQuery.Event
The jQuery event.
The clicked node.
Cannot be used in themes.

When implementing a handling function, use the object passed to it as the parameter. Among the fields of this object, you can find the clicked node. To learn about node's members that you can use, refer to the description of the Node object.

To handle this event, attach a handler to it using the on(eventName, eventHandler) method. For example, the handler in the following code selects/deselects the clicked node.

JavaScript
// ...
var selectNode = function (e) {
    e.node.select(!e.node.isSelected());
};

treeMapInstance.on('click', selectNode);
See Also

disposing

Fires when the widget is being removed.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element. Available only in the Knockout approach.

Instead, you can use the onDisposing option to handle the event.

See Also

NOTE: This event fires only if the widget is removed using the remove(), empty(), or html() jQuery methods.

drawn

Fires when the widget has finished drawing itself.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
Cannot be used in themes.

drill

Fires when the user drills up or down.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
The current node.
Cannot be used in themes.

When implementing a handling function, use the object passed to it as the parameter. Among the fields of this object, you can find the currently displayed node. To learn about node's members that you can use, refer to the description of the Node object.

The drill event can be used to enable/disable other widgets bound to TreeMap. For example, consider that you have a Button. A click on it drills the TreeMap widget one level up from the current node. But when the root node becomes the current, there is nowhere to drill up. In that case, disable the button in the handler of the drill event.

JavaScript
// ...
var disableBackButton = function (e) {
    if (!e.node.getParent()) // checks whether the node has a parent; if it doesn't, it is the root node
        buttonInstance.option('disabled', true);
    else
        buttonInstance.option('disabled', false);
};

treeMapInstance.on('drill', disableBackButton);

Although not provided out-of-the-box, the drill down capability is easy to implement using the API methods. Learn how to do this from the drillDown() method description.

See Also

exported

Fires after data from the widget is exported.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element. Available only in Knockout and AngularJS approaches.

To perform a custom action after data from the widget is exported, implement a handler for this event. For example, this handler can notify the user that the exporting has been completed. Within this handler, you can use the object passed to it as the parameter.

See Also

exporting

Fires before data from the widget is exported.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
model: Object
Data that is available for binding against the element. Available only in the Knockout approach.
fileName: String
The name of the file to which the widget is about to be exported.
cancel: Boolean
Assign true to this field if you need to prevent exporting.

To perform a custom action before data from the widget is exported, implement a handler for this event. Within this handler, you can use the object passed to it as the parameter. For example, using the cancel field of this object, you can cancel exporting.

See Also

fileSaving

Fires before a file with exported data is saved on the user's local storage.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: jQuery
The widget's container.
fileName: String
The name of the file to be saved.
format: String
The format of the file to be saved.
Possible Values: 'PNG' | 'PDF' | 'JPEG' | 'SVG' | 'GIF'
data: BLOB
Exported data as a BLOB.
cancel: Boolean
Assign true to this field if you need to prevent the file from being saved.

To perform a custom action before a file with exported data is saved on the user's local storage, implement a handler for this event. Within this handler, you can use the object passed to it as the parameter. For example, using the cancel field of this object, you can cancel file saving.

See Also

hoverChanged

Fires when the hover state of a node has been changed.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
The node whose hover state has been changed.
Cannot be used in themes.

When implementing a handling function, use the object passed to it as its parameter. Among the fields of this object, you can find the node whose hover state has been changed.

To identify whether the node was hovered over or hovered out, call its isHovered() method. To identify whether the node is a single tile or a group of tiles, call its isLeaf() method. Other accessible fields and methods of a node are described in the Node section.

See Also

incidentOccurred

Fires when an error or warning appears in a widget.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
target: Object
Information about the occurred incident.

When implementing a handling function for this event, you can access information about the occurred incident using the target field of the function's argument. This information includes the following.

  • id
    Contains the ID of the incident. The full list of IDs can be found in the Errors and Warnings section.
  • type
    Contains the type of the incident. This field equals 'error' for errors or 'warning' for warnings.
  • args
    Contains the argument of the incident's message. The content of this field varies greatly, depending on the incident. For example, it may contain the name of the data source field that was not specified correctly, or the name of the option that was not set properly.
  • text
    Contains the text passed to the browser console. This text includes the content of the args field, if there is any.
  • widget
    Contains the name of the widget that produced the error or warning.
  • version
    Contains the currently used version of the ChartJS library.
See Also

initialized

Fires when the widget is initialized.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
element: jQuery
An HTML element of the widget.

Instead, you can use the onInitialized option to handle the event.

See Also

nodesInitialized

Fires when all nodes in the widget are initialized.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
The root node.
Cannot be used in themes.

Implement a handler for this event to perform certain operations on the node structure. It will be called once - at the beginning of the widget's lifetime.

Within the handler, use the object passed to it as the parameter. Among the fields of this object, you can find the root node. Using the getAllChildren() and getChild(index) of this node, you can access any other node in the widget. To learn about other available members of any node including the root node, refer to the description of the Node object.

See Also

nodesRendering

Fires before nodes will be displayed.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
In most cases, the root node. When drilling down, the node of the highest displayed level.
Cannot be used in themes.

Implement a handler for this event to customize nodes before they will be displayed. This handler will be called each time the collection of active nodes is changed.

Within the handler, you can use the object passed to it as the parameter. Among the fields of this object, you can find the currently displayed node. Using the getAllNodes(), getAllChildren(), getChild(index) and getParent() of this node, you can access any other node in the widget. To learn about other available members of any node, refer to the description of the Node object.

See Also

optionChanged

Fires after an option of the component is changed.

Event Handler Argument:
e: Object
Provides function parameters.
Object structure:
component: Object
Provides access to the widget instance.
name: String
Specifies the name of the option whose value is changed.
fullName: String
Specifies a full name of the option whose value is changed. The full name is formed by concatenating the names of the options that are presented in the hierarchy of the given option. The names are delimited by commas.
value: any
Specifies a new value for the option.
element: jQuery
An HTML element of the widget.
model: Object
Provides access to the data that is available for binding against the element. Available only in the Knockout approach.

Instead, you can use the onOptionChanged option to handle the event.

See Also

selectionChanged

Fires when the selection state of a node has been changed.

Event Handler Argument:
e: Object
Information about the event.
Object structure:
component: Object
The widget instance.
element: Object
The widget's container.
The node whose selection state has been changed.
Cannot be used in themes.

When implementing a handling function, use the object passed to it as its parameter. Among the fields of this object, you can find the node whose selection state has been changed.

To identify whether the node was selected or deselected, call its isSelected() method. To identify whether the node is a single tile or a group of tiles, call its isLeaf() method. Other accessible fields and methods of a node are described in the Node section.

See Also