jsTree v.1.0 - Core

Description

Including the files

First of all, as jsTree is a jQuery component, you need to include jQuery itself. jsTree v.1.0 requires jQuery version 1.4.2

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

Then you need to include jsTree:

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

Or you could use the minified version:

<script type="text/javascript" src="jquery.jstree.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 may be used for path autodetection (for example in the themes plugin, but if you really need to rename the file most plugins will give you the option to set the path manually).

Additionally some plugins have dependencies - plugins that detect a dependency is missing will throw an error.

Creating and configuring an instance

You can create a tree in the following manner:

jQuery("some-selector-to-container-node-here").jstree([ config_object ]);

In the optional config object you specify all the options that you want to set. Each plugin will describe its configuration and defaults. In the configuration section below you will find the options defined by the core. Each plugin's options (even the core) are set in their own subobject, which is named after the plugin. For example all of the core's options are set in the core key of the config object:

jQuery("some-selector-to-container-node-here")
	.jstree({
		core : {
			/* core options go here */
		}
	});

Please note that if your options for a given plugin are the same as the defaults you may omit those options or omit the subobject completely (if you do not need to modify the defaults).

There is only one special config option that is not a part of any plugin - this is the plugins option, which defines a list of active plugins for the instance being created. Although many plugins may be included, only the ones listed in this option will be active. The only autoincluded "plugin" is the jstree core.

jQuery("some-selector-to-container-node-here")
	.jstree({
		core : { /* core options go here */ },
		plugins : [ "themes", "html_data", "some-other-plugin" ]
	});

Interacting with the tree

To perform an operation programatically on a given instance you can use two methods:

/* METHOD ONE */
jQuery("some-selector-to-container-node-here")
	.jstree("operation_name" [, argument_1, argument_2, ...]);

/* METHOD TWO */
jQuery.jstree._reference(needle) 
	/* NEEDLE can be a DOM node or selector for the container or a node within the container */
	.operation_name([ argument_1, argument_2, ...]);

NOTE: Functions prefixed with _ can not be called with method one.

jsTree uses events to notify of any changes happening in the tree. All events fire on the tree container in the jstree namespace and are named after the function that triggered them. Please note that for some events it is best to bind before creating the instance. For example:

jQuery("some-container")
	.bind("loaded.jstree", function (event, data) {
		alert("TREE IS LOADED");
	})
	.jstree({ /* configuration here */ });

Please note the second parameter data. Its structure is as follows:

{ 
	"inst" : /* the actual tree instance */, 
	"args" : /* arguments passed to the function */, 
	"rslt" : /* any data the function passed to the event */, 
	"rlbk" : /* an optional rollback object - it is not always present */
}

There is also one special event - before.jstree. This events enables you to prevent an operation from executing. Look at the demo below.

Configuration

html_titles

Boolean. Default is false.

Defines whether titles can contain HTML code.

animation

A number. Default is 500.

Defines the duration of open/close animations. 0 means no animation.

initially_open

An array. Default is [].

Defines which nodes are to be automatically opened when the tree finishes loading - a list of IDs is expected.

rtl

Boolean. Default is false.

Defines whether the tree is in right-to-left mode (also make sure you are using a RTL theme - for example the included default-rtl).

strings

Object. Default is { loading : "Loading ...", new_node : "New node" }.

Contains strings needed for the operation of the tree so that you can localize.

Demos

Binding to an event and executing an action

Preventing an action

This is the same demo as above, but this time the operation will be prevented.

The important part is e.stopImmediatePropagation(); return false.

API

Use extra caution when working with functions prefixed with an underscore - _!
Those functions are probably for internal usage only.

jQuery.jstree.defaults

An object. Default is a collection of all included plugin's defaults.

This object is exposed so that you can apply standart settings to all future instances

jQuery.jstree.plugin ( plugin_name , plugin_data )

This function is used by developers to extend jstree (add "plugins").

string plugin_name
The plugin name - it should be unique.
object plugin_data
The plugin itself. It consists of __init & __destroy functions, defaults object (that of course could be an array or a simple value) and a _fn object, whose keys are all the functions you are extending jstree with. You can overwrite functions (but you can in your function call the overriden old function), and you are responsible for triggering events and setting rollback points. You can omit any of the elements in the plugin_data param. Keep in mind jstree will automatically clear classes prepended with jstree- and all events in the jstree namespace when destroying a tree, so you do not need to worry about those.

Read jstree's code for examples on how to develop plugins.

