Migrating from versions 3.0 to 4.0

Customer and Forms API

In CF Embed version 3, whenever a user would change the value of a field, it immediately reflected on the CF.customer object. For instance, if you typed in “John” for the first name field then ran CF.customer.get('first_name'), you would get “John”. As of CF 4, this is no longer the case, instead this change reflects after the form has been successfully submitted.

We did this to avoid unintentional side-effects that can occur when CF.customer changes, and further encapsulate the behavior of our forms which in turn improves performance.

Event: cf:customer_changed

If you were relying on the cf:customer_changed event to detect changes made in a form in realtime, you need to change the event to cf:field_changed. Here’s an example:

Before:

document.addEventListener('cf:customer_changed', function(event) {
  var changed = event.detail.changed;

  if (changed.some_data_column_key) {
    // do something with changed.some_data_column_key
  }
});

After:

document.addEventListener('cf:field_changed', function(event) {
  var formId = event.detail.formId;
  var columnKey = event.detail.columnKey;
  var value = event.detail.value;

  // in a form with an id of <formId>, a field with a column key of <columnKey> changed and is now <value>.

  if (columnKey == 'some_data_column_key') {
    // do something with value
  }
});

Using CF.customer.set to mutate form data

Before:

CF.customerReady(function() {
  // Change the value of any first name field in any form to 'Tom'
  CF.customer.set('first_name', 'Tom');
})

After:

CF.ready(function() {
  var $form = document.querySelector('[data-cf-form="adJX0r"]');

  // Change the value of any first name field in this form to 'Tom'
  $form.cfForm.setFieldValue('first_name', 'Tom');
});

Using CF.customer.get to query form data

Changes made to the form will not update CF.customer in real-time. As of version 4.0.0, CF.customer.get will only return guest data, data that has been saved, or data explicitly set via CF.customer.set.

If you wish to query the form for changes made in real-time, use cfForm.getFieldValue instead of CF.customer.get:

Before:

CF.customerReady(function() {
  // Get the value of the customer's first_name
  CF.customer.get('first_name');
})

After:

CF.ready(function() {
  var $form = document.querySelector('[data-cf-form="adJX0r"]');

  // Get the field of this form's first_name field
  $form.cfForm.getFieldValue('first_name');
});