jqTree

JqTree is a tree widget.

Features

Create a tree from JSON data
Drag and drop
Works on ie7+, firefox 3.6+, chrome and safari
Written in Coffeescript

The project is hosted on github, has a test suite and some examples.

var data = [
    {
        label: 'node1',
        children: [
            { label: 'child1' },
            { label: 'child2' }
        ]
    },
    {
        label: 'node2',
        children: [
            { label: 'child3' }
        ]
    }
];
$('#tree1').tree({
    data: data,
    autoOpen: true,
    dragAndDrop: true
});

Requirements

jQuery 1.5+

Downloads

All (version 0.10): jqTree.tar.gz
Javascript: tree.jquery.js
Css: jqtree.css
Image: jqtree-icons.png

Tutorial

Include jQuery.

<script src="jquery-1.7.2.min.js"></script>

Include tree.jquery.js:
```
<script src="tree.jquery.js"></script>
```
Include jqtree.css:
Optionally, for saveState include jquery-cookie:
```
<script src="jquery.cookie.js"t></scriptt>
```
Create a div.
```
<div id="tree1"></div>
```

Create tree data.

var data = [
    {
        label: 'node1',
        children: [
            { label: 'child1' },
            { label: 'child2' }
        ]
    },
    {
        label: 'node2',
        children: [
            { label: 'child3' }
        ]
    }
];

Create tree widget.

$(function() {
    $('#tree1').tree({
        data: data
    });
});

Alternatively, get the data from the server.

$.getJSON(
    '/some_url/',
    function(data) {
        $('#tree1').tree({
            data: data
        });
    }
);

Changelog

0.11 (july 8 2012)

Autoescape text
Added autoEscape option
Issue 33: appendNode does not correctly refresh the tree
Issue 34: unset internal pointer to previously selected node on DOM deselect
Issue 38: Correctly check if browser has support for localstorage
Issue 41: Open nodes are not displayed correctly in ie7

0.10 (june 10 2012)

Optimized getNodeById
Issue #18 and #26: Made comparison in getNodeById less strict
Added function prependNode
Added 'data-url' option
Added removeNode function
Issue #24: Tree with jquery ui Dialog: expand causes resize and move problem
Added Travis ci support
Added addNodeAfter, addNodeBefore and addParentNode
Renamed icons.png to jqtree-icons.png
selectNode with empty node deselects the current node

0.9 (may 9 2012)

Issue #15: 'tree.open' event is not triggered when dragging nodes
Issue #18: Allow moveNode to be canceled through ev.preventDefault()
Use sprite for images
Added function closeNode
Added support for localstorage
Implemented alternative data format

0.8 (april 18 2012)

Replace jquery.ui widget with SimpleWidget
Added 'previous_parent' to 'tree.move' event
Add posibility to load subtree
Added 'tree.open' and 'tree.close' events

Tree options

data

Define the contents of the tree. The data is a nested array of objects. This option is required.
It looks like this:

var data = [
    {
        label: 'node1',
        children: [
            { label: 'child1' },
            { label: 'child2' }
        ]
    },
    {
        label: 'node2',
        children: [
            { label: 'child3' }
        ]
    }
];
$('#tree1').tree({data: data});

label: label of a node (required)
children: array of child nodes (optional)

You can also include other data in the objects. You can later access this data.
For example, to add an id:

{
    label: 'node1',
    id: 1
}

dataUrl

Load the node data from this url.

$('#tree1').tree({
   dataUrl: '/example_data.json' 
});

You can also set the data-url attribute on the dom element:

<div id="tree1" data-url="/example_data.json"></div>
<script>
    $('#tree1').tree();
</script>

autoOpen

Open nodes initially.

true: open all nodes.
false (default): do nothing
n: open n levels

Open all nodes initially:

$('#tree1').tree({
    data: data,
    autoOpen: true
});

Open first level nodes:

$('#tree1').tree({
    data: data,
    autoOpen: 0
});

