How to implement Forms APIs on Wix Studio

In this video we are going to go over the Wix Forms APIs and how they can be used with Wix Apps such as the new Wix Forms.

When building web forms on a site built on Wix Studio, you can utilize powerful APIs that allow you to create your own custom forms and handle all of the related backend events associated with user submissions.

As a disclaimer, the Wix Forms APIs are only available on Wix Studio.

Let’s begin by briefly introducing the Wix Forms app to gain an understanding of how you can create web forms on Wix Studio. 

We’ll start by installing the Wix Forms App from the App Market. You can do so by clicking on the App Market Icon on the Left Side Panel. Next we’ll search for Wix Forms and click ‘Add to Site’.

On this blank template we’ll add a form element now that we’ve installed the app. We’ll do so by pressing the Add Icon on the Left Side Panel, ‘Contact & Forms’, and then clicking on ‘Create New Form’. This adds a WixFormsV2 Editor Element to your page.

Wix Forms is an App solution that allows us to build forms, store user input in a database, and send auto generated emails after submission without writing any code. 

Additionally, you can use the frontend Forms APIs associated with the WixFormsv2 element if you want to extend the built in functionality, as we’ll see in our upcoming example.

Now let’s go over how we can use the Wix Forms APIs on this demo site for a fictitious law firm.

This contact form is built using the Wix Forms App.

While much of this functionality is provided by the app without any code, there is a frontend API associated with this WixFormsv2 element which allows you to submit and add a callback when a site visitor submits a Wix Form.

In this form we chose to remove the default submit button so we could add a custom button which programmatically submits the form using the Velo API.

This can be done by using the $w to select the WixFormV2 element and then using the .submit() method to submit the form

Additionally, we will use the .onSubmitSuccess() and .onSubmitFailure() event handlers to display a success or failure message depending on how the form submission process goes.

Let’s see this form in action on the live site. 

Let’s see how this submission was saved on the dashboard.

We’ll navigate to the submission by clicking on the WixFormsv2 Element, ‘Manage’, then ‘Manage Forms’. On the Forms and Submissions dashboard we’ll click ‘Edit’ on the contact form we want to view submissions for and we’ll finally then head over to the Submissions Tab. Here we’ll see all user submissions including those who have been detected as spam or placed in the trash. You can see our recently submitted form data here.

While the Wix Forms App handles most user needs, sometimes you have more advanced requirements which require backend operations. This is where the Wix Forms APIs come in. The Wix Forms APIs, also referred to as ‘Wix-Forms-v2’ on the Velo API, are a set of methods separated into two primary sets of APIs.  We will begin by introducing the Submissions API.

Submissions is a set of methods which allow you to create and manage submissions made on a form. Before we begin, it’s important to note that the Wix Forms API can be used in different Wix Apps such as Wix Forms, Wix Pricing Plans (such as when handling orders), or Wix Online Programs when building a quiz.

In any case when you use the Wix Forms APIs, submitting a form follows a standard lifecycle.

The first step of the submission life cycle begins when you call the .createSubmission() method and pass the form field values as a parameter.

These values are passed in an object where the keys are the unique column field names for each form input. These values can be seen in the Form dashboard.

On this page, we created a form using standard Wix Elements (such as Text Input, Upload 

Button, and Dropdown Inputs). 

This method allows you to build a custom form outside of the Wix Forms App widget using the  Wix Forms APIs.

Let’s talk about how we implemented our form.

Here we used the .createSubmission() method which submits the form and passes the input field values when the user clicks the submit button. Additionally, we created a function that validates the user’s form inputs according to set pattern validation.

In order to test this .createSubmission() method within the editor we will click on the Play Icon next to the web method we want to test. This will open a new tab within the editor which allows us to add sample parameter values and run the function.

Once the .createSubmission() method runs the form field values are sent to the server.

The server proceeds to validate the submission according to what each field expects based on data type.

If the validation is successful, the .createSubmission() method submits the form and records the data into the associated WixForms collection.

If the validation is unsuccessful, the server will throw an error message letting you know why it failed and then abort the submission process.

Please note, when using the .createSubmission() method it’s important to format the submission object according to the expected structure.

The ‘submissions’ key is an object in the submission parameter which represents the user’s form input data. The ‘formID’ key is a required ID associated with the WixForm you are submitting.

In order to get a WixForms form ID you can use the .querySubmissionsByNamespace() method which returns a list of submissions under a particular name space. In this case we will use the Wix Forms namespace, and find the relevant form IDs using known submissions.

The Submissions API also has other methods for handling form submissions in your backend  operations according to your needs including methods that count, get, update, delete, and confirm existing submissions.

Additionally, if you would like to handle form submissions with files via the API only, you can use the .getMediaUploadURL() method to get an upload url. You can use the returned upload url to send a PUT request which uploads a file associated with the form submission to the site's media manager.

Let’s see how this custom submission form utilizing the WixFormsV2 API works on the live site.

Here we can see all of the submission data including the sample ‘resume.pdf’ uploaded by the user.

When using the Wix Forms API you also have access to an Events API. Wix Forms events are fired in your site's backend when certain events related to forms occur. You can then write event handlers that react to these events. 

These are saved in your events.js file in the Backend section of your site. Each event type has an associated event object which has information about the submission as well as the metadata for the event.

There are three different types of event types that can be handled using this API including when a submission is created, deleted or updated. 

Here we added event API handlers that will log messages when we add a new submission, to the console.

These will be visible in our backend monitoring tools. We’ll access these tools by hovering on the Wix Studio logo on the top bar and clicking ‘Dashboard’. Here hover on Developer tools then click ‘Logs’. Finally, we’ll click on ‘Site Events’.

The Event APIs open the possibility to support advanced backend operations related to your user’s submissions. Here we can see some of the logged messages triggered by the Event APIs upon submitting and updating a submission.

And just like that we learned how you can use the Wix Form APIs to handle form submissions and associated backend operations on your site built on Wix Studio.