I recently used jsTree in a Google extension to visualize a multi-level hierarchy, where each level contained different entities. For those of you familiar with the agile development process and VersionOne, it is the teams/iterations/stories/tasks hierarchy that looks like this:
Introduction
After reviewing a few free components out there, I decided to go with jsTree, which is a JavaScript-based component in the form of a jQuery plugin. Here are some of the reasons that influenced my decision, in no particular order:
- Very easy to use
- Highly configurable
- Lots of functionality (including checkboxes, if needed)
- Easy to inject into a page from a Google Chrome extension
- Broadly used
- Open source
To get an overview of the supported functionality and see the component in action, or download it, go to http://www.jstree.com/. I will attempt to go over the core functionality here, and dive into some of the more advanced topics, including things that are not officially supported but can be achieved through html/css trickery, in later posts. For my use case, I ended up with the HTML data source, but it also supports JSON and XML. All I needed was a few nested HTML unordered list, looking similar to this:
<div id="selector">
<ul>
<li><a>Team A's Projects</a>
<ul>
<li><a>Iteration 1</a>
<ul>
<li><a>Story A</a></li>
<li><a>Story B</a></li>
<li><a>Story C</a></li>
</ul>
</li>
<li><a>Iteration 2</a>
<ul>
<li><a>Story D</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
All it takes is a single line of code to bring your tree to life!
$("#selector").jstree(); Here is the result:
The result is a fully-functional tree where you can expand nodes to reveal their children. It features some nice sliding effects and is pretty smooth overall.
Customizing your tree Now let’s look at customizing it a little bit. We can start by changing the images for the team and iteration nodes. jsTree allows you to initialize it with settings supplied in the JSON format. First, we’ll need to define some rel attributes for the team and iteration li nodes, like so:
..
...
<ul>
<li rel="team"><a>Team A's Projects</a>
<ul>
<li rel="iteration"><a>Iteration 1</a>
...
Now we can use the values from the rel attributes to associate images to those types.
$("#selector").jstree({
"types" : {
"types" : {
"team" : {
"icon" : {
"image" : "../resources/icons/team.png"
}
},
"iteration" : {
"icon" : {
"image" : "../resources/icons/iteration.png"
}
}
}
},
"plugins" : [ "html_data", "types", "themes" ]
});
Notice the plugins definition at the bottom. jsTree includes a set of plugins that provide functionality and can be activated, if needed. By default, only the core is enabled, but you can enable additional plugins, by listing them in the plugins configuration option. In our case above, the types functionality is enabled by including the types plugins, and the themes plugin enhances the appearance of our tree. To see a list of the plugins that are available, go to the jsTree documentation page.
After adding the configurations above, our tree will display the custom icons for the team and iteration nodes.
Sliding animations
You can control the sliding animations by specifying a duration in the core block of the configuration like so:
"core" : {
"animation" : 0
}
The number is in milliseconds, and 0 means no animations.
Selection in the tree
You can allow elements to be selected in your trees by including the ui plugin. There are a few ui configurations that are worth mentioning here.
You can limit the number of items that can be selected in your tree, by specifying a select_limit. The default is -1, which means no limit.
"ui" : {
"select_limit" : 2
}
Or you can specify nodes that should default to selected by identifying them in your HTML code and adding them to the initially_selected list. Their parents will default to expanded to reveal them.
...
<ul>
<li><a>Iteration 1</a>
<ul>
<li><a>Story A</a></li>
...
</ul>
</li>
<li><a>Iteration 2</a>
<ul>
<li><a>Story D</a></li>
</ul>
</li>
</ul>
...
And the configuration:
"ui" : {
"initially_select" : [ "iteration1", "iteration2" ]
}
By using disable_selecting_children, you can prevent selecting children whose parents have already been selected. This only prevents selecting a child AND its parent, you can still select the child if you deselect its parent. The default is false
"ui" : {
"disable_selecting_children" : "true"
}
You can specify what happens when a parent is collapsed while one or more of its children are selected with selected_parent_close. The default is “select_parent”, but you can also use “false”, which means do nothing, or select_parent, which will cause the parent to become selected.
Perform actions on the tree
Now that we’ve gone over some of the basic configurations that have to do with the selection in your tree, let’s switch gears and look at how to programatically select items, deselect items, etc. I will add a button at the bottom of my tree and wire it with a click event to demonstrate how to interact with the tree.
<div id="selector">...</div>
<button id="actionButton">Do it!</button>
To select an item, we can add the following code:
$("#actionButton").click(function() {
$("#selector").jstree("select_node", $("#iteration1"), true);
});
The first argument can be a DOM node, a jQuery node, or a jQuery selector to an element in your tree. The second argument allows you to enforce the selection limit you may have set in your configuration, by setting it to true. It’s worth mentioning that if the parent of the node you are selecting is collapsed, it will be expanded to reveal your selection.
Deselecting items is just as easy. To deselect a specific node, add:
$("#actionButton").click(function() {
$("#storySelector").jstree("deselect_node", $("#iteration1"));
});
You can deselect all nodes with this:
$("#actionButton").click(function() {
$("#storySelector").jstree("deselect_all");
});
You can specify a context when calling the deselect_all method in order to limit its scope to a subset of nodes in your tree:
$("#actionButton").click(function() {
$("#storySelector").jstree("deselect_all", $("#iteration1"));
});
So, if we had stories selected under both Iteration 1 and Iteration 2, the code above would cause only the one under Iteration 1 to become deselected.
In order to iterate over the selected nodes you can use the following snippet:
$("#actionButton").click(function() {
$.each($("#selector").jstree("get_selected"), function(index, element) {
alert("Index " + index + ": " + $(element).find("a:first").text());
});
});
Similar to the deselect_all method, you can limit the scope of the get_selected by specifying a context as a second argument.
You can also test whether a specific node is selected:
$("#actionButton").click(function() {
alert($("#storySelector").jstree("is_selected", $("#iteration1")));
});
Events
I can’t wrap up the first part of the tutorial if I don’t touch upon event handling. You can listen for events by using bind. Events live in the jstree namespace and are named after the function that triggered them. Note that for some events you will need to bind before creating the instance.
Here is an example that displays a dialog when an item is selected in the tree:
$("#storySelector").bind("select_node.jstree", function(event, data) {
alert($(data.args[0]).text());
}).jstree({
...
});
Conclusion
As you can see from the examples above, jsTree is pretty easy to use and configure. We have only scratched the surface with this tutorial, and there is much more to it than the basic operations I’ve covered here, but this should get you off to a good start. I would suggest reading the documentation AND reading up on forums and blogs, as I have found the documentation to be pretty stale. Let me know if there is any particular functionality you want me to cover next and I’ll do my best to do so in future parts to this guide. Until next time!
