Velo Tutorial: Using the Upload Button with Code

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.

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 Input section of the Add Elements 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: 

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.

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 uploadFiles() function, which performs the actual upload.

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

It returns a Promise that resolves to an array of UploadedFile objects with information about the uploaded files 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.

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 fileUrl property of the first UploadedFile object in the array, 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.

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 Settings. In the Button Settings panel, scroll down to Manage visitor files and click View Uploaded Files, which opens the images that have been received by your site. There you should see the image you just uploaded.