Form Event Handlers

(Pro Plan Only) Event handlers are custom scripts that run in response to specific events in your forms, such as input changes or form submissions. They allow you to enhance form functionality, apply custom validation rules, and perform advanced operations based on user interactions. This feature is ideal for users who want more control over their forms, enabling a more tailored and dynamic experience.

To access the event handlers in your form:

1. Navigate to the "Code" Section:
   • From the form builder, look for the "Code" option on the left side of the screen.
   • Click on "Code" to open the Form Events page.
2. Adding an Event Handler:
   • On the Form Events page, you'll find an option to add an event handler. Click on the Add Event Handler button to expand a menu showing all available events.

Adding and editing event handlers:

Once you've selected the event you want to handle from the dropdown menu:

1. Click on the Event:
   • Selecting an event will open a code editor section where you can write your custom JavaScript code.
2. Write Your Code:
   • In the code editor, enter the script that should run when the selected event is triggered. This is where you can apply your custom logic, whether it's for validation, data transformation, or other purposes.
3. Save Your Changes:
   • After you've finished writing your event handler, click the Save button located at the bottom of the page to apply your changes.

Available Events

The following events are available:

onFormLoaded : Runs once after the first page of the form is loaded

onInput : Runs after the value of an input changes

onPageSubmitted : Runs after the user has submitted a form page, but before the request is sent to the backend

onValidationFailed : Runs after the user has submitted a form page and the request has returned with validation errors

onPageChanged : Runs after the user is redirected to the next page after submitting or after the user has manually changed the page using the navigation buttons in the footer

onFormCompleted : Runs after the submission has been saved in the database and just before the outcome is displayed

Each event receives a context object as an argument. The contents of context depends on the event.

Some events allow you to do custom validation or format the value

onInput

In onInput you can add custom validation logic. To return a validation error you can do the following:

function isValidEmail(answer) {
    return answer.includes('@mycompany.com');
}

function onInput(context) {
    if (context.block.id === 'c8e18fe9-cf24-49b8-a5ad-b0051e167788' && !isValidEmail(context.answer)) {
        return {
            type: 'error',
            error: 'Please try another email address.',
        }; 
    }
}

You can also format the value:

function onInput(context) {
    if (context.block.id === 'c8e18fe9-cf24-49b8-a5ad-b0051e167788') {
        return {
            type: 'success',
            answer: context.answer.trim(),
        }; 
    }
}

onPageSubmitted

In onPageSubmitted you can also add custom validation logic:

function isValidEmail(answer) {
    return answer.includes('@mycompany.com');
}

function onPageSubmitted(context) {
    if (!isValidEmail(context.answers['c8e18fe9-cf24-49b8-a5ad-b0051e167788'])) {
        return {
            type: 'error',
            errors: {
                'c8e18fe9-cf24-49b8-a5ad-b0051e167788': 'Please try another email address.'
            },
        }
    }
}

You can also format values:

function onPageSubmitted(context) {
    return {
        type: 'success',
        values: {
            ...context.answers,
            'c8e18fe9-cf24-49b8-a5ad-b0051e167788': context.answers['c8e18fe9-cf24-49b8-a5ad-b0051e167788'].trim(),
        },
    }
}

What's the difference between 'Event handlers' and 'Embedded form events'?

Event handlers are configured in the form builder and the code is executed inside the context of the form page.

Embedded form events are configured in the embed snippet and the code is executed inside the context of your own website.

If you're experiencing issues or have questions, please contact us at [email protected]. We're here to assist you!