jQuery File Tree

Written by Cory S.N. LaViska on March 25th, 2008

A configurable, AJAX file browser plugin for jQuery.

The responses to jQuery File Tree have been incredible over the past few months. A special thanks to everyone for your compliments and support :)

If anyone is interested in a 2.0 release, let me know. I'm thinking that I'd like to branch this project into a generic AJAX tree that can use custom connectors for more than just files and folders. I've been considering some really great features, but I'd prefer to hear what you folks want before I make any final decisions. If I get a decent response, there's a good chance you'll see another version of this plugin in the near future.

Overview
Features
Compatibility
Demo
Download
Usage
Connector Scripts
1. Custom Connector Scripts
Version History
Licensing & Terms of Use
Special Thanks
Comments

Overview

jQuery File Tree is a configurable, AJAX file browser plugin for jQuery. You can create a customized, fully-interactive file tree with as little as one line of JavaScript code.

Currently, server-side connector scripts are available for PHP, ASP, ASP.NET, JSP, and Lasso. If you’re a developer, you can easily make your own connector to work with your language of choice.

Features

Produces valid, semantic XHTML
Fully customizable via CSS
Ability to style icons based on file extension
Uses AJAX to fetch file information on the fly
Easy to configure and implement
Includes connector scripts for PHP and ASP.NET (C#)
Supports custom connector scripts for extended functionality
Customizable expand/collapse event
Customizable expand/collapse speeds
Supports jQuery easing functions
Single- and multi-folder views
Configurable load message

Compatibility

jQuery File Tree works in all browsers supported by jQuery. It has been fully tested in:

Internet Explorer 6 & 7
Firefox 2 & 3 (beta)
Safari 3
Opera 9

Demo

View a live demonstration of the file tree with various options.

Download

Current version: Version 1.01 (12 April 2008)

Usage

Dependencies

jQuery File Tree requires jQuery 1.2 or above. For easing effects, you will need the jQuery Easing Plugin or another jQuery easing plugin of your choice.

Creating a File Tree

In it’s simplest form, you can create a file tree using the following code:

$(document).ready( function() {

    $('#container_id').fileTree({ root: '/some/folder/' }, function(file) { 

        alert(file);

    });

});

where #container_id is the ID of an empty DIV element that exists on your page. The file tree will automatically load when your page loads.

Configuring the File Tree

Parameters are passed as an object to the fileTree() function. Valid options include:

Parameter	Description	Default Value
`root`	root folder to display	`/`
`script`	location of the serverside AJAX file to use	`jqueryFileTree.php`
`folderEvent`	event to trigger expand/collapse	`click`
`expandSpeed`	Speed at which to expand branches (in milliseconds); use -1 for no animation	`500`
`collapseSpeed`	Speed at which to collapse branches (in milliseconds); use -1 for no animation	`500`
`expandEasing`	Easing function to use on expand	None
`collapseEasing`	Easing function to use on collapse	None
`multiFolder`	Whether or not to limit the browser to one subfolder at a time	`true`
`loadMessage`	Message to display while initial tree loads (can be HTML)	`Loading...`

To create a file tree with multiple parameters, your code will look something like this:

$(document).ready( function() {

    $('#container_id').fileTree({

      root: '/some/folder/',

      script: 'jqueryFileTree.asp',

      expandSpeed: 1000,

      collapseSpeed: 1000,

      multiFolder: false

    }, function(file) { 

        alert(file);

    });

});

Styling the File Tree

The file tree relies 100% on CSS for styling. To give your users an aesthetically pleasing experience, you should either use the included stylesheet for your file tree or create your own. Refer to jqueryFileTree.css to make any changes in the styles.

Handling Feedback

When a file is selected, jQuery File Tree passes the filename back as a string. The easiest way to capture and handle this is by using an anonymous function. If you want to pass the selected filename to a function you create called openFile(), your code will look like this:

function openFile(file) {

    // do something with file

}

$(document).ready( function() {

    $('#container_id').fileTree({ [options] }, function(file) { 

        openFile(file);

    });

});

Connector Scripts

jQuery File Tree comes with a handful of serverside connector scripts that are used to read the file system on your server and return data to the clientside script via AJAX. The default connector script is jqueryFileTree.php. You can use a connector script for another language by setting the script parameter to the location of the script you want to use (see Configuring the File Tree). Alternatively, you can build a custom connector script to extend the functionality of jQuery File Tree to better suit your needs (see Custom Connector Scripts).

Connector scripts for the following languages are included in the download:

PHP by Cory S.N. LaViska
ASP (VBS) by Chazzuka
ASP.NET (C#) by Andrew Sweeny
ColdFusion by Tjarko Rikkerink
JSP by Joshua Gould
Lasso by Marc Sabourdin
Lasso by Jason Huck
Python/Django by Martin Skou
Ruby by Erik Lax

If you would like to share a connector that you’ve written for another language, let us know! We’ll be happy to add it to the download for everyone to use!

The connector scripts provided with jQuery File Tree are only designed to read information from a specified root folder. Although this is typically harmless, there exists a potential for malicious individuals to be able to view your entire directory structure by spoofing the root parameter. It is highly recommended that you add some form of check to your connector script to verify the path being scanned is a path that you want to allow visitors to see.

Custom Connector Scripts

You can create a custom connector script to extend the functionality of the file tree. The easiest way to do this is probably by modifying one of the scripts supplied in the download. If you want to start from scratch, your script should accept one POST variable (dir) and output an unsorted list in the following format:

<ul class="jqueryFileTree" style="display: none;">

    <li class="directory collapsed"><a href="#" rel="/this/folder/">Folder Name</a></li>

    (additional folders here)

    <li class="file ext_txt"><a href="#" rel="/this/folder/filename.txt">filename.txt</a></li>

    (additional files here)

</ul>

Note that the corresponding file extension should be written as a class of the li element, prefixed with ext_. (The prefix is used to prevent invalid class names for file extensions that begin with non-alpha characters.)

Version History

1.01

Updated to work with foreign characters in directory/file names (12 April 2008)

1.00

Initial release (24 March 2008)

Licensing & Terms of Use

Special Thanks

A special thanks goes out to FAMFAMFAM for their excellent Silk Icon Set.

Comments

Looks really great! Nice job.

Any plans for jpg thumbnail support?

#1 Floopie on Mar 26th, 2008

very well designed and cute

#2 Coskun on Mar 27th, 2008

Any plans to offer a JSP connector?

#3 Demetrios Kyriakis on Mar 27th, 2008

Demetrios, I'd love to offer more connectors including JSP, ColdFusion, Ruby, etc. If you or anyone else is willing to write a stable connector for another language I will be glad to include it (with credit, of course) in the download.

#4 Cory S.N. LaViska on Mar 27th, 2008

I think that's a very nice plugin. Thanks for creating it with customization and flexibility in mind. That's what I always need when using plugins. Great job.

#5 Ihsan on Mar 27th, 2008

Congrats ! This plugin is just great..
Just one thing,.. when I change the handler to openFile(file) and click on a file in the tree, nothing happens ? Did I forget something ?

#6 John on Mar 28th, 2008

John, I've updated the article to better explain this. Please reread the section on Handling Feedback.

#7 Cory S.N. LaViska on Mar 28th, 2008

openFile(); method isn't part of the package. It's just an example of how you can use an anonymous callback function.

#8 Levi Lewis on Mar 28th, 2008

Thanks for the feedback guys,... you might also point out the scandir() function in jqueryFileTree.php is only supported in PHP5 (yet alternative methods are available in PHP4)

#9 John on Mar 28th, 2008

Good call, John. I've posted a PHP4 alternative to scandir() here: http://abeautifulsite.net/notebook.php?article=59

#10 Cory S.N. LaViska on Mar 28th, 2008

I am already using jQuery. This plug-in looks cool in demo. I love to use it in future projects.

#11 Kevin on Mar 28th, 2008

Excellent, just need a bit modifications to fit what i need, a checkbox to get multiselect file name for further process

thank you

#12 bali web designer on Apr 1st, 2008

Very nice work!

Seeing some great uses for this project, yet just not right now. Would be neat to see some features like (yes, these are Ext/YUI inspired):

- get data from a JSON/XML file, and no output in pure UL's (and not necessarily link it to a filesystem)
* bonus: load in the tree in one call

- drag and drop support
* treenode properties such as: allowChildren, allowDrag, etc.

- save tree state in cookie

- some functions like:
* get a node and manipulate it (change text or icon for example)
* reload the tree
* collapse the full tree
* ..

Just sending in some suggestions here, maybe they'll make in the 2.0 release. If you need any help on these here, feel free to ping/mail me ;)

#13 Bramus! on Apr 1st, 2008

Congratulations for your beautiful work!
I found it very useful, and since I am currently working with the prototype framework, I picked your plugin and translated it for prototype.

You can find it on my website (I gave you all the credits you need :) )

Oh, I fused the PHP4 scandir "hack" into the PHP connector ...

Please, pay a visit and tell me what you think, we could even enlarge our projects and work together to make them better and better.

My regards ! ;)

