rafasashi / jqueryfiletree

jQuery File Tree is a configurable, AJAX file browser plugin for jQuery. Continuation of unmaintained jQuery File Tree (v1.01) (12 April 2008) from ABeautifulSite.net

jQueryFileTree

jQuery File Tree is a configurable, AJAX file browser plugin for jQuery. This repo is a continuation of unmaintained jQuery File Tree (12 April 2008) by Cory S.N. LaViska at ABeautifulSite.net

jQuery File Tree requires at least jQuery 1.2

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
• Multi-select select with checkboxes
• Supports event listening for callback hooks

CREATING A FILE TREE

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

$(document).ready( function() {
	$('.class').fileTree({ root: '/some/folder/' }, function(file) {
		alert(file);
	});
});

Where .class is the class of an empty DIV element that exists on your page. The file tree will automatically load when your page loads. Any DIV elements with this class will share the same file tree.

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 to expand branches (in ms); use -1 for no animation	500
collapseSpeed	Speed to collapse branches (in ms); use -1 for no animatio	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..."
multiSelect	Append checkbox to each line item to select more than one	false

There are many options available, which would look something like this:

$(document).ready( function() {
	$('.class').fileTree({
		root: '/some/folder/',
		script: 'jqueryFileTree.php',
		expandSpeed: 1000,
		collapseSpeed: 1000,
		multiFolder: false
	}, function(file) {
		alert(file);
	});
});

STYLING THE FILE TREE

The file tree relies 100% on CSS for styling. Refer to jqueryFileTree.css to make any changes to the default styling.

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 provided:

• PHP by Cory LaViska (originally)
• 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

(DAVE) Note that all of the connector scripts have been left unmaintained outside of the PHP one in which I have updated (and will continue to do so). If you've improved or created a connector, feel free to add it to this repo.

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">
	<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.)

Additionally you may choose to enable multi-select, which appends a checkbox to each item. Visible child elements will automatically be checked/unchecked along with the parent. Currently this is only supported in PHP; feel free to update other connectors to reflect the following format:

<ul class="jqueryFileTree">
	<li class="directory collapsed"><input type='checkbox' /><a href="#" rel="/this/folder/">Folder Name</a></li>
	(additional folders here)
	<li class="file ext_txt"><input type='checkbox' /><a href="#" rel="/this/folder/filename.txt">filename.txt</a></li>
	(additional files here)
</ul>

CALLBACK HOOKS

jQuery File Tree now supports binding event listeners to the file tree element

$('.filetree')
	.on('filetreeexpand', function (e, data)	{ console.log(data); })
	.on('filetreeexpanded', function (e, data)	{ console.log(data); })
	.on('filetreecollapsed', function (e, data)	{ console.log(data); })
	.on('filetreecollapse', function (e, data)	{ console.log(data); })
	.on('filetreechecked', function (e, data)	{ console.log(data); })
	.on('filetreeunchecked', function (e, data)	{ console.log(data); })
	.on('filetreeclicked', function(e, data)	{ console.log(data); });

All return the data object with the following properties

Property	Value
li	LI jQuery object
type	file | directory
value	name of the file or directory
rel	relative path to file or directory
trigger	type of trigger called

Pretty much has the information you need, but I included the LI object anyways so you can easily get any other data you want with something like data.li.prop('class')

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.