5.15.0

Methods Traditional

Core

Note

If you pass a large Blob that was created using JavaScript in the browser into addFiles, you should consider calling the removeFileRef method after the file has been successfully uploaded to free up any memory consumed by the Blob.

addFiles (files[, params[, endpoint]])

Submit one or more files to the uploader.

A BlobWrapper object:

Property Description
blob the bytes of the Blob object being uploaded
name the name of the Blob


A CanvasWrapper object:

Property Description
canvas the <canvas> to be converted to a file & then uploaded
name the name to assign to the created file
quality 1-100 value indicating the desired quality of the converted file (only for image/jpeg)
type MIME type of the file to create from this <canvas>
Parameters:
Array
files

An array of Files, <input>s, Blobs, BlobWrapper objects, <canvas>es, or CanvasWrapper objects. You may also pass in a FileList.


Object
params

A set of parameters to send with the file to be added


String
endpoint

The endpoint to send this file to


addInitialFiles (initialFiles)

Submit one or more canned/initial files to the uploader. See the Initial File List feature page for more details.

Parameters:
Array
initialFiles

An array of objects that describe files already on the server.


cancel (id)

Cancel the queued or currently uploading item which corresponds to the id.

Parameters:
Integer
id

The file's id


cancelAll ()

Cancels all queued or currently uploading items.


clearStoredFiles ()

Clears the internal list of stored items. Only applies when autoUpload is false


continueUpload (id)

Attempts to continue a paused upload.

Parameters:
Integer
id

A file id


Returns:
Boolean
`true` if attempt was successful.

deleteFile (id)

Parameters:
Integer
id

Send a delete request to the server for the corresponding file id.


drawThumbnail (id, targetContainer[, maxSize[, fromServer[, customResizer]]])

Draws a thumbnail.

Parameters:
Integer
id

The id of the image file.


HTMLElement
targetContainer

The element where the image preview will be drawn. Must be either an <img> or <canvas> element.


Integer
maxSize

The maximum dimensions (for width and height) you will allow this image to scale to.


Boolean
fromServer

true if the image data will come as a response from the server rather than be generated client-side.


function
customResizer

Ignored if the current browser does not support image previews. If you want to use an alternate library to resize the image, you must contribute a function for this option that returns a Promise. Once the resize is complete, your promise must be fulfilled. You may, of course, reject your returned Promise is the resize fails in some way.

A resizeInfo object, which will be passed to the supplied function, contains the following properties:

  • blob - The original File or Blob object, if available.
  • height - Desired height of the image after the resize operation.
  • image - The original HTMLImageElement object, if available.
  • sourceCanvas - HTMLCanvasElement element containing the original image data (not resized).
  • targetCanvas - HTMLCanvasElement element containing the HTMLCanvasElement that should contain the resized image.
  • width - Desired width of the image after the resize operation.

Returns:
promise
Fulfilled by passing the container back into the success callback after the thumbnail has been rendered. If the thumbnail cannot be rendered, failure callbacks will be invoked instead, passing an object with `container` and `error` properties.

getButton (id)

Returns the button container element associated with a file

Parameters:
Integer
id

The file id


Returns:
HTMLElement
The button container element associated with a file, or `undefined` if the file was not submitted via a Fine Uploader controlled upload button.

getFile (id)

Returns the file identified by the id. File API browsers only.

Parameters:
Integer
id

The file id.


Returns:
File or Blob
A `File` or `Blob` object.

getEndpoint ([id])

Returns the endpoint associated with a particular file, or the current catch-all endpoint for all files (if no ID is specified).

Parameters:
Integer
id

The ID of the associated file.


getInProgress ()

Returns the number of items that are either currently uploading or waiting for an available connection (qq.status.QUEUED). If called inside of a cancel event handler, then this method will return a value that includes the upload associated with the cancel event handler. This is because the upload will not be canceled until the event handler returns.

Returns:
Integer
The number of items that are currently uploading or queued.

getName (id)

Returns the name of the file with the associated id.

Parameters:
Integer
id

The file id


Returns:
String
Returns the name of the file identified by the id.

getNetUploads ()

Get the number of items that have been successfully uploaded and have not been deleted.

Returns:
Integer
The number of items that have been successfully uploaded and not deleted.

getParentId (scaledFileId)

Get the ID of the parent file for this scaled file.

Parameters:
Integer
id

The ID of a scaled image file


Returns:
Integer
Returns the ID of the scaled image's parent file. `null` if this is not a scaled image or a parent cannot be located.

getRemainingAllowedItems ()

Returns the numer of remaining allowed items that may be submitted for upload based on validation.itemLimit.

Returns:
Integer
The number of items that may be submitted for upload.

getResumableFilesData ()

Returns an array of potentially resumable items. Each resumable is represented by an object with the following properties:

Property Description
name filename
uuid the unique id
partIdx the index of the part where the resume will start from
Returns:
Array
An array of resumable items.

getSize (id)

Returns the size of the item with the associated id.

Parameters:
Integer
id

The file id.


Returns:
Integer
The size of the file with the corresponding id.

getUploads (filter)

Return information about all the items that have been submitted to the uploader. The objects being iterated over will have the following properties: id, uuid, originalName, name, status, and size. For information on filtering via the filter parameter, see the upload status feature page.

Parameters:
Object
filter

An object which indicates which keys and values must be present in an upload to be returned.


Returns:
Array or Object
A list of items or a single item that has been filtered/found. This returns an array only when there is a potential for the operation to return more than one file in the result set. This excludes queries for a specific, single ID or UUID. All other queries will return an array.

