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.

Contents

1. Features
2. Compatibility
3. Demo
4. Download
5. Usage
   1. Dependencies
   2. Creating a File Tree
   3. Configuring the File Tree
   4. Styling the File Tree
   5. Handling Feedback
6. Connector Scripts
   1. Custom Connector Scripts
7. Version History
8. Licensing & Terms of Use
9. Special Thanks
10. Comments

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 requires jQuery 1.2.6 or above and has been tested to work in the following browsers:

• Internet Explorer 6 & 7
• Firefox 2 & 3
• Safari 3
• Chrome
• Opera 9

Demo

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

Download

Current version: jQuery File Tree – Version 1.01 (12 April 2008)

This plugin is provided to you as-is, at absolutely no cost. If you would like to support its development, feel free to contribute any amount you prefer via PayPal. As always, you are welcome to contribute code for bug fixes and feature enhancements as well. Either way, thanks for supporting our efforts!

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_idis 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 thefileTree()function. Valid options include:

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 tojqueryFileTree.cssto 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 calledopenFile(), 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 isjqueryFileTree.php. You can use a connector script for another language by setting thescriptparameter 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
• Perl by Oleg Burlaca
• 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 therootparameter. 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 thelielement, prefixed withext_. (The prefix is used to prevent invalid class names for file extensions that begin with non-alpha characters.)

Licensing & Terms of Use

This plugin is dual-licensed under the GNU General Public License and the MIT License and is copyright 2008 A Beautiful Site, LLC.

Special Thanks

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