A simple and elegant solution to displaying hierarchical tree structures (i.e. a Tree View) while levering the best that Twitter Bootstrap has to offer.
Where provided these are the actual versions bootstrap-treeview has been tested against. Other versions should work but you use them as your own risk.
Sorry no support planned for Bootstrap 2.
A full list of dependencies required for the bootstrap-treeview to function correctly.
<!-- Required Stylesheets -->
<link href="./css/bootstrap.css" rel="stylesheet">
<!-- Required Javascript -->
<script src="./js/jquery.js"></script>
<script src="./js/bootstrap-treeview.js"></script>
The component will bind to any existing DOM element.
<div id="tree"></div>
Basic usage may look something like this.
function getTree() {
// Some logic to retrieve, or generate tree structure
return data;
}
$('#tree').treeview({data: getTree()});
In order to define the hierarchical structure needed for the tree it's necessary to provide a nested array of JavaScript objects.
Example
var tree = [
{
text: "Parent 1",
nodes: [
{
text: "Child 1",
nodes: [
{
text: "Grandchild 1"
},
{
text: "Grandchild 2"
}
]
},
{
text: "Child 2"
}
]
},
{
text: "Parent 2"
},
{
text: "Parent 3"
},
{
text: "Parent 4"
},
{
text: "Parent 5"
}
];
At the lowest level a tree node is a represented as a simple JavaScript object. Just one required property text will build you a tree.
{
text: "Node 1"
}
If you want to do more, here's the full node specification
{
text: "Node 1",
icon: "glyphicon glyphicon-stop",
color: "#000000",
backColor: "#FFFFFF",
href: "#node-1",
tags: ['available'],
nodes: [
{},
...
]
}
The following properties are defined to allow node level overrides, such as node specific icons, colours and tags.
String. Mandatory
The text value displayed for a given tree node, typically to the right of the nodes icon.
String. Optional
The icon displayed on a given node, typically to the left of the text.
For simplicity we directly leverage Bootstraps Glyphicons support and as such you should provide both the base class and individual icon class separated by a space.
By providing the base class you retain full control over the icons used. If you want to use your own then just add your class to this icon field.
String. Optional
The foreground color used on a given node, overrides global color option.
String. Optional
The background color used on a given node, overrides global color option.
String. Optional
Used in conjunction with global enableLinks option to specify anchor tag URL on a given node.
Boolean. Default: true
Whether of not a node is selectable in the tree. False indicates the node should act as an expansion heading and will not fire selection events.
Array of Strings. Optional
Used in conjunction with global showTags option to add additional information to the right of each node; using Bootstrap Badges
You can extend the node object by adding any number of additional key value pairs that you require for your application. Remember this is the object which will be passed around during selection events.
Array of Objects. No default, expects data
This is the core data to be displayed by the tree view.
String, any legal color value. Default: inherits from Bootstrap.css.
Sets the default background color used by all nodes, except when overridden on a per node basis in data.
String, any legal color value. Default: inherits from Bootstrap.css.
Sets the border color for the component; set showBorder to false if you don't want a visible border.
String, class name(s). Default: "glyphicon glyphicon-minus" as defined by Bootstrap Glyphicons
Sets the icon to be used on a collapsible tree node.
String, any legal color value. Default: inherits from Bootstrap.css.
Sets the default foreground color used by all nodes, except when overridden on a per node basis in data.
String, class name(s). Default: "glyphicon" as defined by Bootstrap Glyphicons
Sets the icon to be used on a tree node with no child nodes.
Boolean. Default: false
Whether or not to present node text as a hyperlink. The href value of which must be provided in the data structure on a per node basis.
String, class name(s). Default: "glyphicon glyphicon-plus" as defined by Bootstrap Glyphicons
Sets the icon to be used on an expandable tree node.
Boolean. Default: true
Whether or not to highlight the selected node.
String, any legal color value. Default: '#F5F5F5'.
Sets the default background color activated when the users cursor hovers over a node.
Integer. Default: 2
Sets the number of hierarchical levels deep the tree will be expanded to by default.
String, class name(s). Default: "glyphicon glyphicon-stop" as defined by Bootstrap Glyphicons
Sets the default icon to be used on all nodes, except when overridden on a per node basis in data.
String, any legal color value. Default: '#FFFFFF'.
Sets the foreground color of the selected node.
String, any legal color value. Default: '#FFFFFF'.
Sets the background color of the selected node.
Boolean. Default: true
Whether or not to display a border around nodes.
Boolean. Default: false
Whether or not to display tags to the right of each node. The values of which must be provided in the data structure on a per node basis.
Boolean. Default: false
Whether or not to allow multiselection of nodes. Multiselection is working without any additional advanced functionality. It means, that it just simply allowing to select more than one node without any automatic selection of parents, etc.
Removes the tree view component. Removing attached events, internal attached objects, and added HTML elements.
$('#tree').treeview('remove');
Receiver can be either an array to which will be selected nodes added, or a function with will be called with all selected nodes as paramater
var selectedNodes = []
$('#tree').treeview('getSelectedNodes', [selectedNodes]);
or
var callback = function(selectedNodes) {
//do something
}
$('#tree').treeview('getSelectedNodes', [callback]);
Deselect all nodes in the tree view component.
$('#tree').treeview('deselectAllNodes');
Fired when a user selects a node. You can bind to it using either the callback handler or the standard jQuery .on method
Example using options callback handler:
var options = {
onNodeSelected: function(event, node) {
// Your logic goes here
}
}
$('#tree').treeview(options);
and using jQuery .on method
$('#tree').on('nodeSelected', function(event, node) {
// Your logic goes here
});
Copyright 2013 Jonathan Miles
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.