4.4.0

Events

Fine Uploader’s event system enables integrators to execute any operations at almost any point in the upload process. Knowing how these callbacks work, and when they are called, is crucial to unlocking the full potential of Fine Uploader.

Syntax

There is a significant difference in the way events are defined between the jQuery and non-jQuery uploaders.

When using the non-jQuery version, events are defined as functions in the callbacks option object.

There are two things to keep in mind when using the jQuery plugin version. First, event handlers are defined by calling the jQuery .on() function which will bind a function to an event. Secondly, event handler parameters are passed an extra jQuery Event object. If using the jQuery plugin, this Event object will precede all arguments listed.

See the Integrating jQuery page for code examples and more details.

non-jQuery

When using the non-jQuery uploader, the following syntax is the correct way to define event handlers:

callbacks: {
    onDelete: function(id) {
    // ...
    },
    onDeleteComplete: function(id, xhr, isError) {
    //...
    }
}

jQuery

The syntax below is only acceptable when using the jQuery plugin for the uploader:

$("#my_uploader").on("deleteComplete", function(event, id, xhr, isError) {
    //...
}).on("delete", function(event, id) {
    // ...
});

autoRetry

Called before each automatic retry attempt for a failed item.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.
Integer
attemptNumber

The number of retry attempts for the current file so far.

cancel

Called when the item has been canceled. Return false to prevent the upload from being canceled. Also can return a qq.Promise if non-blocking work is required here. Calling failure() on the promise is equivalent to returning false. If using a Promise, then processing of the cancel request will be deferred until the promise is fullfilled. Since there is no way to ‘pause’ the upload in progress while waiting for the promise to be fullfilled the upload may actually complete until the promise has actually be fullfilled.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.

complete

Called when the item has finished uploading.

The responseJSON will contain the raw response from the server including the ‘success’ property which indicates whether the upload succeeded.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.
Object
responseJSON

The raw response from the server.
XMLHttpRequest or XDomainRequest
xhr

The object used to make the request.

allComplete

Called when all submitted items have reached a point of termination. A file has reached a point of termination if it has been cancelled, rejected, or uploaded (failed or successful). For example, if a file in the group is paused, and all other files in the group have uploaded successfully the allComplete event will not be invoked for the group until that paused file is either continued and completes the uploading process, or canceled. This event will not be called if all files in the group have been cancelled or rejected (i.e. if none of the files have reached a status of qq.status.UPLOAD_SUCCESSFUL or qq.status.UPLOAD_FAILED).
Parameters:
Array
succeeded

IDs of all files in the group that have uploaded successfully (status = qq.status.UPLOAD_SUCCESSFUL).
Array
failed

IDs of all files in the group that have failed (status = qq.status.UPLOAD_FAILED).

delete

Called just before a delete request is sent for the associated item.
Parameters:
Integer
id

The current file’s id.

deleteComplete

Called just after receiving a response from the server for a delete file request.
Parameters:
Integer
id

The current file’s id.
XMLHttpRequest or XDomainRequest
xhr

The object used to make the request.
Boolean
isError

true if there has been an error, false otherwise.

error

Called whenever an exceptional condition occurs (see Handling Errors
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.
String
errorReason

The reason for the current error.
XMLHttpRequest or XDomainRequest
xhr

The object used to make the request.

manualRetry

Called before each manual retry attempt.

Return false to prevent this an all future retry attempts on the associated item.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.

pasteReceived

Called when a pasted image has been received (before upload).

The pasted image is represented as a Blob. Also can return a qq.Promise if non-blocking work is required here. If using a Promise the value of the success parameter must be the name to associate with the pasted image. If the associated attempt is marked a failure then you should include a string explaining the reason in your failure callback for the Promise.

Note:

The promptForName option, if true, will effectively wipe away any custom implementation of this callback. The two are not meant to be used together. This callback is meant to provide an alternative means to provide a name for a pasted image. If you are using Fine Uploader Core mode then you can display your own prompt for the name by overriding the default implementation of this callback.
Parameters:
Blob
blob

An object encapsulating the image pasted from the clipboard.

progress

Called during the upload, as it progresses, but only for the AJAX uploader.

For chunked uploads, this will be called for each chunk.

Useful for implementing a progress bar.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name
Integer
uploadedBytes

The number of bytes that have been uploaded so far.
Integer
totalBytes

The total number of bytes that comprise this file.

resume

Called just before an upload is resumed. See the uploadChunk event for more info on the chunkData object.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name
Object
chunkData

The chunk that will be sent next when file upload resumes.

sessionRequestComplete

Invoked when a session request has completed. The response will be either an Array containing the response data or null if the response did not contain valid JSON. The success parameter will be false if ANY of the file items represented in the response could not be parsed (due to bad syntax, missing name/UUID property, etc).

See the Initial File List feature page for more details.
Parameters:
Array
response

The raw response data.
Boolean
success

Indicates whether success has been achieved or not.
XMLHttpRequest or XDomainRequest
xhrOrXdr

The raw request.

statusChange

Invoked whenever the status changes for any item submitted by the uploader.

The status values correspond to those found in the qq.status object. For reference:

  • SUBMITTED
  • QUEUED
  • UPLOADING
  • UPLOAD_RETRYING
  • UPLOAD_FAILED
  • UPLOAD_SUCCESSFUL
  • CANCELED
  • REJECTED
  • DELETED
  • DELETING
  • DELETE_FAILED
  • PAUSED
Parameters:
Integer
id

The current file’s id.
String
oldStatus

The previous item status.
String
newStatus

The new status of the item.

submit

Called when the item has been selected and is a candidate for uploading.

This does not mean the item is going to be uploaded. Return false to prevent submission to the uploader. A qq.Promise can be used if non-blocking work is required. Processing of this item is deferred until the promise is fullfilled. If a promise is returned, a call to failure is the same as returning false.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.

submitDelete

Called before an item has been marked for deletion has been submitted to the uploader.

A qq.Promise can be used if non-blocking work is required. Processing of this item is deferred until the promise is fullfilled. If a promise is returned, a call to failure is the same as returning false.
Parameters:
Integer
id

The current file’s id.

submitted

Called when the item has been successfully submitted to the uploader.

The file will upload immediately if there is a) at least one free connection (see: maxConnections option) and b) autoUpload is set to true (see autoUpload option).

