5.16.2

Options UI

UI

Fine Uploader UI mode has a few different options as well as some options pertaining specifically to the UI which core mode does not have.

Any options that exist in Core mode also exist in UI mode, and, in most cases, can be overridden.

element

Container element for the default drop zone

Type:
HTMLElement
Default Value:
null

listElement

Container element for the item list.

Type:
HTMLElement
Default Value:
null

multiple

When false this will prevent the user from simultaneously selecting or dropping more than one item. Dropping or selecting another item will clear the upload list. If another is already uploading, it will be canceled. To ignore rather than cancel, simply return false in the 'validate' or 'submit' event handlers.

Type:
Boolean
Default Value:
true

showMessage

Provide a function here to display a message to the user when the uploader receives an error or the user attempts to leave the page. The provided function may return a promise if one wishes to do asynchronous work whilst waiting for user input.

Type:
Function
Default Value:
function(message) { window.alert(message); }

showConfirm

Provide a function here to prompt the user to confirm deletion of a file. The provided function may return a promise if one wishes to do asynchronous work whilst waiting for user input.

Type:
Function
Default Value:
function(message) { window.confirm(message); }

showPrompt

Provide a function here to prompt the user for a filename when pasting file(s). The provided function may return a promise if one wishes to do asynchronous work whilst waiting for user input.

Type:
Function
Default Value:
function(message, defaultValue) { window.prompt(message, defaultValue); }

template

This points to the container element that contains the template to use for one or more Fine Uploader UI instances. You can either specify a string, which is the element ID (the ID of the container element on the page) or an Element that points to the container element.

Type:
String or Element
Default Value:
qq-template

deleteFile

This section defines UI specific options for the core deleteFile option.

confirmMessage

The message displayed in the confirm delete dialog.

Type:
String
Default Value:
Are you sure you want to delete {filename}?

deletingFailedText

The status message to appear next to a file that has failed to delete.

Type:
String
Default Value:
Delete failed

deletingStatusText

The status message to appear next to a file that is pending deletion.

Type:
String
Default Value:
Deleting...

forceConfirm

If this value is set to true, the user will be required to confirm the file delete request via a confirmation dialog.

Type:
Boolean
Default Value:
false

display

fileSizeOnSubmit

Enable or disable the display of the file size next to the file after it has been submitted.

Type:
Boolean
Default Value:
false

prependFiles

When true batches of files are added to the top of the UI's file list. The default is to append file(s) to the bottom of the list.

Type:
Boolean
Default Value:
false

dragAndDrop

extraDropzones

Designate additional drop zones for file input.

Type:
Array
Default Value:
[]

reportDirectoryPaths

Include the path of dropped files (starting with the top-level dropped directory). This value will be sent along with the request as a qqpath parameter.

Type:
Boolean
Default Value:
false

failedUploadTextDisplay

enableTooltip

Enable or disable a tooltip that will display the full contents of the error message when the mouse pointer hovers over the failed item.

Type:
Boolean
Default Value:
true

mode

Set the message to display next to each failed file. One of: 'default' which displays the failedUploadText, 'custom' which displays the error response from the server, or 'none' which displays no text.

Type:
String
Default Value:
default

responseProperty

The property from the server response that contains the error text to display next to a failed item. Ignored unless mode is 'custom'

Type:
String
Default Value:
error

messages

tooManyFilesError

Text sent to showMessage when multiple is false and more than one file is dropped at once.

Type:
String
Default Value:
You may only drop one file.

unsupportedBrowser

Text displayed to users who have ancient browsers.

Type:
String
Default Value:
Unrecoverable error - the browser does not permit uploading of any kind.

Note:

messages is also in the Core mode options. This section defines UI specific options for messages

retry

This section defines UI specific options for the core retry option

autoRetryNote

The text of the note that will optionally appear next to the item during automatic retry attempts. Ignored if showAutoRetryNote is false.

Type:
String
Default Value:
Retrying {retryNum}/{maxAuto} ...

showButton

Enable or disable the showing of a button/link next to the failed item after all retry attempts have been exhausted. Clicking the button/link will force the uploader to make another attempt.

Type:
Boolean
Default Value:
false

showAutoRetryNote

Enable or disable a status message appearing next to the item during auto retry attempts.

Type:
Boolean
Default Value:
true

thumbnails

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.
Type:
Function
Default Value:
undefined

maxCount

Maximum number of previews to render per Fine Uploader instance. A call to the reset method resets this value as well.

Type:
Integer
Default Value:
0

timeBetweenThumbs

The amount of time, in milliseconds, to pause between each preview generation process. This is in place to prevent the UI thread from locking up for a continuously long period of time, as preview generation can be a resource-intensive process.

Type:
Integer
Default Value:
750

thumbnails.placeholders

notAvailablePath

Absolute URL or relative path to the image to display if the preview/thumbnail could not be generated/displayed.

Type:
String
Default Value:
null

waitingPath

Absolute URL or relative path to the image to display during preview generation (modern browsers) or until the server response has been parsed (older browsers).

Type:
String
Default Value:
null

waitUntilResponse

Set this to true if you want the 'waiting' placeholder image to remain in place until the server response has been parsed. This is useful if you expect to return thumbnail URLs in your upload responses for files types that cannot be previewed. This option is ignored in older browsers where client-side previews cannot be generated.

Type:
Boolean
Default Value:
false

paste

namePromptMessage

Text that will appear in the showPrompt dialog.

Type:
String
Default Value:
Please name this image

promptForName

Enable or disable the usage of showPrompt by Fine Uploader to prompt the user for a filename for a pasted file.

Type:
Boolean
Default Value:
false

scaling

See the Upload Scaled Images feature page for more details.

failureText

Text that will appear next to a scaled image that could not be generated. This is in addition to the behavior associated with this property provided by Fine Uploader Core.

Type:
String
Default Value:
Failed to scale

hideScaled

Set this to true if you do not want any scaled images to be displayed in the file list.

Type:
Boolean
Default Value:
false

text

failUpload

Text that appears next to a failed item

Type:
String
Default Value:
Upload failed

formatProgress

Appears next to a currently uploading item

Type:
String
Default Value:
{percent}% of {total_size}

paused

Appears next to a paused item

Type:
String
Default Value:
Paused

waitingForResponse

Appears next to item once the last bytes have been sent (differs on the user-agent)

Type:
String
Default Value:
Processing...