Go to: Creating an instance | Configuration | Datastores | API

# Using jsTree

## 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.

# Configuration

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.

## data.async `Boolean`

If this is set to `true` a request will be made each time a closed node is opened, and its data is not yet loaded.

Default is `false`.

## data.type `String`

A string specifying one of the included datastores (`"html"` and `"json"` are in the main source file (`jquery.tree.js`) and `"xml_flat"` and `"xml_nested"` are available in the `plugins/` directory).

Default is `"html"`.

## data.opts `Object`

An object specifying all the options for the chosen datastore.

Default is `{ method: "GET", url: false }`.

## data.opts.method `String`

The method used when querying the server for data. Either `"GET"` or `"POST"`. Keep in mind that while all included datastore plugins respect this setting, other third party datastore plugins may choose not to.

Default is `"GET"`.

## data.opts.url `String`

The URL used when querying the server for data. You may specify GET parameters here, or use the `beforedata` callback.

Default is `false`.

## 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.

## ui.dots `Boolean`

Should the tree have guiding dots or not.

Default is `true`.

## ui.animation `Integer`

The duration in milliseconds of the open/close animation.

Default is `0` (meaning no animation).

## ui.scroll_spd `Integer`

When dragging near the edge of the tree container it scrolls if neccessary. This setting controls the speed of the scroll.

Default is `4`.

## ui.selected_parent_close `mixed`

This option specifies the behavior of the tree when a parent of a selected node is closed. The options are `"select_parent"` - which deselects the selected node and selects the closed one (similar to windows explorer), `"deselect"` - only deselects the selected node or `false` - does nothing.

Default is `"select_parent"`.

## ui.selected_delete `mixed`

This option specifies the behavior of the tree when a selected node is deleted. The options are `"select_previous"` - which selects the previous node (similar to windows explorer) or `false` - does nothing.

Default is `"select_previous"`.

## ui.theme_path `String`

The folder where jsTree's themes are located. If this is set to false, jsTree will autodetect the folder using its own folder location and appending `themes/` at the end.

Default is `false` (meaning autodetect).

## ui.theme_name `String`

The theme to use. If set to `false` no theme is loaded.

Default is `"default"`.

## 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
    		}
    	}
    }

## type.clickable `mixed`

Are nodes of this type clickable. `Boolean` or `Function`.

## type.renameable `mixed`

Are nodes of this type renameable. `Boolean` or `Function`.

## type.deletable `mixed`

Are nodes of this type deletable. `Boolean` or `Function`.

## type.creatable `mixed`

Can new nodes be created in nodes of that type. `Boolean` or `Function`.

## type.draggable `mixed`

Are nodes of this type draggable. `Boolean` or `Function`.

## type.max_children `mixed`

The maximum number of direct children allowed in this type of node. `-1` means unlimited amount of direct children, `0` means no children are allowed, `1` means maximum one child is allowed, etc. `Integer` or `Function`.

## type.max_depth `mixed`

The maximum number of levels below this type of node. `-1` means unlimited amount of levels, `0` means no children are allowed, `1` means maximum one level is allowed, etc. `Integer` or `Function`.

## type.valid_children `mixed`

Types of nodes allowed inside this type of node. Can be an `Array` of string values (one for each allowed type), if set to `String` `"all"` nodes of any type can be children of a nodes of this type. Can also be a `Function`

## type.icon `Object`

An optional configuration of the icon used for that node type. If using a sprite (a big image with a lot of icons in it) define the `image` property on the `"default"` node type and for all other types just define the `position` property. Keep in mind IE6 is not supported (internally this uses a `node[attribute=value] > node` selector).

Default is: `{ image : false, position : false }`, which means the icon is defined in the theme.

## rules `Object`

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

## rules.multiple `mixed`

This controls multiple selection. Can be either `false` - multiple selection is off, `"ctrl"` - multiple selection is on when the Ctrl key is held down or `"on"` - multiple selection is always on.

Default is: `"ctrl"`

## rules.multitree `mixed`

This controls accepting nodes from other trees. Can be either `"none"` - will not accept any nodes from any tree, `"all"` - will accept from any tree or `Array` - an array of strings, each one representing the ID of the container of a tree to accept from.

Default is: `"none"`

## rules.type_attr `String`

The attribute to read the type of the node from.