The callback is invoked after the ‘submit’ event is handled without returning a false value. In Fine Uploader Core mode it is usually safe to assume that the associated elements in the UI representing the associated file have already been added to the DOM immediately before this callback is invoked.
Parameters:
Integer
id

The current file’s id.
String
name

THe current file’s name.

totalProgress

Called during a batch of uploads, as they progress, but only for the AJAX uploader. This represents the total progress of all files in the batch.

Useful for implementing an aggregate progress bar.
Parameters:
Integer
totalUploadedBytes

The number of bytes that have been uploaded so far in this batch.
Integer
totalBytes

The total number of bytes that comprise all files in the batch.

upload

Called just before an item begins uploading to the server.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.

uploadChunk

Called just before a chunk request is sent.

The chunkData object, which is passed into the ‘uploadChunk’ event handler, has 4 properties:

  • partIndex - the 0-based index of the associated partition.
  • startByte - the byte offset of the current chunk.
  • endByte - the last byte of the current chunk.
  • totalParts - the total number of partitions associated with the File or Blob.
Parameters:
Integer
id

The current file’s id.
String
name

The current file’s name.
Object
chunkData

An object encapsulating the current chunk of data about to be uploaded.

uploadChunkSuccess

This is similar to the complete event, except it is invoked after each chunk has been successfully uploaded.

See the uploadChunk event for more information on the chunkData object.
Parameters:
Integer
id

The current file’s id.
Object
chunkData

An object encapsulating the current chunk of data about to be uploaded.
Object
responseJSON

The raw response from the server.
XMLHttpRequest or XDomainRequest
xhr

The object used to make the request.

validate

Called once for each selected, dropped, or addFiles submitted file and for each addBlobs submitted Blob.

This callback is always invoked before the default Fine Uploader validators execute.

This event will not be called if you return false in your validateBatch event handler, or if the stopOnFirstInvalidFile validation option is true and the validate event handler has returned false for an item.

A qq.Promise can be used if non-blocking work is required. Processing of this item is deferred until the promise is fullfilled. If a promise is returned, a call to failure is the same as returning false.

A buttonContainer element will be passed as the last argument, provided the file was submitted using a Fine Uploader tracked button.

The blobData object has two properties: name and size. The size property will be undefined for browsers without File API support.
Parameters:
File or Blob
data

A File or Blob.
HTMLElement
buttonContainer

The button corresponding to the respective file if the file was submitted to Fine Uploader using a tracked button.

validateBatch

This callback is always invoked before the default Fine Uploader validators execute.

This event will not be called if you return false in your validateBatch event handler, or if the stopOnFirstInvalidFile validation option is true and the validate event handler has returned false for an item.

A qq.Promise can be used if non-blocking work is required. Processing of this item is deferred until the promise is fullfilled. If a promise is returned, a call to failure is the same as returning false.

A buttonContainer element will be passed as the last argument, provided the file was submitted using a Fine Uploader tracked button.

The fileOrBlobDataArray object has two properties: name and size. The size property will be undefined for browsers without File API support.
Parameters:
Array
fileOrBlobDataArray

An array of File‘s or Blob‘s.
HTMLElement
buttonContainer

The button corresponding to the respective file if the file was submitted to Fine Uploader using a tracked button.