saveState

Save and restore the state of the tree automatically. Saves in a cookie which nodes are opened and selected.
The state is saved in localstorage. In browsers that do not support localstorage, the state is saved in a cookie. For this to work, please include jquery-cookie.

For this to work, you should give each node in the tree data an id field:

{
    label: 'node1',
    id: 123,
    childen: [
        label: 'child1',
        id: 124
    ]
}

true: save and restore state in a cookie
false (default): do nothing
string: save state and use this name to store in a cookie

$('#tree1').tree({
    data: data,
    saveState: true
});

Example: save state in key 'tree1':

$('#tree1').tree({
    data: data,
    saveState: 'tree1'
});

dragAndDrop

Turn on dragging and dropping of nodes.

true: turn on drag and drop
false (default): do not allow drag and drop

Example: turn on drag and drop.

$('#tree1').tree({
    data: data,
    dragAndDrop: true
});

selectable

Turn on selection of nodes.

true: turn on selection of nodes
false (default): turn off selection of nodes

Example: turn on selection of nodes.

$('#tree1').tree({
    data: data,
    selectable: true
});

onCanSelectNode

You can set a function to override if a node can be selected. The function gets a node as parameter, and must return true or false.
For this to work, the option 'selectable' must be 'true'.

// Example: nodes with children cannot be selected
$('#tree1').tree({
    data: data,
    selectable: true
    onCanSelectNode: function(node) {
        if (node.children.length == 0) {
            // Nodes without children can be selected
            return true;
        }
        else {
            // Nodes with children cannot be selected
            return false;
        }
    }
});

onCreateLi

The function is called for each created node. You can use this to define extra html.

$('#tree1).tree({
    data: data,
    onCreateLi: function(node, $li) {
        // Add 'icon' span before title
        $li.find('.title').before('');
    }
});

onIsMoveHandle

You can override this function to determine if a dom element can be used to move a node.

$('#tree1').tree({
    data: data,
    onIsMoveHandle: function($element) {
        // Only dom elements with 'title' class can be used
        // as move handle.
        return ($element.is('.title'));
    }
});

onCanMove

You can override this function to determine if a node can be moved.

$('#tree1').tree({
    data: data,
    dragAndDrop: true,
    onCanMove: function(node) {
        if (! node.parent.parent) {
            // Example: Cannot move root node
            return false;
        }
        else {
            return true;
        }
    }
});

onCanMoveTo

You can override this function to determine if a node can be moved to a certain position.

$('#tree1').tree({
    data: data,
    dragAndDrop: true,
    onCanMoveTo: function(moved_node, target_node, position) {
        if (target_node.is_menu) {
            // Example: can move inside menu, not before or after
            return (position == 'inside');
        }
        else {
            return true;
        }
    }
});

autoEscape

Determine if text is autoescaped. The default is true.

Functions

loadData

function loadData(data);
function loadData(data, parent_node);

Load the tree with new data.

// Assuming the tree exists
var new_data = [
    {
        label: 'node1',
        children: [
            { label: 'child1' },
            { label: 'child2' }
        ]
    },
    {
        label: 'node2',
        children: [
            { label: 'child3' }
        ]
    }
];
$('#tree1').tree('loadData', new_data);

It's also possible to add the nodes to an existing node in the tree.

// Get node by id (this assumes that the nodes have an id)
var node = $('#tree1').tree('getNodeById', 100);

// Add new nodes
var data = [
    { label: 'new node' },
    { label: 'another new node' }
];
$('#tree1').tree('loadData', data, node);

toJson

function toJson();
Get the tree data as json.

// Assuming the tree exists
$('#tree1').tree('toJson');

getNodeById

function getNodeById(id);
Get a tree node by node-id. This assumes that you have given the nodes in the data a unique id.