Default is: `"rel"`

## rules.createat `String`

Specifies the default location to insert new nodes at - at the top amongst the parent node's children or at the bottom. Also controls what happens if a node is dropped onto another node. Should be either `"top"` or `"bottom"`.

Default is: `"bottom"`

## rules.drag_copy `mixed`

This controls how to copy when dragging. Can be either `false` - when the user drags a move is always performed, `"ctrl"` - a copy is made if the Ctrl key is held down or `"on"` - the drag always results in a copy.

Default is: `"ctrl"`

## rules.drag_button `String`

This controls which button initiates a drag. Can be either `"left"`, `"right"` or `"both"`.

Default is: `"left"`

## rules.use_max_children `Boolean`

Should max_children rules be checked when moving/copying nodes.

Default is: `true`

## rules.use_max_depth `Boolean`

Should max_depth rules be checked when moving/copying nodes.

Default is: `true`

## type.max_children `Integer`

The maximum number of root nodes allowed. `-1` means unlimited amount of root nodes, `1` means maximum one root node is allowed, etc.

Default is: `-1`

## type.max_depth `Integer`

The maximum number of levels. `-1` means unlimited amount of levels, `1` means maximum one level is allowed, etc.

Default is: `-1`

## type.valid_children `mixed`

Types of nodes allowed as root nodes. Can be an `Array` of string values (one for each allowed type), if set to `String` `"all"` nodes of any type can be root nodes.

Default is: `"all"`

## langs `Object`

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

## lang.new_node `mixed`

The default name for newly created nodes (if the new name is not specified on creation). Can be a `String` or an `Array` of strings for each defined language. If you use multiple languages but set this to a single string - it will be used in all languages.

Default is `"New folder"`.

## lang.loading `String`

The string displayed when loading content from the server.

Default is `"Loading ..."`.

## callback `Object`

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

## callback.beforechange Should return: `Boolean`

Triggered before selection changes. Receives two parameters - the node involved in the event and a reference to the tree instance. If `false` is returned selection is not changed.

Default is: `function(NODE, TREE_OBJ) { return true }`

## callback.beforeopen Should return: `Boolean`

Triggered before opening a node. Receives two parameters - the node about to be opened and a reference to the tree instance. If `false` is returned the node is not opened.

Default is: `function(NODE, TREE_OBJ) { return true }`

## callback.beforeclose Should return: `Boolean`

Triggered before closing a node. Receives two parameters - the node about to be closed and a reference to the tree instance. If `false` is returned the node is not closed.

Default is: `function(NODE, TREE_OBJ) { return true }`

## callback.beforemove Should return: `Boolean`

Triggered before moving a node. Receives four parameters - the node about to be moved, the reference node in the move, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`) and a reference to the tree instance. If `false` is returned the node is not moved.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ) { return true }`

## callback.beforecreate Should return: `Boolean`

Triggered before creating a node. Receives four parameters - the node about to be created, the reference node in the creation, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`) and a reference to the tree instance. If `false` is returned the node is not created.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ) { return true }`

## callback.beforerename Should return: `Boolean`

Triggered before renaming a node. Receives three parameters - the node about to be renamed, the current language and a reference to the tree instance. If `false` is returned the node is not renamed.

Default is: `function(NODE, LANG, TREE_OBJ) { return true }`

## callback.beforedelete Should return: `Boolean`

Triggered before deleting a node. Receives two parameters - the node about to be deleted and a reference to the tree instance. If `false` is returned the node is not deleted.

Default is: `function(NODE, TREE_OBJ) { return true }`

## callback.beforedata Should return: `Object`

Used for passing custom parameters to the server. Receives two parameters - a node (if applicable) and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { return { id : $(NODE).attr("id") || 0 } }`

## callback.ondata Should return: `mixed`

Used for modifying the data received from the server before parsing it.

Default is: `function(DATA, TREE_OBJ) { return DATA; }`

## callback.onparse Should return: `String`

Used for modifying the HTML about to be inserted in the DOM before actually inserting it.

Default is: `function(STR, TREE_OBJ) { return STR; }`

## callback.onhover

Triggered when a node is hovered. Receives two parameters - the hovered node and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { }`

## callback.onselect

