4.4.0
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.
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 HTMLElement
s or Node
s.
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")] } });
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' });
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.
Use of the on
function is not possible until jQuery >=1.7
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 });
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.
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); });
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 ... */ });