jQuery.jstree.rollback ( rollback_object )

This function will roll the tree back to the state specified by the rollback object

string rollback_object
Normally you will get this object from the event you are handling. You can of course use .get_rollback() to get the current state of the tree as a rollback object.
```
$("some-container").bind("some-event.jstree", function (e, data) {
	$.jstree.rollback(data.rlbk);
});
```
Keep in mind that not all events will give you a rollback object - sometimes data.rlbk will be false.

jQuery.jstree._focused ()

Returns the currently focused tree instance on the page. If not interaction has been made - it is the last one to be created.

jQuery.jstree._reference ( needle )

Returns the tree instance for the specified needle.

mixed needle
This can be a DOM node, jQuery node or selector pointing to the tree container, or an element within the tree.

jQuery.jstree._instance ( index , container , settings )

This function is used internally when creating new tree instances. Calling this function by itself is not enough to create a new instance. To create a tree use the documented method $("selector").jstree([ options ]).

jQuery.jstree._fn

This object stores all functions included by plugins. It is used internally as a prototype for all instances - do not modify manually.

.data

An object where all plugins store instance specific data. Do not modify manually.

.get_settings ()

Returns a copy of the instance's settings object - the defaults, extended by your own config object.

._get_settings ()

Returns the instance's settings object - the defaults, extended by your own config object.

.get_index ()

Returns the internal instance index.

.get_container ()

Returns the jQuery extended container node of the tree.

._set_settings ( settings )

Replace the settings object with the settings param. Please note that not all plugins will react to the change. Unless you know exactly what you are doing you'd be better off recreating the tree with the new settings.

.init ()

This function is used internally when creating a new instance. Triggers an event, which fires after the tree is initialized, but not yet loaded.

.destroy ()

Destroys the instance - it will automatically remove all bound events in the jstree namespace & remove all classes starting with jstree-. Triggers an event.

.save_opened ()

Stores the currently open nodes before refreshing. Used internally. Triggers an event.

.reopen ( is_callback )

Reopens all the nodes stored by save_opened or set in the initially_open config option on first load. It is called multiple times while reopening nodes - the is_callback param determines if this is the first call (false) or not. Used internally. Triggers an event.

.refresh ( node )

Refreshes the tree. Saves all open nodes, and reloads and then reopens all saved nodes. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree. If set this will reload only the given node - otherwise - the whole tree. Passing -1 also reloads the whole tree.

.loaded ()

A dummy function, whose purpose is only to trigger the loaded event. This event is triggered once after the tree's root nodes are loaded, but before any nodes set in initially_open are opened.

.set_focus ()

Makes the current instance the focused one on the page. Triggers an event.

.is_focused ()

Returns true if the current instance is the focused one, otherwise returns false.

._get_node ( node )

Return the jQuery extended LI element of the node, -1 if the container node is passed, or false otherwise.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree.

._get_next ( node , strict )

Gets the LI element representing the node next to the passed node. Returns false on failure.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree, whose next sibling we want.
bool strict
If set to true only immediate siblings are calculated. Otherwise if the node is the last child of its parent this function will "jump out" and return the parent's next sibling, etc. Default is false.

._get_prev ( node , strict )

Gets the LI element representing the node previous to the passed node. Returns false on failure.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree, whose previous sibling we want.
bool strict
If set to true only immediate siblings are calculated. Otherwise if the node is the first child of its parent this function will "jump out" and return the parent itself. Default is false.

._get_parent ( node )

Gets the LI element representing the parent of the passed node. Returns false on failure.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree, whose parent we want.

._get_children ( node )

Gets the LI elements representing the children of the passed node. Returns false on failure (or if the node has no children).

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree, whose children we want. Use -1 to return all root nodes.

.get_path ( node , id_mode )

Return the path to a node, either as an array of IDs or as an array of node names.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element within the tree, whose path we want.
bool id_mode
If set to true IDs are returned instead of the names of the parents. Default is false.

.open_node ( node , callback , skip_animation )

Opens a closed node, so that its children are visible. If the animation config option is greater than 0 the children are revealed using a slide down animation, whose duration is the value of the animation config option in milliseconds. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element we want opened.
function callback
A callback function executed once the node is opened. Used mostly internally, you'd be better of waiting for the event. You can skip this, by not specifying it, or by passing false.
bool skip_animation
If set to true the animation set in the animation config option is skipped. Default is false.

.close_node ( node , skip_animation )