var $tree = $('#tree1);
var data = [
    { id: 10, name: 'n1' },
    { id: 11, name: 'n2' }
];

$tree.tree({
    data: data
});
var node = $tree.tree('getNodeById', 10);

selectNode

function selectNode(node);
function selectNode(node, must_open_parents);

Select this node. If must_open_parents is true, then open all parents, so the node is visible.

// create tree
var $tree = $('#tree1');
$tree.tree({
    data: data,
    selectable: true
});

var node = $tree.tree('getNodeById', 123);
$tree.tree('selectNode', node, true);

openNode

function openNode(node);
function openNode(node, skip_slide);

Open this node with a slide animation. The node must have child nodes.

// create tree
var $tree = $('#tree1');
$tree.tree({
    data: data
});

var node = $tree.tree('getNodeById', 123);
$tree.tree('openNode', node);

To open the node without the slide animation, call with skip_slide parameter is true.

$tree.tree('openNode', node, true);

closeNode

function closeNode(node);
function closeNode(node, skip_slide);

Close this node with a slide animation. The node must have child nodes.

var node = $tree.tree('getNodeById', 123);
$tree.tree('closeNode', node);

To close the node without the slide animation, call with skip_slide parameter is true.

$tree.tree('closeNode', node, true);

getSelectedNode

Get the selected node. Returns the row data or false.

var node = $tree.tree('getselectednode');

addNodeAfter

function addNodeAfter(new_node_info, existing_node);

Add a new node after this existing node.

var node1 = $('#tree1').getNodeByName('node1');
$('#tree1').addNodeAfter(
    {
        label: 'new_node',
        id: 456
    },
    node1
);

addNodeBefore

function addNodeBefore(new_node_info, existing_node);

Add a new node before this existing node.

addParentNode

function addParentNode(new_node_info, existing_node);

Add a new node as parent of this existing node.

var node1 = $('#tree1').getNodeByName('node1');
$('#tree1').addParentNode(
    {
        label: 'new_parent',
        id: 456
    },
    node1
);

removeNode

function removeNode(node);

Remove node from the tree.

$('#tree1').tree('removeNode', node);

appendNode

function appendNode(new_node_info, parent_node);

Add a node to this parent node. If *parent_node* is empty, then the new node becomes a root node.

var parent_node = $tree.getNodeById(123);

$tree.appendNode(
    {
        label: 'new_node',
        id: 456
    },
    parent_node
);

To add a root node, leave *parent_node* empty:

$tree.appendNode(
    {
        label: 'new_node',
        id: 456
    }
);

Events

tree.click

Triggered when a tree node is clicked.

// create tree
$('#tree1').tree({
    data: data
});

// bind 'tree.click' event
$('#tree1').bind(
    'tree.click',
    function(event) {
        // The clicked node is 'event.node'
        var node = event.node;
        alert(node.name);
    }
);

tree.contextmenu

Triggered when the user right-clicks a tree node. The event contains the following properties:

node: the node that is clicked on
click_event: the original click event

// bind 'tree.contextmenu' event
$('#tree1').bind(
    'tree.contextmenu',
    function(event) {
        // The clicked node is 'event.node'
        var node = event.node;
        alert(node.name);
    }
);

tree.move

Triggered when the user moves a node.

Event.move_info contains:

moved_node
target_node
position: (before, after or inside)
previous_parent

$('#tree1').tree({
    data: data,
    dragAndDrop: true
});

$('#tree1).bind(
    'tree.move',
    function(event) {
        console.log('moved_node', e.move_info.moved_node);
        console.log('target_node', e.move_info.target_node);
        console.log('position', e.move_info.position);
        console.log('previous_parent', e.move_info.previous_parent);
    }
);

You can prevent the move by calling event.preventDefault()

$('#tree1).bind(
    'tree.move',
    function(event) {
        event.preventDefault();
    }
);

You can later call event.move_info.doMove() to move the node. This way you could ask the user before moving the node:

$('#tree1).bind(
    'tree.move',
    function(event) {
        event.preventDefault();

        if (confirm('Really move?')) {
            event.doMove();
        }
    }
);