Writing Custom Code in Embeddables

How to get the most out of custom code blocks in Embeddables

Custom Code blocks in Embeddables are where you can escape the confines of no-code and create entirely custom functionality.

Custom Code exists in two main places: Computed Fields and Actions.

Example Computed Field

function result(userData, helperFunctions, triggerContext) {
  ...
}

Available arguments in Custom Code functions

Custom Code blocks provide various bits of context through arguments in the root functions. They are, in order:

#	Argument	Description
1	userData	The current User Data
2	helperFunctions	An object containing various helper functions (see full list below)
3	triggerContext	An object containing data on what triggered the Computed Field or Action (see full list below)

Helper Functions

The following helper functions are available in both Computed Fields and Actions through the helperFunctions argument:

Page Navigation Functions

goToNextPage()

Navigates to the next page in the flow.

This is useful when you want to navigate to the next page in the flow, but don’t want to use the default navigation logic.

// Example usage
await helperFunctions.goToNextPage();

goToPrevPage()

Navigates to the previous page in the flow.

This is useful when you want to navigate to the previous page in the flow, but don’t want to use the default navigation logic.

// Example usage
await helperFunctions.goToPrevPage();

goToPage(pageKeyOrIdOrIndex: string | number)

Navigates to a page with the specified key, ID, or index - you can choose which type of identifier to pass in.

// Example usage
await helperFunctions.goToPage('page_key_1234567890');  

Data Management Functions

getUserData()

Returns the current User Data from the flow controller.

This is useful when you need to read the current state of User Data, as opposed to the initial userData value that was passed in as the first argument.

// Example usage
const currentData = helperFunctions.getUserData();

setUserData(key: string, value: any)

Updates a specific key/value pair in the User Data.

// Example usage
helperFunctions.setUserData('userName', 'John');

setUserData(updates: Record<string, unknown>)

Updates multiple fields in the User Data at once.

Accepts an object containing key/value pairs to update - i.e. to merge into the existing User Data.

Note that nested objects will be replaced entirely, not merged.

// Example usage
helperFunctions.setUserData({
  userName: 'John',
  age: 30,
  preferences: { theme: 'dark' }
});

resetUserData()

Resets all User Data to its initial state, effectively starting fresh.

Use with caution as this will clear all previously stored User Data.

// Example usage
helperFunctions.resetUserData();

Component and UI Functions

getComponentElement(key: string)

Returns the DOM element for a component with the specified key.

Useful for direct DOM manipulation, accessing element properties (such as value for a password input field), or setting up custom event listeners.

// Example usage
const element = helperFunctions.getComponentElement('submit_button');
element.disabled = true;

openInfoBox(infoBoxPageKey: string)

Opens an info box with the specified page key.

The page key must refer to a page which is designed to be shown within an info box.

Returns a Promise that resolves when the info box is opened.

// Example usage
await helperFunctions.openInfoBox('infobox_faqs_popup_page');

closeInfoBox()

Closes the currently open info box. Returns a Promise that resolves when the info box is closed.

// Example usage
await helperFunctions.closeInfoBox();

Action and Flow Control

triggerAction(actionId: string)

Programmatically triggers an action by its ID.

Returns a Promise that resolves when the action is complete.

Useful for chaining actions or conditional action execution.

// Example usage
await helperFunctions.triggerAction('action_aaaaaaaaaaaa');

triggerValidation()

Triggers form validation on the flow controller.

Useful when you need to validate form inputs programmatically.

// Example usage
helperFunctions.triggerValidation();

Analytics and Events

trackCustomEvent(customEventName: string, customEventProps: any)

Tracks a custom analytics event with the given name and properties.

// Example usage
helperFunctions.trackCustomEvent('button_clicked', {
  buttonId: 'submit',
  timestamp: Date.now()
});

Additional Helpers

helpers

An object containing various utility helper functions. The exact available helpers depend on the context and implementation.

// Example usage
const { formatDate, validateEmail } = helperFunctions.helpers;

Trigger Context variables

Trigger Context for Computed Fields

type TriggerContext = {
  inputs_causing_recompute: string[]; // List of keys of inputs that caused the recompute
  old_input_values: string[]; // List of old values of those inputs (last time this Computed Field was computed)
  new_input_values: string[]; // List of current values of those inputs
  old_user_data: Record<string, unknown>; // Snapshot of User Data from when this Computed Field was last computed
  new_user_data: Record<string, unknown>; // Current value of User Data (identical to the first userData argument)
};

Please note that old_user_data and new_user_data currently only contain the input keys for the Computed Field, not all of User Data. This may change in the future.