JavaScript Events
Throughout the lifecycle of our scripts on the storefront, we emit a variety events that you might find useful.
Form events
You can attach event listeners to the document
, or a <form>
element (unless noted otherwise.) Adding event listeners to the <form>
element can be helpful when you have multiple forms on the same page.
Targeting a form
For example, say we have a form with an ID of ak23jN
, we can find the form element on the page and attach event listeners to it:
var formId = 'ak23jN';
var $form = document.querySelector('form[data-cf-form="' + formId + '"]');
$form.addEventListener('cf:field_changed', function(event) {
// ...
});
$form.addEventListener('cf:step_changed', function(event) {
// ...
});
Note
Later examples will reference the
$form
variable described above, when applicable.
cf:ready
Any CF form(s) have been rendered. Attempts to access a <form>
element’s cfForm
property will result in an error until this event is emitted.
Usage:
var $form = document.querySelector('form[data-cf-form="ak23jN"]');
$form.cfForm.setFieldValue('favorite_color', 'Magenta');
// -> Error: Cannot read property 'setFieldValue' of undefined
document.addEventListener('cf:ready', function() {
// Forms are mounted on the page!
$form.cfForm.setFieldValue('favorite_color', 'Magenta'); // Works!
});
// Alternatively, we provide a short-hand function for this:
CF.ready(function() {
// Forms are mounted on the page!
$form.cfForm.setFieldValue('favorite_color', 'Magenta'); // Works!
});
Note
Listeners for this event cannot be attached to a
<form>
element.
cf:field_changed
A field inside a CF form has been changed by user input, or by calling cfForm.setFieldValue
.
Example usage:
$form.addEventListener('cf:field_changed', function(event) {
var fieldId = event.detail.fieldId;
var columnKey = event.detail.columnKey;
var value = event.detail.value;
console.log(formId, columnKey, value, event.target);
// -> 897424, "favorite_color", "Blue", <div class="cf-field" data-cf-field-id="897424">
});
Note
Be cautious when storing a reference to a
.cf-field
element, as it may get removed when the step changes, due to the nature of React.
cf:field_validated
A field’s validations have been processed. Any errors won’t display until the user has defocused the field for the first time.
Example usage:
$form.addEventListener('cf:field_validated', function(event) {
var fieldId = event.detail.fieldId;
var columnKey = event.detail.columnKey;
var errors = event.detail.errors;
console.log(formId, columnKey, errors, event.target);
// -> 123456, "email", ["Please enter a valid email address"], <div class="cf-field" data-cf-field-id="123456">
});
The errors
array contains error messages from validations configured in the app.
cf:rule_actions_determined
A field has changed, causing the form to handle any actions generated by rules with passing conditions.
Example usage:
$form.addEventListener('cf:rule_actions_determined', function(event) {
var formId = event.detail.formId;
var actions = event.detail.actions;
console.log(formId, actions, event.target);
/*
"n89j3k",
[
{
effect: 'hide_field',
metadata: {
fieldId: 123456,
},
},
{
effect: 'set_column_value',
metadata: {
columnKey: 'favorite_color',
columnType: 'text',
value: 'Blue'
}
}
],
<form data-cf-form="n89j3k">
*/
});
cf:step_changed
Step navigation has been caused by user input, or by calling cfForm.goToStep
, cfForm.goToNextStep
, or cfForm.goToPreviousStep
.
Example usage:
$form.addEventListener('cf:step_changed', function(event) {
var formId = event.detail.formId;
var fromIndex = event.detail.fromIndex;
var toIndex = event.detail.toIndex;
console.log(formId, fromIndex, toIndex, event.target);
// -> "a39Jk2", 0, 1, <form data-cf-form="n89j3k">
});
Step indexes begin at zero. For example, if the user navigates from step 1 to step 2, fromIndex
will be 0
and toIndex
will be 1
.
cf:form_submitted
A form has been submitted successfully.
Example usage:
$form.addEventListener('cf:form_submitted', function(event) {
var formId = event.detail.formId;
var submissionData = event.detail.submissionData;
console.log(formId, submissionData, event.target);
// -> "a39Jk2", { first_name: 'John', last_name: 'Smith', ... }, <form data-cf-form="n89j3k">
});
cf:form_submission_failed
Our servers returned error(s) upon a form’s submission.
Example usage:
$form.addEventListener('cf:form_submission_failed', function(event) {
var formId = event.detail.formId;
var errors = event.detail.errors;
console.log(formId, errors, event.target);
/* ->
"a39Jk2",
{
email: ['is invalid']
},
<form data-cf-form="n89j3k">
*/
});
Read more about the errors
object on our page about handling server errors. The errorObj
described there is the same as the errors
variable above.
Customer events
Various interactions with CF.customer
can cause the following events to be emitted.
cf:customer_ready
CF.customer
is ready for use. Attempts to use CF.customer
will result in thrown errors until this event is emitted.
Example usage:
CF.customer.set('favorite_color', 'Blue');
// -> Error: cannot read property 'set' of undefined
document.addEventListener('cf:customer_ready', function() {
CF.customer.set('favorite_color', 'Blue'); // OK!
});
// Or, use this short-hand function that is always available:
CF.customerReady(function() {
CF.customer.set('favorite_color', 'Blue'); // OK!
});
cf:customer_changed
The data inside CF.customer
has been changed by calling CF.customer.set
.
Example usage:
document.addEventListener('cf:customer_changed', function(event) {
var changed = event.detail.changed;
console.log(changed, changed.favorite_color);
// -> { favorite_color: "Blue" }, "Blue"
});
cf:customer_tags_changed
The customer’s tags have been changed (not yet saved,) by calling CF.customer.addTag
or CF.customer.removeTag
.
Example usage:
document.addEventListener('cf:customer_tags_changed', function(event) {
var tags = event.detail.tags;
console.log(tags);
// -> ["new", "and", "existing", "tags"]
});
Note
This event will be emitted by a form if a rule has added or removed a tag.
cf:customer_saved
CF.customer.save
has been called, and the data has been successfully saved.
Example usage:
document.addEventListener('cf:customer_saved', function(event) {
// Show success modal, etc.
});
Note
This event will be emitted by a form when it has been submitted without guest submission behavior.
cf:guest_data_saved
CF.customer.saveAsGuest
has been called and the data has been successfully stored in the browser’s localStorage
.
Example usage:
document.addEventListener('cf:guest_data_saved', function(event) {
// Show success modal, etc.
});
cf:customer_save_failed
CF.customer.save
has been called, and our servers have returned errors. Learn more about how to handle errors from our servers.
Example usage:
document.addEventListener('cf:customer_save_failed', function(event) {
var errors = event.detail.errors;
console.log(errors);
// -> { email: ['is invalid'], ... }
// Inform the user on how to fix the errors, etc.
});