simpleTree - A jQuery Plugin for Searchable Tree Views
This plugin renders a tree view into any div container.
Example Screenshot
The screenshot displays an example tree with a search box. The user is searching for kera
. All occurrences of the search term in the tree are highlighted. The user has selected the node labeled "Mittelalterliche Glasurkeramik".
Features
- Rendering tree nodes, each with a label, a value and child nodes into any given jQuery div element
- Collapsing and expanding of non-leaf nodes
- Custom indenting and styling
- Toggling visibilty of nodes
- Filtering tree view by providing a search input box; search term is highlighted in matching node labels
- Retrieving, setting and clearing the selected node
- Programmatic scrolling and expanding to any given node
Installation
Add the files simpleTree.js
and simpleTree.css
to your project
simpleTree is available via NPM:
npm install @esciencecenter/simple-tree
Requirements
- jQuery v3 (might also work with earlier versions, not tested)
- A container element in the DOM
Limitations
- All node data must be provided upon initialization
- Nodes cannot be added or removed at runtime
- Only single nodes can be selected
Initialization
To render the tree, simply invoke the simpleTree()
function on the jQuery element.
$('#mytree').simpleTree(options, data);
Arguments:
options
is an object that can be used to override the default simpleTree options. The defaults are as follows:
var _defaults = { // Optionally provide here the jQuery element that you use as the search box for filtering the tree. simpleTree then takes control over the provided box, handling user input searchBox: undefined, // Search starts after at least 3 characters are entered in the search box searchMinInputLength: 3, // Number of pixels to indent each additional nesting level indentSize: 25, // Show child count badges? childCountShow: true, // Symbols for expanded and collapsed nodes that have child nodes symbols: { collapsed: 'â–¶', expanded: 'â–¼' }, // these are the CSS class names used on various occasions. If you change these names, you also need to provide the corresponding CSS class css: { childrenContainer: 'simpleTree-childrenContainer', childCountBadge: 'simpleTree-childCountBadge badge badge-pill badge-secondary', highlight: 'simpleTree-highlight', indent: 'simpleTree-indent', label: 'simpleTree-label', mainContainer: 'simpleTree-mainContainer', nodeContainer: 'simpleTree-nodeContainer', selected: 'simpleTree-selected', toggle: 'simpleTree-toggle' } };
data
is an array of top-level nodes that will always be visible. Each node has the following properties:
label
(string): The node labelvalue
(any): The app's value to identify the nodechildren
(array): An array of child nodes. Can be empty or omitted if this is a leaf nodeexpanded
(boolean, optional): Determines whether the node, if it has children, will be initially displayed as expanded. (default:false
)
An example data
array:
let data = [ { label: 'Animals', value: 'animals', children: [ { label: 'Puppy the dog', value: 'puppy' }, { label: 'Pussy the cat', value: 'pussy' } ] }, { label: 'People', value: 'people', children: [ { label: 'Tom', value: 'tom', children: [ { label: 'Sue', value: 'sue' } ] }, { label: 'Cathy', value: 'cathy' } ] } ];
Methods
The tree object's public method API can be retrieved by calling $('#mytree').data('simpleTree');
The ojbect exposes the following methods, which can be chained unless a return value is mentioned explicitly:
-
getSelectedNode()
: returns the currently selected node object, orundefined
if no node is selected -
setSelectedNode(node)
: makesnode
the selected node -
clearSelection()
: Clears any selection -
getNodeCount()
: Get total count of nodes in the tree -
expandAll()
: Expand all non-leaf nodes -
collapseAll()
: Collapse all non-leaf nodes -
toggleSubtree(node)
: expands or collapses the descenandants ofnode
-
getNodeFromValue(value)
: Returns the node with he correspondingvalue
property -
scrollTo(node)
: Scrolls the tree container to the givennode
-
expandTo(node)
: Makes sure that all ancestor nodes ofnode
are expanded -
isNodeVisible(node)
: Determines whether the ancestry ofnode
is expanded and not hidden viahideNode()
, i.e. the node is rendered and visible somewhere in the container -
showNode(node)
: Shows a previously hiddennode
in the DOM. This only works on nodes that are visible in the tree (i.e.isNodeVisible(node)
would evaluate totrue
) -
hideNode(node)
: Hides a visiblenode
in the DOM. This only works on nodes that are visible in the tree (i.e.isNodeVisible(node)
would evaluate totrue
) -
toggleNodeVisibility(node)
: Toggles the visibility of thenode
by invoking either showNode(node) or hideNode(node) -
traverseTree(callback, [startNode])
: Traverses the tree data using a depth-first search and invokes thecallback
function with the current node as a parameter. The parameterstartNode
can be provided as the starting node for traversal; if omitted, the this method will traverse the whole tree
Events
The simpleTree element fires the following events:
simpleTree:change
is fired when the node selection changes based on user input. The currently selected node is passed along with the event. Note this event is also fired when the node selection is cleared (e.g. byclearSelection()
); the selected node is thenundefined
.
Changelog
See the changelog.
License
simpleTree is licensed under the MIT License.