5.16.2
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.
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.
Called before each automatic retry attempt for a failed item.
The current file's id.
The current file's name.
The number of retry attempts for the current file so far.
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.
The current file's id.
The current file's name.
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.
The current file's id.
The current file's name.
The raw response from the server.
The object used to make the request.
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
).
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.
The current file's id.
Called just after receiving a response from the server for a delete file request.
The current file's id.
The object used to make the request.
true
if there has been an error, false
otherwise.
Called whenever an exceptional condition occurs (see Handling Errors)
The current file's id.
The current file's name.
The reason for the current error.
The object used to make the request.
Called before each manual retry attempt.
Return false
to prevent this and all future retry attempts on the associated item.
The current file's id.
The current file's name.
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.
An object encapsulating the image pasted from the clipboard.
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.
The current file's id.
The current file's name
The number of bytes that have been uploaded so far.
The total number of bytes that comprise this file.
Called just before an upload is resumed. See the uploadChunk
event for more info on the chunkData
object.
The current file's id.
The current file's name
The chunk that will be sent next when file upload resumes.
Any custom resume data provided for this resumable file.
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.
The raw response data.
Indicates whether success has been achieved or not.
The raw request.
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
The current file's id.
The previous item status.
The new status of the item.
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
.
The current file's id.
The current file's name.
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.
The current file's id.
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.
The current file's id.
THe current file's name.
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.
The number of bytes that have been uploaded so far in this batch.
The total number of bytes that comprise all files in the batch.
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.
The current file's id.
The current file's name.
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).The current file's id.
The current file's name.
An object encapsulating the current chunk of data about to be uploaded.
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.
The current file's id.
An object encapsulating the current chunk of data about to be uploaded.
The raw response from the server.
The object used to make the request.
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.
An object with a name
and size
property.
The button corresponding to the respective file if the file was submitted to Fine Uploader using a tracked button.
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.
An array of Objects
with name
and size
properties.
The button corresponding to the respective file if the file was submitted to Fine Uploader using a tracked button.