Link Search Menu Expand Document

Form API

Even though our app already offers powerful features for building valuable form experiences, we understand that we can’t cover every use-case. Because of that, we offer a set of tools to augment our forms with custom JavaScript.

Usage

We expose functions on the <form> element that our script injects a form into. This property is called cfForm. Here’s how you can easily find it:

// Wait until the form is done initializing
CF.ready(function() {
  // Find the first CF form on the page.
  var $myForm = document.querySelector('form[data-cf-form]');
  var cfForm = $myForm.cfForm;
});

For most use cases that will suffice, but if you have multiple forms on one page you will need to target the form by its form ID:

CF.ready(function() {
  // Find a CF form on the page with an ID of a34Kl0
  var $myForm = document.querySelector('form[data-cf-form="a34Kl0"]');
  var cfForm = $myForm.cfForm;
});

The cfForm object

In the cfForm object, you will find the following properties:

  • addValidator(customValidation)

    Add your own custom validations to a form. You can even add validations that hook into a third party service! Read more here.

  • goToStep(index: number, validate?: boolean)

    Navigate to a specific step in the form by its index. If validate is true, navigation will not occur unless the current step is valid.

  • goToNextStep(validate?: boolean)

    Go to the next step in the form. If validate is true, navigation will not occur unless the current step is valid.

  • goToPreviousStep(validate?: boolean)

    Go to the previous step in the form. If validate is true, navigation will not occur unless the current step is valid.

  • setFieldValue(columnKey: string, value: any)

    Sets the value of fields with the corresponding columnKey to the provided value.

  • getFieldValue(columnKey: string)

    Returns the value of any field with the provided columnKey.

  • beforeSave(callback: () => Promise<void> | void)

    Adds callback to the list of functions that get called when the form is submitted and validated, but just before the record is saved. If your callback returns a Promise, the form will await it before submitting.

If you have a use-case that our JS Form API doesn’t support, please get in touch so we can get a conversation started! Providing tools for developers to extend our forms is very important to us.


Next up: Custom validations


Table of contents


Have any questions or comments about this post? Let us know! Your feedback is greatly appreciated.

Customer Fields is a Shopify app made by Helium.

Copyright © Helium Development, LLC