jqTree

JqTree is a tree widget.

Features

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

Downloads

Tutorial

Changelog

0.11 (july 8 2012)
0.10 (june 10 2012)
0.9 (may 9 2012)
0.8 (april 18 2012)

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});

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.

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
    ]
}
$('#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.

Example: turn on drag and drop.

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

Turn on 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:

// 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:

$('#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();
        }
    }
);