5.16.2

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

The following syntax is the correct way to define event handlers:

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

where callbacks is specified as a FineUploader option.

onAutoRetry

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.


onCancel

Called when the item has been canceled. Return false to prevent the upload from being canceled. Also can return a 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.


onComplete

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.


onAllComplete

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).


onDelete

Called just before a delete request is sent for the associated item. Note that this is not the correct callback to influence the delete request. To do that, use the onSubmitDelete callback instead.

Parameters:
Integer
id

The current file's id.


onDeleteComplete

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.


onError

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.


onManualRetry

Called before each manual retry attempt.

Return false to prevent this and all future retry attempts on the associated item.

Parameters:
Integer
id

The current file's id.


String
name

The current file's name.


onPasteReceived

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

The pasted image is represented as a Blob. Also can return a 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.


onProgress

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.


onResume

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.


Object
customResumeData

Any custom resume data provided for this resumable file.


onSessionRequestComplete

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.


onStatusChange

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.


onSubmit

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 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.


onSubmitDelete

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

A 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.

Use this callback to influence the delete request. For example, you can change the custom parameters sent with the underlying delete request using the setDeleteParams API method.

Parameters:
Integer
id

The current file's id.


onSubmitted

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.


onTotalProgress

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.


onUpload

Called just before an item begins uploading to the server. If asynchronous work must be performed, you may return a Promise. To fail the upload, reject the Promise. Otherwise, resolve it. Additionally, you can pause the upload when resolving the Promise by passing an object with { pause: true } to the resolve function.

Parameters:
Integer
id

The current file's id.


String
name

The current file's name.


onUploadChunk

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.

Note that you can also return a Promise from this handler. To fail the upload, simply reject the Promise. Otherwise, resolve the Promise. Additionally, you can order Fine Uploader to use a specific endpoint, parameters, method, and headers for this specific chunk upload request simply by passing an object to the resolve function that contains values for those four request attributes. The following object properties may be passed to your resolve function to influence the chunk upload request:

  • endpoint - The endpoint to send the upload chunk request.
  • headers - Any headers to be included with the upload chunk request.
  • method - The HTTP method to use for the upload chunk request.
  • params - Any parameters to send in either the body or the URL of the upload chunk request (depending on if this is a multipart encoded request).
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.


onUploadChunkSuccess

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.


onValidate

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

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 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:
Object
data

An object with a name and size property.


HTMLElement
buttonContainer

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


onValidateBatch

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 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 Objects with name and size properties.


HTMLElement
buttonContainer

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