jQuery treetable

Download the latest release from the jQuery Plugin Registry or grab the source code from Github. Please report issues through Github issues. This plugin is released under both the MIT and the GPLv2 license by Ludo van den Boom.

Basic jQuery treetable Example
Tree column	Additional data
Node 1: Click on the icon in front of me to expand this branch.	I live in the second column.
Node 1.1: Look, I am a table row and I am part of a tree!	Interesting.
Node 1.1.1: I am part of the tree too!	That's it!
Node 2: I am another root node, but without children	Hurray!

Overview
Usage
Configuration
Public API
Examples
Test Suite
CHANGELOG.txt

1. Overview

jQuery treetable is a plugin for jQuery, the 'Write Less, Do More, JavaScript Library'. With this plugin you can display a tree in an HTML table, e.g. a directory structure or a nested list. Why not use a list, you say? Because lists are great for displaying a tree, and tables are not. Oh wait, but this plugin uses tables, doesn't it? Yes. Why do I use a table to display a list? Because I need multiple columns to display additional data besides the tree.

Unobtrusiveness

One of the goals of jQuery treetable is to be as unobtrusive as possible. Being 'unobtrusive' is very cool nowadays, so that was an important requirement. But it is cool for a reason: it keeps your HTML documents clean and it allows the code to degrade nicely when Javascript is not available.

The treetable plugin only requires that you add specific data attributes to every row that is part of your tree. The plugin uses these attributes to determine what your tree looks like. Otherwise, it would have to guess the structure of the tree and it wouldn't be very successful in doing that. See the Usage chapter for more information on how to prepare your tree.

Features

It can display a tree of data in a table column.
It does this as unobtrusively as possible.
It allows branches to be collapsed and expanded (think of how a directory structure works in most file explorers).
It allows unlimited tree depth.
It uses the lightweight jQuery Javascript libray.

2. Usage

Note: This chapter assumes that you have already installed jQuery as described on their website.

Include the plugin in your document

The plugin can either be installed manually or by using the Bower package manager.

Installing with Bower

bower install jquery-treetable

Note that the only listed dependency is jQuery. If you also want to use the drag & drop feature you'll have to install jQuery UI yourself.

Installing manually

Copy the files jquery.treetable.js and css/jquery.treetable.css to your project. Paste the following code right before the closing body tag in your HTML document. Make sure these lines are below the line where you include jQuery. Change the red parts to reflect your situation.

<link href="path/to/jquery.treetable.css" rel="stylesheet" type="text/css" />
<script src="path/to/jquery.treetable.js"></script>
<script>
$("#your_table_id").treetable();
</script>

Styling the tree

By default the tree has little styling. Use the file css/jquery.treetable.theme.default.css as a template for your own styling, or just use this default theme.

Representing your tree in a table

When you pasted the above code and adjusted it to reflect your situation, you enabled the possibility of displaying a tree in your table. To make the tree actually display as a tree you have to add data-tt-id and data-tt-parent-id attributes to your table rows (tr).

How to do this?

First, you should add a unique data-tt-id attribute to each of the rows in your table, for example 'node-x'. Then you add a data-tt-parent-id attribute to each child of a node, give this class a value of 'node-x'. The node-x part should be the same as the data-tt-id of its parent. Do you still follow me? Let me show you an example of a very simple tree: a single parent with a single child. For more examples you should view the source code of this page, where you find several tables for the examples in the examples chapter.

<table>
  <tr data-tt-id="1">
    <td>Parent</td>
  </tr>
  <tr data-tt-id="2" data-tt-parent-id="1">
    <td>Child</td>
  </tr>
</table>

Please note that the plugin expects the rows in the HTML table to be in the same order in which they should be displayed in the tree. For example, suppose you have three nodes: A, B (child of node A) and C (child of node B). If you create rows for these nodes in your HTML table in the following order A - C - B, then the tree will not display correctly. You have to make sure that the rows are in the order A - B - C.