getUuid (id)

Returns the UUID of the item with the associated id.

Parameters:
Integer
id

The fild id.


Returns:
String
A level 4 UUID which identifies the corresponding file.

log (message[, level])

Output a message to the console, if possible.

Parameters:
String
message

The message to print


String
level

The level to output the message at.


pauseUpload (id)

Attempts to pause an in-progress upload.

Parameters:
Integer
id

The file id.


Returns:
Boolean
`true` if the attempt was successful. `false` otherwise.

removeFileRef (id)

Parameters:
Integer
id

Remove internal reference to the associated Blob/File object. For Blobs that are created via JavaScript in the browser, this will free up all consumed memory.


reset ()

Reset Fine Uploader


retry (id)

Attempt to upload a specific item again.

Parameters:
Integer
id

The file id.


scaleImage (id, options)

Generates a scaled version of a submitted image file.

Parameters:
Integer
id

The id of the image file.


Object
options

Information about the scaled image to generate. The following properties are supported:

  • maxSize (required) (integer).
  • orient (boolean, defaults to true)
  • type (string, defaults to the type of the reference image)
  • quality (number between 0 and 100, defaults to 80)
  • includeExif (boolean, defaults to false).
  • customResizer (function) - Ignored if the current browser does not support image previews. If you want to use an alternate library to resize the image, you must contribute a function for this option that returns a Promise. Once the resize is complete, your promise must be fulfilled. You may, of course, reject your returned Promise is the resize fails in some way.

A resizeInfo object, which will be passed to your (optional) customResizer function, contains the following properties:

  • blob - The original File or Blob object, if available.
  • height - Desired height of the image after the resize operation.
  • image - The original HTMLImageElement object, if available.
  • sourceCanvas - HTMLCanvasElement element containing the original image data (not resized).
  • targetCanvas - HTMLCanvasElement element containing the HTMLCanvasElement that should contain the resized image.
  • width - Desired width of the image after the resize operation.

Returns:
promise
Fulfilled by passing the scaled image as a `Blob` back into the success callback after the original image has been scaled. If the scaled image cannot be generated, the failure callback will be invoked instead.

setCustomHeaders (customHeaders[, id])

Set custom headers for an upload request. Pass in a file id to make the headers specific to that file.

Parameters:
Object
customHeaders

The custom headers to include in the upload request. Fine Uploader may also send some other required headers.


Integer
id

The file id.


setEndpoint (path[, identifier])

Modify the location where upload requests should be directed. Pass in a file id to change the endpoint for that specific item.

Parameters:
String
path

A valid URI where upload requests will be sent.


Integer or HTMLElement
identifier

An integer corresponding to a file.


setDeleteFileCustomHeaders (customHeaders[, id])

Set custom headers for a delete file request. Pass in a file id to make the headers specific to that file.

Parameters:
Object
customHeaders

The custom headers to include in the delete request. Fine Uploader may also send some other required headers.


Integer
id

The file id.


setDeleteFileEndpoint (path[, identifier])

Modify the location where delete requests should be directed. Pass in a file id to change the endpoint for that specific item.

Parameters:
String
path

A valid URI where delete requests will be sent.


Integer or HTMLElement
identifier

An integer corresponding to a file.


setDeleteFileParams (params[, id])

Set the parameters for a delete request. Pass in a file id to make the parameters specific to that file.

Parameters:
Object
params

The parameters to include in the delete request.


Integer
id

The file id.


setItemLimit (newItemLimit)

Change the validation.itemLimit option set during construction/initialization.

Parameters:
Integer
newItemLimit

The new file count limit.


setForm (formElementOrId)

Bind a <form> to Fine Uploader dynamically. See the form support feature page for more details.

Parameters:
HTMLFormElement or String
formElementOrId

A form element or a form element's ID.


setName (id, name)

Change the name of a file.

Parameters:
Integer
id

The file id.


String
name

The new file name.


setParams (params[, id])

Set the parameters for an upload request. Pass in a file id to make the parameters specific to that file.

Parameters:
Object
params

The parameters to include in the upload request.


Integer
id

The file id.


setUuid (id, uuid)

Change the UUID of a file.

Parameters:
Integer
id

The file id.


String
uuid

The new file UUID.


setStatus (id, newStatus)

Modify the status of an file.

The status values correspond to those found in the qq.status object. Currently, the following status values may be set via this method:

  • qq.status.DELETED
  • qq.status.DELETE_FAILED
Parameters:
Integer
id

The file id.


String
newStatus

The new qq.status value.


uploadStoredFiles ()

Begin uploading all queued items. Throws a NoFilesError of there are no items to upload.


UI

addExtraDropzone (element)

Mark element as a drop zone.

Parameters:
HTMLElement
element

The element to mark as a drop zone.


getDropTarget (id)

Returns the (drop zone) element where the file was dropped. Undefined if drop event was not involved.

Parameters:
Integer
id

The id of a file.


Returns:
HTMLElement
The drop zone element where the file as dropped.

getId (element)

Returns the file id associated with an HTMLElement.

Parameters:
HTMLElement
element

Returns the ID of the associated file, given a file container element or a child of a file container element.


Returns:
Integer
The id of the file.

getItemByFileId (id)

Returns the HTMLElement associated with the file id.

Parameters:
Integer
id

The file id.


Returns:
HTMLElement
The `HTMLElement` that is associated with the file id.

removeExtraDropzone (element)

Used to un-mark an element as a drop zone.

Parameters:
HTMLElement
element

The element to un-mark as a drop zone.