Using the JavaScript Events API

Published in Convert Forms
Updated 30 Oct, 2019

The Convert Forms JavaScript Events API is extremely powerful, providing a set of events on which you can bind your custom Javascript functionality to further extend Convert Forms to suit your specific needs.

Events API for v2.4.0+

BeforeSubmit

Fires before the form submission starts. This is rather useful when you need to do some extra validations, change field values and prevent the form submission.

var form = document.querySelector("#cf_1");
form.addEventListener("beforeSubmit", function(event) {
	// your code
});

Validate and limit characters allowed in a field

This example displays an error message when the field message exceeds the characters limit.

var form = document.querySelector("#cf_1");
form.addEventListener("beforeSubmit", function(event) {
	var input = form.querySelector('input[name="cf[name]"]');

	if (input.value.length > 10) {
		event.preventDefault();
		event.detail.error = "Maximum character limit reached.";
	}
});

AfterSubmit

Fires after the form submission request is completed regardless if the submission was successfull or not.

var form = document.querySelector("#cf_1");
form.addEventListener("afterSubmit", function(event) {
	// your code
});

AfterTask

Fires after the form is successfully submitted and the form task is finished. Eg: Display the thank you message.

var form = document.querySelector("#cf_1");
form.addEventListener("afterTask", function(event) {
    var response = event.detail.response // The response in JSON format
    var task = event.detail.task // The task name executed 

	// your code
});

Success

Fires after the form is successfuly submitted. This is rather useful when you want to modify the success message displayed in the form.

var form = document.querySelector("#cf_1");
form.addEventListener("success", function(event) {
	// your code
});

Modify the default success message

The example below modifies the success message.

var form = document.querySelector("#cf_1");
form.addEventListener("success", function(event) {
	event.detail.response.value = "The form has been successfully submitted!";
});

Error

Fires when an error occurs during form submission. This is rather useful when you want to modify the error message displayed in the form.

var form = document.querySelector("#cf_1");
form.addEventListener("error", function(event) {
	// your code
});

Modify the error message

The example below modifies the error message.

var form = document.querySelector("#cf_1");
form.addEventListener("error", function(event) {
	event.detail.response.error = "The form can't be submitted right now.";
});

Impression

Fires after the form is seen by the user.

var form = document.querySelector("#cf_1");
form.addEventListener("afterSubmit", function(event) {
	var entry = event.entry // The IntersectionObserverEntry
	// your code
});

Events API for v2.4.0 and below

Success

This event fires once the form has received a successful response after submission.

$("#cf_1").on("success", function(event, response) {
	// your code
});

Fail

This event fires once the form has received an unsuccessful response after submission.

$("#cf_1").on("fail", function(event, response) {
	// your code
});

BeforeSubmit

This event fires at the exact instant before the form starts the submission process.

$("#cf_1").on("beforeSubmit", function(event) {
	// your code
});

AfterSubmit

This event fires at the exact instant after the form has completed the submission process.

$("#cf_1").on("afterSubmit", function(event) {
	// your code
});

Notes

Document ready combined with self enclosure

Please note that any of the above examples will not work unless you wrap it with the Combined Document Ready - Self Enclosure snippet.

jQuery(function($) {
	// your code goes here
});

Your custom JavaScript code also needs to be enclosed within the script tags.

<script type="text/javascript">
	// your code goes here
</script>

Use the correct ConvertForm ID

The above code blocks refair to the ConvertForm with id #1 for demonstration purposes. Replace this number with your ConvertForm's id.