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.
- The
dataandcontextproperties allow you to pass information and functionality to your Builder components. - The
dataandcontextproperties are optional for Builder components.
To pass data down, 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:
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:
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.
Both context and data are optional arguments for a BuilderComponent. The key difference is how they are used and what they represent.
Use the context prop to pass globally available objects or functions, such as utilities or services used across multiple components.
The context prop is not directly accessible to visual editor users, making it less visible than the data prop. This makes it ideal for exposing JavaScript libraries, utility functions, or global data within Builder.
Use the data prop to pass content-specific data that affects rendering or behavior in the BuilderComponent.
The data prop is accessible in the visual editor. Users can view this data in the Data tab under the Content State panel. This data could then be utilized within the Element data bindings panel. For instance, the data prop could store user details like a username.
You can add an action to any element, though button actions are frequently customized, which this section covers.
The following example demonstrates a context object that defines a single function called myFunction(), which displays an alert with "Hi!" when called.
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.
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.
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.
Use double curly braces to insert state variables:
{{state.someValue}}You can use data binding for any text content. For example, to create a personalized greeting:
Hello {{state.userName}}!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.
Leverage data and Modify state with actions, or create Custom actions and Custom code in the Visual Editor.
- 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.