Tree tree.js

Usage

The tree provides a categorical selection interface that allows for interaction and selection of nested elements.

Via JavaScript

Call the tree control via JavaScript:

{% highlight js %} dataSource = function(parentData, callback){ //... }; $('#myTree').tree({ dataSource: dataSource }); {% endhighlight %}

Methods

.tree('destroy')
Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup
.tree('selectedItems')
Returns an array containing selected items and associated data
.tree('selectItem', $('#itemId'))
Select the passed in non-folder item in the tree.
.tree('selectFolder', $('#itemId'))
Select the passed in folder item in the tree.
.tree('openFolder', $('#folderId'))
Open the targeted folder
.tree('closeFolder', $('#folderId'))
Close the targeted folder
.tree('toggleFolder', $('#folderId'))
Toggle the targeted folder (opened or closed)
.tree('closeAll')
Close all folders (collapse the entire tree).
.tree('discloseAll')
Disclose all folders (expand the entire tree).
.tree('discloseVisible')
Disclose only currently visible folders (expand already displayed folders).
.tree('populate', $el)
deprecated Populate the passed in element as if it were a new copy of the instantiated tree. If you call this on an already instantiated tree, it will append all of the items to the tree again. You probably don't want to call this. It will most likely become a private function in the future.
.tree('render')
Calls datasource callback for entire tree. Caution: Does not remove current top-level tree nodes.
.tree('refreshFolder', $('#folderId'))
Removes children and calls datasource callback for specified folder. Does not update data and attributes of the specified folder.
.tree('collapse')
deprecated Same as .tree('closeAll')

Options

You can pass options via data attributes or JavaScript. For data attributes, append the option name to data-. For example, you could use data-selected="".

Name type default description
multiSelect boolean false Allows multiple tree items to be selected at once
cacheItems boolean true Prevents refresh of sub-items when a user closes and reopens a folder
folderSelect boolean true Enables folder selection
ignoreRedundantOpens boolean false Makes openFolder() behave like toggleFolder() instead. Will be deprecated in 3.7.0 when openFolder() will only open the folder instead of toggling
disclosuresUpperLimit integer 0 How many times discloseAll() should be called before a stopping and firing an exceededDisclosuresLimit.fu.tree event. You can force it to continue by listening for this event, setting data-ignore-disclosures-limit to true and starting discloseAll() back up again. This lets you make more decisions about if/when/how/why/how many times discloseAll() will be started back up after it exceeds the limit. 
    $tree.one('exceededDisclosuresLimit.fu.tree', function () {
        $tree.data('ignore-disclosures-limit', true);
        $tree.tree('discloseAll');
    });
disclusuresUpperLimit defaults to 0, so by default this trigger will never fire. The true hard the upper limit is the browser's ability to load new items (i.e. it will keep loading until the browser falls over and dies). On the Fuel UX index.html testing page, the point at which the page became super slow (enough to seem almost unresponsive) was 4, meaning 256 folders had been opened, and 1024 were attempting to open.

Required Data Source

The tree control requires an array of objects in order to create a tree. To determine what tree nodes to create, the tree control uses a callback function named datasource that returns an object with an array named data within it. Items in data will be created when a branch is opened. All tree nodes must be loaded into the control one folder (branch) at a time. However, one can store the entire tree from a single network request, and use the datasource function to parse this combined object and not make additional network requests. The following are reserved keys within each item object.

Key Type Description
text string Required. Text of tree node. *Please note: text replaces and deprecates name
type string Required. Options are folder or item.
attr object Unless it is a reserved key in this table, child keys will be added as attributes to .tree-item or .tree-branch.
attr.cssClass string CSS classes that will be added to .tree-item or .tree-branch
attr.data-icon string CSS classes that will be added to .icon-item
attr.id string Adds id to .tree-item or .tree-branch and adds ARIA support with aria-labelledby.
attr.hasChildren boolean Set to false to hide the chevron next to folders. Defaults to true.

Events

Event Type Description
selected.fu.tree Fires when a user selects an item or folder. Returns an object containing an array of the selected items' jQuery data and the jQuery data of the triggering item. { selected: [array], target: [object] }
deselected.fu.tree Fires when a user deselects an item or folder. Returns an object containing an array of the selected items' jQuery data and the jQuery data of the triggering item. { selected: [array], target: [object] }
loaded.fu.tree Fires when sub-content has been is loaded. Returns the jQuery element of the folder loaded.
updated.fu.tree Fires after selected.fu.tree and deselected.fu.tree events. Returns an object containing an array of selected items' jQuery data, the triggering jQuery element and the event type. { selected: [array], item: [object], eventType: [string] }
disclosedFolder.fu.tree Fires when a user opens a folder. Returns an object containing the jQuery data of the opened folder.
refreshedFolder.fu.tree Fires when a user refreshes a folder. Returns an object containing the jQuery data of the opened folder.
closed.fu.tree Fires when a user closes a folder. Returns an object containing the jQuery data of the closed folder.
closedAll.fu.tree Fires when all folders have finished closing. Returns an object containing an array of closed folders' jQuery data and the tree's jQuery element. The length of reportedClosed will provide the number of folders closed. { reportedClosed: [array], tree: [$element] }
disclosedVisible.fu.tree Fires when all visible folders have disclosed/opened. Returns an object containing an array of disclosed folders' jQuery data and the tree's jQuery element. The length of reportedOpened will provide the number of folders opened. { reportedOpened: [array], tree: [$element] }
exceededDisclosuresLimit.fu.tree Fires when tree halts disclosing due to hitting discloserLimit cap. Returns an object containing { disclosures: [number], tree: [$element] }
disclosedAll.fu.tree Fires when all folders have disclosed. It will not fire if tree stops disclosing due to hitting discloserLimit cap. Returns an object containing { disclosures: [number], tree: [$element] }

All tree events are triggered from the .tree classed element.

{% highlight js %} $('#myTree').on('selected.fu.tree', function (event, data) { // do something with data: { selected: [array], target: [object] } }) {% endhighlight %}

Examples

Tree provides a categorical element selection. Use it to create a file system interface. Wrap the wrapper tree containers with .fuelux .tree

Please note the location of .glyphicon-play outside .tree-branch-name. The control allows folders to be selected by default unless the folderSelect option is set to false, which then requires slightly different markup ("Items selectable only," shown further below)

{% highlight html %} {% endhighlight %}

Please note the location of .glyphicon-play inside .tree-branch-name. This markup is used if the folderSelect option is set to false.

{% highlight html %} {% endhighlight %}