This feature is available on Beefree SDK Core plan and above. If you're on the Essentials plan, upgrade a development application for free to try this and other Core-level features.
There are three types of pre-built reusable content you can provide your application's end users with. These are the following:
In this page, we will look at a sample rowsConfiguration that incorporates defaultRows, emptyRows, selectedRowType, and externalContentURLs. The Implement Custom Rows page will discuss the steps to integrate Custom Rows.
The following code snippet provides a sample rowsConfiguration.
This section explains each of the properties listed in the rowConfiguration code snippet.
These properties are the following:
emptyRows: Set of empty rows. The same rows available when rowsConfiguration is not included. End users can use these empty rows to structure and customize their own content within.
defaultRows: A set of rows that contain sample content. End users can use the sample content as inspiration for customizing them with their own look and feel.
selectedRowType: Specify which type of row should be pre-selected when the end user opens the Rows selection in the visual builder.
externalContentURLs: Each item in this list defines an option available in the Rows tab drop-down.
You can add pre-built default rows to your builder by setting the defaultRows property to true in your beeConfig.
Default rows are a set of rows that contain sample content. That’s why we also call them sample rows. They may be used as a supporting feature for starting templates, or to speed up the process of building a message from scratch.
Allowed values: boolean, can be set to true or false.
Default value: false
They are presented as follows in the builder’s default theme (the screenshot shows the first 2 default rows):
You can add pre-built empty rows to your builder by setting the emptyRows property to true in your beeConfig. Empty rows are a set of rows that aren't prefilled with content. However, they offer a general structure for content to be placed within them. These are the same rows available to end users when the rowsConfiguration parameter is not included in the beeConfig.
Allowed values: boolean, can be set to true or false.
Default value: true
Will always be included as the last element if omitted in the configuration.
They are presented as follows in the builder’s default theme (the screenshot shows the first 4 empty rows with unique structures):
This property is used to specify which type of row should be pre-selected when the end user opens the Rows selection in the visual builder. You have several options for what value to assign to this property, and its role is to simplify the end user's interaction with the builder by focusing their attention on a specific type of row by default.
Possible values for selectedRowType:
'defaultRows': This value will automatically select the default rows that come with the builder, which usually contain pre-designed content that users can easily modify and adapt. It helps users start with a pre-configured structure and quickly adjust it to meet their needs.
'emptyRows': This value pre-selects an option for the user to start with empty rows. This is useful for users who prefer to build their layouts entirely from scratch, without any predefined content or structure.
The handle of a row in externalContentURLs:
You can also pass the handle of a row that is listed in externalContentURLs to pre-select a row from an external source. A handle in this context refers to the unique identifier or name used to reference a specific row from an external list. Think of it as a unique key that allows the system to identify which external row to load or pre-select.
For example, if you have external content rows listed in externalContentURLs, such as "Rows list 01" or "Rows list 02," you can pass their respective handle (typically a string like "Rows list 01") as the value for selectedRowType. This will automatically load and pre-select that specific external row, saving the user the step of manually selecting it from the list.
The externalContentURLs property accepts a row's name and url. You can add multiple items to the property. Each item in the list defines an option available in the Rows drop-down.
name: the text displayed in the Rows drop-down
value: URL that will be called by the builder when the user selects the corresponding name in the drop-down. The URL must return a set of rows as a JSON object.
The following image displays an example of how the name value appears in the drop-down menu.
In the drop-down menu, you can see a visual example of each pre-built content type mentioned in this article and in Implement Custom Rows:
Empty rows: When the end user clicks the Empty option in the drop-down menu, they will be redirected to a list of row structures to choose from.
Default rows: When the end user clicks the Default option in the drop-down menu, they will be redirected to a list of default rows to choose from.
My Saved Rows: When the end user clicks the My Saved Rows option in the drop-down menu, they will be redirected to a list of rows they created and saved to reuse at a later time.
Custom rows: The MailChimp Footers, HubSpot Footers, and Sendgrid footers are additional options added to the drop-down through the Custom Rows feature. When an end user clicks on any of these three options, they will be redirected to the lists of rows available in that external resource.
A handle acts like a reference key to point to a specific row in an external list. Handles are typically unique names or identifiers that can be used to quickly access specific rows from an external content source, ensuring that the correct row is fetched and displayed to the user. For instance, in the following configuration:
If you want to pre-select "Rows list 01" from the external content list, you would set selectedRowType: 'Rows list 01', where 'Rows list 01' is the handle of that specific external content row. The handle here refers to the name or a unique identifier that the system recognizes and uses to select the correct row from the external content list.
Visit Manage Reusable Content to learn more about editing, deleting, categorizing, and managing rows within the builder.
Custom Rows are a powerful way to provide “ready-to-go” content directly into the builder. Think products, blog articles, events, coupons. And don’t forget that Saved Rows your customers might have will be loaded as Custom Rows the next time they load the builder.
All this content is crucial to make the most out of the Beefree SDK experience, and that’s why you can add UI elements in your app’s interface to:
jump right to a Custom Rows category, without the need for the user to go into the Rows tab, click on the dropdown and select the category;
provide additional information on the available rows, either through a tooltip or by showing a Content dialog with all the information and the links to the rows.
With this feature, you will reduce the friction needed to discover and access the builder’s Custom Rows. To do so, you’ll use the loadRows event, which will trigger the Custom Rows content dialog.
Here’s an example of our Beefree product, which integrates Beefree SDK, taking advantage of this method to load custom rows from its UI.
The toolbar in the application contains explicit call-to-action text links to load footers, which correspond to different categories of Custom Rows in the application.
When users click on “Mailchimp Footers”, the Custom Rows Content Dialog is triggered, meaning that the builder opens a communication channel with your application. In this case, no additional UI will be displayed, as the host application provides the URL to the rows associated with that call-to-action. This way, the Rows tab will be immediately selected, with the “Mailchimp Footers” category already selected:
But what if you wanted users to select the email footers they need from a large catalog of pre-built content? In that scenario, you could have a more generic “Load footers” call-to-action in the toolbar.
Clicking on “Load Footers” will once again trigger the Custom Rows content dialog, but this time the application could provide a dialog window where users can browse or search through available footers, and get some additional context on them. Here is a visual example of how it might look like, but as with all content dialogs you have complete freedom on what to show:
When users click on MailChimp, the modal window fades off, the builder switches to the “Rows” tab, and the MailChimp Footers are shown, ready to be dragged into the message.
You can trigger the Custom Rows content dialog via the loadRows instance event.
Once the Content Dialog is triggered, you have two options, as explained in the How it works section:
Immediately return the rows URL, without displaying the Content Dialog. This is useful if you have a menu and already know which rows to load based on the interaction by the end user with you application’s UI.
By letting you establish an interaction layer between the editor and your application (e.g., you show a modal window), it allows your users to locate/build/insert new rows, thus making the Rows tab in the editor dramatically more flexible and scalable.
To start using it, you need to add the contentDialog object to beeConfig, or add the externalContentURLs parameter if you already use this feature in your editor configuration.
Here is an example of the syntax that needs to be added to the editor configuration document (beeConfig):
From the perspective of your users, this additional configuration adds a new item (using your text label) in the Rows drop-down.
Here is a visual example of how the “Search products” label will be shown, at the bottom of the Rows drop-down.
You can use this event to display a form where the user can search for new items to insert in the message. Here is a visual example:
You could also ask the user to enter parameters that will affect the very structure of the rows (JSON documents) that will be imported into the editor, affecting the way they will display:
You can also mix both forms in a 2-step pattern.
When the selection is made, you must return to the resolve function a URL containing the result (row’s list).
The response must match the same format used to define the externalContentURLs in beeConfig:
This response will:
Create a new drop-down choice with the provided name
Display the rows provided by the URL in the rows panel
Notice that in the rows list, names returned by the Content Dialog display as highlighted elements to give them further visibility over starting choices.
The Content Dialog can be used as many times as the user needs and, depending on the response, the behavior may change:
This overwrites the existing results, keeping the same name in the drop-down. This behavior perfectly matches our example above, where the host application returns “Your search results” every time the content dialog is resolved.
This creates a new drop-down choice, keeping the previous results as selectable elements. Previous results are available directly in the drop-down.
Here is a visual example:
In our example, we are using this event to display a search form and transfer the user selection to the editor as custom rows.
The form is part of the application, so we are using the same elements and styles that users of the application are used to.
These same rows can then be fed back into the editor by leveraging Custom Rows.
To do so, the host application must make them available in a reachable location specified through the externalContentURLs parameter.
The rows are displayed based on your rows configuration, so you can categorize them, creating multiple lists of rows to improve the user experience.
Here is an example of a rows configuration that displays saved items divided into usage categories:
And here is another example where saved rows are organized based on the campaign type:
The following is an example of the response schema when the editor calls one of the provided URLs:
Interact with the end user, as described in our documentation, and eventually return a URL of custom rows.
allows you to build user interfaces that let your users locate & insert additional content (Custom Rows) while they are working on their message.
Note that Content Dialog may be used to load other content types, as merge tags, special links, or display conditions. .
When the user clicks on the new menu item (e.g., “Search products” in the example above), what you define in the handler (a function with a -like signature) is triggered.
Rows can be saved directly in the editor using the . These rows are returned to the host application as JSON objects that you can store based on your application logic.
With the introduction of Saved Rows Management, we’ve also introduced the ability to load external rows with an instance method. See for more details.
