Search.../
  1. APIs

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

  1. The site visitor clicks the upload button, and chooses which files to upload by selecting the files in a native file chooser dialog.
  2. At that point, the selected files are stored in the upload button's value property as an array of File objects.
  3. The onChange() event is triggered.
  4. Validations on the files are performed, following which the valid, validity, and validationMessage properties are updated. Because onChange() is fired before validations are performed, do not check any of the validation properties in the code of the onChange() event handler. For example, do not code an if statement that checks the valid property in the onChange() because the property at this point contains values prior to the onChange().
  5. The site visitor clicks the regular button.
  6. The regular button's onClick() event handler calls the uploadFiles() function. This function triggers the actual upload of the files stored in the upload button's value property.
  7. The upload either succeeds and returns an UploadedFile object, or fails and returns an UploadError 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 an UploadError object if the fileSizeExceedsLimitor fileTypeNotAllowed 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 updated uploadFiles() function is available instead. With uploadFiles(), you can upload multiple files at the same time.
  • The value property returns 2 additional parameters, valid and validationMessage.
  • The fileType property has an additional Gallery value that accepts both images and videos at the same time.
  • The validity property has an additional exceedsFileLimit validity message in the ValidityState 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?