jsTree bundled plugins documentation

Go to: Checkbox | Contextmenu | Cookie | Hotkeys | Metadata | Themeroller | XML flat | XML nested

To be able to use any plugin, all you need to do is include its source:

`<script type="text/javascript" src="``path-to-source/jquery.tree.plugin.js``"></script>`

If you included a datastore you can already use it in any instance with the `get` function. Or to use it to populate an entire tree - check the `data.type` config option.

If the included plugin is not a datasore you need to activate it for every instance you want to use it, or just activate it for all instances. To activate it on an instance check the `plugins` config option. To activate it on all instances modify the `jQuery.tree.defaults` object - all instances created AFTER the modification will have the plugin enabled.

To just activate the plugin without modifying any options (if available) use this code in the `plugins` section:

    plugins : {
    	"plugin-name" : { }
    }

To modify any of the options (if available) use this code in the `plugins` section:

    plugins : {
    	"plugin-name" : { option : value, other-option : other-value }
    }

# Checkbox

Converts a tree to a checkbox three where each node can be checked, unchecked or undetermined (if for example it has two children and one of the is checked and the other isn't). To get the visual feedback it is recommended to use the "checkbox" theme or define your own classes to handle the visualization of the items.

### Options

## three_state `Boolean`

If set to `true` each node will respect the state of its children - like an options tree in windows, so the "undetermined" state will be available. If set to `false` each node is either checked or not, regardless of its children states.

Default is: `true`

### Functions

## jQuery.tree.plugins.checkbox.get_checked([ tree ]) Return value: `jQuery`

This functions returns a collection of all checked nodes within a tree.

Arguments: `jsTree` `tree`

The instance to use - defaults to the currently focused tree.

## jQuery.tree.plugins.checkbox.get_unchecked([ tree ]) Return value: `jQuery`

This functions returns a collection of all unchecked nodes within a tree.

Arguments: `jsTree` `tree`

The instance to use - defaults to the currently focused tree.

## jQuery.tree.plugins.checkbox.get_undetermined([ tree ]) Return value: `jQuery`

This functions returns a collection of all undetermined nodes within a tree.

Arguments: `jsTree` `tree`

The instance to use - defaults to the currently focused tree.

## jQuery.tree.plugins.checkbox.uncheck(node) Return value: `Boolean`

This functions unchecks a node.

Arguments: `mixed` `node`

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

## jQuery.tree.plugins.checkbox.check(node) Return value: `Boolean`

This functions checks a node.

Arguments: `mixed` `node`

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

# Contextmenu

Enables a custom context menu in the tree. Please not this does not work in Opera, as the browser has a policy against custom context menus.

### Options

## class_name `String`

A class name to use on the item that invoked the context menu.

Default is: `"hover"`

## items `Object`

An object containing all the items of the context menu.

Default is:

    items : {
    	create : {
    		label	: "Create",
    		icon	: "create",
    		visible	: function (NODE, TREE_OBJ) {
    			if(NODE.length != 1) return 0;
    			return TREE_OBJ.check("creatable", NODE);
    		},
    		action	: function (NODE, TREE_OBJ) {
    			TREE_OBJ.create(false, TREE_OBJ.get_node(NODE[0]));
    		},
    		separator_after : true
    	},
    	rename : {
    		label	: "Rename",
    		icon	: "rename",
    		visible	: function (NODE, TREE_OBJ) {
    			if(NODE.length != 1) return false;
    			return TREE_OBJ.check("renameable", NODE);
    		},
    		action	: function (NODE, TREE_OBJ) {
    			TREE_OBJ.rename(NODE);
    		}
    	},
    	remove : {
    		label	: "Delete",
    		icon	: "remove",
    		visible	: function (NODE, TREE_OBJ) {
    			var ok = true;
    			$.each(NODE, function () {
    				if(TREE_OBJ.check("deletable", this) == false) {
    					ok = false;
    					return false;
    				}
    			});
    			return ok;
    		},
    		action	: function (NODE, TREE_OBJ) {
    			$.each(NODE, function () {
    				TREE_OBJ.remove(this);
    			});
    		}
    	}
    }

Each item consists of a few settings:

## label `String`

The label of the menu item.

## icon `String`

The icon used infront of the menu item - if left blank - no icon is shown. If the string contains a `/` it is interpreted as a path to an image, otherwise it is used as a class that you can style yourself using a selector like:
`.tree-theme_name_here-context a ins.icon-string-here { }`

## visible(node, tree) Should return: `1, 0 or -1`

This function is called just before the context menu is shown. You receive the node the menu is invoked on and the tree instance as arguments. You can hide or disable some of the items. `1` means show, `0` means disable and `-1` means hide.

## action(node, tree)

This function is called when this specific menu item is clicked. You receive the node the menu is invoked on and the tree instance as arguments.

# Cookie

Enables the user to save the state of the tree across sessions. What this basically does is save the opened and selected nodes in a cookie, and reopens/reselects them the next time the user uses the tree. Depends on the jQuery Cookie plugin, which can be found in the `lib/` folder.

### Options

## prefix `String`

A prefix to prepent on all cookies created by that specific instance. Useful if you have multiple trees.

Default is: `""`

## options `Object`

All the options used in the jQuery Cookie plugin.

Default is:

    options : {
    	expires: false,
    	path: false,
    	domain: false,
    	secure: false
    }

## types `Object`

An object of Boolean values storing which cookies should be set (currently `selected` and `open` are the only options). If you don't want to save the selected state of the tree (for example) just set `selected` to `false`.

Default is:

    types : {
    	selected	: true,
    	open		: true
    }

## keep_selected `Boolean`

If some nodes are marked for selection in the config of the tree (using `selected`) should the plugin respect those or remove them.

Default is: `false`

## keep_opened `Boolean`

If some nodes are marked for opening in the config of the tree (using `opened`) should the plugin respect those or remove them.

Default is: `false`

# Hotkeys

Enables keyboard navigation on the tree. Depends on the jQuery Hotkeys plugin, which can be found in the `lib/` folder.

### Options

## hover_move `Boolean`

Should the navigation functions only move the hover state or change the selected node.

Default is: `false`, meaning the selected node is changed.

## functions `Object`

Each key in this object is a string representing a keyboard button (or combination of buttons) and its value is the function to be executed. In the function `this` points to the tree instance.

Default is:

    functions : {
    	"up"	: function () { $.tree.plugins.hotkeys.get_prev.apply(this); return false; },
    	"down"	: function () { $.tree.plugins.hotkeys.get_next.apply(this); return false; },
    	"left"	: function () { $.tree.plugins.hotkeys.get_left.apply(this); return false; },
    	"right"	: function () { $.tree.plugins.hotkeys.get_right.apply(this); return false; },
    	"f2"	: function () { if(this.selected) this.rename(); return false; },
    	"del"	: function () { if(this.selected) this.remove(); return false; },
    	"ctrl+c": function () { if(this.selected) this.copy(); return false; },
    	"ctrl+x": function () { if(this.selected) this.cut(); return false; },
    	"ctrl+v": function () { if(this.selected) this.paste(); return false; }
    }

# Metadata

Enables inline rule definitions (such as clickable, deletable, etc). You can define those in an arbitrary attribute. Each bundled datastore provides the ability to pass attributes, so that should not be an issue. Depends on the jQuery Metadata plugin, which can be found in the `lib/` folder.

### Options

## attribute `Sting`

The attribute used for storing metadata.

Default is: `"data"`.

# Themeroller

Enables the tree to use the Themeroller (jQuery UI) styles by assigning various classes provided by the library. It is neccessary to use the "themeroller" theme when using this plugin.

# XML flat

A datastore - depends on Sarrissa for transformations - Sarrissa can be found in the `lib/` folder. Supports `async` and the `static` option (check the `data.opts` config option). Data should follow this structure:

    <root>
    	<item id="node_id" parent_id="the_parent_node_id" state="open" attribute="value">
    		<content>
    			<name lang="language_code" icon=""><![CDATA[Root node 1]]></name>
    		</content>
    	</item>
    	<item id="node_id" parent_id="the_parent_node_id" state="open" attribute="value">
    		<content>
    			<name lang="language_code" icon=""><![CDATA[Root node 2]]></name>
    		</content>
    	</item>
    </root>

For root nodes or when using async set `parent_id` to 0. All attributes of `<item>` nodes get copied over to the resulting `<li>` nodes. All attributes you set on `<name>` nodes get copied over to the resulting `<a>` nodes. Each language is represented by a `<name>` node. If you use only one language you may omit the `lang` attribute. Use the `icon` attribute only for a custom icon - otherwise theme and type icons are applied.

# XML nested

A datastore - depends on Sarrissa for transformations - Sarrissa can be found in the `lib/` folder. Supports `async` and the `static` option (check the `data.opts` config option). The structure is the same as in XML flat with all the same clarifications, the only thing different is that you should not set a `parent_id` attribute on `<item>` nodes and you should instead nest the nodes. Like so:

    <root>
    	<item id="node_id" state="open" attribute="value">
    		<content>
    			<name><![CDATA[Root node 1]]></name>
    		</content>
    		<item id="node_id" state="open" attribute="value">
    			<content>
    				<name<![CDATA[Child node 1]]></name>
    			</content>
    		</item>
    	</item>
    	<item id="node_id" attribute="value">
    		<content>
    			<name><![CDATA[Root node 2]]></name>
    		</content>
    	</item>
    </root>