#14 Daniele Di Bernardo on Apr 1st, 2008

Superb script! I`d like to translate this article to Polish.

regards

#15 decimus on Apr 1st, 2008

Pretty amazing. I could definitely this.

#16 mark on Apr 1st, 2008

Forgot to tell you the reference page for my Prototype File Tree project:

http://www.marzapower.com/blog/show/211

#17 Daniele Di Bernardo on Apr 2nd, 2008

The best solution for my problem!

#18 pavlentij on Apr 4th, 2008

please help me!! jquery file tree dont work for spanish directories. E.g.: c:\imágenes.
please mail me!!!
thnx!!!

#19 Ignacio on Apr 11th, 2008

Ignacio, I have updated the script to work with foreign characters. Please download the latest version.

#20 Cory S.N. LaViska on Apr 12th, 2008

Excelent! Thanks for update!! :)

#21 Ignacio on Apr 14th, 2008

very nice work, how to expand all the folder when the page loaded.

#22 Prakaash on Apr 18th, 2008

Hello everybody, in 1st place i would like to thank Cory for this script.

Now ... can please anyone tellme how to make the files downloadble? Make an example/ piece of code for dummies like me :)

tanks in advance for your time

Luis

#23 Luis on Apr 19th, 2008

Awesome script! Does anyone have any ideas how you could programatically drill-down into nested folders? I know I can trigger the click event on single directories, but I'd like to drill-down several directories deep. I can't seem to work out a solution to this.

#24 Travis Phipps on Apr 21st, 2008

FYI: Looks like the zip archive linked on this page still contains v1.0 of the plugin. I was able to get v1.01 from the demonstration site.

#25 Travis Phipps on Apr 22nd, 2008

Thanks, Travis. I've corrected the download now. It reverted last night when I added the JSP connector.

#26 Cory S.N. LaViska on Apr 22nd, 2008

tanks alot for the file tree. i have modified it to be used as a navigation for my portfolio site: http://www.kasparbumke.net
some questions:
1.how should i credit your work?
2. is it possible to make the hyperlink for folders actually go somewhere. (i want the page in another frame to change) ?
3. Any way to include the icons in the hyperlink?

just point me to where in the files this could be changed and i will figure it out.

#27 kaspar on Apr 22nd, 2008

I was finally able to programmatically navigate the tree structure! I had to add an "ajaxCallback" to the plugin to support what I needed. I simply added the following line: if( o.ajaxCallback != undefined ) o.ajaxCallback(t);
after the bindTree(c) function call. This allows me to specify a function to be called after each AJAX call. Then I can use this to navigate down into a specific sub-folder n levels deep. Thanks again for such a great control!

#28 Travis Phipps on Apr 23rd, 2008

I cannot use it. I added all the files in the same directory, I uploaded them but it shows me a blank file tree. Though, the Connector works. When I access the website, it loads everything (Loading...) but the tree is not visible. In DOM I can only see the original node. Can you help me with that?

#29 Sabrina on Apr 24th, 2008

The JSP Backend contains a small bug:
In the extension exatraction line:
String ext = dotIndex > 0 ? file.substring(dotIndex) : "";
there should be used "dotIndex + 1" to get the correct extension without the dot.

#30 Demetrios Kyriakis on May 1st, 2008

Any plans to add some more functionality to your file tree?
E.g. something like the FileTree from ExtJS project?
http://filetree.extjs.eu/

The backend protocol might be described in the link above could be used for your tree too since it supports all required operations.

#31 Demetrios Kyriakis on May 1st, 2008

I am not able to get it to work. I just see empty div. Could you also include the code for the demo page in the zip file as well. Thanks.

#32 adarsh on May 3rd, 2008

This was almost exactly what I was looking for, simple and not over bloated with a million features I won't use. There is one thing I need to be able to do, any suggestions or pointers would be greatly appreciated.
I'm calling the initial function several times in a page, but I need to be able to "title" each dir listing. I hope that makes some sort of sense.
Thanks.

#33 Stephen on May 7th, 2008

use
HttpUtility.UrlDecode(Request.Form["dir"])

in C# for better location

#34 Ernest on May 7th, 2008

Ok, I figured it out - well, I figured out something that would work for me.
Fist of all, add a variable to pass to jqueryFileTree.js (I used base:)

$(document).ready( function() {
$('#dirList').fileTree({ root: 'USVDR11/', script: 'jqueryFileTree.php', multiFolder: false, base: 'Service Desk' }, function(file) {
showFile(file);
});
});

and then, in the connector (jqueryFileTree.php in my case) just before the echo"<ul..."; add

echo "<div id=\"base\" style=\"display: none;\"></div>";

and lastly in the jqueryFileTree.js add the following to the list of "defaults":
if( o.base == undefined ) o.base = 'Tree';

and lastly add
$(c).find('DIV:hidden').replaceWith(o.base).show();
to the beginning of the if statement in the show() function.

This may not be the best or most clever way to handle it, but it works for me.

Thanks.

#35 Stephen on May 9th, 2008

Sorry - at the end, that should have been showTree() function

#36 Stephen on May 9th, 2008

I'm going to have to say that I'm a little disappointed that there's not drag-drop support built in. Ext JS's platform has this support, but their library is a massive honking multi-megabyte download. jQuery is much nicer. If you could add drag-drop support, I would pay you to use the tree in my apps.

#37 Matt on May 10th, 2008

Int he multi-param example you have a ";" as a terminator after the word "false". That is a syntax error, just drop it :)

#38 Soulhuntre on May 14th, 2008

Hi, when I creating nonjavascript link (example: filetree.php?module=files&file=image.jpg) for file in the directory, and I click on this link in filetree the page is reload and after the filetree is collapse. How I make filetree where after the page loading the filetree will expand in current location where is the file locate. thnx

#39 Mato on May 23rd, 2008

Is there a ASP.NET (VB) connector?

Tried the C# and I am struggling with setting the directory correctly. For some reason it says the directory cannot be found. Tried it straight out of the box, with only directory changes. Any help is appreciated. Thanks.

#40 Seth on May 29th, 2008

Hello ;-)

Just one thing:

It would be cool to put this code into php connector:
$ext = strtolower($ext);

What's the magic: the icons with uppercase extensions will appear :-P

#41 Dalibor on Jun 4th, 2008

I'm trying out the Lasso connector. The file tree displays correctly but the callback does not display the file path and name in the alert box when the file is clicked. Could this be a flaw in the connector? Any ideas?

#42 Rp on Jun 4th, 2008

Hi

Is it possible to do this :
When we click on a file, we are sent to a website

#43 kpo on Jun 4th, 2008

Thank u for the great work. Was wondering how to go about keeping certain directories password protected. The scripts seem to override the .htaccess settings. Thoughts?

#44 sam on Jun 12th, 2008

> Was wondering how to go about keeping certain
> directories password protected. The scripts seem to > override the .htaccess settings. Thoughts?
If I see right, this component is a JavaScript (so Client) side component in first place (and that was the hardest part to implement).
The communication protocol is described, and the "connector"s or the serverside code is there only as an example - you can extend and do what you want with it, thus allowing protecting as many directories as you want.

#45 Demetrios Kyriakis on Jun 15th, 2008

I found a little hiccup in your file tree plug in. I am using ajaxSubmit form plug in to upload files to the directory tree. In the callback I reload your file tree plug in so the newly uploaded file appears. Works fine however when I click on the file name nothing happens. The feedback doesn't fire. Need to use livequery for binding the click events perhaps but not I'm not sure how that can be called within your plug in. Maybe you have a suggestion?

#46 Rp on Jun 16th, 2008

The script is great. But it doesn't seem to work for Japanese/Chinese/Korean characters. Any help there?

BTW: Email addresses ended with info/name are valid too :)

#47 Vincent on Jun 18th, 2008

Never mind on that ajaxSubmit callback problem. I was not executing the openFile(file) function in my callback which of course adds the click event to the file name. Oops. Working now.

#48 Rp on Jun 20th, 2008

Wow! This is perfect. Just what I was looking for. Excellent job!

#49 Chris on Jun 25th, 2008

hi,

I want to use this structure in windows explorer, for all my client files.
So don't want to use it on the i-net.

How? Please help.

Thanks,
Deniz

#50 Deniz on Jun 26th, 2008

I am totally new to this. I have used the php tree from this site before but am not understanding this one. Where do I put the code in my page to create this tree.

#51 matt on Jul 7th, 2008

Thank you for this great script. One question: I would like to start an AJAX-call when clicking a folder/directory/map. At this moment only an action is performed when clicking a file. Thank You in advance.

#52 Allan on Jul 8th, 2008

@Allan
as a quick-and-dirty solution, just add:

o.folderclicked($(this));

and set folderclicked as option when you construct the tree.

For example:
$('#tree').fileTree({
root: '',
folderclicked: function(node) { alert(node.get(0).text); },
script: 'whatever.php' },
function(file) {
alert(file);
});
});

#53 Richard van Zon on Jul 9th, 2008

@Allan
sorry, didn't quite tell you where to add the line. It's after line 73, above '} else {'

#54 Richard van Zon on Jul 9th, 2008

Richard,

Thank You (Bedankt dus)! Works like a charm! Can you tell me if it is possible to hide files and only show maps.

Allan

#55 Allan on Jul 13th, 2008

Richard,

Very strange, but it doesn't work anymore. I added the line: o.folderclicked($(this)); on line 73 before } else {.

When I construct the tree and click an folder I receive an Javascript Alert "Undefined".

My line: of code in het main programm:
"$('#fileTreeDemo_3').fileTree({ root: '../audio/audio/', script: 'jqueryFileTree.php', folderclicked: function(node) { alert(node.get(0).text); }, folderEvent: 'click', expandSpeed: 750, collapseSpeed: 750, expandEasing: 'easeOutBounce', collapseEasing: 'easeOutBounce', loadMessage: 'Bezig met laden...' }, function(file) {
alert(file);
});
.

Where's my error?

#56 Allan on Jul 13th, 2008

Nice FileTree...
But still missing the sortable function :(

after 2 years nobody was able to get it right

#57 mogio on Jul 16th, 2008

very thanks

#58 klima on Jul 17th, 2008

1.I have downloaded the jquery.1.2.6.js.
But I don't know how to use it.
2.jquery file tree can list a folder automatically?
It is urgent,I need your help.

Thank you very much

#59 Cherry on Jul 20th, 2008

Great!..so usefull and nice style. I downloaded for test

#60 Felix on Jul 21st, 2008

Is callback "function(file){ alert(file); })" able to catch if the SHIFT button is pressed?

i.e.
if (evt.shiftKey!==1) alert("Here SHIFT has not been pressed")
else alert("Got a SHIFT-based event!")

#61 eugeny on Jul 22nd, 2008

Hi, love this plugin.

I've come across an issue when using TinyMCE's plugin popup. Basically as soon as I include tiny_mce_popup.js the File Tree stops working. I'm lost as according to Firebug it still seems to be working but the data is never populating.

Any ideas?

#62 Nick on Jul 30th, 2008

First let me say this script its bad ass!

I am a little confused as to why the PHP connector is not nearly as advanced as the PHP File Tree script.
I was hopping to be able to specify what file types to display. Is this feature planned or am i going to have to modify it?

#63 John on Jul 31st, 2008

Superb!!!

Excelent!. Amazing.

Thanks,
gab

#64 gab on Jul 31st, 2008

I love this plugin. It's great!
However, I have a question when I use it.
When I add a folder by using ajax PHP, how can I refresh the jqueryFileTree to display that folder?

Thanks!

#65 user on Aug 2nd, 2008

Dear Cory S.N. LaViska!

Do you have an idea concerning callback "function(file){ alert(file); })" able to catch if the SHIFT button is pressed?

i tried this way

function(evt){
evt = (evt) ? evt : ((window.event) ? window.event : null);
if (evt.shiftKey!==1) alert("Here SHIFT has not been pressed");
else alert("Got a SHIFT-based event!");
})

but it doesnt work ):

#66 Eugeny on Aug 4th, 2008

@Eugeny: This should help you out: http://www.simpltry.com/2007/01/04/shift-key-detection/

#67 Cory S.N. LaViska on Aug 4th, 2008

I love this plug in but what is the best way to make the files downloadable once they are in the folders? I tried the openFile function but it didn't work.

#68 tiffany on Aug 6th, 2008

@tiffany: Try this http://abeautifulsite.net/notebook/27

#69 Cory S.N. LaViska on Aug 6th, 2008

@Nick: Sorry, I wasn't able to replicate the problem with TinyMCE. Send me some code if you like...

#70 Cory S.N. LaViska on Aug 6th, 2008

I'm using asp, will that php work on that?

#71 tiffany on Aug 7th, 2008

Is possible adapat the plugin to tree view (itens)?

#72 Ju on Aug 12th, 2008

very cool stuff.

I have a problem though:

when i click a file the alert always shows the content 'file'. what am i doing wrong?

i use the following callback:

function(file){alert(file);}

#73 thomas on Aug 18th, 2008

Love the treeview...

#74 Ross on Aug 19th, 2008

Hello.
Is that possible that a specific directory initializes already opened?

Great job!!

#75 Berkowitz on Aug 21st, 2008

How is use for open software ?

#76 kbrothers on Aug 24th, 2008

Newb Question: I'm interested in passing the filename to a function like "openFile()", as mentioned above - and ultimately generating a link to the actual file for download purposes. I don't mind if the browser handles opening the file (opposed to opening a save-as prompt), but I would like it to open in a new window.

Can someone help me with the step-by-step process to generating a file download link onClick. Thanks in advance!

function openFile(file) {
// do something with file
}

$(document).ready( function() {
$('#container_id').fileTree({ [options] }, function(file) {
openFile(file);
});
});

#77 Paul Jauregui on Aug 24th, 2008

Can the tree be populated by xml data

#78 Rav on Aug 25th, 2008

// Open same page
function openLink(file)
{

window.document.location.href=fil ;
}
// Open new page

function openLink(file)
{
window.open(file); return false;
}

$(document).ready( function() {
$('#container_id').fileTree({ [options] }, function(file) {
openLink(file);
});
});

#79 AddictDownload.com on Aug 26th, 2008

Pretty cool script but can't make it work with ASP.NET / C#

When I apply it to my ASP DropDownList it works, shows up and everything.. but when I submit I only get the first selected item... I figured I'd try with a ListBox... same thing happens! and yes I set multiple=multiple on the dropdown and selectionmode=multiple on the listbox..

can't get the data :( Any help?

thx

#80 Mike on Aug 27th, 2008

^ you should delete the message above this one and this one... sorry

A Beautiful Site

Search the Notebook

Popular Entries

Related Entries

Archives

Announcements