# jstree
[jsTree](http://www.jstree.com/) is jquery plugin, that provides interactive trees. It is absolutely free, [open source](https://github.com/vakata/jstree) and distributed under the MIT license.
jsTree is easily extendable, themable and configurable, it supports HTML & JSON data sources, AJAX & async callback loading.
jsTree functions properly in either box-model (content-box or border-box), can be loaded as an AMD module, and has a built in mobile theme for responsive design, that can easily be customized. It uses jQuery's event system, so binding callbacks on various events in the tree is familiar and easy.
You also get:
* drag & drop support
* keyboard navigation
* inline edit, create and delete
* tri-state checkboxes
* fuzzy searching
* customizable node types
_Aside from this readme you can find a lot more info on [jstree.com](http://www.jstree.com) & [the discussion group](https://groups.google.com/forum/#!forum/jstree)_.
---
<!-- MarkdownTOC depth=0 autolink=true bracket=round -->
- [Getting Started](#getting-started)
- [Include all neccessary files](#include-all-neccessary-files)
- [Populating a tree using HTML](#populating-a-tree-using-html)
- [Populating a tree using an array (or JSON)](#populating-a-tree-using-an-array-or-json)
- [The required JSON format](#the-required-json-format)
- [Populating the tree using AJAX](#populating-the-tree-using-ajax)
- [Populating the tree using AJAX and lazy loading nodes](#populating-the-tree-using-ajax-and-lazy-loading-nodes)
- [Populating the tree using a callback function](#populating-the-tree-using-a-callback-function)
- [Working with events](#working-with-events)
- [Interacting with the tree using the API](#interacting-with-the-tree-using-the-api)
- [More on configuration](#more-on-configuration)
- [Plugins](#plugins)
- [checkbox](#checkbox)
- [contextmenu](#contextmenu)
- [dnd](#dnd)
- [massload](#massload)
- [search](#search)
- [sort](#sort)
- [state](#state)
- [types](#types)
- [unique](#unique)
- [wholerow](#wholerow)
- [More plugins](#more-plugins)
- [License & Contributing](#license--contributing)
<!-- /MarkdownTOC -->
---
## Getting Started
### Include all neccessary files
To get started you need 3 things in your page:
1. jQuery (anything above 1.9.1 will work)
2. A jstree theme (there is only one theme supplied by default)
3. The jstree source file
```html
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/jstree/3.0.9/themes/default/style.min.css" />
<script src="//cdnjs.cloudflare.com/ajax/libs/jstree/3.0.9/jstree.min.js"></script>
```
_If you decide to host jstree yourself - the files are located in the `dist` folder. You can safely ignore the `dist/libs` folder._
---
### Populating a tree using HTML
Now we are all set to create a tree, inline HTML is the easiest option (suitable for menus). All you need to do is select a node (using a jQuery selector) and invoke the `.jstree()` function to let jstree know you want to render a tree inside the selected node. `$.jstree.create(element)` can be used too.
```html
<div id="container">
<ul>
<li>Root node
<ul>
<li>Child node 1</li>
<li>Child node 2</li>
</ul>
</li>
</ul>
</div>
<script>
$(function() {
$('#container').jstree();
});
</script>
```
[view result](http://jsfiddle.net/vakata/2kwkh2uL/)
_You can add a few options when rendering a node using a data-attribute (note the quotes):_
```html
<li data-jstree='{ "selected" : true, "opened" : true }'>Root node ...
```
---
### Populating a tree using an array (or JSON)
Building trees from HTML is easy, but it is not very flexible, inline JS data is a better option:
```html
<div id="container"></div>
<script>
$(function() {
$('#container').jstree({
'core' : {
'data' : [
{ "text" : "Root node", "children" : [
{ "text" : "Child node 1" },
{ "text" : "Child node 2" }
]
}
]
}
});
});
</script>
```
[view result](http://jsfiddle.net/vakata/2kwkh2uL/1/)
Unlike the previous simple HTML example, this time the `.jstree()` function accepts a config object.
For now it is important to note that jstree will try to parse any data you specify in the `core.data` key and use it to create a tree. As seen in the previous example, if this key is missing jstree will try to parse the inline HTML of the container.
#### The required JSON format
The data you use must be in a specific format, each branch of the tree is represented by an object, which must at least have a `text` key. The `children` key can be used to add children to the branch, it should be an array of objects.
_Keep in mind, you can use a simple string instead of an object if all you need is node with the given text, the above data can be written as:_
```js
[ { "text" : "Root node", "children" : [ "Child node 1", "Child node 2" ] } ]
```
There are other available options for each node, only set them if you need them like:
* `id` - makes if possible to identify a node later (will also be used as a DOM ID of the `LI` node). _Make sure you do not repeat the same ID in a tree instance (that would defeat its purpose of being a unique identifier and may cause problems for jstree)_.
* `icon` - a string which will be used for the node's icon - this can either be a path to a file, or a className (or list of classNames), which you can style in your CSS (font icons also work).
* `data` - this can be anything you want - it is metadata you want attached to the node - you willbe able to access and modify it any time later - it has no effect on the visuals of the node.
* `state` - and object specifyng a few options about the node:
- `selected` - if the node should be initially selected
- `opened` - if the node should be initially opened
- `disabled` - if the node should be disabled
- `checked` - __checkbox plugin specific__ - if the node should be checked (only used when `tie_selection` is `false`, which you should only do if you really know what you are doing)
- `undetermined` - __checkbox plugin specific__ - if the node should be rendered in undetermined state (only used with lazy loading and when the node is not yet loaded, otherwise this state is automatically calculated).
* `type` - __types plugin specific__ - the type of the nodes (should be defined in the types config), if not set `"default"` is assumed.
* `li_attr` - object of values which will be used to add HTML attributes on the resulting `LI` DOM node.
* `a_attr` - object of values which will be used to add HTML attributes on the resulting `A` node.
Here is a new demo with some of those properties set:
```html
<div id="container"></div>
<script>
$(function() {
$('#container').jstree({
'core' : {
'data' : [
{
"text" : "Root node",
"state" : {"opened" : true },
"children" : [
{
"text" : "Child node 1",
"state" : { "selected" : true },
"icon" : "glyphicon glyphicon-flash"
},
{ "text" : "Child node 2", "state" : { "disabled" : true } }
]
}
]
}
});
});
</script>
```
[view result](http://jsfiddle.net/vakata/2kwkh2uL/11/)
---
### Populating the tree using AJAX
Building off of the previous example, let's see how to have jstree make AJAX requests for you.
```html
<div id="container"></div>
<script>
$(function() {
$('#container').jstree({
'core' : {
'data' : {
"url" : "//www.jstree.com/fiddle/",
"dataType" : "json" // needed only if you do not supply JSON headers
}
}
});
});
</script>
```
The server response is:
```json
[{
"id":1,"text":"Root node","children":[
{"id":2,"text":"Child node 1"},
{"id":3,"text":"Child node 2"}
]
}]
```
[vi