🧰How it works
Last updated
Last updated
© Bee Content Design, Inc. San Francisco, CA | Part of Growens
When the builder starts, you can feed to it multiple lists of custom rows, which will display in the rows selector:
Each list is an array of objects (JSON) describing the rows and must be returned by a URL that the builder will call when the user selects its name. These objects may be Saved Rows or Simplified Rows (a JSON schema that allows you to generate rows from existing contents through an API).
When the user selects the list name, the builder will call the given URL to retrieve the rows and display them:
If the URL is not available, a warning message will be displayed in the bottom right, and the builder will display the next set of rows or fallback to empty rows or default rows(depending on your configuration):
There is no limit to the number of rows passed to the builder in each array of custom rows.
However, the builder UI will only display the first 30 items (i.e., the first 30 rows in the array).
The rest of them will not show until the user performs a search that matches them. If the search matches over 30 items, the first 30 are displayed.
This filtering is applied to prevent performance degradation in the browser.
The search field allows users to narrow down the content shown after they select a list of custom rows.
The search is performed against all elements of the array (i.e., both visible and hidden), and the first 30 items (i.e., the first 30 rows in the array that match the search criteria) are shown.
All textual content included in the selected array – including image file names – is used to find a match.
Defines the usage of custom rows in the beeConfig object when you start the builder:
This section explains each of the parameters listed in the JSON rowConfiguration code snippet displayed in the previous section.
These parameters are the following:
emptyRows: Set of empty rows. The same rows available when no rowsConfiguration is included.
defaultRows: A set of rows that contain sample content.
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 drop-down.
Set of empty rows. The same rows available when no rowsConfiguration is included.
Allowed values: true / 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):
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: true / false
Default value: false
They are presented as follows in the builder’s default theme (the screenshot shows the first 2 default rows):
This parameter 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 parameter, 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.
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.
Each item in this 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.
Here is an example of how the Rows drop-down looks when the application configuration includes:
Empty rows (see above)
Default rows (see above)
Saved rows (learn about displaying Saved rows)
3 additional arrays for Custom rows
The order of the JSON nodes in rowsConfiguration defines the order in which the lists of custom rows will display in the drop-down. It also determines which list of rows will be used as default (selected) when the user clicks on the Rows tab for the first time during the session.
The first ordering factor refers to the type of row (empty, default, custom). That’s defined by how the following parameters are listed in rowsConfiguration:
emptyRows
defaultRows
externalContentURLs
So obtain the order shown in this screenshot…
… you would list defaultRows before emptyRows:
defaultRows
emptyRows
externalContentURLs
The order inside the externalContentURLs node defines the order of the Custom rows.
In the above example configuration:
emptyRows will be the first item in the drop-down and the default selection when clicking on the Rows tab
defaultRows will be the second item in the drop-down
The lists of rows defined in externalContentURLs will follow their ordering in the drop-down
It’s up to you – the host application – to decide what’s available and in which order.
emptyRows and defaultRows are not required
this allows you to load just Custom rows, if needed, controlling which content users can drag and drop into the builder
