# jQuery treeTable Plugin Documentation

Simple treeTable Example
TreeColumn | 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!

See the Examples chapter for more examples. To download releases of this plugin, visit treeTable's project page. The source code of this plugin and this documentation is available on GitHub: http://github.com/ludo/jquery-plugins/tree/master/treeTable.

## Table of Contents

1. Introduction
2. Installation
3. Usage
   1. Include the plugin in your html document
   2. Representing your tree in a table
   3. Configuration
4. Examples
   1. A complex tree
   2. A tree that is not collapsable
   3. Dragging and dropping example
   4. A large, complex table with drag and drop

## 1. Introduction

treeTable is a plugin for jQuery, the 'Write Less, Do More, JavaScript Library'. With this plugin you can display a tree in a table, i.e. 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.

This plugin is released under the MIT license by Ludo van den Boom.

#### Unobtrusiveness

I wanted this plugin 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 my code to degrade nicely when JavaScript is not available.

Unfortunately, the treeTable plugin requires that you add `class` and `id` attributes to every row that is part of the tree. It would have been great if this weren't necessary, because it doesn't look pretty in your html, but the plugin needs to know 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 describe a 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.

NOTE: This plugin was originally released under the name ActsAsTreeTable, but has been renamed to treeTable with version 2.0.

## 2. Installation

Installing this plugin is straight-forward. You will have to copy several files and, if necessary, adjust some paths so that every file is available to the plugin.

1. Add jQuery to your project. See their website for instructions on doing this. You need at least version 1.2.6.
2. Add `src/javascripts/jquery.treeTable.js` (or the minified version) to your project.
3. Add the stylesheet `src/stylesheets/jquery.treeTable.css` to your project.
4. Copy the images in `src/images` to your project.
5. Adjust the paths to `background-image`s in the stylesheet `jquery.treeTable.css` to point to the image files that you have just copied.

That's it! You are now ready to start using the plugin in your project.

## 3. Usage

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

### 3.1 Include the plugin in your html document

Paste the following code between the `head` tags in your html document, underneath the part 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 type="text/javascript" src="path/to/jquery.treeTable.js"></script>
    <script type="text/javascript">

    $(document).ready(function()  {
      $("#your_table_id").treeTable();
    });

    </script>

### 3.2 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 `id` and `class` attributes to your table rows (`tr`).

#### How to do this?

First, you should add a unique `id` to each of the rows in your table, for example '`node-x`' where x is a number. Then you add a `class` attribute to each child of a node, give this class a name of '`child-of-node-x`'. The node-x part should be the same as the `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 id="tree">
      <tr id="node-1">
        <td>Parent</td>
      </tr>
      <tr id="node-2" class="child-of-node-1">
        <td>Child</td>
      </tr>
      <tr id="node-3" class="child-of-node-2">
        <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.3 Configuration

There are several settings that let you adjust the behavior of the plugin. Each of these settings is described in this section. See Example 3 for an example of how to change these settings.

Setting | Type | Default | Description
--- | --- | --- | ---
`childPrefix` | `string` | `"child-of-"` | Customize the prefix used for node classes.
`clickableNodeNames` | `bool` | `false` | Set to true to expand branches not only when expander icon is clicked but also when node name is clicked.
`expandable` | `bool` | `true` | Should the tree be expandable? An expandable tree contains buttons to make each branch with children collapsable/expandable.
`indent` | `int` | `19` | The number of pixels that each branch should be indented with.
`initialState` | `string` | `"expanded"` | Possible values: `"expanded"` or `"collapsed"`.
`treeColumn` | `int` | `0` | The number of the column in the table that should be displayed as a tree.

## 4. Examples

The examples in this chapter all use the treeTable plugin to display a tree in a table, with collapsable branches. View the source code of this file to see how it is done and read the Usage chapter for further details.

### 4.1 A complex tree

Example 1: A complex tree.
Node 1
Node 1.1
Node 1.2
Node 1.3
Node 2
Node 2.1
Node 2.1.1
Node 2.2
Node 2.2.1
Node 2.2.1.1
Node 2.2.2

### 4.2 A tree that is not collapsable

    $("#example3").treeTable({
      expandable: false
    });

Example 2: A tree that is not collapsable.
Tree column | Column 2
--- | ---
Node 1 | Second column
Node 1.1 | Second column
Node 1.2 | Second column
Node 1.3 | Second column
Node 2 | Second column
Node 2.1 | Second column
Node 2.1.1 | Second column
Node 2.2 | Second column
Node 2.2.1 | Second column
Node 2.2.2 | Second column

### 4.3 Draging and dropping example

This example uses the jQuery UI components Draggable and Droppable to create a tree that can be manipulated by dragging and dropping of the nodes. You can drag a node by clicking on it's title and drag it to a different position. This behavior requires a bit more coding than the simple trees above, but it is still pretty straight-forward. The code for this example is listed below. The most interesting line in this code, from the plugin's point of view is `$($(ui.draggable).parents("tr")).appendBranchTo(this);`. Here the `appendBranchTo` function is called to move the selected branch to a new location.

Example 3: Dragging and dropping example.
Title | Size | Kind
--- | --- | ---
CHANGELOG | 4 KB | Plain text
doc | -- | Folder
images | -- | Folder
bg-table-thead.png | 52 KB | Portable Network Graphics image
folder.png | 4 KB | Portable Network Graphics image
page_white_text.png | 4 KB | Portable Network Graphics image
index.html | 4 KB | HTML document
javascripts | -- | Folder
jquery.js | 56 KB | JavaScript source
stylesheets | -- | Folder
master.css | 4 KB | CSS style sheet
MIT-LICENSE | 4 KB | Plain text
README.markdown | 4 KB | Markdown document
src | -- | Folder
images | -- | Folder
bullet_toggle_minus.png | 4 KB | Portable Network Graphics image
bullet_toggle_plus.png | 4 KB | Portable Network Graphics image
stylesheets | -- | Folder
jquery.treeTable.css | 4 KB | CSS style sheet
jquery.treeTable.js | 8 KB | JavaScript source

    /* NOTE: Do not forget to download the jQuery UI Draggable and Droppable
     * components if you want to enable dragging and dropping behavior!
     */

    // Configure draggable nodes
    $("#dnd-example .file, #dnd-example .folder").draggable({
      helper: "clone",
      opacity: .75,
      refreshPositions: true, // Performance?
      revert: "invalid",
      revertDuration: 300,
      scroll: true
    });

    // Configure droppable rows
    $("#dnd-example .folder").each(function() {
      $(this).parents("tr").droppable({
        accept: ".file, .folder",
        drop: function(e, ui) {
          // Call jQuery treeTable plugin to move the branch
          $($(ui.draggable).parents("tr")).appendBranchTo(this);
        },
        hoverClass: "accept",
        over: function(e, ui) {
          // Make the droppable branch expand when a draggable node is moved over it.
          if(this.id != $(ui.draggable.parents("tr")[0]).id && !$(this).is(".expanded")) {
            $(this).expand();
          }
        }
      });
    });

    // Make visible that a row is clicked
    $("table#dnd-example tbody tr").mousedown(function() {
      $("tr.selected").removeClass("selected"); // Deselect currently selected rows
      $(this).addClass("selected");
    });

    // Make sure row is selected when span is clicked
    $("table#dnd-example tbody tr span").mousedown(function() {
      $($(this).parents("tr")[0]).trigger("mousedown");
    });