5.15.0
Fine Uploader has a wealth of ways to respond to error messages. By default, Fine Uploader assumes an error when the
server response does not have a key of success
set to true
. If any error is thrown, then the onError
callback will be invoked.
Sometimes errors are not intended, or unexpected. Fine Uploader provides the
debug
option which will make the plugin spit out logging messages to the
browser's developer tools console.
To enable debug mode, set the debug
option of Fine Uploader to true
and open the developer console in your browser. Interact with Fine Uploader
and notice that it is logging specifically what is happening. These messages
can be crucial in determining why something is not working as expected.
Handling error messages and errors can take place inside of the onError
callback. onError
is triggered whenever Fine Uploader encounters an error.
The text to be displayed in the case of an error is passed in as the errorReason
parameter.
The following code snippet shows how one might display a custom alert on the event of an error.
var uploader = new qq.FineUploader({ /* other required config options left out for brevity */ callbacks: { onError: function(id, name, errorReason, xhrOrXdr) { alert(qq.format("Error on file number {} - {}. Reason: {}", id, name, errorReason)); } } });
By default, if Fine Uploader does not receive a successful server response,
it will look for the error
property of the response body and will pass
that value to the onError
callback.
If the server indicates failure in the response, but does not include an
error
property and the response status indicates failure, then the
defaultResponseError
property will be used as the error message.
var uploader = new qq.FineUploader({ /* other required config options left out for brevity */ text: { defaultResponseError: 'An unknown upload error occurred.' } });
The messages
property in the core Fine Uploader options provides a
handful of properties one can override to display custom error messages.
var uploader = new qq.FineUploader({ /* other required config options left out for brevity */ messages: { typeError: '{file} has an invalid extension. Valid extension(s): {extensions}.' // other messages can go here as well ... } });
Error messages include primitive String
interpolation that allows integrators
to inject variable data into error messages. For example, the typeError
message could be modified:
messages: { typeError: 'Invalid extension detected in file, {file}.' }
The filename of the file which the error was thrown on will be injected
instead of the "{file}"
String
.
The failedUploadTextDisplay
option defines properties used for displaying
text when an upload fails.
var uploader = new qq.FineUploader({ /* other required config options left out for brevity */ // These are all the DEFAULT values... failedUploadTextDisplay: { mode: 'default', responseProperty: 'error', } });
The mode
property has three settings, each of which determine how failed
upload errors are displayed.
'default'
will display the failUploadText
defined in the text
option
properties next to each item.'none'
will not display any text next to a failed item.'custom'
will display an error response text from the server next to each
failed item).'custom'
mode will use the provided responseProperty
(which defaults
to 'error'
) as its text