TreeList Widget

Since 0.20.0

A list for displaying tree-structured data. This was added in 0.20.0 and has quite a minimal functionality.

Options

data

Type: Array

The initial data for the treelist.

The tree is represented as an Array of items. These are the top-most items in the tree structure. Each item may have a children property that identifies the children of the item.

[
    {
        label: 'Local',
        icon: 'fa fa-rocket',
        children: [
            { label: "child 1"},
            { label: "child 2"}
        ]
    }
]

Each item can have the following properties:

Property Description
label The label for the item.
id (optional) A unique identifier for the item
class (optional) A css class to apply to the item
icon (optional) A css class to apply as the icon, for example "fa fa-rocket".
checkbox (optional) If set, displays a checkbox next to the item.
radio (optional) since 2.1 If set, and checkbox not set, displays a radio box next to the item. The value should be a string used to group the radio buttons.
selected (optional) Sets the initial selected state of the item.
children (optional) Identifies the child items of this one. Can be provided as an array if the children are immediately known, or as a function to get the children asynchronously. See below for details.
expanded (optional) If the item has children, set whether to display the children
deferBuild (optional) Delay building any UI elements for the item’s children until it is expanded for the first time. This can have a significant performance benefit for large data sets.
element (optional) Custom DOM element to be used in place of the node’s label. This is ignored if label is set.

If the children property is provided as a function, that function should accept a single argument of a callback function. That callback function should be called with the array of child items. This allows for the items to be retrieved asynchronously, such as via HTTP request.

children: function(done) {
    $.getJSON('/some/url', function(result) {
        done(result);
    })
}

After the item has been added to the treeList, it is augmented with some additional properties and functions:

Property Description
item.parent The parent item in the tree
item.depth The depth in the tree, with 0 being the root of the tree
item.treeList.container The DOM element containing the item
item.treeList.label The DOM element containing the label
Function Description
item.treeList.remove(detach) Remove the item from the tree. Set detach to true to preserve any event handlers on the item - required if the item is going to be readded elsewhere.
item.treeList.makeLeaf(detachChildElements) Turns an element with children into a leaf node, removing the UI decoration. Set detachChildElements to true to preseve any child element event handlers.
item.treeList.makeParent(children) Make the item a parent item, adding the child items
item.treeList.insertChildAt(item, pos, select) Adds a new item at the desired position, optionally selecting it after doing so
item.treeList.addChild(item, select) Appends a child item, optionally selecting it after doing so
item.treeList.expand(done) Expand the item to show child items, with optional done callback that is called when complete
item.treeList.collapse() Collapse the item to hide its children
item.treeList.sortChildren(sortFunction) Sort the item’s children using the provided sort function. The sort function should match the compareFunction used with Array.sort()
item.treeList.replaceElement(element) Replace the item’s custom DOM element

Methods

data()

Returns the data the treeList is displaying.

If any items had the selected property set on them, its value will reflect the current checkbox state.

data( items )

Sets the data to be displayed by the list.

See the data option for details of the items argument.

$(".input").treeList('data',[{label:"Colours"}]);

empty()

Removes all items from the list.

$(".input").treeList('empty');

show( itemId )

Ensures an item is visible in the list. The argument itemId must correspond with the id property of an item in the list.

Note: This currently only works for the topmost items in the list. It cannot be used to reveal items below the top level of the tree.

$(".input").treeList('show','my-red-item');

Events

treelistselect( event, item )

Triggered when an item is clicked. If the item had the selected property set originally, its value will be updated to reflect the state of the item’s checkbox.

$(".input").on('treelistselect', function(event, item) {
    if (item.selected) {
        // The checkbox is checked
    } else {
        // The checkbox is not checked
    }
} );

treelistmouseout( event, item )

Triggered when the mouse moves out of the item.

$(".input").on('treelistmouseout', function(event, item) { });

treelistmouseover( event, item )

Triggered when the mouse moves over an item.

$(".input").on('treelistmouseover', function(event, item) { });