jsTree v.1.0 Core documentation

# 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 (if they are not present they will first be loaded) when the tree finishes loading - a list of IDs is expected.

### initially_load

An array. Default is `[]`.

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

### load_open

A Boolean. Default is `false`.

When set to `true` forces loading of nodes marked as open, which do not have children. Otherwise nodes are only visualized as open without any children and opening/closing such a node won't cause it to load (make a server call).

### open_parents

Boolean. Default is `true`.

If set to true opening a node will also open any closed ancestors it has (will open the whole chain down to this node).

### notify_plugins

Boolean. Default is `true`.

If set to true loading nodes with some metadata will trigger some actions on the corresponding plugin. So you can actually set the selected/checked/etc

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

- Root node 1
  - Child node 1
  - Child node 2
- Root node 2

### Preventing an action

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

- Root node 1
  - Child node 1
  - Child node 2
- Root node 2

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.

### .get_container_ul ()

Returns the jQuery extended first UL node in the container 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.

### .unset_focus ()

If the current instance is focused this removes the focus. Triggers an event.

### .is_focused ()

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

### .lock ()

Sets the tree to a locked state - no methods can be called on that instance except for `unlock` and `is_locked`.

### .unlock ()

Sets the tree to a unlocked state (the default state).

### .is_locked ()

Returns `true` if the tree is locked, 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`.

### .correct_state ( node )

Corrects closed items to leaf items, if no children are found. Used internally, triggers an event.

- `mixed` node

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

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

### .after_open ( node )

A dummy function, it triggers an event after the open animation has finished.

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

### .after_close ( node )

A dummy function, it triggers an event after the close animation has finished.

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

- `boolean` do_animation

  If set to `true` all nodes are opened with an animation. This can be slow on large trees.

- `mixed` original_obj

  Used internally when recursively calling the same function - do not pass this param.

### .close_all ( node, do_animation )

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.

- `boolean` do_animation

  If set to `true` all nodes are closed with an animation. This can be slow on large trees.

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

Returns the needed string from the config object. If the key does not exist the key itself is returned.

- `string` key

  The name of the string you are looking for.

### .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
`.oc` - the original node (if there was a copy)
`.cy` - boolen indicating if the move was a copy
`.cr` - same as `np`, but if a root node is created this is -1
`.op` - the former parent
`.or` - the node that was previously in the position of the moved node