Custom Data and Context

Custom actions give you a powerful tool for creating dynamic and interactive experiences in Builder. You can add new functionality to your UI, reuse code across multiple components, and create a more engaging and user-friendly experience for your users.

Tip: The techniques covered in this document are for the Gen 1 React SDK. For detailed information on the Gen 2 SDKs, visit SDK Comparison.

Passing data down with `BuilderComponent`

To pass data down, you can use the data prop in the BuilderComponent and assign it an object with key-value pairs. For example, you can pass a list of products and additional data, such as an isLoggedIn boolean:

<BuilderComponent
  model="page"
  data={{
    products: productsList,
    isLoggedIn: true,
  }}
  content={builderJson}
/>

The data passed down is available in Builder actions and bindings using the prefix state.*. For example, state.products refers to the productsList passed down in the example above.

You can also pass down functions and complex data using the context prop. For example:

<BuilderComponent
  model="page"
  context={{
    addToCart: () => myService.addToCart(currentProduct),
    lodash: lodash,
  }}
  content={builderJson}
/>

Here, the context object is assigned two key-value pairs:

a function addToCart()
the library lodash

The context passed down is available in Builder using the prefix context.*. For example, context.lodash refers to the lodash library passed down in the example above.

Example: setting up a custom action on a button

You can add an action to any element, though button actions are frequently customized, which this section covers.

In your code: passing down a function

The following example demonstrates a context object that defines a single function called myFunction(), which displays an alert with "Hi!" when called.

export default () => (
  <BuilderComponent 
    name="page" 
    context={{ 
      myFunction: () => alert('Hi!') 
    }} 
  />
)

By passing down functions using the context prop, you can create flexible and dynamic UI components in the Builder Visual Editor that respond to user input and other events.

In Builder: adding an on click event

To assign the function to run on click of a button:

Select the button.
Go to the Data tab.
Expand the Element events section. For this example, leave the default of On to click.
Click the + New Event button.
Click Edit Action > + Action > Custom Code.
Add your custom Javascript. In this example, add context.myFunction().

The following video demonstrates this process:

After you've set up a custom action on an element, such as a button, you can save the element as a Template or Symbol for reusability.

Data binding in rich text fields

In addition to custom actions and passing data down with BuilderComponent, Builder supports data binding directly within rich text fields. This feature means you can dynamically insert content into any text or link value using state variables.

When using data binding in rich text fields, for example, state.someValue, you must set up your Node server correctly so that this functionality works in production environments.

For more information on proper setup, including the use of the isolated-vm package, read the Enabling data bindings in Node environments in Integration Tips.

Syntax

Use double curly braces to insert state variables:

{{state.someValue}}

Examples

Text Content

You can use data binding for any text content. For example, to create a personalized greeting:

Hello {{state.userName}}!

Link URLs

Data binding also works with hyperlink URLs:

Hello {{state.userName}}!

This feature works with any text content, both in inline text fields and Rich Text Editor (RTE) fields. No additional configuration is required within the Builder interface to use the undefined syntax.

However, to populate these state values with actual data, you need to pass the data to the BuilderComponent in your code, similar to how you pass data for custom actions:

The data passed this way is accessible using state.* in the rich text fields, just as it is in Builder actions and bindings.

Better support for localization (coming soon): The content API will provide improved support for localization, including querying based on localization features.
Support for multi-level nested references (coming soon): The content API will allow you to query, resolve, and return content that has nested references of other contents and symbols.

Was this article helpful?