Triggered when a node is selected. Receives two parameters - the selected node and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { }`

## callback.ondeselect

Triggered when a node is deselected. Receives two parameters - the deselected node and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { }`

## callback.onchange

Triggered when selection is changed in any way (select or deselect). Receives two parameters - the node involved and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { }`

## callback.onrename

Triggered when a node is renamed. Receives three parameters - the renamed node, a reference to the tree instance and a rollback object that you can use with `jQuery.tree.rollback`.

Default is: `function(NODE, TREE_OBJ, RB) { }`

## callback.onmove

Triggered when a node is moved. Receives five parameters - the node that was moved, the reference node in the move, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`), a reference to the tree instance and a rollback object that you can use with `jQuery.tree.rollback`.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ, RB) { }`

## callback.oncopy

Triggered when a node is copied. Receives five parameters - the node that was copied, the reference node in the copy, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`), a reference to the tree instance and a rollback object that you can use with `jQuery.tree.rollback`.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ, RB) { }`

## callback.oncreate

Triggered when a node is created. Receives five parameters - the node that was created, the reference node in the create operation, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`), a reference to the tree instance and a rollback object that you can use with `jQuery.tree.rollback`.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ, RB) { }`

## callback.ondelete

Triggered when a node is deleted. Receives three parameters - the node that was deleted, a reference to the tree instance and a rollback object that you can use with `jQuery.tree.rollback`.

Default is: `function(NODE, TREE_OBJ, RB) { }`

## callback.onopen

Triggered when a node is opened. Receives two parameters - the node that was opened and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { }`

## callback.onopen_all

Triggered when a `open_all` operation completes. Receives one parameter - a reference to the tree instance.

Default is: `function(TREE_OBJ) { }`

## callback.onclose

Triggered when a node is closed. Receives two parameters - the node that was closed and a reference to the tree instance.

Default is: `function(NODE, TREE_OBJ) { }`

## callback.onclose_all

Triggered when a `close_all` operation completes. Receives one parameter - a reference to the tree instance.

Default is: `function(TREE_OBJ) { }`

## callback.error

Triggered when an error occurs. Receives two parameters - the error string and a reference to the tree instance.

Default is: `function(TEXT, TREE_OBJ) { }`

## callback.ondblclk

Triggered when a node is doubleclicked. Receives two parameters - the node that was doubleclicked and a reference to the tree instance.

Default is:

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

## callback.onrgtclk

Triggered when a node is rightclicked. Receives three parameters - the node that was rightclicked, a reference to the tree instance and the event object. To prevent the browser menu use:

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

Default is: `function(NODE, TREE_OBJ, EV) { }`

## callback.onload

Triggered when the tree is loaded with data for the first time or refreshed. Receives one parameter - a reference to the tree instance.

Default is: `function(TREE_OBJ) { }`

## callback.oninit

Triggered when the tree is initialized and before any data is requested or parsed. Receives one parameter - a reference to the tree instance.

Default is: `function(TREE_OBJ) { }`

## callback.onfocus

Triggered when the tree is focused. When creating a new tree it is always focused and the callback fires after `oninit`, but if a data request should be made to the server - possibly before `onload`. Receives one parameter - a reference to the tree instance.

Default is: `function(TREE_OBJ) { }`

## callback.ondestroy

Triggered before the tree is destroyed. Receives one parameter - a reference to the tree instance.

Default is: `function(TREE_OBJ) { }`

## callback.onsearch

Triggered after a search is performed and results are ready. Receives two parameters - a jQuery collection of nodes matching the search and a reference to the tree instance.

Default is: `function(NODES, TREE_OBJ) { NODES.addClass("search"); }`

## callback.ondrop

Triggered when a foreign node is dropped on the tree. Receives four parameters - the foreign node that was dropped, the reference node in the move, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`) and a reference to the tree instance.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ) { }`

## callback.check

Triggered when a node is checked for a certain rule. Receives four parameters - the rule that is checked, the node that is checked, the value computed so far (as the callback is called last - before that types are evaluated) and a reference to the tree instance.

Default is: `function(RULE,NODE,VALUE,TREE_OBJ) { return VALUE; }`

## callback.check_move Should return: `Boolean`

Triggered when a move is evaluated. Receives four parameters - the node that is moved, the reference node in the move, the new position relative to the reference node (one of `"before"`, `"after"` or `"inside"`) and a reference to the tree instance.

