You can work with Forms using Velo APIs in 2 different ways:
- Use the Wix Forms app and its APIs.
- Create your own custom form with input elements and submit buttons. Then use Velo to save the data to a collection.
Let's present each approach so you can decide which to use.
Wix Forms APIs
Wix Forms is an app solution that provides you with a built-in suite of form functionalities, such as an out-of-the-box submission button, database collection creation, and auto-generated emails after submission.
First use the Wix Forms app to set up your forms quickly and efficiently, taking advantage of Wix Forms features. You even get a starter collection for your form that you can use to store the form data.
Then use the WixForms Velo APIs to customize the visitor experience even more. For example, you can display a personalized thank you message when a visitor submits the form.
Check out the benefits of the Wix Forms app!
- Choose from a variety of designs for your form from a set of templates.
- You can design and customize the layout of the form in the Editor.
- Each form design comes with its own collection for storing form data. You don't have to create your own from scratch.
- Each field on your form is automatically connected to the collection. You don't have to connect fields one by one.
- The Wix Forms app sets up email notifications so you don't have to. The information is saved for your contacts, and goes through the Inbox (Wix CRM).
- The Wix Forms app makes it easy to set up payment forms, multi-step forms, and subscription forms.
Using Wix Forms Starter Collections
When you add the Wix Forms app to your site, you pick the type of form you want. Depending on the form you pick, you get a collection specifically built for that form. In addition to the form appearing in the Form Submissions tab in the Dashboard's Customer Management area, you can also see the collection in the Database section of the Velo Sidebar.
We call these collections starter collections because that's exactly what they are for, to help you get started. You can use the collection "as is" or you can change the collection to meet your needs. For example, when we add a Donations form to our site, we get a starter collection called Donors with basic fields. Here we customized the collection by adding a Signature field.
The fields on the Donations form are connected to the fields in the Donors collection. This means that each time a visitor submits a form, the form field data is stored in the corresponding field in the collection.
The opposite is not true. Adding a field to a starter collection does not add a corresponding field to the form.
Using the WixForms API
- Add and set up a Wix Form on your site in the Wix Editor.
- Enable Dev Mode.
You will see a WixForms wixForms1 element and its corresponding form element form1 on your page.
The Form element is a container for the input elements and buttons in the Wix Form. If you hide or collapse either the WixForms or Form element, the other element is also hidden/collapsed.
Note that we apply the WixForms functions and events to the WixForms element, not the Form element.
- Client-side event handlers:
Write the code for the client-side event handlers onWixFormSubmitted( ) and onWixFormSubmittedError( ) to handle what happens when a visitor submits the form.
onWixFormSubmitted() provides information, such as field names and field values, that is available only on the client side. You can code operations to run on the client side, such as displaying a message after form submission. This event fires when the server indicates that the submission was received, even if the server is still asynchronously processing.
Here is sample code for displaying a personalized message on the page thanking the visitor for a donation.
$w("#wixForms1").onWixFormSubmitted( {fields} => {
let firstName = fields[0].fieldValue;
let lastName = fields[1].fieldValue;
let donation = fields[2].fieldValue;
let email = fields[3].fieldValue;
$w('#text1').text = `Thank you, ${firstName} ${lastName}, for your generous donation of ${donation}.`;
});
/* fields array of objects:
* [
* {
* "id":"inputFirstName",
* "fieldValue":"Maria",
* "fieldName":"Enter first name"
* }
* {
* "id":"inputLastName",
* "fieldValue":"Santora",
* "fieldName":"Enter last name"
* },
* {
* "id":"inputDonation",
* "fieldValue":"1000",
* "fieldName":"Enter donation amount"
* },
* {
* "id":"inputEmail",
* "fieldValue":"ms@theCompany",
"fieldName":"Enter email"
* }
* ]
*/
- Backend Event Handler:
Write the code for the backend onFormSubmit() event handler function to perform operations on the server side when the visitor submits a form. `onFormSubmit()` provides additional information that the page does not have, such as the form's submission time and the contact ID. Keep in mind that the functions on the server run asynchronously and do not hold up onWixFormSubmitted( ) operations.
Custom Forms
To provide your site visitors with a fully customized form experience that you totally control, you can create custom forms manually. Add user input elements and buttons to the page, and code their usage to act like a form.
Using Velo APIs to create your own custom forms may take a bit more time and coding than using the Wix Forms app, but customizing your own forms can offer some advantages, such as enabling additional field types and using advanced functionality with code, without adding Ascend to your site.
Using APIs for Custom Forms
- Use standard $w input elements and buttons to create your form. The user input elements on your form can use functionality provided by FormElement.
- Write code for the event handlers to customize your visitors' experience.
Here are some examples and tutorial articles to help you get started.
Tutorial Articles
Examples
Previously published at https://support.wix.com/en/article/velo-working-with-forms
