Skip to content

Latest commit

 

History

History
executable file
·
564 lines (551 loc) · 22 KB

options-fineuploaderbasic.md

File metadata and controls

executable file
·
564 lines (551 loc) · 22 KB
Raw

FineUploaderBasic mode options

Name Type Default Note
debug boolean false If enabled, this will result in log messages (such as server response) being written to the javascript console. If your browser does not support the [window.console object](https://developer.mozilla.org/en-US/docs/DOM/console.log), the value of this option is irrelevant.
button element null Specify an element to use as the "select files" button. Note that this may NOT be a <button>, otherwise it will not work in Internet Explorer. Please see issue #33 for details.
multiple boolean true In FineUploaderBasic mode, this will simply prevent you from simultaneously selecting or dropping more than one file or `Blob`. In FineUploader mode, dropping or selecting another file or `Blob` will clear the upload list. If another is already uploading, it will be cancelled. If you you want Fine Uploader to simply ignore subsequently dropped/selected items, simply return false in your onValidate or onSumbit callback handler for any subsequent item that has been dropped. Note that the behavior described for FineUploader mode is in addition to the behavior already provided by FineUploaderBasic mode.
maxConnections integer 3 Maximum allowable concurrent requests (per request-type). For example, if the number is 3, you will be limited to 3 concurrent deleteFile requests and 3 concurrent upload requests, along with 3 of whatever other request types Fine Uploader supports.
disableCancelForFormUploads boolean false If true, the cancel link does not appear next to files when the form uploader is used. This may be desired since it may not be possible to interrupt a form-based upload in some cases.
autoUpload boolean true Set to false if you want to be able to begin uploading selected/queued items later, by calling uploadStoredFiles().
formatFileName function (see source code) By default, this function limits the name displayed in the UI or error messages to 33 characters, plus 3 ellipses separating the first several and the last several characters of the item name. Override this function if you want more control over the display of item names.
### `request` option properties: ###
Name Type Default Note
endpoint string (path) /server/upload The is the endpoint used by both the form and ajax uploader. In the case of the form uploader, it is part of the form's action attribute value along with all parameters. In the case of the ajax uplaoder, it is makes up part of the URL of the XHR request (again, along with the parameters).
params object {} These parameters are sent with the request to the endpoint specified in the action option. An individual parameter value may be a number, string, another object, or a function that returns a number or string. See the associated blog post for more details.
paramsInBody boolean true Set this to true if you want all parameters to be sent in the request body. Note that setting this option to true will force all requests to be multipart encoded. If the value is false all params will be included in the query string. See the associated blog post for more details.
customHeaders object {} Additional headers sent along with the XHR POST request. Note that is option is only relevant to the ajax/XHR uploader.
forceMultipart boolean true While form-based uploads will always be multipart requests, this forces XHR uploads to send files or `Blob` objects using multipart requests as well.
inputName string qqfile This usually only useful with the ajax uploader, which sends the name of the file or `Blob` as a parameter, using a key name equal to the value of this options. In the case of the form uploader, this is simply the value of the name attribute of the file's associated input element.
uuidName string qquuid The name of the parameter, sent along with each request, that uniquely identifies the associated file or `Blob`. The value of this parameter is a version 4 UUID.
totalFileSizeName string qqtotalfilesize Name of the parameter passed with a multipart encoded request that specifies the total size in bytes of the associated file or `Blob`. Note that this is only passed with MPE requests that originate from the XHR uploader, since there is no way to determine file size client-side when using the form uploader.

validation option properties:

Name Type Default Note
allowedExtensions array of strings [] This may be helpful if you want to restrict uploaded files to specific file types. Note that this validation option is only enforced by examining the extension of uploaded file names. For a more complete verification of the file type, you should use, for example, magic byte file identification on the server side and return {"success": false} in the response if the file type is not on your whitelist.
acceptFiles comma-separated strings null This option is used solely by the file selection dialog. If you'd like to restrict valid file types that appear in the selection dialog, you can do this here by listing valid content type specifiers. See the [documentation on the accept attribute of the input element](https://developer.mozilla.org/en-US/docs/HTML/Element/Input) for more information.
sizeLimit integer 0 (no limit) Maximum allowable size, in bytes, for a file or `Blob`.
minSizeLimit integer 0 (no limit) Minimum allowable size, in bytes, for a file or `Blob`.
stopOnFirstInvalidFile boolean true If true, when submitting multiple files or `Blob` objects, once an item is determined to be invalid, no further files in the batch will be processed. If false, all valid items in the batch will be processed. Note: One downside to a false value can be seen when using FineUploader if the default showMessage implementation is not overriden. In this case, an alert dialog will appear for each invalid item in the batch, and the upload process will not continue until the dialog is dismissed. If this is bothersome, simply override showMessage with a desirable implementation.

messages option properties:

Name Type Default Note
typeError string {file} has an invalid extension. Valid extension(s): {extensions}. Text sent to the `onError` callback (and `showMessage` if running in FineUploader mode) if an invalid file type is submitted, according to the validation settings.
sizeError string {file} is too large, maximum file size is {sizeLimit}. Text sent to the `onError` callback (and `showMessage` if running in FineUploader mode) if a file or `Blob` that is too large, according to the validation settings, is submitted.
minSizeError string {file} is too small, minimum file size is {minSizeLimit}. Text sent to the `onError` callback (and `showMessage` if running in FineUploader mode) if a file or `Blob` that is too small, according to the validation settings, is submitted.
emptyError string {file} is empty, please select files again without it. Text sent to the `onError` callback (and `showMessage` if running in FineUploader mode) if a zero-sized file or `Blob` is submitted.
noFilesError string No files to upload. Text sent to the `onError` callback (and `showMessage` if running in FineUploader mode) if a an empty array of files or `Blob` objects is submitted.
onLeave string The files are being uploaded, if you leave now the upload will be cancelled. Message display to the user (by the browser) if the user attempts to leave the page while uploads are still in progress.

retry option properties:

Name Type Default Note
enableAuto boolean false If set to true, any error or non-200 response will prompt the uploader to automatically attempt to upload the file or `Blob` again.
maxAutoAttempts number 3 The maximum number of times the uploader will attempt to retry a failed upload. Ignored if enableAuto is false.
autoAttemptDelay number 5 The number of seconds the uploader will wait in between automatic retry attempts. Ignored if enableAuto is false.
preventRetryResponseProperty string preventRetry If this property is present in the server response and contains a value of true, the uploader will not allow any further retries of this file or `Blob` (manual or automatic).

chunking option properties:

For more complete details regarding the file chunking feature, along with code examples, please see this blog post. on the topic.

Name Type Default Note
enabled boolean false If set to true, each file or `Blob` will be split up into parts. Each part will be sent in a separate request. The size of the part is determined by the partSize option value. See the server-side readme for more details.
partSize number 2000000 The maximum size of each part, in bytes.

chunking.paramNames option properties:

For more complete details regarding the file chunking feature, along with code examples, please see this blog post. on the topic.

Name Type Default Note
partIndex string qqpartindex Name of the parameter passed with a chunked request that specifies the index of the associated partition.
partByteOffset string qqpartbyteoffset Name of the parameter passed with a chunked request that specifies the starting byte of the associated chunk.
chunkSize string qqchunksize Name of the parameter passed with a chunked request that specifies the size in bytes of the associated chunk.
totalParts string qqtotalparts Name of the parameter passed with a chunked request that specifies the total number of chunks associated with the underlying file or `Blob`.
filename string qqfilename Name of the parameter passed with a chunked request that specifies the name of the associated file or `Blob`. This is useful for chunked requests that are multipart encoded, since the filename reported by the user agent in the content-disposition header will be either "blob" or an empty string.

resume option properties:

For more details, please read the blog post on the file resume feature.

Name Type Default Note
enabled boolean false If set to true, the ability to resume a failed/stopped chunked upload will be possible. See the server-side readme for more details.
id number, string, or boolean null If this value is not defined or if the value does not fit into one of the acceptable types, the cookie name used to identify a file chunk will be composed of the filename, file size, and max partition/chunk size. If this value IS defined and DOES fit into one of the acceptable types, it will be added as an additional component of the cookie name.
cookiesExpireIn number 7 The number of days before a persistent resume cookie will expire.

resume.paramNames option properties:

For more details, please read the blog post on the file resume feature.

Name Type Default Note
resuming string qqresume Sent with the first request of the resume, with a value of true.

text option properties:

Name Type Default Note
sizeSymbols array of strings ['kB', 'MB', 'GB', 'TB', 'PB', 'EB'] Symbols used to represent file size, in ascending order.

deleteFile option properties:

For more information on the Delete File feature, please read the associated blog post and check out the server-side readme.

Name Type Default Note
enabled boolean false Set this to true if you would like to allow users to delete uploaded files. In FineUploader mode, this will also render a "delete" link next to each successfully uploaded file or `Blob`.
endpoint string /server/upload This should be the endpoint to where any DELETE (file) request should be sent. Note that this is a DELETE request, and the UUID of the associated file is sent as the last part of the URI path.
customHeaders object {} Any additional headers to attach to all DELETE (file) requests.
params object {} Any additional parameters to attach to DELETE (file) requests. This works the exact same way as the params property of the request option. Note that all parameters are sent in the query string.

cors option properties:

For more information on CORS support, please read the associated blog post and check out the server-side readme.

Name Type Default Note
expected boolean false Set this to true if all requests will be cross-domain requests. If this is set to true, all iframe-initiated requests must include responses that follow the convention described in the CORS support blog post.
sendCredentials boolean false Set this to true if you would like credentials (i.e. cookies) sent along with each CORS request. Your response must, as a result, include the appropriate headers.

blobs option properties:

Options used when Blob objects are to be uploaded.

Name Type Default Note
defaultName string Misc data If you do not include a name along with the `Blob` submitted to the uploader (via a `BlobData` object) this default name will be used.

blobs.paramNames option properties:

Options used when Blob objects are to be uploaded.

Name Type Default Note
name string qqblobname A request parameter used to specify the associated name with any uploaded `Blob`.