Dynatree documentation

This document describes dynatree version: $Version:$.
Document revision: $Revision:$.
A current version may be found at the project site http://wwwendt.de/tech/dynatree/index.html.

Dynatree is a dynamic JavaScript tree view control with support for checkboxes, drag'n'drop, and lazy loading.

Main features:

Dynatree runs best, when the HTML document is rendered in a strict mode like
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">.
Avoid the quirks mode.

Download

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.

Examples

This documentation contains script examples and links.
See also the Example Browser for some more advanced live demos.

Using the [View source code] link in the Example Browser is probably the best way to learn about Dynatree.

Quick start

Let's start with a simple example:

Try this example...
<html>
<head>
	<!-- Include the required JavaScript libraries: -->
	<script src='jquery/jquery.js' type="text/javascript"></script>
	<script src='jquery/jquery-ui.custom.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(node) {
				// 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 " + node.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.

Initializing the tree

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

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", // Tree's name (only used for debug outpu)
	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 }
	noLink: false, // Use <span> instead of <a> tags for all nodes
	// 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: set focus to node.
	onBlur: null, // null: remove focus from node.

	// 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
	onPostInit: null, // Callback(isReloading, isError) when tree was (re)loaded.
	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/collapsed.
	onLazyRead: null, // Callback(dtnode) when a lazy node is expanded for the first time.
	onCustomRender: null, // Callback(dtnode) before a node is rendered. Return a HTML string to override.
	onCreate: null, // Callback(dtnode, nodeSpan) after a node was rendered for the first time.
	onRender: null, // Callback(dtnode, nodeSpan) after a node was rendered.
	postProcess: null, // Callback(data, dataType) before an Ajax result is passed to dynatree.

	// Drag'n'drop support
	dnd: {
		// Make tree nodes draggable:
		onDragStart: null, // Callback(sourceNode), return true, to enable dnd
		onDragStop: null, // Callback(sourceNode)
		// Make tree nodes accept draggables
		autoExpandMS: 1000, // Expand nodes after n milliseconds of hovering.
		preventVoidMoves: true, // Prevent dropping nodes 'before self', etc.
		revert: false, // true: slide helper back to source if drop is rejected
		onDragEnter: null, // Callback(targetNode, sourceNode, ui, draggable)
		onDragOver: null, // Callback(targetNode, sourceNode, hitMode)
		onDrop: null, // Callback(targetNode, sourceNode, hitMode, ui, draggable)
		onDragLeave: null // Callback(targetNode, sourceNode)
	},
	ajaxDefaults: { // Used by initAjax option
		cache: false, // false: Append random '_' argument to the request url to prevent caching.
		timeout: 0, // >0: Make sure we get an ajax error for invalid URLs
		dataType: "json" // Expect json format and pass json object to callbacks.
	},
	strings: {
		loading: "Loading…",
		loadError: "Load error!"
	},
	generateIds: false, // Generate id attributes like <span id='dynatree-id-KEY'>
	idPrefix: "dynatree-id-", // Used to generate node id's like <span id="dynatree-id-<key>">.
	keyPathSeparator: "/", // Used by node.getKeyPath() and tree.loadKeyPath().
	cookieId: "dynatree", // Choose a more unique name, to allow multiple trees.
	cookie: {
		expires: null // Days or Date; null: session cookie
	},
	// Class names used, when rendering the HTML markup.
	// Note:
	// These settings only apply on initialisation.
	// If only single entries are passed for options.classNames, all other
	// values are still set to default.
	classNames: {
		container: "dynatree-container",
		node: "dynatree-node",
		folder: "dynatree-folder",

		empty: "dynatree-empty",
		vline: "dynatree-vline",
		expander: "dynatree-expander",
		connector: "dynatree-connector",
		checkbox: "dynatree-checkbox",
		nodeIcon: "dynatree-icon",
		title: "dynatree-title",
		noConnector: "dynatree-no-connector",

		nodeError: "dynatree-statusnode-error",
		nodeWait: "dynatree-statusnode-wait",
		hidden: "dynatree-hidden",
		combinedExpanderPrefix: "dynatree-exp-",
		combinedIconPrefix: "dynatree-ico-",
		hasChildren: "dynatree-has-children",
		active: "dynatree-active",
		selected: "dynatree-selected",
		expanded: "dynatree-expanded",
		lazy: "dynatree-lazy",
		focused: "dynatree-focused",
		partsel: "dynatree-partsel",
		lastsib: "dynatree-lastsib"
	},
	debugLevel: 1 // 0:quiet, 1:normal, 2:debug
});

Details:

opts.classNames
Type: dictionary, default: $.ui.dynatree.defaults.classNames.
Override class names, that are used, when rendering the HTML markup.
Typically this will require some customization of the CSS file too.
Note: class names are applied on initialisation only.
Example:
$("#tree1").dynatree({
	checkbox: true,
	// Override class name for checkbox icon:
	classNames: {checkbox: "dynatree-radio"},
	[...]
opts.clickFolderMode
Type: integer, default: 3.
Define, how a mouse click will change a folder status.
  1. Single-clicking a folder title (or pressing the [enter] or [space] key) will activate it.
    In this mode documents and folders behave the same.
  2. Single-clicking a folder title expands the node. The folder cannot be activated.
  3. Single-clicking a folder title will activate and expand it.
opts.persist
Type: boolean, default: false.
True: the tree's expansion, activation, focus and selection state is saved to a session cookie, so reloading the page will restore the status.
Notes: this may not work with lazy nodes.
See cookie option.

Initializing the tree structure

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:

  1. If the children option is passed, it will be used.
  2. Otherwise, if the initAjax option is passed, it will be used.
  3. Otherwise, if the initId option is passed, it will be used.
  4. Otherwise, if the the container <div> element contains a <ul> element, it will be used.
  5. Otherwise, the tree is left empty.
    But we may choose to do so, if we want to modify the tree programmatically.

Methods 1-3 expect a list of node options, as described in the following sections.

Node options

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.
	href: null, // Added to the generated <a> tag.
	icon: null, // Use a custom image (filename relative to tree.options.imagePath). 'null' for default icon, 'false' for no icon.
	addClass: null, // Class name added to the node's span tag.
	noLink: false, // Use <span> instead of <a> tag for this node
	activate: false, // Initial active status.
	focus: false, // Initial focused status.
	expand: false, // Initial expanded status.
	select: false, // Initial selected status.
	hideCheckbox: false, // Suppress checkbox display for this node.
	unselectable: false, // Prevent selection.
	// 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(node) {
	alert("You activated " + node.data.title);
},

Details:

data.activate
If set to true, the node will be initially activated.
data.addClass
Class name that is added to the node's <span> element.
Example:
{ title: "Pretty node", addClass: "customClass1" }
or
<li data="addClass: 'customClass1'">Pretty node
can be styled using css as
span.customClass1 a { background-color: maroon; color: yellow; }
data.children
Array of node options, that are used to generate child nodes.
This option is only valid when passed to certain functions, like DynTreeNode.addChild().
data.expand
If set to true, the node will be initially expanded.
data.focus
If set to true, the node will be initially focused.
data.hideCheckbox
Suppress display of checkbox icon.
It is still possible to (de)select the node using the API, keyboard or initialization data. (The selection state may be visualized by a CSS style.)
See also unselectable.
data.href
Contains the link URL, if the tree was initialized from a <ul> tag:
<div id="tree"><ul>
	<li class="expanded folder">Search engines
	<ul>
		<li><a href="http://www.google.com" target="_self">Google</a>
		<li><a href="http://www.bing.com">Bing</a>
data.icon
Optional name of an image file relative to the image directory.
If null specified, a default image is used depending on the node type (folder or document). This is the default.
If false specified, no image is displayed.
data.isFolder
Marks node as folder (treated as a document otherwise).
See Folders and Documents
data.isLazy
Enables delayed loading of the node contents. When a lazy node is expanded for the first time, the onLazyRead() callback is called.
data.key
Uniquely identifies this node. It is optional, but we need it for some functions like tree.activateKey().
If specified, the node's element id is generated by prepending a prefix like this: dynatree-id-1234.
If not specified, a random key id is generated.
data.select
If set to true, the node will be initially selected.
data.target
See data.href.
data.title
Type: string, default: "".
Displayed name of the node (html markup is allowed here).
data.tooltip
Optional string to display in a popup window when the cursor hovers over the node.
data.unselectable
Prevent (de)selection of this node using API, mouse, and keyboard.
It is still possible, to (de)select this node in the initialization data or indirectly (in multi-hier mode).
See also hideCheckbox.

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,
			[...]

Folders and documents

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.

Initializing the tree structure from an object array

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.

Initializing the tree structure from an Ajax response

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 web service.

$("#tree").dynatree({
	initAjax: {url: "/ajaxTree",
			   data: {key: "root", // Optional arguments to append to the url
					  mode: "all"
					  }
			   },
	[…]
});

The web service is expected to return a valid 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.
See Persistence for lazy trees for a sample on how to combine this with persistence.

Initializing the tree structure from a <ul> element

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. For example

<li data="url: 'http://jquery.com'">jQuery home
<li data="url: 'http://example.com', addClass: 'customClass1'">Example page

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.

Note that <a> elements are recognized:
<li><a href='URL' target='TARGET'>TITLE</a> will result in
node.data.title = TITLE
node.data.href = URL
node.data.target = TARGET

Try this example...
<head>
	<!-- Include the required JavaScript libraries: -->
	<script src='jquery/jquery.js' type="text/javascript"></script>
	<script src='jquery/jquery-ui.custom.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(node) {
				alert("You activated " + node);
			}
		});
	});
	</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>

Initializing the tree structure programmatically