Default is: `function(NODE, REF_NODE, TYPE, TREE_OBJ) { return true; }`

## 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: `{ }`

# Datastores

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.

# API

## 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.

Arguments: `object` `options`

An optional object, specifing all the options for the tree (or trees) that will be created. This object internally extends the global defaults object. So you may only pass values that are different from the defaults.

### 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.

Arguments: `object` `options`

An optional object, specifing a few options:

- `boolean` `show`

  Should there be a drag helper. Defaults to `false`.

- `string` `type`

  The node type that should be used for the current drop when evaluating the drag rules. Defaults to `"default"`.

- `string` `str`

  The text used in the drag helper. Defaults to `"Foreign node"`.

## 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.

Arguments: `mixed` `needle`

This can be either the instance ID (the ID of the container node), an ID of any contained DOM element, an actual DOM element contained within the tree, or a jQuery extended DOM node container within the tree.

## 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.

Arguments: `object` `data`

This is a rollback object, usually obtained in a callback or by calling `get_rollback` on a specific instance.

### 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.

Arguments: `string` `callback_name`

The callback to fire.

`array` `args`

The arguments for the callback.

## 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.

Arguments:

`string` `rule`

The rule you want to check.

`mixed` `node`

A DOM node, jQuery object or selector, pointing to the node you want to check inside the tree.

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

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

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to the node that is being moved.

`mixed` `ref_node`

A DOM node, jQuery object or selector, pointing to the reference node.

`string` `move_type`

One of `"before"`, `"after"` or `"inside"`.

## children(reference_node) Return value: `jQuery`

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

Arguments:

`mixed` `reference_node`

The reference node. A DOM node, jQuery object or selector, pointing to a node inside the tree.

## 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).

Arguments:

`mixed` `node`

Optional argument. A DOM node, jQuery object or selector, pointing to a node inside the tree. If passed only this node and its children are closed, if not passed - every node in the tree is closed.

## 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).

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

`boolean` `disable_animation`

Optional argument. If `true` is passed, there will be no animation regardless of the settings in the tree config.

## 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).

Arguments:

`mixed` `node`

Optional argument - the node to be copied. A DOM node, jQuery object or selector, pointing to a node inside the tree. If omitted the currently selected node (or nodes) are marked.

## 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.

Arguments:

`object` `data`

Optional argument. The object follows the built in JSON structure, so you can specify name (or names if using language versions) for the newly created node, attributes, type of the node, open/closed state, etc. If omitted the new node's type is "default" and as soon as it is inserted the `rename` function is called on the node.

`mixed` `reference_node`

Optional argument. A DOM node, jQuery object or selector, pointing to a node inside the tree. If `-1` is passed a new root node is created. If omitted the currently selected node is used as reference node.

`mixed` `position`

Optional argument. Possible values are `"before"`, `"after"` or `"inside"`, which mark the position relative to the reference node. An integer may also be passed - in that case the new node will be created at that specific offset among the reference node's children.

## 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).

Arguments:

`mixed` `node`

Optional argument - the node to be cut. A DOM node, jQuery object or selector, pointing to a node inside the tree. If omitted the currently selected node (or nodes) are marked.

## 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).

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

## destroy()

Destroys the instance.

## error(error_string) Return value: `false`

All errors go through this function. Used internally.

Arguments:

`string` `error_string`

## 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.

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree. This is the node you want returned, if this argument omitted the whole tree is returned.

`string` `format`

Optional argument. The format you want the returned data in. It should be one of the defined datasources. If omitted the tree's current datasource is used.

`object` `options`

Optional argument. The options for the datasource - if omitted, the tree's current options are used.

## 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.

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

## 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.

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

`string` `language`

This parameter is optional and only useful if language versions are used. You may specify the language in which you want the title (it should be one of the defined languages). If you ommit this parameter the title is returned in the currently visible language.

## 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.

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

## hover_branch(node)

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

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

## 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()`.

Arguments:

`mixed` `element`

This is a DOM node, jQuery object, or a valid jQuery selector, pointing to a container element. This parameter is required.

`object` `config`

An optional object, specifing all the options for the tree (or trees) that will be created. This object internally extends the global defaults object. So you may only pass values that are different from the defaults.

## lock(state)

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

Arguments:

`boolean` `state`

