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!

Table of Contents

  1. Overview
  2. Usage
  3. Configuration
  4. Public API
  5. Examples
  6. Test Suite
  7. 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, 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.

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

2. Usage

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

Include the plugin in your document

Copy the files javascripts/src/jquery.treetable.js and stylesheets/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 stylesheets/jquery.treetable.theme.default.css as a template for your own styling. You can also just use this default theme, in that case don't forget to copy the images from images and update the paths in the CSS accordingly.

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="#">&nbsp;</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 all nodes at once.
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.
reveal(id)
Reveal a node in the tree.
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 to the 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
controllers
application_controller.rb
helpers
models
views
$("#example-basic-expandable").treetable({ expandable: true });

Complex Tree With Drag and Drop

This example uses jQuery UI's Draggable and Droppable components. The tree has 459 nodes.


Examples: 2-1-1, 3-1-1-2-2 and 3-2-1-2-3-1-2-2-1-1-1-1-2-5
Expand all Collapse all
Name Kind Size
Acknowledgements.rtf File 480.95 KB
CHUD Folder --
amber Folder --
AmberTraceFormats.pdf File 124.46 KB
BigTop Folder --
BigTopUserGuide.pdf File 1314.71 KB
Saturn Folder --
SaturnUserGuide.pdf File 694.29 KB
Shark Folder --
SharkUserGuide.pdf File 12902.51 KB
simg4 Folder --
simg4_plus Folder --
simg5 Folder --
DocSets Folder --
com.apple.ADC_Reference_Library.CoreReference.docset Folder --
Contents Folder --
Info.plist File 1.23 KB
Resources Folder --
docSet.dsidx File 41504 KB
docSet.skidx File 43072 KB
Documents Folder --
documentation Folder --
Accessibility Folder --
Reference Folder --
AccessibilityCarbonRef Folder --
CarbonAXRefRevisions Folder --
CarbonAXRefRevisions.html File 7.44 KB
Index Folder --
index_of_book.html File 174.1 KB
index.html File 1.1 KB
Reference Folder --
reference.html File 196.28 KB
toc.html File 15.92 KB
AccessibilityLowlevel Folder --
accessibility Folder --
CompositePage.html File 5.7 KB
index.html File 1.67 KB
toc.html File 2.87 KB
accessibility-constants.html File 26.94 KB
accessibility-datatypes.html File 11.02 KB
accessibility-functions.html File 15.55 KB
accessibility-mpindex.html File 9.87 KB
AXActionConstants Folder --
CompositePage.html File 15.08 KB
index.html File 1.67 KB
toc.html File 4.9 KB
AXAttributeConstants Folder --
AXError Folder --
AXNotificationConstants Folder --
AXRoleConstants Folder --
AXTextAttributedString Folder --
AXUIElement Folder --
AXValue Folder --
AXValueConstants Folder --
index.html File 10.1 KB
UniversalAccess Folder --
adcstyle.css File 15.86 KB
AppleApplications Folder --
Reference Folder --
AddressBookC_Collection Folder --
Index Folder --
index_of_book.html File 153.98 KB
index.html File 13.62 KB
Introduction Folder --
Introduction.html File 5.41 KB
RevisionHistory.html File 4.66 KB
AddressBookRefUpdate Folder --
Articles Folder --
AddressBook_10.1-10.2_SymbolChanges.html File 80.84 KB
AddressBook_10.2-10.3_SymbolChanges.html File 54.2 KB
AddressBook_10.3-10.4_SymbolChanges.html File 14.78 KB
AddressBook_10.4-10.5_SymbolChanges.html File 11.03 KB
Introduction.html File 7.3 KB
RevisionHistory.html File 6.19 KB
index.html File 1.08 KB
toc.html File 2.84 KB
AMWorkflow_class Folder --
AMWorkflowController_class Folder --
AMWorkflowView_Class Folder --
AppleApp_Aperture_002 Folder --
Automator_constants Folder --
AutomatorFramework Folder --
AutomatorReference Folder --
AutomatorRefUpdate Folder --
CalendarStoreFramework Folder --
CalendarStoreReference Folder --
CalendarStoreRefUpdate Folder --
Dashboard_Ref Folder --
FinalCutPro_XML Folder --
InstantMessageFramework Folder --
InstantMessageFrameworkRef Folder --
InstantMessageRefUpdate Folder --
iSyncJavaScriptRef Folder --
iSyncManualTestSuiteRef Folder --
iSyncSyncMLRef Folder --
MessageFrameworkReference Folder --
Motion_FXPlug_Ref Folder --
SafariCSSRef Folder --
SafariHTMLRef Folder --
SyncServicesRefUpdate Folder --
SyncServicesSchemaRef Folder --
WebKitDOMRef Folder --
AppleScript Folder --
Reference Folder --
StudioReference Folder --
art Folder --
boxes.gif File 11.52 KB
browser.gif File 26.04 KB
button_in_window.gif File 8.17 KB
cc_app_info_window.gif File 24.36 KB
circular_prog_indicator.gif File 0.65 KB
color_panel.jpg File 24.91 KB
color_well.gif File 7.58 KB
combobox.gif File 1.44 KB
comboboxlist.gif File 4.12 KB
display_alert.gif File 28.69 KB
display_dialog.gif File 28.42 KB
doc_exp_groups.gif File 22.52 KB
drawer.gif File 34.4 KB
drawer_content_view.gif File 8.21 KB
drawer_instances_in_nib.gif File 20.97 KB
drawers_in_palette.gif File 17.34 KB
files_owner_in_nib.gif File 15.24 KB
font_panel.gif File 17.16 KB
hw_exp_grps_files.gif File 15.35 KB
ib_number_formatter.gif File 1.46 KB
image_tab_mainmenu_nib.gif File 12.33 KB
image_view_from_app.gif File 17.18 KB
matrix.gif File 7.36 KB
menu_item.gif File 16.85 KB
menu_showing_file_menu.gif File 17 KB
movie_view.gif File 34.76 KB
number_formatter_info.gif File 24.8 KB
open_panel.gif File 32.06 KB
outline_view.gif File 18.7 KB
popup_button.gif File 6.76 KB
progindindet.gif File 3.78 KB
save_panel.gif File 39.43 KB
secure_text_field.gif File 9.91 KB
simple_toolbar.gif File 10.4 KB
sliders.gif File 11.01 KB
sounds_in_nib_window.gif File 22.26 KB
split_view.gif File 15.73 KB
stepper.gif File 1.08 KB
table_app.gif File 22.72 KB
table_view.gif File 14.55 KB
tabview.gif File 24.86 KB
text_fields.gif File 7.1 KB
text_view.gif File 12.18 KB
to_do_outline.gif File 15.4 KB
window.gif File 6.41 KB
Index Folder --
index.html File 1.13 KB
sr10_panel_suite Folder --
sr10_pplugin_suite Folder --
sr11_textview_suite Folder --
sr1_about Folder --
sr2_fundamentals Folder --
sr3_app_suite Folder --
sr4_container_suite Folder --
sr5_control_suite Folder --
sr6_data_suite Folder --
sr7_doc_suite Folder --
sr8_drag_drop_suite Folder --
sr9_menu_suite Folder --
sr_history Folder --
toc.html File 132.84 KB
Carbon Folder --
Cocoa Folder --
CoreFoundation Folder --
css Folder --
Darwin Folder --
DeveloperTools Folder --
DeviceDrivers Folder --
Games Folder --
GraphicsImaging Folder --
Hardware Folder --
HardwareDrivers Folder --
images Folder --
index-date.html File 74.06 KB
index-date0.html File 284.1 KB
index-date2.html File 73.94 KB
index-date3.html File 74.4 KB
index-date4.html File 75.11 KB
index-date5.html File 41.11 KB
index-rev-date.html File 49.03 KB
index-rev-revision.html File 49.01 KB
index-rev-title.html File 49.03 KB
index-rev-topic.html File 71.41 KB
index-rev-topic0.html File 93.76 KB
index-rev-topic2.html File 29.61 KB
index-title.html File 73.91 KB
index-title0.html File 284.11 KB
index-title2.html File 74.7 KB
index-title3.html File 73 KB
index-title4.html File 74.15 KB
index-title5.html File 42.91 KB
index-topic.html File 72.46 KB
index-topic0.html File 601.26 KB
index-topic10.html File 74.41 KB
index-topic2.html File 73.6 KB
index-topic3.html File 72.47 KB
index-topic4.html File 71.89 KB
index-topic5.html File 73.89 KB
index-topic6.html File 73.1 KB
index-topic7.html File 70.55 KB
index-topic8.html File 71.25 KB
index-topic9.html File 72.56 KB
index.html File 20.65 KB
Internationalization Folder --
InternetWeb Folder --
iPhone Folder --
js Folder --
LegacyTechnologies Folder --
MacOSX Folder --
MacOSXServer Folder --
MusicAudio Folder --
Networking Folder --
OpenSource Folder --
Performance Folder --
Porting Folder --
Printing Folder --
QuickTime Folder --
Resources Folder --
ScriptingAutomation Folder --
Security Folder --
Storage Folder --
TextFonts Folder --
UserExperience Folder --
WebObjects Folder --
referencelibrary Folder --
adc.css File 1.46 KB
base.css File 1.08 KB
images Folder --
body_bg.gif File 0.24 KB
main_bgbottom.gif File 2.35 KB
main_bgtop.gif File 6.88 KB
main_bgtop_stroke.gif File 7.62 KB
UpdateBanner_core.png File 24.25 KB
index.html File 1.15 KB
version.plist File 0.44 KB
com.apple.ADC_Reference_Library.DeveloperTools.docset Folder --
Contents Folder --
Info.plist File 1.33 KB
Resources Folder --
docSet.dsidx File 2752 KB
docSet.skidx File 5664 KB
Documents Folder --
documentation Folder --
adcstyle.css File 15.86 KB
AppleApplications Folder --
AppleApplications.html File 0.22 KB
Conceptual Folder --
Dashcode_UserGuide Folder --
Contents Folder --
Resources Folder --
de.lproj Folder --
Advanced Folder --
chapter_8_section_1.html File 6.71 KB
chapter_8_section_2.html File 7.93 KB
chapter_8_section_3.html File 6.38 KB
Art Folder --
apple_birthday_widget.jpg File 33.5 KB
canvas_inspector.jpg File 71.75 KB
countdown_attributes.jpg File 46.69 KB
project_window.jpg File 107.57 KB
source_code_inspector.jpg File 76.19 KB
webapp_add_code.jpg File 85.65 KB
webapp_add_part.jpg File 108.16 KB
webapp_first_test.jpg File 86.82 KB
webapp_project_window.jpg File 152.27 KB
chapter_999_section_1.html File 6.3 KB
CodeAndDebugging Folder --
Dashcode_UserGuide.pdf File 1875.27 KB
DebuggingSharing Folder --
DesignTools Folder --
index.html File 1.11 KB
Introduction Folder --
MakingaWebApp Folder --
MakingaWidgetwithDashcode Folder --
PartsReference Folder --
Templates Folder --
toc.html File 38.57 KB
WidgetProjects Folder --
en.lproj Folder --
Advanced Folder --
chapter_8_section_1.html File 6.6 KB
chapter_8_section_2.html File 7.4 KB
chapter_8_section_3.html File 6.24 KB
Art Folder --
chapter_999_section_1.html File 6.2 KB
CodeAndDebugging Folder --
Dashcode_UserGuide.pdf File 1087.36 KB
DebuggingSharing Folder --
DesignTools Folder --
index.html File 1.09 KB
Introduction Folder --
MakingaWebApp Folder --
MakingaWidgetwithDashcode Folder --
PartsReference Folder --
Templates Folder --
toc.html File 38.11 KB
WidgetProjects Folder --
es.lproj Folder --
fr.lproj Folder --
it.lproj Folder --
ja.lproj Folder --
nl.lproj Folder --
zh.lproj Folder --
Dashboard-date.html File 10.88 KB
Dashboard-rev-date.html File 8.85 KB
Dashboard-rev-revision.html File 8.83 KB
Dashboard-rev-title.html File 8.85 KB
Dashboard-title.html File 10.71 KB
index-date.html File 11.79 KB
index-rev-date.html File 9.38 KB
index-rev-revision.html File 9.36 KB
index-rev-title.html File 9.37 KB
index-rev-topic.html File 9.37 KB
index-title.html File 11.78 KB
index-topic.html File 12.39 KB
index.html File 7.24 KB
iSync-date.html File 8.17 KB
iSync-title.html File 8 KB
Carbon Folder --
Carbon.html File 0.21 KB
DesignGuidelines-date.html File 9.93 KB
DesignGuidelines-rev-date.html File 7.45 KB
DesignGuidelines-rev-revision.html File 7.44 KB
DesignGuidelines-rev-title.html File 7.45 KB
DesignGuidelines-title.html File 9.77 KB
index-date.html File 19.66 KB
index-rev-date.html File 12.35 KB
index-rev-revision.html File 12.33 KB
index-rev-title.html File 12.34 KB
index-rev-topic.html File 12.98 KB
index-title.html File 19.65 KB
index-topic.html File 22.64 KB
index.html File 10.96 KB
IntelBasedMacs-date.html File 10.5 KB
IntelBasedMacs-title.html File 10.33 KB
Performance-date.html File 9.14 KB
Performance-title.html File 8.98 KB
Porting-date.html File 8.78 KB
Porting-title.html File 8.63 KB
Tools-date.html File 16.03 KB
Tools-rev-date.html File 10.85 KB
Tools-rev-revision.html File 10.83 KB
Tools-rev-title.html File 10.84 KB
Tools-title.html File 15.88 KB
UserExperience-date.html File 8.85 KB
UserExperience-title.html File 8.69 KB
Cocoa Folder --
CoreFoundation Folder --
css Folder --
Darwin Folder --
DeveloperTools Folder --
GraphicsImaging Folder --
HardwareDrivers Folder --
images Folder --
index-date.html File 38.14 KB
index-rev-date.html File 20.91 KB
index-rev-revision.html File 20.89 KB
index-rev-title.html File 20.9 KB
index-rev-topic.html File 45.06 KB
index-title.html File 38.14 KB
index-topic.html File 77.78 KB
index.html File 17.08 KB
Internationalization Folder --
InternetWeb Folder --
Java Folder --
js Folder --
LegacyTechnologies Folder --
MacOSX Folder --
OpenSource Folder --
Performance Folder --
Porting Folder --
Resources Folder --
ScriptingAutomation Folder --
UserExperience Folder --
Xcode Folder --
featuredarticles Folder --
adcstyle.css File 15.86 KB
AppleApplications Folder --
idxDashboard-date.html File 8.35 KB
idxDashboard-title.html File 8.24 KB
index-date.html File 8.52 KB
index-title.html File 8.51 KB
index-topic.html File 8.51 KB
index.html File 6.46 KB
Carbon Folder --
Cocoa Folder --
css Folder --
DeveloperTools Folder --
Games Folder --
images Folder --
index-date.html File 16.03 KB
index-title.html File 16.03 KB
index-topic.html File 19.32 KB
index.html File 10.98 KB
js Folder --
LegacyTechnologies Folder --
ScriptingAutomation Folder --
UserExperience Folder --
index.html File 0.23 KB
qa Folder --
reference Folder --
referencelibrary Folder --
releasenotes Folder --
samplecode Folder --
technicalnotes Folder --
technicalqas Folder --
technotes Folder --
version.plist File 0.44 KB
iPhone SDK License.rtf File 37.93 KB
Perl Folder --
wxPerl Folder --
INSTALL.pod File 8.26 KB
todo.txt File 2.3 KB
Python Folder --
PyObjC Folder --
announcement.txt File 2.33 KB
api-notes-macosx.html File 30.09 KB
api-notes-macosx.txt File 18.37 KB
C-API.html File 11 KB
C-API.txt File 8.67 KB
coding-style.html File 4.53 KB
coding-style.txt File 2.92 KB
gnustep.html File 1.96 KB
gnustep.txt File 1.52 KB
index.html File 2.75 KB
index.txt File 2.64 KB
intro.html File 44.82 KB
intro.txt File 38.38 KB
protocols.html File 3.48 KB
protocols.txt File 2.79 KB
PyObjCTools.html File 10.96 KB
PyObjCTools.txt File 7.9 KB
Quartz Folder --
api-notes.txt File 1.47 KB
release-process.html File 3.83 KB
release-process.txt File 2.65 KB
structure.html File 6.55 KB
structure.txt File 5.1 KB
TODO.html File 13.49 KB
TODO.txt File 9.06 KB
tutorial Folder --
tutorial_embed Folder --
tutorial_reading.html File 12.85 KB
tutorial_reading.txt File 11.12 KB
website.lst File 0.58 KB
wrapping.html File 6.04 KB
wrapping.txt File 5.2 KB
xcode Folder --
Xcode-Templates.html File 13.97 KB
wxPython Folder --
RubyCocoa Folder --
wxWidgets Folder --
Xcode Tools License.rtf File 18.79 KB
$("#example-advanced").treetable({ expandable: true });

// Highlight selected row
$("#example-advanced tbody").on("mousedown", "tr", function() {
  $(".selected").not(this).removeClass("selected");
  $(this).toggleClass("selected");
});

// Drag & Drop Example Code
$("#example-advanced .file, #example-advanced .folder").draggable({
  helper: "clone",
  opacity: .75,
  refreshPositions: true,
  revert: "invalid",
  revertDuration: 300,
  scroll: true
});

$("#example-advanced .folder").each(function() {
  $(this).parents("tr").droppable({
    accept: ".file, .folder",
    drop: function(e, ui) {
      var droppedEl = ui.draggable.parents("tr");
      $("#example-advanced").treetable("move", droppedEl.data("ttId"), $(this).data("ttId"));
    },
    hoverClass: "accept",
    over: function(e, ui) {
      var droppedEl = ui.draggable.parents("tr");
      if(this != droppedEl[0] && !$(this).is(".expanded")) {
        $("#example-advanced").treetable("expandNode", $(this).data("ttId"));
      }
    }
  });
});

AJAX enabled D&D example

See https://github.com/ludo/jquery-treetable-ajax-example.

Using treetable with PersistJS

See https://github.com/jughead/jquery-treetable-ajax-persist.