Finally, it is always possible to program the DynaTree and DynaTreeNode objects directly.

See also Programming dynatree.

Try this example...
$(function(){
	// Initialize the tree in the onload event
	$("#tree").dynatree({
		onActivate: function(node) {
			alert("You activated " + node);
		}
	});
	// Now get the root node object
	var rootNode = $("#tree").dynatree("getRoot");
	// Call the DynaTreeNode.addChild() member function and pass options for the new node
	var childNode = rootNode.addChild({
		title: "Child node 1",
		tooltip: "This child node was added programmatically.",
		isFolder: true
	});
	//
	childNode.addChild({
		title: "Document using a custom icon",
		icon: "customdoc1.gif"
	});
});

Handling events

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 Dynatree object.
The node options can be accessed like this:

onActivate: function(node) {
	alert("You activated " + node.data.title);
},

See also Programming dynatree.

DynaTree callbacks

The this context is set to the tree object.
Use tree.isUserEvent(), tree.isInitializing(), and tree.isReloading() to determine who generated this event.
opts.onActivate(node)
Called when a node was activated.
onActivate: function(node) {
	if(node.tree.isUserEvent()){
		[...] // Do something after user activated the node (using mouse or keyboard)
	}
}
opts.onBlur(node)
Called when a node lost the focus.
opts.onClick(node, event)
Called when a node was clicked.
Use node.getEventTargetType(event) to check which area was clicked.
Return false to prevent default processing (setting focus, activate the node, expand folders, etc.).
onClick: function(node, event) {
	if(node.getEventTargetType(event) == "title"){
		[...] // Handle the click event
		return false;// Prevent default processing
	}
}
opts.onCreate(node, nodeSpan)
Called after a node's HTML tag was created, i.e. when a node becomes visible for the first time.
This callback may be used to bind events or widgets for nodes that are created lazily or programatically.
onCreate: function(node, nodeSpan) {
	$(span).click(function(e){
		alert('clicked ' + node);
	});
}
(Note that the use of jQuery live events may often be a more efficient solution.)
See also opts.onRender.
opts.onCustomRender(node)
Called before a node's title HTML tag will be created. This happens when a node becomes visible for the first time.
This callback may return a string that will be used instead of the default HTML markup.
onCustomRender: function(node) {
	return "<span class='dynatree-title'>SPAM</span>"
}
opts.onDblClick(node, event)
Called when a node was double clicked.
Use node.getEventTargetType(event) to check which area was clicked.
Return false to prevent default processing (currently none).
opts.onDeactivate(node)
Called when a node was deactivated.
opts.onExpand(flag, node)
Called when a node was expanded/collapsed.
opts.onFocus(node)
Called when a node receives the focus.
opts.onKeydown(node, event)
Called on keydown events.
Return false to prevent default processing (generate keyboard navigation, focus, expand, activate, etc.).
opts.onKeypress(node, event)
Called on keypress events.
Return false to prevent default processing (currently none).
opts.onLazyRead(node)
Called when a lazy node is expanded for the first time.
opts.onPostInit(isReloading, isError [, XMLHttpRequest, textStatus, errorThrown])
Called when the tree was (re)loaded.
In case of an error, isError will be true and addition info is passed: XMLHttpRequest, textStatus, errorThrown.
opts.onQueryActivate(flag, node)
Called before a node is (de)activated. Return false to prevent this.
opts.onQueryExpand(flag, node)
Called before a node is expanded/collapsed. Return false to prevent this.
opts.onQuerySelect(flag, node)
Called before a node is (de)selected. Return false to prevent this.
opts.onRender(node, nodeSpan)
Called after every time a node's HTML tag was created or changed.
This callback may be used to modify the HTML markup.
onRender: function(node, nodeSpan) {
	$(nodeSpan).find("a.dynatree-title").css("color", "red");
}
See also opts.onCreate.
opts.onSelect(flag, node)
Called when a node was (de)selected.
opts.dnd.onDragStart(sourceNode)
This function must be defined to enable dragging for the tree. Return false to cancel dragging of node.
opts.dnd.onDragEnter(targetNode, sourceNode, ui, draggable)
Return true to make tree nodes accept dropping of draggables.
opts.dnd.onDragOver(targetNode, sourceNode, hitMode, ui, draggable)
opts.dnd.onDragLeave(targetNode, sourceNode, ui, draggable)
opts.dnd.onDrop(targetNode, sourceNode, hitMode, ui, draggable)
This function must be defined to enable dropping of items on the tree.
opts.dnd.onDragStop(sourceNode)
ajaxOptions.success(node)
(Passed as argument to node.appendAjax(...).)
Called after nodes have been created and the waiting icon was removed. 'this' is the options for this Ajax request
ajaxOptions.error(node, XMLHttpRequest, textStatus, errorThrown)
(Passed as argument to node.appendAjax(...).)

Handling activate/click

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.

Try this example...
$("#tree").dynatree({
	[…]
	onActivate: function(node) {
		if( node.data.url )
			window.open(node.data.url);
		$("#echoActive").text(node.data.title);
	},
	onDeactivate: function(node) {
		$("#echoActive").text("-");
	},
	[…]
});

Handling selection events

The following example writes the title of the currently focused node to the <span id='echoFocused'> element:

Try this example...
	$("#tree").dynatree({
		[…]
		onSelect: function(flag, node) {
			if( ! flag )
				alert("You deselected node with title " + node.data.title);
			var selectedNodes = node.tree.getSelectedNodes();
			var selectedKeys = $.map(selectedNodes, function(node){
				return node.data.key;
			});
			alert("Selected keys: " + selectedKeys.join(", "));
		},
		[…]
	});
	

Handling focus changes

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:

Try this example...
$("#tree").dynatree({
	[…]
	onFocus: function(node) {
		$("#echoFocused").text(node.data.title);
	},
	onBlur: function(node) {
		$("#echoFocused").text("-");
	},
	[…]
});

Loading child nodes on demand ('lazy loading')

Dynatree supports delayed loading of tree nodes, which means we read the child nodes only when their parent is expanded.

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.

To make this happen, we have to

Try this example...
$("#tree").dynatree({
	[…]
	onLazyRead: function(node){
		node.appendAjax({url: "/sendData",
						   data: {"key": node.data.key, // Optional url arguments
								  "mode": "all"
								  }
						  });
	},
	[…]
});

Typically we would implement onLazyRead by calling the node.appendAjax() function.
It expects one option object argument, as described in the documentation for the jQuery.ajax() command.

These options are set by default:
cache: false and dataType: "json".

Note that the success and error options are implemented differently from the jQuery standard:
They pass different arguments and are called after the Dynatree default processing took place.
This makes it easy to use the success callback to apply any custom postprocessing, for example activating a node or binding events.

$("#tree").dynatree({
	[…]
	onLazyRead: function(node){
		node.appendAjax({url: "/sendData",
						   data: {"key": node.data.key, // Optional url arguments
								  "mode": "all"
								  },
						   // (Optional) use JSONP to allow cross-site-requests
						   // (must be supported by the server):
//                         dataType: "jsonp",
						   success: function(node) {
							   // Called after nodes have been created and the waiting icon was removed.
							   // 'this' is the options for this Ajax request
							   },
						   error: function(node, XMLHttpRequest, textStatus, errorThrown) {
							   // Called on error, after error icon was created.
							   },
						   cache: false // Append random '_' argument to url to prevent caching.
						  });
	},
	[…]
});

The web service is expected to return a valid JSON node list, formatted like this:
[ { "title": "Node1", "isLazy": true, "key": "BC13B21636CD6D5C", … }, { … }, … ]
See Node options for a list of supported attributes.

When the response was received, appendAjax() appends the child nodes and calls node.setLazyNodeStatus(DTNodeStatus_Ok) to remove the wait icon.

Note that initAjax is simply a special case, where the tree's root node is loaded on startup.
See Initializing the structure from an Ajax response for a sample to initialize the whole tree with an Ajax request.

This sample code (written in Python) shows how a server could create a response:

# Build node list as JSON formatted string:
res = '['
res += '{ "title": "Node 1", "key": "k1", "isLazy": true },'
res += '{ "title": "Node 2", "key": "k2", "isLazy": true },'
res += '{ "title": "Node 3", "key": "k3", "isLazy": true }' # no trailing "," at the last line
res += ']'

# Add support for the JSONP protocol:
# This means, if the request URL contains an argument '?callback=xxx',
# wrap the result as 'xxx(result)'
if "callback" in argDict:
	res = argDict["callback"] + "(" + res + ")"

# Make sure, content type is JSON:
start_response("200 OK", [("Content-Type", "application/json")])

# Return result (the square brackets are Python / WSGI specific):
return [ res ]

See dynatree_server.py for a sample implementation of a web server that handles this (~150 lines of Python code).
When this server is running, you can try this live example of a lazy tree.

Loading custom formats

If we need more control, or if the server cannot provide JSON in Dynatree's native format, we could also use jQuery.ajax() to fetch the data, then transform it and call node.addChild():

