4.4.0
This tutorial will serve as a step-by-step walkthrough for getting starting with Fine Uploader. It is geared towards those who have minimal experience with Javascript, server-side concepts, or the web.
The tutorial is not comprehensive or meant to cover all aspects of Fine Uploader. For more information, make sure to read through the list of features as well as the API documentation.
You can get Fine Uploader in the downloads section. The download comes bundled with all required scripts and modules.
Fine Uploader comes with two different modes pertaining to the user interface.
The most basic Fine Uploader mode. Core mode assumes that the developer will code their own UI but still make use of Fine Uploader’s API. Core mode is suggested for advanced developers who wish for to heavily customize the uploader’s user interface. To use Core Mode:
var uploader = new qq.FineUploaderBasic({/* options go here .... */});
Inherits everything from Core mode. UI mode also comes with a fully functional user interface which includes, but is not limited to: a default upload button, progress bars, retry/cancel/delete buttons, proper display of error messages, and more. UI mode is recommended for beginning developers or for those who are pleased with the default Fine Uploader interface or can customize the default Fine Uploader UI via CSS. To use UI Mode:
var uploader = new qq.FineUploader({/* options go here ... */});
If you are using Fine Uploader UI, you MUST include a template in your document/markup. You can
use the default.html
file in the templates
directory bundled with the library and customize it as desired. See the
styling documentation page for more details.
To use the traditional endpoint handler, simply declare Fine Uploader as you normally would.
Amazon’s S3 is currently the most popular cloud service. Fine Uploader comes with built in support that allows all files to be uploaded directly to S3 via the browser. To make use of Fine Uploader S3:
var uploader = new qq.s3.FineUploader({/* options go here ... */});
Fine Uploader comes with built in support that allows all files to be uploaded directly to Azure via the browser. To make use of Fine Uploader Azure:
var uploader = new qq.azure.FineUploader({/* options go here ... */});
Fine Uploader Azure does not support IE9 and older. This is due to the fact that Azure’s API does
not allow files to be uploaded via multipart encoded POST requests, which is critical for IE9 and older support.
If you need to support IE9 and older, you will need to load/use Fine Uploader with its traditional endpoint
handler if the value of qq.supportedFeatures.ajaxUploading
is false
.
Fine Uploader is also easily used as a jQuery plugin. This plugin gives you the ability to use either Core or UI mode.
To use Core Mode with the jQuery plugin simply set the uploaderType to be ‘basic’:
$("#fine-uploader").fineUploader({uploaderType: 'basic' /* options go here... */});
To use UI Mode with the jQuery plugin:
$("#fine-uploader").fineUploader({/* options go here... */});
To use Fine Uploader S3 with the jQuery plugin:
$("#fine-uploader").fineUploaderS3({/* options go here... */});
To use Fine Uploader Azure with the jQuery plugin:
$("#fine-uploader").fineUploaderAzure({/* options go here... */});
Henceforth this walkthrough will utilize the jQuery plugin of Fine Uploader. This is because jQuery is more or less ubiquitous on the web, and its a safe bet to assume it is included somewhere on your page. If you are forced to use the non-jQuery version, then keep in mind that the syntax will be slightly different.
Like many other JavaScript libraries, Fine Uploader implements a event system that uses callbacks to execute user-provided functions at runtime, based on specific events. These events are listed here. Depending on whether you are using the jQuery plugin or not, the callback syntax is a bit different:
With the non-jQuery plugin, callbacks are defined in the callbacks
option
property. The parameters for the callbacks are the same as listed in the
documentation.
Example:
var uploader = new qq.FineUploader({ // options callbacks: { onUpload: function (id, name) { }, onSubmitted: function (id, name) { } } });
The jQuery plugin uses a slightly different callback syntax. This syntax will
be familiar to thsoe used to working with jQuery plugins. Note that an extra
Event
object is passed into the handler
function as the first parameter, the consecutive parameters are the same as
those listed in the events documentation.
Example:
$("#fine-uploader") .fineUploader({/* options go here... */}) .on('upload', function (event, id, name) { // callback code here... }) .on('submitted', function (event, id, name) { // callback code here... });
You may use traditional callback handler functions with the jQuery plug-in if you wish.
If you do contribute traditional callback functions via the callbacks
option, you should disregard event handler section
of the above example as this will bypass the jQuery plug-in entirely. Also, while it is possible to contribute
two callbacks of the same type via a jQuery event handler and a callbacks
option, you should be aware that the
callbacks
function will always be evaluated first, and the return value from the callbacks
function will be
accepted instead of the return value from the jQuery event handler if the return value of the callbacks
function is non-null.
Next, let’s check out some of Fine Uploader’s options.
Proceed by selecting either: