4.4.0

jQuery Plugin

jQuery is a cross-browser JavaScript library designed to simplify client-side scripting of HTML. It provides tons of workarounds for various browsers, and makes developing client-side JavaScript for the web much easier. Overall, it is recommended to use jQuery unless you are specifically trying to develop without it.

Fortunately, Fine Uploader provides wrapper code that integrates with jQuery while still allowing the integrator to choose between Core and UI modes. The Fine Uploader jQuery plugin has a couple of syntactical differences than the regular Fine Uploader plugin. Also, some of the options are defined differently. Note that all conventions commonly associated with jQuery plug-ins are followed faithfully here, so if you have worked with jQuery plug-ins before, this should all be quite intuitive.

DOM elements

With the Fine Uploader jQuery plugin there is no need to specify the element option. Instead, using the jQuery plugin syntax, you provide the element or elements you would like to associate with your Fine Uploader instance like so:

// This will instantiate an instance of Fine Uploader on the element
// with an id of "fine-uploader"
$("#fine-uploader").fineUploader({
    /* options go here */
});

Also, Fine Uploader is smart enough to know you are using jQuery and allows you to pass in jQuery objects instead of HTMLElements or Nodes.

For example, if you specify the button option, the value can be $("#myButton") rather than $("#myButton")[0] or document.getElementById("button").

If the option takes an array of HTMLElements any item in the array that is a jQuery object will be evaluated and all HTMLElements associated with that jQuery object will be added to the array when it is passed to the native Fine Uploader. For instance, if you specify a value for extraDropzones which is [$(".myExtraDropzone")], and the element contains three child elements, then the plugin will pass all three elements to the native Fine Uploader.

$("#fine-uploader").fineUploader({
    /* ... */
    button: $("#button"),
    dragAndDrop: {
        extraDropzones: [$(".dropzones")]
    }
});

Uploader Type

The Fine Uploader jQuery plugin still provides integrators with a way to specify whether they are using basic or ui mode by specifying the uploaderType option on instantiation.

When the type is 'basic' then basic mode is used, otherwise UI mode is assumed.

$("#fine-uploader").fineUploader({
    uploaderType: 'basic'
});

Callbacks and Events

The biggest syntactical difference between the jQuery and non-jQuery plugin is the callback syntax. All callbacks defined in Fine Uploader are still avaiable to jQuery plugin users.

Note

Use of the on function is not possible until jQuery >=1.7

Note:

When using the jQuery plugin, all events pass an extra event parameter as the first parameter to your callback functions.

$("#fine-uploader").fineUploader({
    request: {
        endpoint: '/upload/endpoint'
    }
}).on('error', function (event, id, name, reason) {
    // do something
}).on('complete', function (event, id, name, responseJSON) {
    // do something
});

Note:

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 everything on this page when writing code inside of your callback functions 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.

API Methods

All public API methods are also accessible when using the jQuery plugin, but — as with callbacks — there are just a few syntactical differences.

// To call a method on Fine Uploader, refer to it's jQuery object:
var files = $("#fine-uploader").fineUploader('getStoredFiles'):

$("#cancel-button").click(function (event) {
    // Trivial example to check if the 1st file registered with the uploader
    var exists = $("#fine-uploader").fineUploader('doesExist', 0);
});

Endpoint Handlers

The jQuery plugin cares not about what your endpoint is, but if you plan to use the S3 uploader rather than the traditional uploader, ensure that you are using the right plugin name:

$("#s3-fine-uploader").fineUploaderS3({ /* options ... */ });