$("#tree").dynatree({
	[…]
	onLazyRead: function(node){
		$.ajax({
			url: […],
			success: function(data, textStatus){
				// In this sample we assume that the server returns JSON like
				// { "status": "...", "result": [ {...}, {...}, ...]}
				if(data.status == "ok"){
					// Convert the response to a native Dynatree JavaScipt object.
					var list = data.result;
					res = [];
					for(var i=0, l=list.length; i<l; i++){
						var e = list[i];
						res.push({title: "" + i + ": " + e.fcurr + "-" + e.tcurr + ":" + e.ukurs,
							icon: false});
					}
					// PWS status OK
					node.setLazyNodeStatus(DTNodeStatus_Ok);
					node.addChild(res);
				}else{
					// Server returned an error condition: set node status accordingly
					node.setLazyNodeStatus(DTNodeStatus_Error, {
						tooltip: data.faultDetails,
						info: data.faultString
					});
				}
			}
		});
	[…]
});

Drag'n'drop

Drag and drop functionality is enabled by defining the appropriate callbacks:

	$("#tree").dynatree({
		[...]
		dnd: {
			onDragStart: function(node) {
				/** This function MUST be defined to enable dragging for the tree.
				 *  Return false to cancel dragging of node.
				 */
				logMsg("tree.onDragStart(%o)", node);
				return true;
			},
			onDrop: function(node, sourceNode, hitMode, ui, draggable) {
				/** This function MUST be defined to enable dropping of items on
				 * the tree.
				 */
				logMsg("tree.onDrop(%o, %o, %s)", node, sourceNode, hitMode);
				sourceNode.move(node, hitMode);
			}
		}
	});

There are a lot more callbacks that can be used to fine tune the behaviour. Check the source code in the samples in the Example Browser to learn more.

Persistence

When initializing a tree in persist mode, we first check, if persistence cookies already exist.
If not, we assume first-time initializing, read the status from the tree source, and store it into new cookies.

Otherwise we assume re-loading, ignore the source node attributes and override them using the cookie info.

In either case, the 'active', 'expand' and 'select' status of a node is read from the data or restored from the cookies.
However, no onQueryActivate, onActivate, onExpand, onSelect, etc. events are fired. (The only event that may be fired is onFocus.)
In order to generate these events on reload, we may use the callback function onPostInit() and tree.reactivate().

$("#tree").dynatree({
	[…]
	onPostInit: function(isReloading, isError) {
		// 'this' is the current tree
		// isReloading is true, if status was read from existing cookies
		// isError is only used in Ajax mode
		// Fire an onActivate() event for the currently active node
		this.reactivate();
	},
	onActivate: function(node) {
		// Use status functions to find out about the calling context
		var isInitializing = node.tree.isInitializing(); // Tree loading phase
		var isReloading = node.tree.isReloading(); // Loading phase, and reading status from cookies
		var isUserEvent = node.tree.isUserEvent(); // Event was triggered by mouse or keyboard

		$("#echoActive").text(node.data.title);
	},

Persistence for lazy trees

The problem with restoring the status of a lazy tree is, that the currently active or selected nodes may not be part of the tree, when it is freshly re-loaded.

The basic idea is to leave it up to the backend web service to deliver not only the top-level nodes, but also all nodes that are required to display the current status.

For example, it may be neccessary to render 3 parent nodes, if the active node is at level # 4.
The backend may also deliver all child nodes of expanded parents.
Or in selectMode 3 (hierarchical) we may want to send all nodes, that are partly selected.

initAjax (and appendAjax) have 3 options, that make it easy to pass persistence information to the web service.

See dynatree_server.py for a sample implementation of a web server that handles this (~150 lines of Python code).
When this server is running, you can try this live example of a lazy tree.

$("#tree").dynatree({
	[…]
	initAjax: {url: "/ajaxTree",
			   data: {key: key,
					  mode: mode,
					  filter: filter
					  },
			   addActiveKey: true,  // add &activeKey= parameter to URL
			   addFocusedKey: true, // add &focusedKey= parameter to URL
			   addExpandedKeyList: true // add &expandedKeyList= parameter to URL
			   },
	onPostInit: function(isReloading, isError) {
		// In lazy mode, this will be called *after* the initAjax request returned.
		// 'this' is the current tree
		// isReloading is set, if status was read from existing cookies
		// isError is set, if Ajax failed
		// Fire an onActivate() event for the currently active node
		this.reactivate();
	},
	onActivate: function(node) {
		// Use status functions to find out about the calling context
		var isUserEvent = node.tree.isUserEvent(); // Event was triggered by mouse or keyboard

		$("#echoActive").text(node.data.title);
	},

Programming dynatree

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();

Dynatree Plugin methods

Besides the constructor, that is called like this:

$("#tree").dynatree({
	[…]
});

The following methods are globally available from the ui.dynatree namespace:

$.ui.dynatree.getNode(el)
Return a DynaTreeNode object for a given DOM element.
`el` may be a DOM element or a jQuery object. Example:
$("#tree a").hover(function(){
		var node = $.ui.dynatree.getNode(this);
		logMsg("Hover in %s", node);
	}, function(){
		[...]
	});
$.ui.dynatree.getPersistData(cookieId, cookieOpts)
Return cookie persistence info as dictionary.
$.ui.dynatree.version
Release version number.

The following methods are directly available from the plugin:

$("#tree").dynatree("disable")
Disable event handling and add a class 'dynatree-disabled' to the container element.
$("#tree").dynatree("enable")
Enable event handling and remove the 'dynatree-disabled' class from the container element.
$("#tree").dynatree("option", )
Set a dynatree option at runtime. Example:
$("#tree").dynatree("option", "autoCollapse", true);
$("#tree").dynatree("option", "fx", { height: "toggle", duration: 200 }); 
$("#tree").dynatree("getTree")
Return the associated DynaTree object.
$("#tree").dynatree("getRoot")
Return the root DynaTreeNode object of the tree.
$("#tree").dynatree("getActiveNode")
Return the DynaTreeNode object that is currently active.
(May be null.)
$("#tree").dynatree("getSelectedNodes")
Return an array of DynaTreeNode objects that are currently selected.
(May be empty: [ ].)

DynaTree class members

tree.activateKey(key)
Activate and focus node with a given key and fire focus and activate events.
If activeVisible option is set, all parents will be expanded as necessary.
If key is null, the current activation is removed.
Return the active DynaTreeNode.
tree.count()
Return the number of nodes.
tree.disable()
Disable input for the tree and display gray. This is a shortcut for $("#tree").dynatreee("disable").
tree.enable()
Complement to tree.disable().
tree.enableUpdate(enable)
Turn rendering on or off and return the previous mode. Disabling update may speedup processing, when adding lots of nodes.
Don't forget to turn rendering back on, after applying the changes:
var prevMode = tree.enableUpdate(false);
[...]
tree.enableUpdate(prevMode);
tree.getActiveNode()
Return the currently active DynaTreeNode or null.
tree.getNodeByKey(key)
Return DynaTreeNode with a given key or 'null' if not found.
tree.getPersistData()
Return cookie persistence info as dictionary.
There is also a global function available: $.ui.dynatree.getPersistData(cookieId, cookieOpts).
tree.getRoot()
Return the invisible root DynaTreeNode object. All visible toplevel nodes are children of this system node.
tree.getSelectedNodes(stopOnParents)
Return a list of currently selected DynaTreeNodes (may be an empty array).
If stopOnParents is set to true, children of selected nodes are skipped. This may be convenient in selectMode:3 (multi-hier).
tree.initialize()
Constructor (internal use).
tree.isInitializing()
Return true, if the tree is in the init phase.
Use this function in an event handler, to check if the event was fired during a page reload, when the cookie persistence is applied.
tree.isReloading()
Return true, if the tree is in the init phase and persistence is on, and the current status was read from existing cookies.
Use this function in an event handler, to check if the event was fired during a page reload, when the cookie persistence is applied.
tree.isUserEvent()
Return true, if the tree is processing a user event.
Use this function in an event handler, to check if the event was fired in response to a mouse click or key stroke.
Otherwise, the the event was generated by an API call or during initialization.
tree.loadKeyPath(keyPath, callback)
Make sure that a node with a given ID is loaded, by traversing - and loading - its parents. This method is ment for lazy hierarchies.
A callback is executed for every node as we go.
tree.loadKeyPath("/_3/_23/_26/_27", function(node, status){
	if(status == "loaded") {
		// 'node' is a parent that was just traversed.
		// If we call expand() here, then all nodes will be expanded
		// as we go
		node.expand();
	}else if(status == "ok") {
		// 'node' is the end node of our path.
		// If we call activate() or makeVisible() here, then the
		// whole branch will be exoanded now
		node.activate();
	}else if(status == "notfound") {
		var seg = arguments[2],
			isEndNode = arguments[3];
	}
});
tree.logDebug(msg), logInfo(msg), logWarning(msg)
(Internal use).
tree.reactivate(setFocus)
Fire onQueryActivate and onActivate events for the currently active node (if there is one).
This may be useful when processing an onPostInit callback.
tree.redraw()
Render all visible nodes. See node.render() for details.
tree.reload()
Reload the the tree.
For lazy trees this is done, by re-submitting the Ajax request that was defined in the initAjax option.
This will not work, if the tree was loaded from an embedded <UL> element, because these elements are removed after they have been rendered.
tree.renderInvisibleNodes()
Force immediate HTML creation for all nodes, even if inside collapsed branches. This may be useful, if we want to bind events or otherwise must access these HTML elements.
It will however degrade performance, especially on large trees!
See node.render() for details.
tree.selectKey(key, flag)
Select or deselect node with a given key and fire focus and select events.
Return the selected DynaTreeNode.
tree.serializeArray(stopOnParents)
Return selected nodes as array of {name: 'TreeName', value: 'NodeKey'} objects, where name is the 'name' attribute of the tree's <div> element.
This format is compatible with jQuery's serializeArray() function and may be used in $.post() calls.
See also the 'form' sample in the Example Browser.
tree.toDict(includeRoot)
Convert the tree into a JavaScript object.
If 'includeRoot' is false or omitted, the result is an array of node dcts.
See node.toDict() for details.
tree.visit(fn, includeRoot)
Call fn(node) for all nodes.
Stop iteration, if fn() returns false. Stop iteration of the current branch, if fn() returns 'skip'.

DynaTreeNode class members

Attribute 'data'
Use this attribute to access all node options that were passed to create this node.
For example node.data.title or node.data.tooltip. See also Node options.
node.activate()
Activate this node - according to flag - and fire a onActivate event.
If activeVisible option is set, all parents will be expanded as necessary.
Focus is not set.
node.activateSilently()
Same as activate(), but does not fire events.
node.addChild(nodeData[, beforeNode])
Append a new child node.
nodeData may be a node data object as defined in Node options, or an array thereof. Also objects and arrays of type DynaTreeNode are allowed.
Example:
var node = $("#tree").dynatree("getTree").getNodeByKey("1234");
node.addChild({title: "New Node", key: "3333"});
Since the nodeData may be a nested data structure, it is possible to create a deep hierarchy with one call.
The optional argument beforeNode specifies a child DynaTreeNode that the new node will be inserted before. (If this parameter is null or omitted, the new node will be appended.)
node.appendAjax(ajaxOptions)
Accepts a standard jQuery Ajax option object.
An asynchronous request is started, so this function returns immediately. While loading, a spinning wheel is displayed. On error, a red icon is shown.
The request handler must return a JSON object, formatted like the data's children object.
Use the setLazyNodeStatus() function to display the result.
See Loading child nodes on demand ('lazy loading') for details.
node.countChildren()
Return the number of descendant nodes, i.e. direct and indirect children.
node.deactivate()
Deactivate this node and fire an onDeactivate event.
node.expand(flag)
Expand or collapse this node - according to flag.
node.focus()
Set focus to this node. Parent nodes are expanded, if this is necessary to make it visible.
node.getChildren()
Return list of child nodes or null.
For lazy nodes that have not yet been loaded, undefined is is returned.
node.getEventTargetType(event)
Return the part of a node, that a click event occurred on.
Possible values: 'prefix' 'expander', 'checkbox', 'icon', 'title'.
null is returned else.
Note: there is no check, if the event was fired on this node.
node.getLevel()
Return the depth (i.e. number of parent nodes).
0 is returned for the root node.
node.getNextSibling()
Return the successor node or null.
node.getParent()
Return the parent node or null.
node.getPrevSibling()
Return the predecessor node or null.
node.hasChildren()
Return true if node has child nodes.
Return false if node is a leaf, i.e. has no child nodes.
Return undefined if this is a lazy node, that was not yet successfully loaded.
A test for 'node is surely empty' would be coded like
if(node.hasChildren() === false) ...
node.isActive()
Return true, if this node is activated. Only one tree node may be active at any time.
node.isChildOf(otherNode)
Return true, if this node is a direct child of otherNode.
node.isDescendantOf(otherNode)
Return true, if this node is a descendent (direct or indirect child) of otherNode.
node.isExpanded()
Return true, if the node is expanded.
node.isFirstSibling()
Return true, if this node is the first of all children of the current parent.
node.isFocused()
Return true, if this node is has the focus.
node.isLastSibling()
Return true, if this node is the last of all children of the current parent.
node.isLazy()
Return true, if the node is lazy (loaded or not).
node.isLoading()
Return true, if the node is lazy and currently loading (i.e. an Ajax request is active).
node.isSelected()
Return true, if the node is selected.
node.isStatusNode()
Return true, if this is an temporary status node. Status nodes are created while loading lazy data, to display a throbber or error condition.
node.isVisible()
Return true, if the node is visible, i.e. all parents are expanded.
node.makeVisible()
Expand all parents as neccessary, to make this node visible.
node.move(targetNode, mode)
Move this node to targetNode. Possible mode:
node.reload(force)
Deprecated. Use reloadChildren() instead.
node.reloadChildren(callback)
Discard and reload all children of a lazy node by triggering the onLazyRead event. if callback is passed, it is called after the Ajax request was executed. Example
node.reloadChildren(function(node, isOk){
	if(!isOk) alert("Node " + node + " could not be reloaded.");
});
node.remove()
Remove this node and descendents from tree.
node.removeChildren()
Remove all child nodes and descendents.
node.render(useEffects, includeInvisible)
Redraw this node with current attributes. All HTML markup is updated and class names are added according to current status.
If this node is expanded, markup for children is recursively generated as well.
Most of the time, there is no need to call this explicitly, since it is internally called on state changes.
node.resetLazy()
Remove all children from a lazy node and make sure it is collapsed. The node will be re-loaded when expanded the next time.
node.scheduleAction(mode, ms)
Schedule a delayed action. Possible mode:
node.select(flag)
Select or deselect this node - according to flag - and fire an onSelect event.
node.setLazyNodeStatus(status)
Display a dummy child node, to provide feedback, when loading a lazy node's content.
Possible status: Messages may be customized using the strings.loading and strings.loadError options.
node.setTitle(title)
Change current node title and redraw.
node.sortChildren(cmp, deep)
Sort child list by title.
cmd: optional compare function. If ommitted sorting is done by node titles.
deep: optional: pass true to sort all descendant nodes.
Example
// Custom compare function (optional) that sorts case insensitive
var cmp = function(a, b) {
	a = a.data.title.toLowerCase();
	b = b.data.title.toLowerCase();
	return a > b ? 1 : a < b ? -1 : 0;
};
node.sortChildren(cmp, false);
node.toDict(recursive, callback)
Convert the node into a JavaScript object.
recursive: set to true, to include child nodes.
callback: (optional) function to allow modifications.
Example
var cb = node.toDict(true, function(dict){
	dict.title = "Copy of " + dict.title;
	delete dict.key; // prevent duplicate keys
});
node.toggleExpand()
Toggle expansion state.
Expanding a lazy node, fires a onLazyRead event.
node.toggleSelect()
Toggle selection state.
node.visit(fn, includeSelf)
Call fn(node) for all child nodes.
Stop iteration, if fn() returns false. Stop iteration of the current branch, if fn() returns the string 'skip'.
node.visitParents(fn, includeSelf)
Call fn(node) for all parent nodes.
Stop iteration, if fn(node) returns false.

Programming examples

The follwing code snippets should give an idea on how to use the API.

Example: Select a node with key '1234'

$("#tree").dynatree("getTree").selectKey("1234");
// or another way:
$("#tree").dynatree("getTree").getNodeByKey("1234").select();
// .. or yet another way (if 'generateIds' option was enabled):
$("#dynatree-id-1234").prop("dtnode").select();

Example: Access the currently active node

var node = $("#tree").dynatree("getActiveNode");
if( node ){
	alert("Currently active: " + node.data.title);
}

Example: Retrieve a node using for a DOM element or jQuery object

$(".dynatree-partsel").each(function(){
	var node = $.ui.dynatree.getNode(this);
	[...]
});

Example: Rename the active node

var node = $("#tree").dynatree("getActiveNode");
node.data.title = "My new title";
node.render();

Example: Add a child to the active node

var node = $("#tree").dynatree("getActiveNode");
var childNode = node.addChild({
	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 such objects.
Also, the children may again contain children attributes, thus defining a sub tree.

Example: Add a hover handler and find the hovered node from any sub element

// Bind hover events to the tree's <a> tags:
$("#tree a").hover(function(){
		var node = $.ui.dynatree.getNode(this);
		logMsg("Hover in %s", node);
	}, function(){
		var node = $.ui.dynatree.getNode(this);
		logMsg("Hover out %s", node);
	});

Example: Expand all nodes

$("#tree").dynatree("getRoot").visit(function(node){
	node.expand(true);
});

Example: Save current tree status to the backend

// Get a JavaScript object copy of the tree
var dict = $("#tree").dynatree("getTree").toDict();
// ... then use Ajax to send this to your server...

Example: activate a node depending on URL

This sample shows how to parse the page URL and activate a node accordingly: http://server/_test-194.html?activate=_11
// Add a helper function to parse the URL
function getURLParameter(name) {
	return unescape(
		(RegExp(name + '=' + '(.+?)(&|$)').exec(location.search)||[,null])[1]
	);
}
// Evaluate the URL after the tree was loaded
$(function(){
	$("#tree").dynatree({
		[...]
		onPostInit: function(isReloading, isError) {
			var key = getURLParameter("activate");
			if( key ) {
				this.activateKey(key);
			}
		},

Theming and translation

The tree's fonts, colors, and icons are defined using CSS, so changing the appearance is simply a matter of including a custom stylesheet or by replacing icons.gif with another version.

Try this example...
<script src="../jquery/jquery.js" type="text/javascript"></script>
<script src="../jquery/jquery-ui.custom.js" type="text/javascript"></script>
<script src="../src/jquery.dynatree.js" type="text/javascript"></script>
<!-- Include the basic stylesheet: -->
<link href="../src/skin-vista/ui.dynatree.css" rel="stylesheet" type="text/css">
<!-- Override CSS with a custom stylesheet : -->
<link href="skin-custom/custom.css" rel="stylesheet" type="text/css" >

<script type="text/javascript">
	$(function(){
		$("#tree").dynatree({
			[…]
		});
	});
</script>

Custom.css would include lines like this:

.dynatree-has-children span.dynatree-icon
{
	background-position: 0 0;
	background-image: url("doc_with_children.gif");
}

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: #ffffbb;
	color: maroon;
}
span.custom1 span.dynatree-icon
{
	background-position: 0 0;
	background-image: url("customDoc2.gif");
}

Translation

Strings can be translated in the tree options:

$("#tree").dynatree({
	[…]
	strings: {
		loading: "Daten werden geladen…",
		loadError: "Fehler beim Laden!"
	},
});

Feedback, version history, credits and known issues

Credits

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.

Feedback and support

First of all: this is work in progress.
Any kind of feedback is very welcome :-)