Legacy: Advanced Use of Marketo Forms Code

Last Updated: December 2, 2022

🔍 Please note: This article is for customers on Standard Bundle, Enrichment, or Clearbit Platform plans.

📝  Please note: It's rarely necessary to supplement Clearbit's Marketo forms enrichment functionality. Where necessary, your engineering team can reference this documentation for further custom form logic. Clearbit cannot own or troubleshoot any supplementary code that is created to handle these events.

As part of our Marketo integration, Clearbit will emit events that developers can tie into, providing a finer level of form control around form submissions based on email addresses or enrichment information. When a website visitor enters an email address onto a Marketo form, Clearbit also hooks into the form submittable state — this is agnostic of any prior form state and is done to help prevent form submission mid-enrichment.

Form Submittable State

When a user begins typing an email address into the email address input, our Marketo Forms JS sets the form submittable state so that the form cannot be submitted (e.g. form.submittable(false)).

The form is then toggled back to a submittable state under one of two scenarios:

• User finishes typing an email address into the input, and enrichment data with a 200 status (or a lack of enrichment data with a 404 status) is returned from the Clearbit API.
• An error occurs within the Marketo JS script and is caught by our error handler.

After either scenario occurs, the form will be toggled back to a submittable state via form.submittable(true), and not prior state. Our Marketo JS file emits additional events that users can tie into, to handle data and re-calibrate state post enrichment.

Clearbit Enrichment Events

After a user has entered an email address into the email input and our code has received a response from the Clearbit API, there are two events that will be emitted by our Marketo JS:

• clearbit-forms-marketo-enrichment-complete denoting an API response for enrichment came back from our servers, and that user may or may not have data (i.e. Clearbit status 200 or 404).
• clearbit-forms-marketo-enrichment-error denoting an error came up from the API request.

The enrichment-complete event only denotes that an API response successfully came back from Clearbit's API. To further distinguish actions based on the enrichment API data, or whether any enrichment information was found altogether, you'll need to further reference the form's text or hidden inputs.

When either of the above events occur, our Marketo JS code will then set the form submittable state to true, enabling users to submit your form by default. Should your form already rely on custom logic that toggles form submission, you'll want to disable form submission post-enrichment.

Example Event Handling

Here's some starter code your team can reference, showing how you could set up an event to toggle form submittable state post-enrichment. This is NOT meant to be a fully comprehensive example and is something your engineering team will need to build out based on your form's needs.

In this example we reference the form and assign it to the form variable, while also defaulting to and disabling form submission post-enrichment, so that existing custom Marketo logic can handle and toggle the form submittable state elsewhere.

<script> 
  document.addEventListener("clearbit-forms-marketo-enrichment-complete", 
    function (e) { 
      // form variable refers to the MktoForms2 instance
      const { form } = e.detail; 

      /* 
         in this example, once enrichment occurs, disable the form 
         from being submittable and allow the submittable state to happen in 
         another event based on Marketo form logic 
      */ 
      form.submittable(false);
  })

  document.addEventListener("clearbit-forms-marketo-enrichment-error",
    function (e) { 
      // form variable refers to the MktoForms2 instance
      const { form } = e.detail;

      // resolve enrichment errors within this function 
  })
</script>