Dynatree is a dynamic JavaScript tree view control with support for checkboxes and lazy loading.
Main features:
This document describes release 0.4.
If you are updating from version 0.3 please read the migration hints first.
The 0.3 documentation is still available.
You can download the current dynatree package at
http://code.google.com/p/dynatree/downloads.
It contains everything needed including the source, some documentation and examples.
jQuery is already included, but you can check the jQuery site
for the latest versions of jquery.js and ui.core.js.
This documentation contains script examples and links.
See also the Example Browser for some more advanced live demos.
Let's start with a simple example:
<html>
<head>
<!-- Include the required JavaScript libraries: -->
<script src='jquery/jquery.js' type='text/javascript'></script>
<script src='jquery/ui.core.js' type='text/javascript'></script>
<script src='jquery/jquery.cookie.js' type='text/javascript'></script>
<link rel='stylesheet' type='text/css' href='skin/ui.dynatree.css'>
<script src='jquery.dynatree.js' type='text/javascript'></script>
<!-- Add code to initialize the tree when the document is loaded: -->
<script type='text/javascript'>
$(function(){
// Attach the dynatree widget to an existing <div id="tree"> element
// and pass the tree options as an argument to the dynatree() function:
$("#tree").dynatree({
onActivate: function(dtnode) {
// A DynaTreeNode object is passed to the activation handler
// Note: we also get this event, if persistence is on, and the page is reloaded.
alert("You activated " + dtnode.data.title);
},
persist: true,
children: [ // Pass an array of nodes.
{title: "Item 1"},
{title: "Folder 2", isFolder: true,
children: [
{title: "Sub-item 2.1"},
{title: "Sub-item 2.2"}
]
},
{title: "Item 3"}
]
});
});
</script>
</head>
<body>
<!-- Add a <div> element where the tree should appear: -->
<div id="tree"> </div>
</body>
</html>
As an alternative, it is possible to leave away the children option and
add a <ul> inside the <div id="tree"> tag instead.
See Initializing the tree structure from a <ul> element for an example.
I am going into more details in the following sections.
Dynatree is based on and made for jQuery. If you are not familiar with this, you might also want to check the jQuery documentation.
The tree is initialized in the onload event of the html document. In jQuery this is usually done by passing a function to $(..) :
<head>
<script type='text/javascript'>
$(function(){
[…]
});
</script>
</head>
The dynatree widget is then attached to an empty <div > element with a given ID of 'tree'.
This id can have any value, it only has to match the jQuery selector, in our case '#tree'.
Options are passed to the dynatree() function as a dictionary in curly braces:
$("#tree").dynatree({
[…]
});
Tree options are passed as plain JavaScript objects in curly braces, e.g.
{ … }.
The following script shows the available options.
All options have a reasonable default, so we may only have to pass the onActivate handler.
$("#tree").dynatree({
title: "Dynatree root", // Name of the root node.
rootVisible: false, // Set to true, to make the root node visible.
minExpandLevel: 1, // 1: root node is not collapsible
imagePath: null, // Path to a folder containing icons. Defaults to 'skin/' subdirectory.
children: null, // Init tree structure from this object array.
initId: null, // Init tree structure from a <ul> element with this ID.
initAjax: null, // Ajax options used to initialize the tree strucuture.
autoFocus: true, // Set focus to first child, when expanding or lazy-loading.
keyboard: true, // Support keyboard navigation.
persist: false, // Persist expand-status to a cookie
autoCollapse: false, // Automatically collapse all siblings, when a node is expanded.
clickFolderMode: 3, // 1:activate, 2:expand, 3:activate and expand
activeVisible: true, // Make sure, active nodes are visible (expanded).
checkbox: false, // Show checkboxes.
selectMode: 2, // 1:single, 2:multi, 3:multi-hier
fx: null, // Animations, e.g. null or { height: "toggle", duration: 200 }
// Low level event handlers: onEvent(dtnode, event): return false, to stop default processing
onClick: null, // null: generate focus, expand, activate, select events.
onDblClick: null, // (No default actions.)
onKeydown: null, // null: generate keyboard navigation (focus, expand, activate).
onKeypress: null, // (No default actions.)
onFocus: null, // null: handle focus.
onBlur: null, // null: handle unfocus.
// Pre-event handlers onQueryEvent(flag, dtnode): return false, to stop processing
onQueryActivate: null, // Callback(flag, dtnode) before a node is (de)activated.
onQuerySelect: null, // Callback(flag, dtnode) before a node is (de)selected.
onQueryExpand: null, // Callback(flag, dtnode) before a node is expanded/collpsed.
// High level event handlers
onActivate: null, // Callback(dtnode) when a node is activated.
onDeactivate: null, // Callback(dtnode) when a node is deactivated.
onSelect: null, // Callback(flag, dtnode) when a node is (de)selected.
onExpand: null, // Callback(flag, dtnode) when a node is expanded.
onLazyRead: null, // Callback(dtnode) when a lazy node is expanded for the first time.
ajaxDefaults: { // Used by initAjax option
cache: false, // false: Append random '_' argument to the request url to prevent caching.
dataType: "json" // Expect json format and pass json object to callbacks.
},
strings: {
loading: "Loading…",
loadError: "Load error!"
},
idPrefix: "ui-dynatree-id-", // Used to generate node id's like <span id="ui-dynatree-id-<key>">.
cookieId: "ui-dynatree-cookie", // Choose a more unique name, to allow multiple trees.
cookie: { // Options passed to $.cookie (see jquery.cookie.js)
expires: null, // Days or Date; null: session cookie
path: undefined, // String; Defaults to current page
domain: undefined, // String; Defaults to creator's domain
secure: undefined // Boolean; Defaults to false
},
debugLevel: 1 // 0:quiet, 1:normal, 2:debug
});
Details:
integer, default: 3.boolean, default: false.cookie option.
A tree structure is made of nodes. Every node may in turn contain
a list child nodes.
A dynatree always has exactly one root node, and all top level nodes
of our tree are created as direct descendants.
The root node is usually hidden, so we only see the nodes that we have added.
Dynatree can read it's structure from different sources:
children option is passed, it will be used.
initAjax option is passed, it will be used.
initId option is passed, it will be used.
Methods 1-3 expect a list of node options, as described in the following sections.
Node options are defined as plain JavaScript objects in curly braces, e.g.
{ … }.
Most of the time we pass a list of node options like this
children: [ { … }, { … }, … ].
The follwing snippet shows the attributes that can be used to define a tree node.
There are reasonable default values for all options, so we may only have to pass a title.
children: [
{
title: null, // (required) Displayed name of the node (html is allowed here)
key: null, // May be used with activate(), select(), find(), ...
isFolder: false, // Use a folder icon. Also the node is expandable but not selectable.
isLazy: false, // Call onLazyRead(), when the node is expanded for the first time to allow for delayed creation of children.
tooltip: null, // Show this popup text.
addClass: null, // Class name added to the node's span tag.
icon: null, // (deprecated: consider using addClass) Use a custom image (filename relative to tree.options.imagePath). 'null' for default icon, 'false' for no icon.
activate: false, // Initial active status.
focus: false, // Initial focused status.
expand: false, // Initial expanded status.
select: false, // Initial selected status.
// The following attributes are only valid if passed to some functions:
children: null // Array of child nodes.
// NOTE: we can also add custom attributes here.
// This may then also be used in the onActivate(), onSelect(), or onLazyTree() callbacks.
},
[…]
]
The node options are also passed to the event handlers and can be accessed like this:
onActivate: function(dtnode) {
alert("You activated " + dtnode.data.title);
},
Details:
{ title: "Pretty node", addClass: "customClass1" }
or
<li data="addClass: 'customClass1'">Pretty nodecan be styled using css as
span.customClass1 a { background-color: maroon; color: yellow; }
DynTreeNode.append().
tree.activateKey().ui-dynatree-id-1234.To override the node attribute defaults, modify the structure before initializing dynatree:
<script type='text/javascript'>
$.ui.dynatree.nodedatadefaults["icon"] = false; // Turn off icons by default
$(function(){
$("#tree").dynatree({
rootVisible: false,
[...]
When a node is of type folder, it get's a special folder icon and class name.
We usually use them to hold child nodes.
Also, folders can be expanded by clicking the title text (this behavior
can be controlled using the clickFolderMode option).
Non-folders ('documents') may also contain child nodes.
Clicking on a child node activates it, so we have to click the small [+] icon in front to expand such a document node.
In the quick example above we have already seen how a tree is initialized by passing a
node array with the children option.
$("#tree").dynatree({
children: [ … ],
[…]
});
See also Node options.
Instead of passing an array of data objects, we can pass a url in the initAjax
option that will be used to contact an Ajax webservice.
$("#tree").dynatree({
initAjax: {url: "/ajaxTree",
data: {key: "root", // Optional arguments to append to the url
mode: "all"
}
},
[…]
});
The webservice is expected to return a JSON node list, formatted like this:
[ { ... }, { ... }, ... ].
Because the data request is performed asynchronously, the document will load faster. Dynatree will display a spinning wheel, while waiting for the request to complete.
See Loading child nodes on demand for details.
If the container <div> contains a <ul> element,
the node titles are read from the <li> tags.
If the title contains html markup, it may be better to wrap it inside a span element.
All other node options are specified in the data attribute of a <li> element.
Note that the data attribute is not valid in <li> elements in
some doctypes (HTML 4.01 transitional and Strict and XHTML 1.0 Strict).
Validators will complain about this.
Also, if the id attribute is used to pass a key, it should be
alphanumeric and start with a letter to be compliant.
(This doesn't seem to affect the functionality however.)
Nested <ul> elements are used to build a hierarchical tree structure.
After the <ul> element was parsed, it is removed from the DOM tree.
<head>
<!-- Include the required JavaScript libraries: -->
<script src='jquery/jquery.js' type='text/javascript'></script>
<script src='jquery/ui.core.js' type='text/javascript'></script>
<link rel='stylesheet' type='text/css' href='skin/ui.dynatree.css' >
<script src='jquery.dynatree.js' type='text/javascript'></script>
<!-- Add code to initialize the tree when the document is loaded: -->
<script type='text/javascript'>
$(function(){
$("#tree").dynatree({
onActivate: function(dtnode) {
alert("You activated " + dtnode);
}
});
});
</script>
</head>
<body>
<!-- Add a <div> element where the tree should appear: -->
<div id="tree">
<ul>
<li id="key1" title="Look, a tool tip!">item1 with key and tooltip
<li id="key2" class="selected">item2: selected on init
<li id="key3" class="folder">Folder with some children
<ul>
<li id="key3.1">Sub-item 3.1
<li id="key3.2">Sub-item 3.2
</ul>
<li id="key4" class="expanded">Document with some children (expanded on init)
<ul>
<li id="key4.1">Sub-item 4.1
<li id="key4.2">Sub-item 4.2
</ul>
<li id="key5" class="lazy folder">Lazy folder
</ul>
</div>
</body>
Finally, it is always possible to program the DynaTree and DynaTreeNode objects directly.
See also Programming dynatree.
$(function(){
// Initialize the tree in the onload event
$("#tree").dynatree({
onActivate: function(dtnode) {
alert("You activated " + dtnode);
}
});
// Now get the root node object
var rootNode = $("#tree").dynatree("getRoot");
// Call the DynaTreeNode.append() member function and pass options for the new node
var childNode = rootNode.append({
title: "Child node 1",
tooltip: "This child node was added programmatically.",
isFolder: true
});
//
childNode.append({
title: "Document using a custom icon",
icon: "customdoc1.gif"
});
});
When a user clicks a node, we want to react in some way. So at least we want to implement an onActivate
handler.
All event handlers are passed an instance of DynaTreeNode as argument.
this refers to the node's <span> tag.
The node options can be accessed like this:
onActivate: function(dtnode) {
alert("You activated " + dtnode.data.title);
},
See also Programming dynatree.
The following example handles an activation event by opening a url in a new window.
This assumes, that we have defined an additional custom attribute named
'url' in the node options, like so:
<ul> <li data="url: 'http://jquery.com'">jQuery home <li data="url: 'http://docs.jquery.com'">jQuery docs
or
children: [
{ title: "jQuery home", url: "http://jquery.com" },
{ title: "jQuery docs", url: "http://docs.jquery.com" },
Also, the title of the currently active node is displayed in the <span id='echoActive'> tag.
$("#tree").dynatree({
[…]
onActivate: function(dtnode) {
if( dtnode.data.url )
window.open(dtnode.data.url);
$("#echoActive").text(dtnode.data.title);
},
onDeactivate: function(dtnode) {
$("#echoActive").text("-");
},
[…]
});
The following example writes the title of the currently focused node to the <span id='echoFocused'> element:
$("#tree").dynatree({
[…]
onSelect: function(flag, dtnode) {
if( ! flag )
alert("You deselected node with title " + dtnode.data.title);
var selectedNodes = dtnode.tree.getSelectedNodes();
var selectedKeys = $.map(selectedNodes, function(node){
return node.data.key;
});
alert("Selected keys: " + selectedKeys.join(", "));
},
[…]
});
If we use the cursor keys to walk the tree nodes, the focus changes to the next node, but the active node remains the same unless we use [Space] or [Enter].
Also, when we click on a folder node it is only focused, but not activated.
The following example writes the title of the currently focused node to the <span id='echoFocused'> element:
$("#tree").dynatree({
[…]
onFocus: function(dtnode) {
$("#echoFocused").text(dtnode.data.title);
},
onBlur: function(dtnode) {
$("#echoFocused").text("-");
},
[…]
});
Dynatree supports delayed loading of tree nodes, which means we read the nodes only when the parent is expanded.
To make this happen, we have to
isLazy option to true.
onLazyRead callback to send an Ajax request,
create the child nodes, and set the 'ok' status.
$("#tree").dynatree({
[…]
onLazyRead: function(dtnode){
dtnode.appendAjax({url: "/sendData",
data: {"key": dtnode.data.key, // Optional url arguments
"mode": "all"
},
success: function(dtnode) {
// Called after nodes have been created and the waiting icon was removed.
// 'this' is the options for this Ajax request
},
error: function(dtnode, XMLHttpRequest, textStatus, errorThrown) {
// Called on error, after error icon was created.
},
cache: false // Append random '_' argument to url to prevent caching.
});
},
[…]
});
Because the data request is performed asynchronously, the browser will not
block and is still responsive. Dynatree will display a spinning wheel, while waiting for the request to
complete.
The webservice is expected to return a JSON node list, formatted like this:
[ { ... }, { ... }, ... ]
When the response was received, appendAjax() appends the child
nodes and calls node.setLazyNodeStatus(DTNodeStatus_Ok) to
remove the wait icon.
appendAjax expects one option object argument, as described
in the jQuery.ajax() command.
Note however, that the optional success and error callbacks
pass different arguments and are called after the Dynatree
default processing took place.
The success callback may be used to apply any custom postprocessing,
for example activating a node or binding events.
See Node options for details.
See Initializing the structure from an Ajax response
for a sample to initialize the whole tree with an Ajax request.
The dynatree widget provides a set of plugin methods, that can be called
directly.
For example
$("#tree").dynatree("disable");
However this plugin implementation is based on a class called DynaTree
that holds a set of DynaTreeNode objects.
These classes expose methods that can be accessed for enhanced functionality.
For example:
// Get the DynaTree object instance:
var tree = $("#tree").dynatree("getTree");
// Use it's class methods:
tree.activateKey("key1234");
// Get a DynaTreeNode object instance:
var node = tree.getNodeByKey("key7654");
var rootNode = $("#tree").dynatree("getRoot");
// and use it
node.toggleExpand();
Besides the constructor, that is called like this:
$("#tree").dynatree({
[…]
});
the following methods are directly available from the plugin:
DynaTree object.
DynaTreeNode object of the tree.
DynaTreeNode object that is currently active.null.)
DynaTreeNode objects that are currently
selected.[ ].)
DynaTree class membersactiveVisible option is set, all parents will be expanded as necessary.true, children of selected nodes
are skipped. This may be convenient in selectMode:3 (multi-hier).
node.toDict() for details.
fn(dtnode, data) for all nodes.DynaTreeNode class membersdtnode.data.title or dtnode.data.tooltip.
See also Node options.
activeVisible option is set, all parents will be expanded as necessary.children option to build a hierarchy.children object.
(See also Node options).
children object.setLazyNodeStatus() function to display the result.DTNodeStatus_Loading: show a spinning wheel, with 'loading...' message.
DTNodeStatus_Error: show an error icon and message.
DTNodeStatus_Ok: Remove the status node.
strings.loading and strings.loadError options.
recursive: set to true, to include child nodes.callback: (optional) function to allow modifications.var cb = node.toDict(true, function(dict){
dict.title = "Copy of " + dict.title;
delete dict.key; // prevent duplicate keys
});
fn(dtnode, data) for all child nodes.The follwing code snippets should give an idea on how to use the API.
$("#tree").dynatree("getTree").selectKey("1234");
// or another way:
$("#tree").dynatree("getTree").getNodeByKey("1234").select();
// .. or yet another way:
$("#ui-dynatree-id-1234").attr("dtnode").select();
var dtnode = $("#tree").dynatree("getActiveNode");
if( dtnode )
alert("Currently active: " + dtnode.data.title);
var dtnode = $("#tree").dynatree("getActiveNode");
var childNode = dtnode.append({
title: "My new node",
tooltip: "This folder and all child nodes were added programmatically."
});
Note: instead of passing a single child object, we could also pass an array
of objects.
Also, the children may again contain children attributes, thus
defining a sub tree.
// Bind hover events to the tree's <a> tags:
$("#tree a").hover(function(){
// Find dtnode object for this <a> tag
var dtnode = $(this).parent("[dtnode]").attr("dtnode");
// (...) for example open a tooltip.
}, function(){
// (...) for example remove the tooltip.
});
$("#tree").dynatree("getRoot").visit(function(dtnode){
dtnode.expand(true);
});
// Get a JavaScript object copy of the tree
var dict = $("#tree").dynatree("getTree").toDict();
// ... then use Ajax to send this to your server...
The tree's fonts, colors, and icons are defined using CSS, so changing the appearance is simply a matter of including a custom stylesheet.
<script src='../jquery/jquery.js' type='text/javascript'></script>
<script src='../jquery/ui.core.js' type='text/javascript'></script>
<script src='../src/jquery.dynatree.js' type='text/javascript'></script>
<!-- Include a customized stylesheet: -->
<link href='custom-skin/ui.dynatree.css' rel='stylesheet' type='text/css' >
<script type='text/javascript'>
$(function(){
$("#tree").dynatree({
[…]
});
});
</script>
Changing the appearance and icons of single nodes is done by assigning a custom class:
<ul> <li data="addClass: 'custom1'">Document with custom class
or
children: [
{ title: "Document with custom class", addClass: "custom1" },
we would then add CSS definitions for the new node to our stylesheet:
span.custom1 a
{
background-color: maroon;
color: yellow;
}
span.custom1 span.ui-dynatree-icon
{
background-image: url("doc_with_children.gif");
}
Strings can be translated in the tree options:
$("#tree").dynatree({
[…]
strings: {
loading: "Daten werden geladen…",
loadError: "Fehler beim Laden!"
},
});
I am using the planize plugin
by Nicolas Perriault for the table of contents.
I am using prettify.js
by Mike Samuel for syntax highlighting in the of source code samples.
First of all: this is work in progress.
Any kind of feedback is very welcome :-)