Velo How-To: Setting Up The File Upload Field With Custom Form Handler

File Upload Scenario

The typical file upload scenario is a two-part process. First your site visitor chooses the file to upload and then they trigger the actual upload. This usually requires at least two page elements, an upload button element and a regular button. The site visitor chooses which file to upload by clicking the upload button and selecting the file in a native file chooser dialog. (The site visitor can only choose from the specified file type.) Then the site visitor clicks the regular button to trigger some code that performs the upload.

Note
The file types of the images, documents, videos, and audios that can be uploaded are listed here.

Upload Example

Let's create a simple form that uploads an image to better understand how this process works. We'll add elements to a page, wire some elements to a bit of code, and then test the form.

Prerequisites

Before you create an upload form, you'll need to be somewhat comfortable with JavaScript code, especially event handlers and Promises.

Add Page Elements

Add the following elements to the page:

An upload button for choosing a file. The upload buttons are found in the User Input section of the Add menu.
A regular button to trigger the upload code.
A text element to display messages to the site visitor.
An image element. Any image is fine. We're only using it as a placeholder for the uploaded image.

Feel free to change the design and text of any of the elements we've just added.

The complete form should look something like this:

Wire Upload Code

The upload button takes care of the site visitor choosing the file for us. But we have to wire code to the regular button to perform the actual upload.

We'll start by adding an onClick event handler for the button.

Next, we'll add the code that performs the upload. In the onClick event handler add the following code so the full function is as follows:

export function button1_click(event) {
  if($w("#uploadButton1").value.length > 0) {
    $w("#text1").text = "Uploading " + $w("#uploadButton1").value[0].name;
    $w("#uploadButton1").startUpload()
      .then( (uploadedFile) => {
        $w("#text1").text = "Upload successful";
        $w("#image1").src = uploadedFile.url;
      })
      .catch( (uploadError) => {
        $w("#text1").text = "File upload error";
        console.log("File upload error: " + uploadError.errorCode);
        console.log(uploadError.errorDescription);
      });
  } 
  else {
    $w("#text1").text = "Please choose a file to upload.";
  }
}

Let's take a look at this code piece by piece to understand what it's doing.

First, on line 2, we check to see if the site visitor has chosen a file. We did not specify a file type, so "image" is assumed.

if($w("#uploadButton1").value.length > 0) {

The

value

property of the upload button returns an array of

File

objects, each representing a file the site visitor has chosen to upload. So we check its

length

to see if this array has at least one item in it, meaning the site visitor has chosen at least one file.

If the array returned by

value

is empty, we move to the

else

on lines 15-17 to display a message to the site visitor in the text element.

else {
  $w("#text1").text = "Please choose a file to upload.";
}

That ends the upload attempt. The site visitor can then choose a file and start the upload again.

If the array has a

File

element in it, meaning the site visitor chose a file to upload, we continue with the upload process.

On line 3, we start the upload process by displaying a message to the site visitor that we are uploading the chosen file.

$w("#text1").text = "Uploading " + $w("#uploadButton1").value[0].name;

Next, on line 4, we call the upload button's

startUpload()

function, which performs the actual upload.

$w("#uploadButton1").startUpload()

It returns a Promise that resolves to an

UploadedFile

object with information about the uploaded file if the upload was successful or rejects to an

UploadError

object with information about the error that occurred if the upload was not successful.

If the upload is successful, the Promise continues with the

then()

on lines 5-8.

.then( (uploadedFile) => {
  $w("#text1").text = "Upload successful";
  $w("#image1").src = uploadedFile.url;
})

Here we display a message to the site visitor saying that the upload was successful and we display the uploaded image. We display the image by getting the

url

property of

uploadedFile

, which returns the Wix URL where the uploaded file is stored.

If the upload is unsuccessful, the Promise rejects with the

catch()

on lines 9-13.

.catch( (uploadError) => {
  $w("#text1").text = "File upload error";
  console.log("File upload error: " + uploadError.errorCode);
  console.log(uploadError.errorDescription);
});

Here we display a message to the site visitor saying that the upload was not successful. We also log the error information from the

uploadError

object using its

errorCode

and

errorDescription

properties.

Testing

Now we can test our form by publishing the site and attempting to upload an image.

First, on the live site, let's try to click the Start Upload button before we choose a file. We should see the status line change to Please choose a file to upload.

Next, let's use the upload button to choose a file and then click the Start Upload button. We should see the status line change to Uploading some_file.png and then after a few moments change again to Upload successful. The image we uploaded should also be displayed on the page.

Finally, let's return to the Editor and find the uploaded file. Select the upload button and click Manage Upload Button. In the Upload Button Settings panel, click Go to File, which opens the images that have been received by your site. There you should see the image you just uploaded.

Previously published at https://support.wix.com/en/article/velo-tutorial-using-the-upload-button-with-code