Tutorial: Form Submission Service Plugin

Wix Service Plugins (formerly SPIs and 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 service plugin 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.

You can manage service plugins from your site's dashboard, and they behave just like the ones Wix already supports. Learn more about using service plugins.

With the Form Submission service plugin 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 plugin 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 plugin on our site.
  2. Implement our plugin with custom code.
  3. Deploy the plugin.

Step 1: Create a new form submission plugin

The first step in setting up your new plugin is to add it to your site. This process creates a new folder in the Service Plugins 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 Service Plugins section by clicking Public & Backend.
  4. Hover over Service Plugins and click . Then click Form Submission.
  5. Follow the prompts to add the plugin 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 plugin

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

submission-config.js

This file is where we write the code for setting up the plugin'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 plugin. 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 service plugin's configuration file and enable the validation.

Copy

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 plugin. 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 Service Plugin 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

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 the plugin

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

Copy

Optional: Test the plugin

You can test your plugin 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 plugin after deploying. To do this, add console logs to your code. The results appear in the Site Events log.

Step 3: Deploy the plugin

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 service plugins are published, open your site.
  3. Your service plugin 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

Remove the plugin

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

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