To lock or unlock (`true` means lock).

## 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.

Arguments:

`mixed` `what`

The node (or nodes) to move/copy/create. A DOM node, jQuery object or selector, pointing to a node inside the tree.

`mixed` `where`

The reference node in the operation. A DOM node, jQuery object or selector, pointing to a node inside the tree.

`string` `how`

One of `"before"`, `"after"` or `"inside"`.

`boolean` `is_new`

If it is a create operation.

`boolean` `is_copy`

If it is a copy operation.

`object` `rollback`

The rollback object created in the first call to the `moved` function.

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

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

Arguments:

`mixed` `reference_node`

The reference node. A DOM node, jQuery object or selector, pointing to a node inside the tree.

`boolean` `strict`

Optional argument - if set to `true` only siblings are returned (nodes within the same parent as the reference node). If not present or `false` behaves like in Windows explorer - when the last child is the reference node the next sibling of the parent node is returned.

## 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.

Arguments:

`mixed` `node`

Optional argument. A DOM node, jQuery object or selector, pointing to a node inside the tree. If passed only this node and its children are opened, if not passed - every node in the tree is opened.

`function` `callback`

Optional argument. A function to be executed once the operation is complete. Used internally, if you need similiar functionality use the `onopen_all` callback.

## 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.

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

`boolean` `disable_animation`

Optional argument. If `true` is passed, there will be no animation regardless of the settings in the tree config.

`function` `callback`

Optional argument. A function to be executed once the operation is complete. Used internally, if you need similiar functionality use the `onopen` callback.

## 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).

Arguments:

`mixed` `reference_node`

The reference node. A DOM node, jQuery object or selector, pointing to a node inside the tree.

## paste([node, position])

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

Arguments:

`mixed` `node`

Optional argument - the reference node in the operation. A DOM node, jQuery object or selector, pointing to a node inside the tree. If omitted the currently selected node (or nodes) are marked.

`mixed` `position`

Optional argument. Possible values are `"before"`, `"after"` or `"inside"`, which mark the position relative to the reference node. An integer may also be passed - in that case the node will be moved/copied at that speicific offset among the reference node's children.

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

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

Arguments:

`mixed` `reference_node`

The reference node. A DOM node, jQuery object or selector, pointing to a node inside the tree.

`boolean` `strict`

Optional argument - if set to `true` only siblings are returned (nodes within the same parent as the reference node). If not present or `false` behaves like in Windows explorer - when a first child is the reference node the parent node is returned.

## 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).

Arguments:

`mixed` `element`

This is a DOM node, jQuery object, or a valid jQuery selector, pointing to a node in the tree. If this parameter is passed, only that node is refreshed, if this parameter is absent, the whole tree is refreshed.

## remove([node])

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

Arguments:

`mixed` `node`

Optional argument - the node to be removed. A DOM node, jQuery object or selector, pointing to a node inside the tree. If omitted the currently selected node is removed.

## 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.

Arguments:

`mixed` `node`

Optional argument - the node to be renamed. A DOM node, jQuery object or selector, pointing to a node inside the tree. If omitted the currently selected node is renamed.

`string` `new_name`

Optional argument - the new name. If omitted - an input box is displayed.

## reselect([is_callback])

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

Arguments:

`boolean` `is_callback`

As the function sometimes calls recursively this parameter shows if this is a recursive call, or the first one.

## 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.

Arguments:

`number` `x`

The x coordinate to check.

`number` `y`

The y coordinate to check.

## 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.

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

## 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.

Arguments:

`string` `needle`

The search string.

`string` `compare_function`

Optional argument. The jQuery function to be used for comparing titles to the string - defaults to `"contains"`.

## 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).

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

`boolean` `is_multiple`

Optional argument. If `true` is passed, it will trigger multiselect (the previously selected node won't be deselected, but the both nodes will be selected).

## 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.

Arguments:

`mixed` `lang`

Either one of the language strings defined in the tree's config, or its key in the array.

## set_type(type [, node])

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

Arguments:

`string` `type`

The new type of the node.

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree. This argument is optional - if not specified - the currently selected node is used.

## toggle_branch(node) Return value: `boolean`

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

Arguments:

`mixed` `node`

A DOM node, jQuery object or selector, pointing to a node inside the tree.

## 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`.