Tutorial: Form Submission Custom Extension

This feature is only available for Wix Studio sites.

Wix Custom Extensions allow you to implement custom logic to change how your site behaves and displays using Velo SPIs. For example, when you set up a form from the Wix Form app, there are a small number of validations to choose from. The form submission custom extension allows you to implement your own submission validations and options using code. You can also connect your site to form validation providers not currently supported by Wix. Any violations to these validations can be displayed on the form.

Custom extensions are implemented using Velo SPIs. You can manage extended services from your site's dashboard, and they behave just like the ones Wix already supports. Learn more about using Custom App Extensions Using SPIs.

With the Form Submission SPI you can define the submission validations for a form that fit your site's needs. Possible validations include:

  • Field validations: Check if the name contains only alphabetic characters.
  • Prevent duplicate submissions: Check for duplicate submissions based on certain criteria and prevent site visitors from submitting the same form multiple times.
  • Verify fields: Call a local post API call to check if the entered postal code is local.

About this tutorial

This tutorial explains how to set up and implement a form submission extension on your site using Velo. We demonstrate how to validate your form submission by checking whether a site visitor entered a name correctly in alphabetical characters only.

The process has 3 steps:

  1. Create a new form submission validation extension on our site.
  2. Implement our extension with custom code.
  3. Deploy the extension.

Step 1: Create a new form submission extension

The first step in setting up your new extension is to add it to your site. This process creates a new folder in the Custom Extensions section of the Velo sidebar, which contains the files for your code.

  1. Add the Wix Forms app to your site.
  2. Enable coding. If necessary, click and then Start Coding.
  3. Go to the Custom Extensions section by clicking Public & Backend.
  4. Hover over Custom Extensions and click . Then click Add Form Submission SPI.
  5. Follow the prompts to add the extension and accept any terms and conditions that display.
  6. Enter a name for your integration and click Add & Edit Code. The name can't contain spaces or special characters.
  7. Publish your site.

Step 2: Implement the extension

The procedure in the previous step creates a folder in the Custom Extensions section of the Velo sidebar. The name of the folder is based on the extension you chose. Inside this is another folder with the name of the extension you set up. This folder contains 2 files, your-extension-config.js and your-extension.js. In our case the files are named submission-config.js and submission.js. We implement the custom code for our extension in these files.

submission-config.js

This file is where we write the code for setting up the extension's configuration.

The code in this file defines a function named getConfig() that returns an object containing the values used to display the form submission validations on your site.

There are several apps that use forms. To validate form submission for a specific Wix app, we need to configure the file by defining the relevant namespace field in the extension. In our example, we want to validate a form in the Wix Forms app, so we set the namespace value as wix.form_app.form in the custom extension's configuration file and enable the validation.

Copy
1
import * as formsSubmissionsExtensionProvider from 'interfaces-forms-v4-submission-extension';
2


3
export function getConfig() {
4
  return {
5
    namespaceConfigs: [
6
      {
7
        namespace: "wix.form_app.form",
8
        submissionValidationEnabled: true
9
      }
10
    ]
11
  };
12
};

submission.js

This file is where we write the code for validating the first name form field. A site visitor tries to enter a first name with a non-alphabetical character. If there are any violations to the submission validation, a warning message can appear on the form as a text box.

The code in this file defines a function named validateSubmission(). This function is called by Wix Forms to retrieve any violations to the validations provided by our extension. The function accepts the following parameter:

options: An object containing data about the source of the request, and the form submission information to validate. This information must include form ID. For more details, see the SPI Reference.

The validateSubmission() function returns an array of validation objects (any validation violations in a site visitor's form). These validation violations can be displayed in the site visitor's form as text boxes with warnings. If there are no validation violations, the response is an object containing an empty list.

The code:

Copy
1
import * as formsSubmissionsExtensionProvider from 'interfaces-forms-v4-submission-extension';
2


3
const options = {
4
    "submission": {
5
        "formId": "e9e8c6ff-a771-401b-b46e-82f7c742ef3d";
6
    };
7
};
8


9
export const validateSubmission = async (options, context) => {
10
    const firstNameValidation = options.submission.submissions["first_name_abae"];
11
    const alphabeticalPattern = new RegExp("^[a-zA-Z]+$");
12
    if (!firstNameValidation.match(alphabeticalPattern)) {
13
        return {
14
            errors: [{
15
                errorPath: "first_name",
16
                customErrorMessage: "First name can only contain alphabetical characters!"
17
            }]
18
        };
19
    } else {
20
        return {}
21
    };
22
};

Line 1: First we import the Wix Forms submission provider module.
Line 3-7: We need to define the form ID so that the code would know which form to validate. To get the form ID, call querySubmissionsByNamespace(). We don't need to define the form field values separately in the submissions object, as the values will be taken directly from the published site form.
Line 9: Then we export the validateSubmission() function where we set the custom logic for our validations.
Lines 10: We save the first name field value into the firstNameValidation variable.
Line 11: Define the Regex pattern so that the field only accepts alphabetical characters.
Line 12: Here we check if a first name field value matches the Regex pattern.
Lines 13-20: Set the violation description that can be displayed when there is a violation to the set pattern. If the form field value doesn't match the pattern, you get an error, and also form submission is aborted.

Optional: Add files to an extension

If you don't want to keep all of your code in the main files, you can add files to the extension's folder and import functions and objects into the main files. To do this, create a new file in the extension's folder. To import from these files to the main files, use the following syntax:

Copy
1
import { functionName } from './myFileName.js';

Optional: Test an extension

You can test your extension before publishing your site using functional testing like you would with any backend Velo code. Make sure your validateSubmission() function's return values are properly formatted.

You can test your extension after deploying. To do this, add console logs to your code. The results appear in the Site Events log.

Step 3: Deploy the extension

Once your code files are ready, publish your site. Navigate to your site, and fill in a form. Any violations to the validations you've customized are displayed on the form.

  1. Once your code files are ready, click Save, and then Publish your site.
  2. After your custom extensions are published, open your site.
  3. Your custom extension is then deployed, and any validation violations should appear on your form.

If a site visitor tries to enter a first name with non-alphabetical characters, there will be an error message that could be shown on the site.

The validation violation response looks like this:

Copy
1
{
2
  "errors": [
3
    {
4
      "errorPath": "first_name_abae",
5
      "customErrorMessage": "First name can only contain alphabetical characters!"
6
    }
7
  ]
8
}

Remove an extension

You can remove the extension from your site. Do the following:

  1. In the Public & Backend section of the Velo sidebar, under Custom Extensions, hover over the extension's folder and click Show More .
  2. Click Delete.
  3. Delete the extension in the prompt.
Was this helpful?
Yes
No