Frontfire documentation

Tree plugin

Version 2.1.0

Frontfire UI provides a hierarchical tree selection control. It looks like a selection box and also allows multiple selection and rearranging items by dragging and dropping. Items can have children and those can be shown or hidden by expanding or collapsing the parent item.

This plugin is only available in the Complete bundle.

Description

A tree contains items that can have child items. The children of an item are displayed with an indentation and can be expanded or collapsed. They can again have child items. Items can be selected by clicking on them. The selected items are highlighted. The tree control is focusable and the selection can be changed with the arrow keys when it has the focus.

The actual (logical) tree items can be of any type. However, their label text and child items must be extractable from each item object. Usually, an item is an object that has properties for the label, children and others like an icon image, together with arbitrary payload properties. The tree will generate HTML elements for each logical item and manage their event handlers to make them clickable and draggable.

The items structure is passed in to the generator function that builds the tree. Further changes to the items must be represented in this items structure and the tree must be notified about changes to update the UI.

Call the tree() plugin method on an element to make it a tree view.

The colours of hovered and selected items can be customised with the CSS variables that start with “--selectable-” or “--tree-”. The border and background can be customised with some of the CSS variables that start with “--textbox-”.

Multiple items may be selected at the same time with the multiSelect option. It handles clicking an item with the Ctrl or Shift key pressed.

Basic example

Selection control

The selected items can be controlled with plugin methods. The getSelectedItems() method returns all selected items. The selectItem() method selects a single item, optionally deselecting all others. The deselectItem() method deselects an item.

When the selection changes (from user interaction or by calling any of these methods), the itemSelected callback function is called.

Selection:

Items updating

To add or remove items to the tree, first the data structure must be updated. The tree methods can only be called to notify the tree about a data change and update its UI elements accordingly. Calling these methods will not change the data itself!

Options

The following options are available:

Name Type Description Default
childrenKey String The object key of the child items for an item. None
doubleClickExpand Boolean Indicates whether an expandable item will be expanded or collapsed when double-clicked. true
dragdrop Boolean Enables drag and drop of items. false
dragHandler Function A function that is called while dragging items. Parameters: dragged items, drop target element None
dropHandler Function A function that is called after a drag&drop operation was completed. Parameters: dragged items, drop target item, drop position None
iconGetter Function A function that returns the icon element for an item. None
isDropTarget Function A function that indicates whether an item is a drop target itself. Parameters: item None
itemDoubleClicked Function A function that is called when an item was double-clicked. Parameters: item None
itemExpanded Function A function that is called when an item was expanded or collapsed. Parameters: item, expandedState (true, false) None
itemHover Function A function that is called when an item was hovered or left. Parameters: item, hoverState (true, false) None
items Array The items of the tree view. []
itemSelected Function A function that is called when an item was selected or deselected. Parameters: item, selectedState (true, false) None
keyHandler Function A function that is called when an unhandled key is pressed. Parameters: event None
labelGetter Function A function that returns the label text for an item. None
multiSelect Boolean Indicates whether multiple items can be selected at the same time. false
singleRoot Boolean Indicates whether a single root item is shown that cannot be collapsed. false
styleGetter Function A function that returns the CSS style text for an item. None

Plugin methods

This plugin provides methods to control the tree view.

deinit

Deinitializes the plugin and removes the tree from the elements.

deselectItem

Deselects an item. If the focus parameter is true, the item is focused.

F("#tree").tree.deselectItem(item);

getSelectedItems

Gets all selected items in the visual order.

F("#tree").tree.getSelectedItems();

hoverItem

Sets or gets the hovered state of an item. If the isHovered parameter is set, the hover state is set according to its value; otherwise, the current state is returned.

Note:
This state is used for highlighting items in the tree, it cannot be used to determine whether the user has currently placed the mouse cursor over an item. Use the callback function in options.itemHover for this purpose instead.

F("#tree").tree.hoverItem(item, true);

insertItem

Inserts a new item into the tree view. The item must already exist in its parent collection. Leave parent unset to insert the item at the root level.

F("#tree").tree.insertItem(item, parentItem);

isItemExpanded

Gets the expanded state of an item.

F("#tree").tree.isItemExpanded(item);

isItemSelected

Determines whether an item is selected. The method returns undefined if the item does not exist in the tree.

F("#tree").tree.isItemSelected(item);

removeItem

Removes the item from the tree view.

F("#tree").tree.removeItem(oldItem);

selectItem

Selects an item and makes sure it’s visible. If the focus parameter is true, the item is also focused. If the keepOtherSelected parameter is not true, all other already selected items are deselected.

F("#tree").tree.selectItem(item, true);

setItemExpanded

Expands or collapses an item. The method returns the new expand state; or undefined, if the state could not be set (e.g. the item does not exist or cannot be expanded).

F("#tree").tree.setItemExpanded(item, true);

updateItem

Updates the item in the tree view.

F("#tree").tree.updateItem(item);

updateView

Updates the entire tree view from the data source, resetting the view state.

F("#tree").tree.updateView();