Introduction
Important: The upload button was recently updated. You can see updates to the upload button here.
When adding an upload button to your site, you generally also add a regular button. The upload button allows a site visitor to add the files they want to upload, and the regular button triggers the actual upload of the files to the site. The following describes the flow for a typical file upload scenario:
Typical File Upload Scenario
- The site visitor clicks the upload button, and chooses which files to upload by selecting the files in a native file chooser dialog.
- At that point, the selected files are stored in the upload button's
value
property as an array ofFile
objects. - The
onChange()
event is triggered. - Validations on the files are performed, following which the
valid
,validity
, andvalidationMessage
properties are updated. BecauseonChange()
is fired before validations are performed, do not check any of the validation properties in the code of theonChange()
event handler. For example, do not code anif
statement that checks thevalid
property in theonChange()
because the property at this point contains values prior to theonChange()
. - The site visitor clicks the regular button.
- The regular button's
onClick()
event handler calls theuploadFiles()
function. This function triggers the actual upload of the files stored in the upload button'svalue
property. - The upload either succeeds and returns an
UploadedFile
object, or fails and returns anUploadError
object.
See the code example in the uploadFiles()
function for the typical file upload scenario.
Note:
The onChange()
event is triggered before validation. As a result, consider the following points if you intend
to call the uploadFiles
function inside the onChange()
event handler:
uploadFiles()
returns promptly with anUploadError
object if thefileSizeExceedsLimit
orfileTypeNotAllowed
validity property is true.- If the validation fails for one of these reasons, causing an error to be returned, the
uploadFiles()
function doesn't attempt the upload.
Updates to the Upload Button
- The
startUpload()
function, which allows you to upload one file at a time, is deprecated. The function will continue to work, but a new and updateduploadFiles()
function is available instead. WithuploadFiles()
, you can upload multiple files at the same time. - The
value
property returns 2 additional parameters,valid
andvalidationMessage
. - The
fileType
property has an additionalGallery
value that accepts both images and videos at the same time. - The
validity
property has an additionalexceedsFileLimit
validity message in theValidityState
object. - The upload button has an additional
.fileLimit
property that gets/sets the maximum amount of files a site vistor can upload at a time.
Was this helpful?
Yes
No