Event Handling#

The interactive behavior of Wunderbaum is controlled by a set of event handlers. These are defined as properties of the tree object, and are called by the tree whenever a certain event occurs.

const tree = new mar10.Wunderbaum({
  id: "demo",
  element: document.getElementById("demo-tree"),
  source: "get/root/nodes",
  ...
  init: (e) => {
    e.tree.setFocus();
  },
  lazyLoad: function (e) {
    return { url: 'get/child/nodes', params: { parentKey: e.node.key } };
  },
  activate: function (e) {
    alert(`Thank you for activating ${e.node}.`);
  },
  ...
});

The Event Object#

Depending on the event type, the event handler functions can return a value, that is used by the tree to control the default behavior. For example, the beforeActivate event handler can return false to prevent activation of a node.

Some events are sent by the tree, others by a distinct node. A node event always passes a reference to the node object. A tree event does not always pass a node reference.

The event handler functions are called with a single argument, of type WbTreeEventType.

The event object contains the following properties:

e = {
  type: string,         // the event type
  tree: Wunderbaum,     // the tree object
  util: object,         // some useful utility functions
  node: WunderbaumNode, // the node object (if applicable)
  event: Event,         // the original DOM event (if applicable)
  flag: boolean,        // a flag (if applicable)
  error: string,        // an error (if applicable)
  ...                   // additional properties (if applicable)
}

Info

See also the overview of available functions of the utility module.

Event Handlers#

Info

A list of all available events can also be found in the API Reference.

Common event handlers include:

activate(WbActivateEventType) - node event: `e.node` was activated.
beforeActivate(WbActivateEventType) - node event: Return `false` to prevent activation of `e.node`.
beforeExpand(WbExpandEventType) - node event: Return `false` to prevent expansion of `e.node`.
beforeSelect(WbSelectEventType) - node event: Return `false` to prevent (de)selection.
buttonClick(WbButtonClickEventType) - tree event: A column header button was clicked, e.g. sort, filter, or menu. Check `e.command` and `e.info.colId`, ... for details.
Note that the actual implementation of the command must be explicitly provided.
See also Search and Filter for examples.
change(WbChangeEventType) - node event: The `change(e)` callback is called when the user has finished editing a cell. More precisely, it is called when the embedded input, select, or textarea element fired a change event.
click(WbClickEventType) - node event: `e.node` was clicked.
Return `false` to prevent default behavior, e.g. expand/collapse, (de)selection, or activation.
dblclick(WbClickEventType) - node event: `e.node` was double-clicked.
Return `false` to prevent default behavior, e.g. expand/collapse.
deactivate(WbDeactivateEventType) - node event: `e.node` was deactivated.
discard(WbNodeEventType) - node event: `e.node` was discarded from the viewport and its HTML markup removed.
edit.apply(WbEditApplyEventType) - node event: `e.node` title was changed.
edit.beforeEdit(WbNodeEventType) - node event: `e.node` title is about to renamend. Return `false` to prevent renaming.
edit.edit(WbEditEditEventType) - node event: `e.node` just switched to edit mode, an input element was created and populated with the current title.
error(WbErrorEventType) - node event: An error occurred, e.g. during initialization or lazy loading.
expand(WbExpandEventType) - node event: `e.node` was expanded (`e.flag === true`) or collapsed (`e.flag === false`)
focus(WbFocusEventType) - tree event: The tree received or lost focus. Check `e.flag`.
iconBadge(WbIconBadgeEventType) - node event: `e.node` is about to be rendered. We can add a badge to the icon cell here.
Returns WbIconBadgeEventResultType.
init(WbInitEventType) - tree event: Fires when the tree markup was created and the initial source data was loaded. Typical use cases would be activating a node, setting focus, enabling other controls on the page, etc. Also sent if an error occured during initialization (check for `e.error` property).
keydown(WbKeydownEventType) - tree event: Fires when a key was pressed while the tree has focus.
`e.node` is set if a node is currently active.
Return `false` to prevent default navigation.
lazyLoad(WbNodeEventType) - node event: Fires when a node that was marked 'lazy', is expanded for the first time. Typically we return an endpoint URL or the Promise of a fetch request that provides a (potentially nested) list of child nodes.
load(WbNodeEventType) - node event: Fires when data was loaded (initial request, reload, or lazy loading), after the data is applied and rendered.
modifyChild(WbModifyChildEventType) - node event: TODO
receive(WbReceiveEventType) - node event: Fires when data was fetched (initial request, reload, or lazy loading), but before the data is uncompressed, applied, and rendered. Here we can modify and adjust the received data, for example to convert an external response to native Wunderbaum syntax.
render(WbRenderEventType) - node event: Fires when a node is about to be displayed. The default HTML markup is already created, but not yet added to the DOM. Now we can tweak the markup, create HTML elements in this node's column cells, etc.
See also `Custom Rendering` for details.
renderStatusNode(WbRenderEventType) - node event: Same as `render(e)`, but for the status nodes, i.e. `e.node.statusNodeType`.
select(WbSelectEventType) - node event: `e.node` was selected (`e.flag === true`) or deselected (`e.flag === false`)
update(WbRenderEventType) - tree event: Fires when the viewport was updated, after scroling, expanding etc.