Including the files

First of all, as jsTree is a jQuery component, you need to include jQuery itself. Currently jsTree uses version 1.3.2 (the latest as of 14.Sept.2009)

<script type="text/javascript" src="source/lib/jquery.js"></script>

Then you need to include jsTree:

<script type="text/javascript" src="source/jquery.tree.js"></script>

Or you could use the minified version:

<script type="text/javascript" src="source/jquery.tree.min.js"></script>

You may change the path to whatever you like, but it is recommended not to rename jquery.tree.js or jquery.tree.min.js as the filenames are used in path autodetection. If you decide to rename them make sure you set the theme_path config option, so that jsTree succesfully includes your chosen theme (you also MUST set this option if you decide to move the folder of your chosen theme out of jstree-location/themes/).

Additionally you may decide to include some of the plugins from the plugins/ folder. If you do that the first time you open a page the plugin you loaded will alert you about missing dependancies - they can all be found lib/ folder.

Creating an instance

You can create an instance in one of two ways. Make sure that you do not use an <ul> node for the container node.

Method 1:

jQuery("selector-to-container-node-here").tree( options * );

* You may pass the configuration options as a parameter to the tree() function. Detailed information about configuring can be found below.

If you use this method, to get the address the instance you just created use this code:

jQuery.tree.reference( selector * );

* Selector can be: the ID of the container node, the ID of any contained DOM element, an actual DOM element contained within the tree, or a jQuery extended DOM node container within the tree

Method 2:

var your-tree-var = jQuery.tree.create();
your-tree-var.init( options * )

* You may pass the configuration options as a parameter to the init() function. Detailed information about configuring can be found below.

If you use this method, the your-tree-var is a reference to the instance. You can still use jQuery.tree.reference(). A note regarding IE8 - it has been known to cause some trouble if you use tree as variable name, so please don't.

The object storing all default values for newly created instances can be found in jQuery.tree.defaults. If you extend or modify the object, all instances created after the modification will use the modified object as default settings. When configuring an instance only pass those values, that are different from the defaults.

data Object

This section of the config stores all data source related settings.

selected mixed

A single node ID, or a list of node IDs to be initially selected when the tree first loads. Either a String, an Array or false.

Default is false.

opened Array

An array of node IDs to be initially opened when the tree first loads.

Default is [].

languages Array

An array of string values, each one representing a language. Keep in mind those string will be used internally for CSS classes, so each string must be a valid CSS classname (a safe approach is to use typical language codes "en", "de", etc).

Default is [].

ui Object

This section of the config stores various user interface related settings.

types Object

This section of the config stores all defined node types and their possible interactions. Each setting (except for icon) may be set to a function - if so whenever a user interaction is evaluated this function will be invoked and will receive two arguments - the node that is being checked and the tree instance. In any new types you define you may only supply the rules that are different from the default type.

By default only the "default" node type is defined:

{
	"default" : {
		clickable	: true,
		renameable	: true,
		deletable	: true,
		creatable	: true,
		draggable	: true,
		max_children	: -1,
		max_depth	: -1,
		valid_children	: "all",

		icon : {
			image : false,
			position : false
		}
	}
}

rules Object

This section is for defining a few rules for the whole tree.

langs Object

This section of the config stores various settings related to languages.

callback Object

This section is for defining all callback functions which fire on various events.

function(NODE, TREE_OBJ) { 
	TREE_OBJ.toggle_branch.call(TREE_OBJ, NODE);
	TREE_OBJ.select_branch.call(TREE_OBJ, NODE);
}

function(NODE, TREE_OBJ, EV) { 
	EV.preventDefault(); 
	EV.stopPropagation(); 
	return false; 
}

plugins Object

This section is for defining active plugins on the instance. Each plugin is a key in this object, and corresponding to that key is the options object for the plugin. For example:

plugins : {
	"plugin-name" : { plugin-option-one : "value", plugin-option-two : { } }
	"second-plugin" : { } // This just activates the plugin without modifying its defaults.
}

Default is: { }

In this section you will find the data format description of the two bundled datasources.

HTML

The simplest of datastores. Used when you need to converted a nested list into an interactive tree. The required structure is as follows:

<some-container-node>
	<ul>
		<li id="node-identificator" rel="node-type">
			<a href="#"><ins>&nbsp;</ins>Root node</a>
			<ul>
				<li id="node-identificator" rel="node-type">
					<a href="#"><ins>&nbsp;</ins>Child node</a>
				</li>
			</ul>
		</li>
	</ul>
</some-container-node>

You can have whatever attributes you like in any of the elements. Also keep in mind that the node ID and type can be omitted and the node type may be stored in some other attribute if you decide to configure it (check the type_attr section).

If you use language versions you will have multiple <a> (one for each language) elements inside any <li> element, they must have a language code (one of the codes defined in the langauges section of the config) for a classname. Like so:

<li id="node-identificator" rel="node-type">
	<a href="#" class="en"><ins>&nbsp;</ins>Title in English</a>
	<a href="#" class="bg"><ins>&nbsp;</ins>Title in Bulgarian</a>
</li>

JSON

The JSON data format is definitely the most widely used amongst jsTree users. Each node has the following structure:

{ 
	attributes: { id : "node_identificator", some-other-attribute : "attribute_value" }, 
	data: "node_title", 
	// Properties below are only used for NON-leaf nodes
	state: "closed", // or "open"
	children: [ /* an array of child nodes objects */ ]
}

As you can see you can pass any attributes you like in the attributes object - in the resulting HTML output those attributes are bound to the <li> element. If you have a leaf node (one with no children) omit the state and children properties.

If you need to specify some attributes for the <a> node in the output, or want to set a custom icon instead of a string, pass an object for the data section. Like so:

{ 
	attributes: { id : "node_identificator", some-other-attribute : "attribute_value" }, 
	data: { title : "Node title", icon : "path_to/icon.pic", attributes : {"key" : "value" } }, 
	// Properties below are only used for NON-leaf nodes
	state: "closed", // or "open"
	children: [ /* an array of child nodes objects */ ]
}

If language versions are used use this syntax for the data property:

data: { 
	"en" : "Title in English", 
	"bg" : "Title in Bulgarian"
}

Or if you need icons and attributes:

data: { 
	"en" : { title : "Title in English", icon : "path_to/icon.pic", attributes : { "key" : "value" } },
	"bg" : "Title in Bulgarian"
}

As you can see - you can mix the short and long syntax.

jQuery(selector).tree([options]) Return value: jQuery

Used on a jQuery selector the tree function converts all matched elements to trees, using the options provided. If a tree already exists in one of the selected DOM nodes, it is first destroyed and then recreated using the passed options object.

Functions and properties bound directly to the global tree object.

jQuery.tree.create() Return value: jsTree

Creates a new tree instance. Accepts no arguments - the configuration object is passed in a subsequest init call on the returned tree object.

jQuery.tree.datastores

This object stores all defined datastores on a global level. Every added datastore extends this object. In order to use a datastore in a tree instance, the datastore should be defined in this object.

jQuery.tree.defaults

The object storing all default values for newly created instances. If you extend or modify the object, all instances created after the modification will use the modified object as default settings. This means that you can even define plugins that should be active on all instances.

jQuery.tree.drag_start function

You can set this to a function - it will be called each time the user initiates a drag. You will receive the event object and a jsTree drag_drop object as parameters. Please note that you attach this callback globally and not on a specific instance. To get the instance involved in the drag start - use the jQuery.tree.reference() function.

jQuery.tree.drag function

You can set this to a function - it will be called each time the mousemove event is fired. You will receive the event object and a jsTree drag_drop object as parameters. Please note that you attach this callback globally and not on a specific instance. To get the instance/instances involved in the drag - use the jQuery.tree.reference() function.

jQuery.tree.drag_end function

You can set this to a function - it will be called each time the user finishes a drag. You will receive the event object and a jsTree drag_drop object as parameters. Please note that you attach this callback globally and not on a specific instance. To get the instance/instances involved in the drag - use the jQuery.tree.reference() function. Do not confuse with the onmove callback which will also be fired if there was a valid move.

jQuery.tree.drop_mode([options]) Return value: none

This function sets all initialized trees on the page in "drop mode", meaning that all the trees start handling mouseover events and evaluating the possible drop, and giving the user feedback.

jQuery.tree.focused() Return value: jsTree

This functions returns the currently focused tree instance.

jQuery.tree.plugins

This object stores all defined plugins on a global level. Every added plugin extends this object. In order to use a specific plugin, it should be defined in this object. Only having a plugin defined here, does not mean it is activated with every instance. If you want to use a plugin with an instance you should define that in the particular instance config.

jQuery.tree.reference(needle) Return value: jsTree

This functions returns a specific tree instance by an ID or contained node.

jQuery.tree.rollback(data) Return value: none

This function performs a rollback when passed a rollback object. It sets all trees involved in the rollback to the state described in the rollback object.

Functions and properties in a tree instance

attach_events() Return value: none

This function binds all the events required for user interaction with the tree. It only fires once at creation time. It is used internally.

callback(callback_name, arguments) Return value: none

This function is used internally. It fires all callbacks.

check(rule, node) Return value: boolean

Checks if a certain action is allowed on a node (for example create, delete, rename, etc) and returns true or false accordingly. Used mainly internally.

check_move(node, ref_node, move_type) Return value: boolean

Checks if a certain move is allowed. Used mainly internally.

children(reference_node) Return value: jQuery

Get the child nodes of the reference node. Returns false on failure.

close_all([node])

Closes all nodes, so that their children are not visible. Has no return value, but returns false on failure (invalid node for example).

close_branch(node [, disable_animation])

Close a node, so that its children are not visible. Has no return value, but returns false on failure (invalid node for example).