3. Configuration

There are several settings that let you adjust the behavior of the plugin. Each of these settings is described in this section. Pass these options and callback functions to the treetable() function. See the examples.

Settings

Setting	Type	Default	Description
`branchAttr`	`string`	`"ttBranch"`	Optional data attribute that can be used to force the expander icon to be rendered on a node. This allows us to define a node as a branch node even though it does not have children yet. This translates to a `data-tt-branch` attribute in your HTML.
`clickableNodeNames`	`bool`	`false`	Set to true to expand branches not only when expander icon is clicked but also when node name is clicked.
`column`	`int`	`0`	The number of the column in the table that should be displayed as a tree.
`columnElType`	`string`	`"td"`	The types of cells that should be considered for the tree (`td`, `th` or both).
`expandable`	`bool`	`false`	Should the tree be expandable? An expandable tree contains buttons to make each branch with children collapsible/expandable.
`expanderTemplate`	`string`	`<a href="#"> </a>`	The HTML fragment used for the expander.
`indent`	`int`	`19`	The number of pixels that each branch should be indented with.
`indenterTemplate`	`string`	`<span class="indenter"></span>`	The HTML fragment used for the indenter.
`initialState`	`string`	`"collapsed"`	Possible values: `"expanded"` or `"collapsed"`.
`nodeIdAttr`	`string`	`"ttId"`	Name of the data attribute used to identify node. Translates to `data-tt-id` in your HTML.
`parentIdAttr`	`string`	`"ttParentId"`	Name of the data attribute used to set parent node. Translates to `data-tt-parent-id` in your HTML.
`stringCollapse`	`string`	`"Collapse"`	For internationalization.
`stringExpand`	`string`	`"Expand"`	For internationalization.

Events

Setting	Type	Default	Description
`onInitialized`	`function`	`null`	Callback function fired when the tree has been initialized.
`onNodeCollapse`	`function`	`null`	Callback function fired when a branch is collapsed.
`onNodeExpand`	`function`	`null`	Callback function fired when a branch is expanded.
`onNodeInitialized`	`function`	`null`	Callback function fired when a node has been initialized.

4. Public API

`treetable()` Plugin Function

The treetable() function accepts the following arguments:

options (optional): A Javascript object of configuration settings as described in the chapter on configuration.
force (optional): Pass the boolean true to force reinitialization of the tree.

Additional Functions

Use the following functions to manipulate the tree programmatically. Calling a function should be done through the treetable() function. For example, to collapse node '42' use $("#tree").treetable("collapseNode", "42").

collapseAll(): Collapse all nodes at once.
collapseNode(id): Collapse a single node, identified by id.
expandAll(): Expand all nodes at once.
expandNode(id): Expand a single node, identified by id.
loadBranch(node, rows): Load additional rows (HTML <tr>s) into the tree, with parent node. If node is null rows will be added as root nodes.
move(nodeId, destinationId): Move node nodeId to new parent with destinationId.
node(id): Select a node from the tree. Returns a TreeTable.Node object.
removeNode(id): Remove a node and all its descendants from the tree.
reveal(id): Reveal a node in the tree.
sortBranch(node), sortBranch(node, columnOrFunction): Sort node's children alphabetically. Defaults to sorting on the values in the configured tree column (see settings). Pass an optional column number or sorting function as the second argument columnOrFunction. See the tests for examples of custom sorting functions. Does not recursively sort children of children.
unloadBranch(node): Remove nodes/rows (HTML <tr>s) from the tree, with parent node. Note that the parent (node) will not be removed.

Classes

The following classes are dynamically added to the tree rows:

expanded: When the row is expanded
collapsed: When the row is collapsed
branch: When the row has children or the branchAttr is present
leaf: When the row has no children

5. Examples

Basic Static Tree

app

controllers

application_controller.rb

helpers

models

views

$("#example-basic-static").treetable();

Basic Expandable Tree

app