Closes an open node, so that its children are not visible. If the animation config option is greater than 0 the children are hidden using a slide up animation, whose duration is the value of the animation config option in milliseconds. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element we want closed.
bool skip_animation
If set to true the animation set in the animation config option is skipped. Default is false.

.toggle_node ( node )

If a node is closed - this function opens it, if it is open - calling this function will close it.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element we want toggled.

.open_all ( node , original_obj )

Opens all descendants of the node node.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element whose descendants you want opened. If this param is omitted or set to -1 all nodes in the tree are opened.
mixed original_obj
Used internally when recursively calling the same function - do not pass this param.

.close_all ( node )

Closes all descendants of the node node.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element whose descendants you want closed. If this param is omitted or set to -1 all nodes in the tree are closed.

.is_open ( node ), .is_closed ( node ), .is_leaf ( node )

Those function check if the node is in a state.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element you want checked.

.clean_node ( node )

Applies all necessary classes to the node and its descendants. Used internally. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element you want cleaned. If this param is omitted or set to -1 all nodes in the tree are cleaned.

.get_rollback ()

Get the current tree's state in the rollback format. Used mainly internally by plugins.

.set_rollback ( html , data )

Rollback the tree. Used ONLY internally! Both arguments are part of the rollback object. If you need to rollback - take a look at jQuery.jstree.rollback(). Triggers event.

.load_node ( node , success_callback , error_callback )

A dummy function that is overwritten by data plugins. Triggers event.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element you want loaded. Use -1 for root nodes.
function success_callback
A function to be executed once the node is loaded successfully - used internally. You should wait for the event.
function error_callback
A function to be executed if the node is not loaded due to an error - used internally. You should wait for the event.

._is_loaded ( node )

A dummy function that should return true if the node's children are loaded or false otherwise.

mixed node
This can be a DOM node, jQuery node or selector pointing to an element you want to check.

.create_node ( node , position , js , callback , is_loaded )

Creates the DOM structure necessary for a new node. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to the element you want to create in (or next to).
mixed position
The position of the newly created node. This can be a zero based index to position the element at a specific point among the current children. You can also pass in one of those strings: "before", "after", "inside", "first", "last".
object js
The data for the newly created node. Consists of three keys:
attr - an object of attributes (same used for jQuery.attr(). You can omit this key;
state - a string - either "open" or "closed", for a leaf node - omit this key;
data - a string or an object - if a string is passed it is used for the title of the node, if an object is passed there are two keys you can specify: attr and title;
function callback
A function to be executed once the node is created - used internally. You should wait for the event.
bool is_loaded
Specifies if the parent of the node is loaded or not - used ONLY internally.

.get_text ( node )

Returns the title of a node.

mixed node
This can be a DOM node, jQuery node or selector pointing to the element whose title you need.

.set_text ( node , text )

Sets the title of a node. Triggers an event. This is used mostly internally - wait for a .rename_node event to avoid confusion.

mixed node
This can be a DOM node, jQuery node or selector pointing to the element whose title you want to change.
string text
The new title.

.rename_node ( node , text )

Sets the title of a node. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to the element whose title you want to change.
string text
The new title.

.delete_node ( node )

Removes a node. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to the element you want to remove.

.prepare_move ( o , r , pos , cb , is_cb )

This function is used internally to prepare all necessary variables and nodes when moving a node around. It is automatically called as needed - you do not need to call it manually. Triggers an event.

.check_move ()

Checks if the prepared move is a valid one.

.move_node ( node , ref , position , is_copy , is_prepared , skip_check )

Moves a node to a new place. Triggers an event.

mixed node
This can be a DOM node, jQuery node or selector pointing to the element you want to move.
mixed ref
This can be a DOM node, jQuery node or selector pointing to the element which will be the reference element in the move. -1 may be used too (to indicate the container node).
mixed position
The new position of the moved node. This can be a zero based index to position the element at a specific point among the reference node's current children. You can also use one of these strings: "before", "after", "inside", "first", "last".
bool is_copy
Should this be a copy or a move operation.
bool is_prepared
Used internally when this function is called recursively.
bool skip_check
If this is set to true check_move is not called.

._get_move ()

Returns the lastly prepared move. The returned object contains:
.o - the node being moved
.r - the reference node in the move
.ot - the origin tree instance
.rt - the reference tree instance
.p - the position to move to (may be a string - "last", "first", etc)
.cp - the calculated position to move to (always a number)
.np - the new parent