jQueryFileTree

NOTE:

v2 is written in CoffeeScript and LESS. Now supports Bower and Gulp (for compiling). View CHANGELOG.md to read more.

DEMO

http://jqueryfiletree.github.io/

INSTALLING

Bower: bower install jqueryfiletree --save

Manual: Download ZIP

ABOUT

jQueryFileTree 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

jQueryFileTree 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 easing functions
• Single- and multi-folder views
• Configurable load message
• Multi-select select with checkboxes
• Supports event listening on unique actions

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 animation	500
expandEasing \*	Easing function to use on expand	"swing"
collapseEasing \*	Easing function to use on collapse	"swing"
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..."
errorMessage	Message to display if unable to load tree	"Unable to get file tree information"
multiSelect	Append checkbox to each line item to select more than one	false
onlyFolders	Filter files and only return folders	false
onlyFiles	Filter folders and only return files	false
preventLinkAction	Prevents default link-clicking action from occurring. This, in effect, prevents the page from resetting to the top.	false

* Anything other than 'swing' and 'linear' requires an external lib or script like jQuery UI or jquery.easing

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.less to make any changes to the default styling.

CONNECTOR SCRIPTS

jQueryFileTree 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 jQueryFileTree to better suit your needs (see Custom Connector Scripts).

Connector scripts for the following languages are provided:

• PHP by Cory LaViska (originally)
• PHP-Laravel 5.* by Jean Jar
• 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
• Node.js by Peng Wang
• 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 create a pull request. Use connector scripts as a starting point, but be mindful that often such (largely) unmaintained examples lack the security necessary for production.

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>

EVENTS

jQueryFileTree now supports binding event listeners to the file tree element

$('.filetree')
	.on('filetreeinitiated', function(e, data)	{ console.log(data); });
	.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('filetreeclicked', function(e, data)	{ console.log(data); });

All except 'filetreeinitiated' 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
container	container jQuery object (ie: `$('.filetree')`)

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.

CONTRIBUTING

Gulp is used to compile the CoffeeScript and LESS files into js and css files respectively. If you are making changes to jQueryFileTree itself (and not the connectors), you MUST make your changes inside jQueryFileTree.coffee and jQueryFileTree.less or the next time jQueryFileTree is compiled your changes will disappear.

TESTING

In order to test, you'll need Bower and Gulp. Right now, I just have a manual browser demo to test functionality.

• In Terminal, go to the /tests/manual/ folder and type bower install to set up the Bower assets.
• gulp coffee will compile /src/coffeescript/jQueryFileTree.coffee to JS, minify, and copy to /dist/ as well as the testing folder (if testing is set up). A non-minified version is saved to /src/ for debugging the output.
• gulp less will compile /src/less/jQueryFileTree.less to CSS, minify, and copy to /dist/ as well as the testing folder (if testing is set up). A non-minified version is saved to /src/ for debugging the output.
• gulp or gulp default will run coffee and less consecutively, then update the manual test folder.

SPECIAL THANKS

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