Fine Uploader

Originally developed/designed by Andrew Valums.
Currently maintained by Ray Nicholus.

Welcome! This project attempts to achieve a user-friendly file-uploading experience over the web. It's built as a Javascript plugin for developers looking to incorporate file-uploading into their website.

Take a look at the new evolving Demo page.

Questions? Comments? Problems? Post in the forums.

Looking for the comment thread from the valums.com website? It is still available, but please use the forum instead.

We would love developers to contribute any improvements and bugfixes they produce. See How do I contribute to other's code in GitHub?.

Table of Contents

• Summary
• Features
• License
• Getting started
• qq.FileUploader - Setting up full upload widget
• Options of both FileUploader & FileUploaderBasic
• Options of FileUploaderBasic
• Options of FileUploader
• Styling FileUploader
• Callbacks (FileUploader & FileUploaderBasic)
• Changing alert/messages to something more user friendly
• Instance methods
• Troubleshooting
• Contributors

Summary

This plugin uses an XMLHttpRequest (AJAX) for uploading multiple files with a progress-bar in FF3.6+, Safari4+, Chrome and falls back to hidden-iframe-based upload in other browsers (namely IE), providing good user experience everywhere.

It does not use Flash, jQuery, or any external libraries.

Features

• Multiple file select, progress-bar in FF, Chrome, Safari
• Drag-and-drop file select in FF, Chrome
• Uploads are cancelable
• No external dependencies
• Doesn't use Flash
• Fully working with HTTPS
• Keyboard support in FF, Chrome, Safari
• Tested in IE7/8, Firefox 3/3.6/4, Safari 4/5, Chrome, and Opera 10.60
• Ability to upload files as soon as they are selected, or "queue" them for uploading at user's request later
• Display specific error messages from server on upload failure (hover over failed upload item)
• Automatic uploads (as files are selected) or queue files to me manually triggered when ready

License

This plugin is open sourced under MIT license, GNU GPL 2 or later and GNU LGPL 2 or later. Please see the license.txt file for details.

Getting started

The fileuploader.js contains two classes that are meant to be used directly. If you need a complete upload widget (from demo) to quickly drop into your current design, use qq.FileUploader.

If you want to customize uploader, by using a different looking file list or change the behaviour or functionality use qq.FileUploaderBasic.

The difference between them is that qq.FileUploader provides a list of files, drag-and-drop, but qq.FileUploaderBasic only creates button and handles validation. Basic uploader is easier extendable, and doesn't limit possible customization.

qq.FileUploader extends qq.FileUploaderBasic, so that all the options present in the basic uploader also exist in the full widget.

qq.FileUploader - Setting up full upload widget

Include fileuploader.js and fileuploader.css into your page. Create container element.

<div id="file-uploader">
<noscript>
    <p>Please enable JavaScript to use file uploader.</p>
    <!-- or put a simple form for upload here -->
</noscript>
</div>

Initialize uploader when the DOM is ready. Change the action option. For example ../server/php.php for the default folder structure. In the server folder you will find examples for different platforms. If you can't find the one you need, check the readme.txt in the same folder.

var uploader = new qq.FileUploader({
	// pass the dom node (ex. $(selector)[0] for jQuery users)
	element: document.getElementById('file-uploader'),
	// path to server-side upload script
	action: '/server/upload'
});

Options of both FileUploader & FileUploaderBasic