cntr

The number of the tree. This is used internally.

copy([node])

Marks a node as copied. A paste operation following the copy operation will create a copy of that node. Has no return value, but returns false on failure (invalid node for example).

create([data, reference_node, position]) Return value: jQuery

Create a new node. Please note this function should mainly be used for user interaction and not for populating the tree initially. Returns the newly created node or false on failure.

current_lang

The language code of the currently visible language.

cut([node])

Marks a node as cut. A paste operation following the cut operation will move that node. Has no return value, but returns false on failure (invalid node for example).

deselect_branch(node)

Removes the selected state from a node in the tree. Has no return value, but returns false on failure (invalid node for example).

destroy()

Destroys the instance.

error(error_string) Return value: false

All errors go through this function. Used internally.

focus()

This function sets the current tree as the focused one in the page.

get([node, format, options]) Return value: mixed

Return the whole tree or a part of it in a given format.

get_lang() Return value: string

This function is only useful if language versions are used. Returns the currently visible language or false on failure.

get_node(node) Return value: jQuery

This function returns the jQuery extended LI DOM node that represents a given tree node.

get_rollback() Return value: object

Returns a rollback object for the tree. The rollback object actually has two properties html (containing the HTML of the container) and selected (the ID of the last selected node - if there is one).

get_text(node [, language]) Return value: string

This function returns the title of the node passed as first parameter.

get_type(node) Return value: string

This function returns the type of a node (types are used to determine nesting/interaction rules). The function returns "default" if no type attribute is found.

hover_branch(node)

Sets a node in the tree as hovered. Has no return value, but returns false on failure (invalid node for example).

init(element [, config])

This function initializes a tree in the given container element, using the optional config passed as a parameter. Usually used after create().

lock(state)

Locks or unlocks the tree instance. A locked tree blocks all user interactions.

locked

A boolean indicating the lock state of the tree.

moved(what, where, how [, is_new, is_copy, rollback]) Return value: jQuery

This function is used internally. It performs all moves and manipulates the DOM. Returns the moved node, but there is no return value if there are multiple moves to be performed or the required data is not yet loaded.

next(reference_node [, strict]) Return value: jQuery

Get the node next to the reference node. Returns false on failure.

off_height()

This function computates the offset of the tree's container node, and also the height of a single node. It is used internally.

open_all([node, callback])

Open all nodes, so that their children are visible. Returns false on failure.

open_branch(node [, disable_animation, callback]) Return value: boolean

Open a node, so that its children are visible. Returns true if succesfull, false if not.

parent(reference_node) Return value: mixed

Get the parent node of the reference node. Normally returns a jQuery extended node, but will return -1 if a root node is passed as reference node, or false on failure (invalid reference node for exmaple).

paste([node, position])

Pastes any copied or cut nodes in the new position. Has no return value, but will return false on failure.

prev(reference_node [, strict]) Return value: jQuery

Get the node previous to the reference node. Returns false on failure.

refresh([element])

This function refreshes the whole tree, or a given node (if passed as a parameter). Opened nodes and selected nodes are saved and reopened/reselected (the reselect function is used for reselecting and reopening).

remove([node])

Removes a node. Has no return value, but will return false on failure.

rename([node, new_name])

Rename a node. If language versions are used only the title in the currently visible language is modified. Has no return value, but will return false on failure.

reselect([is_callback])

This function reselects and reopens nodes in the tree after a refresh. It is used internally.

scroll_check(x, y)

This function detects the need to scroll and scrolls the container (if neccessary) while the user drags a node (or nodes). It is used internally.

scroll_into_view([node])

This function scrolls the container node so that the node passed as parameter is in view. If the parameter is missing the currently selected node is used.

search(needle [, compare_function])

Searches all nodes whose titles match a given string. If async is used a request is made to the server, the response should contain the comma-separated IDs of nodes that need to be opened so that all nodes that match the search string are visible. The search string is provided in the request. The function triggers the onsearch callback, with the nodes found as a parameter.

selected

The currently selected jQuery extended node (if mutliselect is possible this holds the lastly selected node).

selected_arr

An array of jQuery extended DOM nodes that are currently selected.

select_branch(node [, is_multiple])

Sets a node in the tree as selected. Has no return value but will return false on failure (invalid node for example).

settings

All the settings for the current tree. You can modify some of the properties at runtime.

set_lang(lang) Return value: boolean

This function is only useful if language versions are used. Sets the current language to the specified one so that the tree is visible in that language. Returns true on success and false otherwise.

set_type(type [, node])

This function sets the type of a node to a given value (types are used to determine nesting/interaction rules).

toggle_branch(node) Return value: boolean

Toggles the opened/closed state of the node. Returns true on success and false otherwise.

toggle_dots()

Turns dots on or off.

others

A few other variables may emerge at runtime, but they are only used internally, such as: srch , srch_opn , hovered , offset , is_partial_refresh , opened , cl_count , li_height , inp.