###Download the 3.3.1 combined & minified javascript file (along with all other required files) here###
## Authors ## Actively developed by [Futurice Ltd](http://www.futurice.com/) Created by Andrew Valums and Ray Nicholus.
###Table of Contents### - [Summary](#summary) - [Features](#features) - [Getting started](#getting-started) - [Server-side Instructions](https://github.com/futurice/file-uploader/blob/3.2-IP/server/readme.md) - [Using the optional jQuery plug-in](#using-the-optional-jquery-plug-in) - [Setting up the uploader without jQuery](#setting-up-the-uploader-without-jquery) - [How to override options](#how-to-override-options) - [Options of both FineUploader & FineUploaderBasic](#options-of-both-fineuploader--fineuploaderbasic) - [Options of FineUploader](#options-of-fineuploader) - [Styling FineUploader](#styling-fineuploader) - [Callbacks (FineUploader & FineUploaderBasic)](#callbacks-fineuploader--fineuploaderbasic) - [Changing alert/messages to something more user friendly](#changing-alertmessages-to-something-more-user-friendly) - [Instance methods](#instance-methods) - [qQuery (Utility Functions)](#qquery) - [Internet Explorer limitations](#internet-explorer-limitations) - [Building and using the in-progress version](#building-and-using-the-in-progress-version) - [Troubleshooting](#troubleshooting) - [Issue Tracker](#issue-tracker) - [License](#license) - [Contributors](#contributors)
## Authors ## Actively developed by [Ray Nicholus](http://lnkd.in/Nkhx2C). Created by Andrew Valums.
## Features ## * Multiple file select, progress-bar in FF, Chrome, and Safari * Drag-and-drop file select in FF, Chrome, and Safari (OS X) * Uploads are cancelable * No external dependencies **at all** if using FineUploader or FineUploaderBasic. If using the optional jQuery wrapper, jQuery is of course required. * FineUploaderBasic only requires the associated Fine Uploader javascript file. All Fine Uploader css and image files can be omitted. * Doesn't use Flash * Fully working with HTTPS * Tested in IE7+, Firefox, Safari (OS X), Chrome, IOS6, and various versions of Android. IE10 is now also supported! * 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) * Ability to auto-retry failed uploads * Option to allow users to manually retry a failed upload * Create your own file validator and/or use some default validators include with Fine Uploader * Receive callback at various stages of the upload process * Send any parameters server-side along with each file. * Upload directories via drag and drop (Chrome 21+). * [Include parameters in the query string OR the request body.](http://blog.fineuploader.com/2012/11/include-params-in-request-body-or-query.html) * Submit files to be uploaded via the API. * [Split up a file into multiple requests](http://blog.fineuploader.com/2012/12/file-chunkingpartitioning-is-now.html) (file chunking/partitioning). * [Resume failed/stopped uploads from previous sessions](http://blog.fineuploader.com/2013/01/resume-failed-uploads-from-previous.html) * [Delete uploaded files](http://blog.fineuploader.com/2013/01/delete-uploaded-file-in-33.html) * [CORS support](http://blog.fineuploader.com/2013/01/cors-support-in-33.html) * Upload any `Blob` objects via the API. * Any many more!
## Introduction ## 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.
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 other external libraries. There is an optional jQuery plug-in that can be used to integrate Fine Uploader into your project, but it is NOT required. The same features are available with or without the jQuery plug-in.
## Fine Uploader Has Two Modes... ## You can use Fine Uploader in **FineUploader mode**, or in **FineUploaderBasic mode**.
FineUploaderBasic mode is defined in the qq.FineUploaderBasic module in the code. This is the base module for
Fine Uploader, and provides all functions that do not involve UI components. Choose this mode if you need very tight
control over your uploader's UI. If you choose this option, it is expected that you will provide all of your own UI, but
Fine Uploader will do the rest.
FineUploader mode is defined in the qq.FineUploader module in the code. It inherits everything from FineUploaderBasic,
plus it provides a customizable UI, including drag & drop, progress bars, status messages, a file list with color-coded status
indicators, and other UI niceties. Most developers will likely opt to use FineUploader.
Fine Uploader also provides an optional jQuery plug-in. This simply wraps the native uploader code. You can use either of
the modes described above when using the jQuery plug-in via the uploaderType option. More on the plug-in in the
jQuery plug-in section.
## Choose Your Path... ## Once you have decided how you will use Fine Uploader, click on the appropriate link below to get started.
Start here.
Your journey begins here.
Look no further, your plan of action is described here.
I didn't forget about you! Read on, starting here.
### Building and using the in-progress version ### You can use [gradle](http://www.gradle.org/) to build the in-progress version. Simply clone this project, and run `gradlew combineJs` on the command-line. This will combine all of the javascript files into one file, placing it in the "build" directory. If you want the minified or gzipped version of the in-progress version, simply replace `combineJs` on the command-line with `minifyJs` or `gzipJs`, respectively.
If you would like the jQuery plug-in, simply add "jQuery" to the end of any of these tasks. For example, to obtain the
non-minified jQuery plug-in or the minified jQuery plug-in, run gradlew combineJsJquery or gradlew minifyJsJquery
respectively. This will build the Fine Uploader javascript file with the plug-in and everything else you need.
Remember, a in-progress build is not yet released, so it may have some lingering bugs. The trade-off is immediate access to new features without having to wait for a release.
In the future, I may integrate a CI system that creates nightly in-progress builds, but that is a pretty low-priority, especially since building your own in-progress version should be pretty easy.
Don't forget to include the css and image files in your project if you are using FineUploader.
### 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
debugoption of the FineUploader to true. - Open the page where you have a FineUploader.
- 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.
If you are having other issues, please read the FAQ section before posting a question or bug.
### Issue Tracker ### Have a bug or feature request? Please [create an issue here on GitHub](https://github.com/futurice/file-uploader/issues) that conforms with [necolas's guidelines](https://github.com/necolas/issue-guidelines/blob/master/README.md).
### 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.
### Contributors ### We would love developers to contribute any improvements and bugfixes they produce. Note that any pull requests MUST be against an "IP" branch! See [How do I contribute to other's code in GitHub?](http://stackoverflow.com/questions/4384776/how-do-i-contribute-to-others-code-in-github).
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!
## Additional Reading ## * [Frequently Asked Questions (FAQ)](docs/faq.md) * [Styling FineUploader](docs/styling.md) * [Changing alert/messages to something more user friendly](docs/styling.md#changing-dialogs-to-something-more-user-friendly) * [qQuery (Public Utility Functions)](docs/qquery.md) * [Internet Explorer Limitations](docs/limitations-ie.md)