Name	Type	Default	Note
debug	boolean	false	If enabled, this will result in log messages (such as server response) being written to the javascript console. If your browser does not support the [window.console object](https://developer.mozilla.org/en-US/docs/DOM/console.log), the value of this option is irrelevant.
action	string (path)	/server/upload	The is the endpoint used by both the form and ajax uploader. In the case of the form uploader, it is part of the form's action attribute value along with all parameters. In the case of the ajax uplaoder, it is makes up part of the URL of the XHR request (again, along with the parameters).
params	object	{}	These parameters are sent with the request to the endpoint specified in the action option.
customHeaders	object	{}	Additional headers sent along with the XHR POST request. Note that is option is only relevant to the ajax/XHR uploader.
multiple	boolean	true	Set to false puts the uploader into what is best described as 'single-file upload mode'. See the [demo](http://fineuploader.com) for an example.
maxConnections	integer	3	Maximum allowable concurrent uploads.
disableCancelForFormUploads	boolean	false	If true, the cancel link does not appear next to files when the form uploader is used. This may be desired since it may not be possible to interrupt a form-based upload in some cases.
autoUpload	boolean	true	Set to false if you want to be able to begin uploading selected/queued files later, by calling uploadStoredFiles().
allowedExtensions	array of strings	[]	This may be helpful if you want to restrict uploaded files to specific file types. Note that this validation option is only enforced by examining the extension of uploaded file names. For a more complete verification of the file type, you should use, for example, magic byte file identification on the server side and return {success: false} in the response if the file type is not on your whitelist.
acceptFiles	comma-separated strings	null	This option is used solely by the file selection dialog. If you'd like to restict valid file types that appear in the selection dialog, you can do this here by listing valid content type specifiers. See the [documentation on the accept attribute of the input element](https://developer.mozilla.org/en-US/docs/HTML/Element/Input) for more information.
sizeLimit	integer	0 (no limit)	Maximum allowable size, in bytes, for a file.
minSizeLimit	integer	0 (no limit)	Minimum allowable size, in bytes, for a file.
inputName	string	qqfile	This usually only useful with the ajax uploader, which sends the name of the file as a parameter, using a key name equal to the value of this options. In the case of the form uploader, this is simply the value of the name attribute of the file's associated input element.

Options of FileUploaderBasic

Name	Type	Default	Note
button	element	null	Specify an element to use as the "select files" button

Options of FileUploader

Name	Type	Default	Note
element	element	null	Container for the default drop zone (if supported by browser) and files list. **Required**
listElement	element	null	Container for the file list. If null, the list defined in the template will be used.
uploadButtonText	string	Upload a file	Label for the file selector button
cancelButtonText	string	cancel	The cancel button text (which is more of a link than a button).
failUploadText	string	Upload failed	Text that appears next to a failed file item
extraDropzones	array of elements	[]	Useful if you'd like to to designate additional dropozones for file input. Of course, this is not relevant if the form uploader is used.
multipleFileDropNotAllowedMessage	string	"You may only drop one file"	Can be used to customize the message used when one attempts to drop multiple files when multiple == false.

Styling FileUploader

The template option contains default elements with default classes that make up the uploader as a whole in the DOM. For example, the first default element in template is a div with a class of qq-uploader. This is the parent element of the uploader. The default drop area, button, and file list elements are also, by default, contained in this option. You can use this option to add additional elements, modify default template elements, etc.

There is also a fileTemplate option which contains default elements that make up one file item in the file list.

Finally, a classes option allows you to change the default class names for these elements. Be sure the values in classes match the class names used in the corresponding template elements (where appropriate).

Callbacks (FileUploader & FileUploaderBasic)

• onSubmit(String id, String fileName) - called when the file is submitted to the uploader portion of the code. Note that this does not mean the file upload will begin at this point. Return false to prevent submission to the uploader.
• onComplete(String id, String fileName, Object responseJSON) - called when the file upload has finished.
• onCancel(String id, String fileName) - called when the file upload has been cancelled.
• onUpload(String id, String fileName) - called just before the file upload begins
• `onProgress(String id, String fileName, int uploadedBytes, int totalBytes) - called during the upload, as it progresses. Only used by the XHR/ajax uploader.

Changing alert/messages to something more user friendly

If you limited file types and max size, you will probably want to change the default alert and messages as you see fit, this is possible by overriding the showMessage function option, as well as the and messages options. The default showMessage function simply invokes alert with the message text. One instance in which this is used is when the user attempts to select an invalid file for upload. There are general message types with default text that can be overriden as well.

Instance methods

• setParams(Object newParams) - Set the parameters sent along with the request after initializing the uploader. It can be nicely used in onSubmit callback.
• uploadStoredFiles() - If !autoUpload, this will begin uploading all queued files.

Troubleshooting

If you can't get the uploader to work, please try the following steps before asking for help.

If the upload doesn't complete, saying "failed":

• Set the debug option of the FileUploader to true.
• Open the page where you have a FileUploader.
• Open developer console in your browser.
• Try to upload the file. You should see a server response.

It should be {success:true} for completed requests. If it's not, then you have a problem with your server-side script.

Contributors

Thanks to everybody who contributed, either by sending bug reports or donating. The project wouldn't be possible without all this generous help. Thank you!