Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Beefree SDK offers the ability to customize rows. Learn more about what this feature is and what it offers in the following sections:
When the builder starts, you can feed to it multiple lists of custom rows, which will display in the rows selector:
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:
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 contents. 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):
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)
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
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 or (a JSON schema that allows you to generate rows from existing contents through an API).
Saved rows (l)
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:
Interact with the end user, as described in our Content Dialog documentation, and eventually return a URL of custom rows.
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.
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.
Custom rows dramatically improves this area of the builder (now renamed simply Rows):
Introducing the concept of ready-to-go rows, which provide both structure & content.
Allowing you – the hosting application – to pass that ready-to-go content to the builder.
Maintaining the existing, empty structures, for continuity of the current user experience.
Allowing you to turn off empty structures, if you want to, and only provide custom rows.
These new, custom rows can be dragged and dropped into the editing pane the same way users currently add other content elements.
Enabling the Save Rows feature, your users will be able to save into your application design elements that they want to use in other messages.
To display saved rows in the Rows tab, add them to the list of rows available to users by leveraging the Custom Rows feature.
When using the standard, empty rows, users are forced to start from scratch every time they introduce a new row.
A set of pre-built rows may accelerate message construction, providing users with commonly used structures filled with sample content. For example, a set of headers, footers, news sections, etc.
With Custom rows you – the hosting application – are in control of the content that is included. In some cases, providing canned text can speed up the email creation process and provide consistency across all the communications.
Imagine, for example, the case of a CRM where customer success representatives can quickly build curated emails selecting from a number of pre-built text blocks.
In addition to the empty rows that have always been part of the Beefree SDK system, we now provide a set of default rows that you can add to your application with a simple configuration parameter.
They feature a series of popular structures, filled with placeholder text, images, and buttons.
For some users, they may work better than empty rows as they allow them to immediately visualize what they can accomplish with a specific structure.
Reference Rows Configuration to learn more about how to configure these sample rows.
Does your application onboard users asking for company or brand information?
If so, you can use custom rows to provide footers with legal information already applied (and centralized), header designs that already include the company logo, etc.
Other common use cases:
Approved promotional material
QR codes or barcodes
Advertising content
Product recommendation templates
Check how to configure these sample rows below under Rows configuration > Parameters > Default rows
Create custom rows with content from different sources like blogging platforms, content management systems, etc.
This will allow your customers to save time and reduce errors by avoiding copying and pasting text, links, and images.
Additionally, this helps you ensure that only reviewed and approved contents, provided by a common repository, are used in the message creation.
Transform products from your e-commerce catalog into custom rows, using product images, text, and call to actions to create a promotional message with a few clicks.
You can divide the products into categories and feed them into the builder as different arrays of custom rows.
Or you can use different sets of custom rows to provide different layout options in order to add design flexibility.
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:
Custom Rows allows you to easily generate draggable rows from your application content, or other application content, without any design process or complex user interaction.
To make it possible, we built a Simplified Row Schema, a JSON that describes each row and its contents with the minimum number of elements, to easily transform existing content into a destination format compliant by the Beefree SDK system.
The following is an example of four different row objects:
First: A row with a single column and 2 text modules (a title and a paragraph) inside.
Second: A row with 2 equal columns and 2 text modules (a title and a paragraph) inside each one. These columns will not stack when the message is open on mobile devices.
Third: A row with a background image on it.
Four: A row with a display condition.
The row’s name:
A string of plain text that identifies the row.
Displayed in the row card when the row is shown in the Rows panel.
Included in the textual content used in searches
Set a row background image.
Properties:
background-image: valid image url
background-repeat: repeat | no-repeat
background-position: top | bottom + left | center | right
background-color: #c2c2c2 // CSS value
Properties:
display-condition
type
label
description
before
after
Disable stacking on mobile. Set the value to “false” to disable stacking on mobile. If the value is “true”, or not provided, the columns will stack on mobile.
colStackOnMobile: true | false
List of the row columns. Each column type is identified with a weight parameter to indicate how much horizontal space they fill. We use a 12-column grid with the following values as available combinations:
12
9, 3
8, 4
6, 6
6, 3, 3
4, 8
4, 4, 4
3, 9
3, 3, 6
3, 6, 3
3, 3, 3, 3
All the columns weight inside a row must sum 12 as the total value.
See the example above in General Row Schema.
List of content modules inside a column
Every module is identified by a type parameter. Available types are:
title
paragraph
image
button
divider
HTML
Each module type has a set of available options. If none is included, the editor will use the default values.
title adds the text with the following attributes:
Font-size: 18px
Font-weight: Bold
Text-align: left
paragraph will use the following formatting:
Font-size: 14px
Text-align: left
text contains the string that will be displayed as content:
Must be a plain text string
Quotation marks must be escaped to be compliant with the JSON format
If not included, a default “Loren Ipsum” text string will be used
src image public URL
href Image action URL (link)
alt alternate text
dynamicSrc when added, the content applies the dynamic image behavior and uses the value as dynamic URL
text text string that will be displayed as the button content. Must be a plain text string.
If not included, a default text string will be used
href button action URL (link)
Currently there are no additional parameters.
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.
While the feature provides the complex and continuously evolving object used in the message page, the Simplified Row Schema makes it easy to build an API that feeds the editor with contents from different origins like e-commerce stores, blogs, or digital asset management systems.
Set a row display condition. Check the for further details.