Color picker palette overview

The builder’s color palette gathers a list of the default colors to display from multiple sources in order to create a convenient palette of color selections when the editor loads.

Specifically, colors are gathered as follows:

• 3 colors from the body (message background, content background, link) + black (#000000)

• custom colors (as many as customers want)

• 7 most recently used colors

Use the options outlined below to customize the default color palette.

Choosing the default colors in the color picker

The builder allows you to configure a custom color palette (per user), by modifying the client-side configuration. This, for instance, allows you to provide users with easy access to their company’s brand colors.

If no color profile is provided, then the builder will continue to suggest a color palette based on the colors used in the template that is being loaded.

var beeConfig = {
        uid: config.uid,
        defaultColors: ['#ffffff', '#000000', '#95d24f', '#ff00dd'],
        ...        

Disabling the color history

The builder will remember recently selected colors and add them to your color palette. If the browser’s privacy settings allow it, the color picker history will be saved in the browser’s local storage.

If you want the color palette to be static such that recently selected colors are not included, then you can disable the history in your configuration.

var beeConfig = {
        uid: config.uid,
        disableColorHistory: true,
        ...        

Disabling the template's base colors

The builder by default adds colors found in the template’s body section to the color palette.

If you want the color palette to only show the colors you pass in via the bee config document, then you must disable the base colors.

var beeConfig = {
        uid: config.uid,
        disableBaseColors: true,
        ...        

The default configuration returned by the system can be extended by using additional configuration objects such as:

Special links

Special links are links that your system generates dynamically when the message is sent, typically because they include the message ID, the recipient’s email, or some other variable. The most common one is probably the unsubscribe link.

The type parameter will be used to group related links in the UI and simplify the user selection.

Technically, special links are passed to the application in the configuration file as follows:

specialLinks: [
	{
      type: 'Frequently used',
      label: 'Unsubscribe link',
      link: 'http://[unsubscribe]/'
	},{
      type: 'Frequently used',
      label: 'Preference center link', 
      link: 'http://[preference_center]/'
	},
	/* Other special links */
];

and here’s an example of what the user will see in the builder UI, starting from the above code:

Merge Tags & Merge Content

As mentioned above, when you initialize the application, in the configuration file you can submit both “merge tags” and “merge content”.

Really, they are the same thing: some syntax that your system will replace with some meaningful content at the time the email is sent. They differ in the way they are presented to the user.

Merge tags help dynamically insert text into a paragraph, such as the very common scenarios of “Dear {first_name}”.

Merge content, instead, helps the user insert special syntax as content element in other sections of the message that are not text, such a list of recommended products.

Currently it is not possible to group merge tags and merge contents as it is for special links.

Here is an example of adding mergeTags and mergeContents in the configuration file:

var mergeTags = [
	{
		name: 'First Name',
		value: '[first-name]'
	}, {
		name: 'Latest order date',
		value: '[order-date]'
	}
];

var mergeContents = [
	{
		name: 'Headline news',
		value: '{headline}'
	}, {
		name: 'Image of last product viewed',
		value: '{last-product-viewed}'
	}
];

Merge Tag Details

Merge tags can be inserted into a text block by clicking on the “Merge tags” button in the expanded text block toolbar. The button is not shown if no merge tags were submitted in the configuration file.

Merge tags also become available to the user by pressing the @ key on the keyboard while editing a text block.

Here is an example: the user wants the date of the last order to be inserted after “[…] placing an order on …”, so he/she presses the @ key and selects “Last order date” from the list of merge tags found by the builder in the configuration file.

After inserting the merge tag, the text block now shows the placeholder for the last order date.

Ways to load Merge Tags

You can load Merge Tags in the builder when it is initialized by adding a mergeTags node to the JSON configuration file. For example:

var mergeTags = [
	{
		name: 'First Name',
		value: '[first-name]'
	}, {
		name: 'Last Name',
		value: '[last-name]'
	}, {
		name: 'Email',
		value: '[email]'
	}, {
		name: 'Latest order date',
		value: '[order-date]'
	}
];

… or you can allow users to search and insert a merge tag by using the flexible Content Dialog feature. This is especially useful when the number of merge tags is large, and picking from a list would not provide an optimal user experience.

You can use a combination of both approaches, loading frequently used merge tags at the time the builder is initialized, and then allowing users to look for additional merge tags using Content Dialog.

Merge Content details

Merge content differs from merge tags in that it allows the user to drag and drop instances of it as a content element available in the Content panel.

For example, let’s say you have a section of an email where you want to display some recommended products: Merge Content allows you to insert some syntax into the message that your application will replace with the recommended products at the time the email is sent.

When Merge Content elements are submitted to the builder in the configuration file, a new tile is displayed in the Content panel.

The user can drag and drop it into the message just like any other content element.

Once dropped in position, the settings panel will display the instances of merge content available for selection.

In the example below, the user wants to insert some banner ads into the email, using a service such as LiveIntent. An array of Merge Content elements were submitted to the builder in the configuration file, so the user has several banner ads to choose from (i.e. some syntax that will be replaced with HTML when the email is sent).

To create another instance of merge content, the user can either drag and drop it again from the Content tab, or duplicate the existing content element…

… choose another instance of merge content from the available selections…

… and then drag it elsewhere in the message.

Ways to load Merge Content

Just like with Merge Tags, you can load Merge Content in the builder at the time it is initialized by adding a mergeContents node to the JSON configuration file. For example:

var mergeContents = [
	{
		name: 'Headline news',
		value: '{headlines}'
	}, {
		name: 'Lastest blog articles',
		value: '{latest-articles}'
	}, {
		name: 'Latest products viewed',
		value: '{latest-products}'
	}
];

… or you can allow users to search for additional instances of Merge Content by using the Content Dialog feature.

Here too, you can certainly use a combination of both approaches, loading frequently used Merge Content at the time the builder is initialized, and then allowing users to look for additional Merge Content using Content Dialog.

Limitations to Merge Tags & Merge Content

Merge tags limitations

Merge tags are meant to be placeholders that will be replaced at the time an email is sent, or the web content is generated for visitors.

You cannot use HTML code in the text strings passed to the builder because – if you do – it will be encoded and will not function correctly in the source code of the message. Of course, you can replace the tag with HTML code at the time of saving or sending the message.

Standard merge tags do not support sample placeholder content, for now. The syntax will be displayed in the builder as your users design the message or page.

If you want to provide a better experience when working with Merge tags, including using a friendly name instead of the syntax and generating sample content, we recommend to check out Smart merge tags.

Merge Content limitations

Additionally, there are some other limitations that are specific to the Merge Content feature. Among them:

1. Users cannot see & edit the content: what’s in it, the style used, the layout, etc..

2. Not seeing it, they could select the wrong content from the list of available Merge Content.

3. The HTML might be created outside of Beefree SDK, which could lead to rendering issues when it’s inserted into the message.

4. Since the HTML is created elsewhere, and it’s not part of the document created by Beefree SDK, it must be managed separately.

Due to these additional limitations, we now recommend an alternative approach to Merge Content in order to handle dynamic content in Beefree SDK: utilizing Custom Rows with Merge Content & Display Conditions.

Further extending the builder

You can use the Content Dialog feature to introduce an interactive layer between the builder and your application, and through it extend Merge Tags, Merge Content, Special Links, and Display Conditions.

About roles and permissions

In Beefree SDK we introduced the idea that some content may be editable by some users and not others. For example, you may want the header and footer section of an email newsletter to be locked, so that it cannot be inadvertently modified when creating the latest version of your weekly news digest.

Internally, we’ve been calling this feature “Restricted editing”. Others refer to it as “locked regions”, “blocked content”, and more.

To allow for this, we created ways for the application hosting the builder to define user roles and set their permissions. Let’s take a look at how the feature works first and then show you how to configure your application to take advantage of it.

Types of roles

The user roles that you create (e.g. Brand Manager, Senior Editor, Junior Editor, etc.) can have different permissions. You can create as many or few user roles as you wish. The permissions that you can assign to them refer to:

• Locking content (entire rows or specific content blocks)

• Editing locked content

• Using Display Conditions

Specifically, the permission settings that can be configured for each role are:

• Can lock rows (if active, all other permissions are granted)

• Can lock modules

• Can edit locked rows

• Can edit locked modules

• Can select Display Conditions

• Can edit Display Conditions

• Can remove Display Conditions

For example, a Brand Manager all four permissions checked, whereas a Senior Editor might have editing access to rows and modules, but won’t be able to lock rows and modules. Let’s take a look at a few scenarios.

Locking a row

If the user has this permission, locking a row is very easy to do. That user will simply select the row they would like to lock and click on the lock/unlock radio button in the row properties panel.

If a user does not have the permissions needed to edit a locked row, they will see a friendly error when they attempt to select the row, notifying them that the row can’t be edited:

Likewise, they will not be able to drag & drop any content blocks on the locked row, as shown here:

Rows vs content blocks

You can restrict access to layout changes while granting access to content modifications by using user roles and permissions.

This allows you to give your users editing access to the content, while ensuring that the overall layout of the message is not altered, and that specific content blocks that should not be modified are left “as is”. This way, for example, a junior member of the marketing team could focus on updating text & images, without worrying about potentially modifying the structure of the message in an unwanted and/or unauthorized way.

Or, as shown in the example below, the same user could update social media icons and links in the footer of an email, without altering legal language and dynamic fields used in the same footer. That’s accomplished by setting us a social media module that’s editable (unlocked), but in a row that’s locked.

When users without the proper permissions try to edit, move or remove the row, they are told that they may not do so.

Similarly, if they try to edit any content is the row that has not been specifically unlocked, they are told that they are not able to do so. In this case, for instance, the user is not able to edit the merge tags used in the footer of the email.

However, when they click on the social media icons, they are able to edit it.

To accomplish the above, a user with higher permissions needs to:

1. Open the message in the builder

2. Lock a row

3. Unlock one or more specific pieces of content within the row.

Creating and editing user roles

Log into the Beefree SDK Console and click on Manage roles under Application configuration for the selected application:

In the Manage Roles section you’ll be able to create different user roles and set their permissions. For example, your user roles could be Brand Manager, Account Manager, Junior Editor, etc depending on your needs and nomenclature. For each user role you create, you can set and restrict editing permissions, such as the ability to lock or edit rows and content blocks, as you can see below:

Once you create your user roles you’ll be able to see them listed:

How to use the Role Hash parameter

While Role Name is a friendly description of that user role, Role Hash is the parameter that identifies that particular role in Beefree SDK. It must be an alphanumeric string between 8 to 30 characters: it can contain letters and numbers, but cannot contain spaces or special characters (such as “-“, “_”, etc.). You will need to save these role hashes in your application, at the user level – or at the user role level, if you have the concept of “roles” in your application – so that you can retrieve them and pass them to the application when you initialize the builder for that specific user.

The property name is: roleHash.

For user roles to become active in the builder , you will need to add this new property to your Beefree SDK configuration when you configure the builder for a specific user. You will pass:

roleHash: "roleSpecified"

for each of the user, depending on its role. For example, if the Role Hash for a “Junior Editor” is “juniorEditor”, the application configuration will include:

roleHash: "juniorEditor"

Please refer to configuring the builder for more details.

Combination of user roles and permissions

This section goes in more details about the various combinations of permissions. It might help you understand how to best put this feature to work in Beefree SDK with regard to locking & unlocking rows and content blocks.

First, we created some hypothetical roles by using all application combinations of the available user permissions at the row/content level.

Then, we created a table with a number of possible “actions” and see which user role would have access to which actions. This allows you to map a certain combination of permissions (from above) to a specific task carried out in the Beefree SDK builder.

User roles & display conditions

If you use Display Conditions in your builder application, then you can use additional user roles to control the access users have to creating and editing Display Conditions.

Advanced options are available with Beefree SDK. Learn more about the advanced options you can integrate within your web application. Beefree SDK's advanced options include the following capabilities.

Introduction

You can customize the list of fonts available in the editor’s text toolbar and the body settings panel.

This feature allows you (or users of your app) to:

• Expand the list of available fonts, adding web fonts from popular services, such as Google fonts, font library.org or alike.

• Reduce the list of fonts to a limited number of options, removing some or all our default fonts.

Unlike other premium features, fonts are part of the client-side configuration, so they can be defined each time the editor is started.

This flexible approach will help you use this feature in a variety of scenarios. A few example scenarios are the following:

• You want your users to customize the list of fonts loaded in the builder when they edit designs. You can now create an interface in your app to do so, and instruct the editor accordingly (see below).

• You have multiple levels of users, and you want “contributors” to only see a subset of approved fonts, while “editors” have access to a larger list.

• You are a digital marketing agency, and you want to customize the list of fonts in the editor depending on the client/brand for which the email message is being designed.

For instance, in our hosted email design suite (Beefree), we leveraged this Beefree SDK feature to create a “Brand styles > Brand fonts” area where an agency or marketing team can select which fonts have been approved by that brand. Only the selected fonts will be loaded in the builder when an application is initialized. Here is a screenshot.

Adding the editorFonts object

This object, passed as part of the builder configuration, tells the editor which fonts to load in any drop-down where a list of fonts is shown. It defines the availability of the default fonts and provides a list of additional, custom fonts.

editorFonts: {
    showDefaultFonts: true,
    customFonts: [{
        name: "Comic Sans",
        fontFamily: "'Comic Sans MS', cursive, sans-serif"
    }, 
    {
        name: "Lobster",
        fontFamily: "'Lobster', Georgia, Times, serif",
        url: "https://fonts.googleapis.com/css?family=Lobster"
    }]
}

In this example default fonts are loaded, and two new fonts are added: a web safe font (Comic Sans) and a Google hosted web font (Lobster).

Here is a more detailed description on how the editorFonts object is built:

Parameters

Working with custom fonts

When we add a set of custom fonts, we can decide between system fonts and web fonts. Let’s see some details on what you need to know:

System fonts are installed on the operative systems and don’t need any external resource to work, so we can skip the url parameter.

Web fonts are hosted online and need to be loaded by the email client when the email is opened. Beefree SDK accepts only the CSS font embedding method, and the CSS file must be hosted in HTTPS protocol. You can use services like Google fonts, that provides host, font stacks and a well formatted CSS file.

Usage examples

We want the editor to work with only 2 fonts when creating a message, we want that only Lobster and Cabin fonts are available when editing this message:

editorFonts: {
    showDefaultFonts: false,
    customFonts: [{
        name: "Cabin",
        fontFamily: "'Cabin', Helvetica, Arial, sans-serif",
        url: "https://fonts.googleapis.com/css?family=Lobster"
    }, 
    {
        name: "Lobster",
        fontFamily: "'Lobster', Georgia, Times, serif",
        url: "https://fonts.googleapis.com/css?family=Lobster"
    }]
}

In the following example, instead, we don’t want to add new fonts but restrict the default ones to our own selection:

editorFonts: {
    showDefaultFonts: false,
    customFonts: [{
        name: "Helvetica",
        fontFamily: "'Helvetica Neue', Helvetica, Arial, sans-serif",
    },
    {
        name: "Lucida",
        fontFamily: "'Lucida Grande', 'Lucida Sans', Geneva, Verdana, sans-serif"
    },
    {
        name: "Georgia",
        fontFamily: "Georgia, Times, 'Times New Roman', serif"
     },
     {
        name: "Lato",
        fontFamily: "'Lato', Tahoma, Verdana, sans-serif",
        url: "https://fonts.googleapis.com/css?family=Lato"
     },
     {
        name: "Montserrat",
        fontFamily: "'Montserrat', Trebuchet MS, Lucida Grande, Lucida Sans Unicode, sans-serif",
        url: "https://fonts.googleapis.com/css?family=Montserrat"
      }]
}

Notice that if you want to change the default set of fonts, you need to disable them and use custom fonts to indicate the new set, including the URL parameter for web fonts.

This is the complete list of the default fonts in the application and its configuration, including the external URL for web fonts:

  {
    name: "Arial",
    fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
  }, {
    name: "Courier",
    fontFamily: "'Courier New', Courier, 'Lucida Sans Typewriter', 'Lucida Typewriter', monospace"
  }, {
    name: "Georgia",
    fontFamily: "Georgia, Times, 'Times New Roman', serif"
  }, {
    name: "Helvetica Neue",
    fontFamily: "'Helvetica Neue', Helvetica, Arial, sans-serif"
  }, {
    name: "Lucida Sans",
    fontFamily: "'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Geneva, Verdana, sans-serif"
  }, {
    name: "Tahoma",
    fontFamily: "Tahoma, Verdana, Segoe, sans-serif"
  }, {
    name: "Times New Roman",
    fontFamily: "TimesNewRoman, 'Times New Roman', Times, Beskerville, Georgia, serif"
  }, {
    name: "Trebuchet MS",
    fontFamily: "'Trebuchet MS', 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', Tahoma, sans-serif"
  }, {
    name: "Verdana",
    fontFamily: "Verdana, Geneva, sans-serif"
  }, {
    name: "ヒラギノ角ゴ Pro W3",
    fontFamily: "ヒラギノ角ゴ Pro W3, Hiragino Kaku Gothic Pro,Osaka, メイリオ, Meiryo, ＭＳ Ｐゴシック, MS PGothic, sans-serif"
  }, {
    name: "メイリオ",
    fontFamily: "メイリオ, Meiryo, ＭＳ Ｐゴシック, MS PGothic, ヒラギノ角ゴ Pro W3, Hiragino Kaku Gothic Pro,Osaka, sans-serif"
  }, {
    name: "Bitter",
    fontFamily: "'Bitter', Georgia, Times, 'Times New Roman', serif",
    url: "https://fonts.googleapis.com/css?family=Bitter"
  }, {
    name: "Droid Serif",
    fontFamily: "'Droid Serif', Georgia, Times, 'Times New Roman', serif",
    url: "https://fonts.googleapis.com/css?family=Droid+Serif"
  }, {
    name: "Lato",
    fontFamily: "'Lato', Tahoma, Verdana, Segoe, sans-serif",
    url: "https://fonts.googleapis.com/css?family=Lato"
  }, {
    name: "Open Sans",
    fontFamily: "'Open Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif",
    url: "https://fonts.googleapis.com/css?family=Open+Sans"
  }, {
    name: "Roboto",
    fontFamily: "'Roboto', Tahoma, Verdana, Segoe, sans-serif",
    url: "https://fonts.googleapis.com/css?family=Roboto"
  }, {
    name: "Source Sans Pro",
    fontFamily: "'Source Sans Pro', Tahoma, Verdana, Segoe, sans-serif",
    url: "https://fonts.googleapis.com/css?family=Source+Sans+Pro"
  }, {
    name: "Montserrat",
    fontFamily: "'Montserrat', 'Trebuchet MS', 'Lucida Grande', 'Lucida Sans Unicode', 'Lucida Sans', Tahoma, sans-serif",
    url: "https://fonts.googleapis.com/css?family=Montserrat"
  }, {
    name: "Ubuntu",
    fontFamily: "'Ubuntu', Tahoma, Verdana, Segoe, sans-serif",
    url: "https://fonts.googleapis.com/css?family=Ubuntu"
}

In this example, we want to add font weight options to our list:

var editorFonts = {
        showDefaultFonts: true,
        customFonts: [{
          name: "Comic Sans MS",
          fontFamily: "'Comic Sans MS', cursive, sans-serif"
        },{
          name: "Indie Flower",
          fontFamily: "'Indie Flower', cursive",
          url: "https://fonts.googleapis.com/css?family=Indie+Flower"
        },{
          name: "Oswald",
          fontFamily: "'Oswald', sans-serif",
          url: "https://fonts.googleapis.com/css2?family=Oswald:wght@200;300;400;500;600;700&display=swap",
          fontWeight: {
            200: 'Extra-light',
            300: 'Light',
            400: 'Regular',
            500: 'Medium',
            600: 'Semi-bold',
            700: 'Bold',
          }
        }]
      };

Templates with unavailable fonts

We open a saved template that uses fonts that are not available:

• System fonts will display normally in the editor and the text can be edited, but the font-family is not available in the font selector.

• Web fonts will fallback to a system font. Text can be edited and the font-family is not available on the font selector.

• We are able to save the message that already uses unavailable fonts.

The problem

When designing a message or a landing page with Beefree’s editors, there might be cases in which users of your application insert a merge tag, add a link to an image, or apply a conditional statement.

It’s all good until things scale up. For example…

• What if you have 400 merge tags? You can feed an array of merge tags to the editor, but that’s not going to cut it.

• What if it’s a 6,000 product database? How will they locate the right one? Special Links is not the right fit.

• And what if a display condition needs to be built on-the-fly?

A flexible solution

Since the Beefree builders are used in hundreds of applications, and since each of them is facing different user experience challenges like the examples mentioned above, we decided that this was really a case where one size does not fit all.

So we engineered a solution that puts you in control and provides a large amount of flexibility.

If your users want to insert a merge tag or a display condition, you control how that will happen. You can overlay a window on top of the editor, for example, and display a simple search box, a list of categories to browse, or a complex configurator to build an advanced conditional statement.

We call this feature Content Dialog.

An interactive UI layer

Content Dialog allows you to build user interfaces for your users to locate & insert merge tags, links, conditional statements, and more. It lets you establish an interaction layer between the editor and your application (e.g. you show a pop-up window) that allows your users to locate/build/insert specific content (merge tags, links, conditional statements, etc.). And you’re in full control of the UI.

For example, imagine you want your customers to be able to quickly locate a link to a product page and assign that link to a button, image, or text. Content Dialog will let you build the right user experience.

Here is a visual example of what you could accomplish in that find a product link scenario.

The user experience in this interaction layer is entirely up to you. In the example above, the user clicked on “Find a product” (or alike) in the editor, and a modal window was shown, with a search box in it. Since you decide what the user experience will be like, you are fully in control of how users will select and insert:

• a text placeholder (merge tag)

• a dynamic link or a link to specific content (special link)

• a markup placeholder (merge content)

• a conditional statement (display conditions).

For each type of content, you can define the action that will be triggered in your application (e.g. display a modal window), and the text that will be displayed in the Beefree SDK editor’s UI to trigger that action (e.g. “Locate a merge tag”), keeping a consistent UX with other areas of your application.

What it does

Content Dialog introduces new call-to-actions in the editor UI.

Depending on the type of content, the call-to-action will be rendered as a button, a link, or a drop-down choice (see below a detailed list of UI changes).

The text for the action is defined by the host application, so you can use your own wording to provide a better experience.

An example of a possible workflow when the user clicks on a content dialog action:

1. The editor will start waiting mode (same as when the save action is triggered)

   • This mode prevents users from further editing and keeps the focus on the user selection

   • The waiting mode is interrupted if the host application cancels the action

2. The host application will display to the user a UI element to select or define a content item

3. When the selection is done, the host application closes the UI and passes it to the editor

4. The editor receives from the host application the selected content and exits waiting mode

5. The content is applied to the selected item

The same example applied to special links (link to a product) in a text selection:

1. The editor starts waiting mode

2. The host application displays an overlay that hides the editor and lists the categories of products to link. The user browses them to find the desired product and selects it.

3. The editor receives the link and exits waiting mode

4. The link is applied to the selected text

How it works

To set up content dialogs you will need to add the contentDialog object to beeConfig:

contentDialog: {
	specialLinks: {
		label: 'Custom text for links',
		handler: function(resolve, reject) {
			// Your function
		}
	},
	mergeTags: {
		label: 'Custom text for merge tags',
		handler: function(resolve, reject) {
			// Your function
		}
	},
	mergeContents: {
		label: 'Custom text for merge contents',
		handler: function(resolve, reject) {
			// Your function
		}
	},
	rowDisplayConditions: {
		label: 'Custom text for display conditions',
		handler: function(resolve, reject, currentCondition) {
			// Your function
		}
	},
	externalContentURLs: {
            label: 'Custom text for custom rows',
            handler: function(resolve, reject) {
                // Your function
        }
    },
	saveRow: {
    	handler: function (resolve, reject, args) {
        	// Your function
    	}
	},
    editSyncedRow: {
	    label: 'Custom text for synced rows',
        description: 'Custom description for synced rows',
	    notPermittedDescription: 'Custom description for synced rows when not permitted',
        handler: function (resolve, reject, args) => {
        	// Your function
    	}
    }

}

For rowDisplayConditions, there is a third parameter called currentCondition. Use this parameter to return a row's current display condition. This parameter returns an object with the following format:

{
    label: '',
    description: '',
    before: '',
    after: '',
    type: 'BEE_CUSTOM_DISPLAY_CONDITION'
}

Note: You do not have to name the parameter currentCondition. You can use any name that works best for your application and workflow.

You can add all the dialogs, some of them or only one. Is up to your application to create them for all the users or a segment, as there are no related server-side settings, you can customize them for each editor start.

All the dialogs use the same pattern, but the returned object must match the element pattern (described in the following section).

label

Defines the text displayed in the editor UI.

handler

Is a function with a Promise-like signature. This function lets you use your own logic to retrieve the desired value. Once the value is available, you must call the resolve(value) function to pass it to the editor. In case you want to cancel the operation, call the reject() function.

A resolve or reject call is mandatory. If you miss this step, the editor will remain in waiting mode. Error management on the host application must call the reject function to unblock the editor.

Examples

The following code snippet displays and example of applying a link action.

contentDialog: {
  specialLinks: {
    label: 'Add an Example Link',
    handler: function(resolve, reject) {
      resolve({
        type: 'custom',
        label: 'external special link',
        link: 'http://www.example.com'
      })
    }
  },
}

The above code snippet is an example of how to apply a Special link.

When the user clicks on Add an Example Link, the URL http://www.example.com is applied to the selection (a button, an image or a text).

The waiting mode will not be perceived, and there is no cancel action.

Apply a link with a delay

The following code snippet displays and example of applying a link with a delay.

contentDialog: {
  specialLinks: {
    label: 'Add an Example Link after 2 seconds',
    handler: function(resolve, reject) {
      setTimeout(function() {
        resolve({
          type: 'custom',
          label: 'external special link',
          link: 'http://www.example.com'
        })
      }, 2000)
    }
  },
}

The setTimeout function in the above code sample is used to delay the execution of the enclosed code. It delays the call to the resolve function by 2000 milliseconds, or 2 seconds. This means that after initiating the special link dialog process, the application will wait for 2 seconds before adding and displaying the specified special link with the label 'external special link' and the URL 'http://www.example.com'.

Opening a dialog UI element

The following code snippet displays and example of opening a dialog UI element.

contentDialog: {
  specialLinks: {
    label: 'Custom text for links',
    handler: function(resolve, reject) {
      openMySpecialLinkDialog() // Replace this with your application function
        .then(specialLink => resolve(specialLink))
        .catch(() => reject())
    }
  },
},

In this example the openMySpecialLinkDialog() should be replaced with a function that opens a modal window (or other element) of the host application, where the user can select or build a link.

The selection is then returned as the value of specialLink to the resolve() function.

A cancel action will trigger the reject() function instead.

Returned value syntax

Values must use the same pattern used in the beeConfig object.

The returned object is validated against the expected format.

If the validation fails, an error will be returned in the browser console:

E.g., Error getting content rowDisplayConditions, the item is malformed.

These errors will not trigger any visible notification in the UI.

Merge Tags

Merge tags allow you to dynamically insert values into your content, such as user information or other variables. This section will guide you on how to configure merge tags in your host application. See the following section for sample code on setting up merge tags in your content dialog configuration.

Merge Tags Configuration

Take the following steps to configure merge tags in your application:

1. Open your content dialog configuration file:

   Locate the file where you configure your application's content dialog.

2. Add the contentDialog object:

   If it doesn't already exist, add the contentDialog object into your configuration file.

3. Configure the mergeTags property:

   Inside the contentDialog object, insert the mergeTags property as shown below:

   Copy

   contentDialog: {
       mergeTags: {
           label: 'Apply dynamic syntax',
           handler: function(resolve, reject) {
               //your function goes here
           }
       },
   },

4. Define the handler function:

   Within the handler function, write your logic to dynamically insert values into the content.

5. Add a corresponding action in the text toolbar:

   Ensure that the text toolbar includes an action for the merge tag element, allowing users to apply dynamic syntax easily.

6. Test your implementation:

   Validate that the merge tags are working correctly within the UI, ensuring that the dynamic values are properly inserted.

contentDialog: {
	mergeTags: {
		label: 'Apply dynamic syntax',
		handler: function(resolve, reject) {
			//your function goes here
		}
	},
},

You can add a new action, available in the text toolbar, and associated with the merge tag element:

Most common use cases

A few of the most common use case for merge tags are the following:

• Your application has a high number of placeholders and needs to provide a categorization or search form

• Placeholder availability depends on options that the user can select while building the message

• You want to display the same UI your users already know and use in your application

• You need to separate merge tags from other text placeholders

Value

The following code snippet defines an object with name and value parameters meant for handling placeholders in an application. The name parameter, although not immediately displayed, is useful for later reference if the user selection is saved and reloaded. The value parameter contains a text string with specific syntax. This is for inserting dynamic content. This setup is important for applications to manage many placeholders or custom text fields efficiently.

{
	name: 'Placeholder name', // Will not be shown
	value: '{{ syntax }}' // Text string that will be added
}

Special Links

Special links are dynamic URLs embedded within emails to execute predefined actions, such as:

• Unsubscribing a recipient: Allowing users to easily opt-out from mailing lists.

• Loading a Web version of an email: Enabling recipients to view the email content in a browser.

• Sending the email to a friend: Facilitating users to share the email with others.

A few end user benefits of using special links are the following:

• User Convenience: Simplifies adding recurring URLs and actions to designs, which increases efficiency throughout the design creation process.

• Consistent Implementation: Ensures URLs and actions are consistent and accessible across various platforms.

By incorporating special links, end users benefit from the ease of managing various links efficiently across diverse platforms.

This section will explain how to configure special links with steps and provide a code sample to help get you started.

Special Links Configuration

Take the following steps to configure special links in your application:

1. Define a contentDialog object within your configuration or settings file.

2. Add a specialLinks property to the contentDialog object.

3. Set the label property to the desired name for your link, for example, 'Search a post link'.

4. Create a handler function within the specialLinks object where you will define the custom logic for handling the link.

5. Ensure this handler function takes resolve and reject parameters to manage its behavior.

The following code snippet provides an example of how you can configure special links.

contentDialog: {
	specialLinks: {
		label: 'Search a post link',
		handler: function(resolve, reject) {
			//your function goes here
		}
	},
},

Links can be applied to different content types. When you define a link dialog action, it will be displayed in the text-toolbar, which is the same behavior for merge tags, as shown in the following image.

The following image shows an example action that applies to image or button content types.

Most common use cases:

A few of the most common use case for special links are the following:

• Apply links to products or news using a categories pattern, a search form, or a visual browser

• Apply special parameters or configuration to certain links with a wizard or form

• You want to display the same UI your users already know and use in your application

Value

In the following code sample, the parameters serve the following purposes:

• type: Represents the type of link but will not be shown to the user directly.

• label: Provides default text for the link if no specific text is selected.

• link: Contains the URL that will be applied when creating the link, with the possibility of using placeholders.

{
    type: 'A link type', // will not be shown
    label: 'Text', // Will be used as default text when text is not selected
	link: 'http://...' // The URL that will be applied. Placeholders can be used
}

Merge Contents

Merge contents is a feature that allows you to consolidate multiple content sources into a unified display. This section will cover how to configure this feature and its most common use cases.

Merge Contents Configuration

1. Access the configuration file of your application.

2. Locate the contentDialog object within the file.

3. Add a mergeContents property to the contentDialog object.

4. Inside the mergeContents property, set a label with the description you want to appear, such as 'Set up a new product recommendation'.

5. Implement a handler function that will process your custom logic. This function should accept two parameters: resolve and reject.

6. Insert your specific code inside the handler function where indicated.

Your configuration should look like the following:

contentDialog: {
	mergeContents: {
		label: 'Set up a new product recommendation',
		handler: function(resolve, reject) {
			//your function goes here
		}
	},
},

The content dialog adds a button to the merge content list as shown in the following image.

Most common use cases

A few of the most common use case for merge contents are the following:

• Set up the content and/or layout for a product recommendation

• Set up the content and/or layout for a dynamic advertising

• Set up the content and/or layout for another type of targeted content

Value

In the following code snippet, the properties perform the following tasks:

• name: This property specifies the display name of the content. It appears in the editor UI and helps users identify the content item within the messaging interface.

• value: This property represents the actual content that will be injected into the HTML output, shown in the preview. The {{ syntax }} is typically used for dynamic content insertion.

{
	name: 'Content name', // Will be displayed in the editor UI and in the message
	value: '{{ syntax }}' // Text string that will be added to the HTML output (will be show in the preview)
}

Display Conditions

Display conditions allow you to control when specific content is shown based on predefined criteria. This section will cover how to configure display conditions in your application and common use cases.

Display Conditions Configuration

To configure display conditions in your host application, take the following steps:

1. Define the contentDialog Object: Start by defining an object called contentDialog in your code. This object will hold the configuration for the display conditions.

   Copy

   contentDialog: {
       // Configuration properties go here
   },

2. Add the rowDisplayConditions Property: Within the contentDialog object, add a property named rowDisplayConditions. This property will specify the conditions under which a particular row is displayed.

   Copy

   contentDialog: {
       rowDisplayConditions: {
           // Properties for display conditions go here
       },
   },

3. Set the label Property: Inside the rowDisplayConditions object, define a label property. This property sets the text label for the display condition. For example, to set the label as "Open builder":

   Copy

   contentDialog: {
       rowDisplayConditions: {
           label: 'Open builder',
       },
   },

4. Define the handler Function: Add a handler property inside the rowDisplayConditions object. This property is a function that determines the logic for your display conditions. It accepts two parameters: resolve and reject, which are typically used for promise handling.

   Copy

   contentDialog: {
       rowDisplayConditions: {
           label: 'Open builder',
           handler: function(resolve, reject) {
               // Your function goes here
           }
       },
   },

5. Implement the Display Logic: Within the handler function, implement the logic to determine whether the row should be displayed. Use the resolve function to indicate the conditions are met, and the reject function to indicate they are not.

   Copy

   contentDialog: {
       rowDisplayConditions: {
           label: 'Open builder',
           handler: function(resolve, reject) {
               // Your custom logic to determine display conditions
               if (/* condition */) {
                   resolve();
               } else {
                   reject();
               }
           }
       },
   },

6. Complete the Configuration: Make sure your configuration object is properly closed and integrated into your application. Ensure that all necessary conditions and logic are correctly defined within the handler function.

   Copy

   contentDialog: {
       rowDisplayConditions: {
           label: 'Open builder',
           handler: function(resolve, reject) {
               // Your custom logic to determine display conditions
               if (/* condition */) {
                   resolve();
               } else {
                   reject();
               }
           }
       },
   },

A new button will be available in the display condition widget. In this example, the button says “Open builder”, which is the label shown in the JSON configuration file shown above.

Most common use cases:

A few of the most common use case for display conditions are the following:

• Display a condition builder or form to target a segment of recipients

• Display a form to create a loop with the row dynamic contents, as product recommendations

Value

The following code snippet configures a display condition with a specific label, description, and delimiters that define the start and end of the condition block in the template. This will be shown in the editor UI and inserted around the selected row based on the specified conditions.

{
	type: 'A category for this condition', // Will not be shown
	label: 'Condition', // Will be displayed as the condition name
	description: 'Small text describing what the condition does', // Will be displayed in the editor UI to identify the condition action
	before: '{% if something == \'Condition\' %}', // Will be added before the selected row
	after: '{% endif %}', // Will be added after the selected row
}

An example

In this example, a window is shown to users when they click on the button to open the builder.

The UI is entirely up to the hosting application. Here, the developer decided to offer some fields at the top where the Display Condition can be named and described, an area below it where parameters, values, and operators can be selected, and a preview on the right.

When users click on “Confirm”, the information is passed back to the editor and shown in the properties panel.

Of course, it can be edited in the editor like any other Display condition, if the user has the rights to do so.

Reference our Advanced Permissions documentation to learn more about managing the visibility of the Add Condition and Edit Condition buttons.

Custom Rows

Custom rows allow you to import products or news using various patterns, set up predefined content layouts, and create dynamic sections for recommendations, codes, and advertisements. This section will discuss how to configure custom rows in your host application.

Custom Rows Configuration

The following code snippet displays an example of how to configure custom row.

contentDialog: {
    externalContentURLs: {
            label: 'Search products',
            handler: function(resolve, reject) {
                // Your function
        }
    }
}

The content dialog adds a new item, using your text label, in the Rows drop-down:

Most common use cases

A few of the most common use case for custom rows are the following:

• Import a set of products or news, as custom rows, using a categories pattern, a search form, or a visual browser

• Set up the row layout for a set of predefined contents

• Set up rows with dynamic content to build dynamic sections that provide product recommendations, QR or bar codes, advertising content, etc.

Value

The following code snippet configures a custom row with a specific name and value. This will be shown in the editor UI in reference to a specific custom row based on the specified conditions.

{
    "name":"Results name", // Will be added as a new choice in the rows drop-down
    "value":"https://..." // Will be used to get the list of rows
}

This response will:

1. Create a new drop-down choice with the provided name

2. 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:

1. Returning the same name

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.

2. Returning a new name

This creates a new drop-down choice, keeping the previous results as selectable elements. Previous results are available directly in the drop-down. Usage example:

Synced Rows

Synced rows are rows that are used across multiple designs, ensuring consistency when updates to a row are made. This section will cover how to configure synced rows in your application.

Synced Rows Configuration

The following code snippet displays an example of how to configure synced rows.

contentDialog: {
    editSyncedRow: {
		label: 'Edit synced rows',
		description: `This row is used in other designs.
					  You can decide to update all the designs or transform this single row into a regular one`,
		notPermittedDescription: `This row is used in other designs.
                                  Your plan does not permit you to edit it. Please contact your account administrator`,
        handler: function (resolve, reject, args) => {
        	resolve(false) // the boolean will be the value of  'Label of the sidebar button that triggers the contentDialog'`synced`
                           // if false the row will be un-synced, if true nothing will happen.
    	}
    }
}

The label, description and notPermittedDescription fields handle the wording related to the “Edit synced row” call-to-action/button. Here’s how and where they are used:

• label: Label related to the sidebar button that triggers the content dialog

• description: Description of the action on top of the button

• notPermittedDescription: Description of the action when the button is hidden from the dedicated advanced permission

Here’s an example of what label and description would look like:

And here’s an example of what notPermittedDescription would look like:

Save Rows

Save rows refer to the functionality that allows users to save changes made to specific rows in a data table. This section will discuss how to configure the Save rows feature in your host application.

Saved Rows Configuration

The following code snippet displays an example of how to configure save rows.

contentDialog: {
    saveRow: {
        handler: function (resolve, reject, args) {
            // Your function
        }
    }
}

Unlike the rest of content dialog configurations, Save rows doesn’t use the label parameter as the UI element is a save icon displayed on the selected row (and in the row’s properties panel):

The Save rows content dialog is a mandatory step in the Save rows workflow.

The resolve function must return metadata for the selected row. The metadata section of the rows schema allows you to keep track of row-specific information.

The args object in the handler function returns to the host application metadata already applied to the selected row.

Value

The following code snippet configures a save row with a specific name and category. This will be shown in the editor UI in reference to a specific saved row.

{
    "name":"Row name", // Mandatory metadata
    "Category":"A row category" // If you provide category management for saved rows
    "...":"..." // You can add as metadata as your application needs
}

This response will provide metadata that is added to the row in the asset (email, page, popup) before it’s provided through the Save Rows callback.

The row name is the only required metadata and it’s displayed as the row title in the Rows panel:

• A string of plain text that identifies the row.

• Displayed in the row card when the row is shown in the Rows panel.

• Used for text searches within the Rows panel

Check the Saved rows metadata section for further details on recommended metadata.

Forms

Forms are interactive elements that allow users to input and submit data. This section will discuss how to configure forms to meet specific requirements in your host application.

Forms Configuration

The following code snippet displays an example of how to configure forms.

manageForm: {
	label: 'Edit form',
	handler: async (resolve, reject, args) => { 
		// Your function
	} 
},

If you want to have total control on the forms that a Beefree SDK application displays and renders, you can use this forms Content Dialog rather than passing a single form to the Beefree SDK application.

The forms Content Dialog works the same way as the previous Content Dialog for save rows – but in this case, the resolve function should return the structure for the desired form.

The args object in the handler function returns to the host application the form object already applied. With this information, the application can decide what to display to the user (e.g., edit the current form, suggest a similar form, etc.).

To understand how this data is structured, refer to the form structure page on this website.

Custom Attributes

Custom attributes are user-defined metadata that can be added to links and images within an editor. This section will discuss how to configure custom attributes in your host application.

Custom Attributes Configuration

The following code snippet displays an example of how to configure custom attributes.

        customAttribute: {
          label: 'Search Attributes',
          handler: (resolve, reject) => {
            resolve({
              key: '2783f0ea-f6af-44f3-856e-d7a01cd87714',
              name: '100% Custom',
              value: 'My custom value',
              target: 'link',
            })
          }
        },

If your end users need to apply custom attributes to the links and images in their content, you can completely customize the user experience and workflow for adding those attributes with a Content Dialog that will take over the editor’s UI. The dialog will need to return the attribute to apply.

Custom Video

Custom video allows you to integrate and configure videos from custom sources other than standard platforms like YouTube and Vimeo. This section will discuss how to configure custom video for your host application.

Custom Video Configuration

The following code snippet displays an example of how to configure custom video.

addVideo: {
  label: 'Choose a video',
  handler: async (resolve, reject) => {
    resolve({
      videoSrc: 'https://link.to.your.custom.video', // mandatory
      thumbSrc: 'https://my.beautifulimages.com/thebest.jpg', // mandatory
      thumbAlt: 'The title of my custom video!', // optional
    })
  }
}

It is possible to leverage the Content Dialog method to add videos from custom sources – other than YouTube and Vimeo.

You can use the addVideo Content Dialog modal, which will take over the builder’s UI. The video will be added as a thumbnail in the content area.

The user must fill out the video URL from a custom source, the image used as a thumbnail, and an alt text/title by implementing a custom modal window (optional). When the user clicks on the video thumbnail, it will open videoSrc in a new tab/window.

Overview

With Custom Attributes, your end users can easily append additional information to HTML tags in emails and web pages, at the same moment they are creating their content in Beefree SDK. These attributes can be applied to links, both in text blocks and buttons, and images, and they serve a variety of scenarios: personalization, segmentation, styling, accessibility, etc.

Use cases

Custom attributes enable a wide array of use cases, depending on your application’s capabilities and your users’ needs. Here are a few examples:

• flagging specific links so that user activity for those won’t be tracked (e.g. clicktracking="off” in SendGrid);

• handling internal statistical segmentation or reporting (e.g. data-reportingname="October_promo" data-reportingtags="promo,iphone");

• adding conditions to a single content element (using an attribute such as condition="customer_exists");

• embedding a single image by adding an attribute like embedded="true", processed when the message is sent;

• adding custom CSS classes for custom CSS;

• adding WAI-ARIA attributes for accessibility requirements.

How it works

The host application can provide the editor with a list of attributes that will be available to the user through the UI. How the attribute value is formatted impacts how the builder UI displays it and how the user interacts with it.

Custom attributes can be applied to:

• Links in text blocks

• Links in buttons

• Images (including thumbnails generated by the Video block)

For images and buttons, these attributes will be visible in the editor sidebar, under the new “ATTRIBUTES” section.

For links in text blocks, they will be part of the dialog window for creating a link.

You can provide the editor with a list of attributes that will be available to the user through the UI. How the attribute value is formatted impacts how the builder UI displays it and how the user interacts with it.

Depending on how custom attributes are implemented, users may:

• add a custom attribute from a list of attributes already defined, and specify the value of the attribute, if appliable:

  • from a predefined list

  • in a text input

  • defining a boolean property (yes/no, true/false, etc.)

• add a “custom” custom attribute by manually specifying both name and value

• open an additional interface, through a content dialog, where users have complete freedom on how to build custom attributes.

Regardless of how a custom attribute is added, it will be included in the a or img tag when HTML is generated for an email/page, like the segment attribute in this hyperlink:

How to activate it

Custom attributes are a client-side configuration that needs to be passed when initializing the editor. There are different shades of implementation complexity, based on the outcome you want to obtain. These approaches can be combined as preferred.

Basic

The easiest implementation is to just pass a simple configuration at startup:

With this setup, users can indicate a “Custom” custom attribute by manually specifying Name and Value. Please note that users must know exactly what they are doing, as there will be no guidance in the editor.

Standard

You can pass the necessary custom attributes in the initial configuration. Those attributes will be available in the interface, and the user will be able to specify the value for these attributes, if possible.

Let’s look through the attributes defined in the example above, and how they will look like in the builder.

The Deeplink attribute has a single, predefined value, so when added in the builder it will look like this:

The Segment attribute has two possible values, which can be selected by the user:

The Class attribute has no defined value, so the user can enter anything in a text input:

Advanced

Overview

With Meta Tags, you can now apply various tags to your HTML that can greatly benefit your SEO and accessibility needs.

These Meta Tags include:

• Title

• Description

• Subject

• Preheader

• Language Attributes

For the Email Builder, Meta Tags promote improved deliverability performance. For the Page Builder, Meta Tags promote greater customization and improved search engine results.

Page Builder

The following image displays the Title and Description fields from within the page builder.

Title

A page title, also known as a Title tag, is a short description of a webpage that appears at the top of a browser window and in SERPs (Search engine results page). This is an important element of an optimized SEO page, as it affects the page ranking in search engines. The title tag will be located within the <title> element of a page’s HTML output, and its value will be saved inside the JSON template.

Here is an example of what a Title Tag inside Beefree SDK’s HTML output might look like:

Description

The description tag is located within the <meta> tag element of a page’s HTML, and it has a limit of 190 characters. The tag will be located within the <meta> element of the page’s HTML output, and its value will be saved inside the JSON template.

Here is an example of what a description tag inside Beefree SDK’s HTML output might look like:

JSON Page Builder Example

The following code snippet is an example of what the Meta Tags will look like inside the JSON.

Email Builder

The following image displays the Subject and Preheader fields from within the email builder.

Subject

The subject field has a maximum of 190 characters. Here is an example of what a subject tag inside Beefree SDK’s HTML output might look like:

Preheader

The preheader field has a maximum of 130 characters. Here is an example of what a preheader tag inside Beefree SDK’s HTML output might look like:

JSON Email Example

The following code snippet is an example of what the Meta Tags will look like inside the JSON.

Language Attribute

The HTML lang attribute is used to identify the language of text content on the web. This information helps search engines return language-specific results, and it is also used by screen readers that switch language profiles to provide the correct accent and pronunciation for accessibility purposes.

When loading the builder, the host application can specify in the configuration a list of languages for their users to choose from (e.g. en-US), see the example below where the only option “Italian, it-IT” is provided. If there are no values provided via configuration file, a standard list of common languages will be provided.

Here is an example of what a language attribute inside Beefree SDK’s HTML output might look like:

How they work

Display conditions allow you to change the content that is shown to a recipient of an email depending on who the recipient is.

Your users will have the ability to pick a condition (or write one from scratch if they are technically savvy), apply it to a row, and thus show different content based on who the recipient (or viewer) is.

The feature provides a number of benefits, including:

Ease of use for email designers

Display conditions allow anyone that is using the builder to easily create personalized messages without writing a line of code.

Any syntax for the conditional statements

Use whatever syntax your application understands. The feature is language agnostic: it can be used with whatever syntax matches your tech stack. Does your sending engine understand the Liquid markup? Then you can use Liquid. Does it use a proprietary templating language? No problem.

User permissions

Restrict access to some of the functionality based on user roles. For example, some users may be able to edit the syntax of the conditional statements, while others may not. Use this flexibility to simplify the UI or promote upselling.

Activating and using the feature

As the application hosting the builder, you can now pass an array of conditions.

Those conditions become available for users of the editor to select, assuming the feature is turned on and the user has permissions to apply a condition to a row.

They will do so by browsing through categories or searching by keyword. For example…

The condition that they pick is applied to the row and displayed when the row is selected.

It can be changed (i.e. the user decides to apply another condition) or edited (if the user has the technical skills to do so, and its user role has been granted those permissions).

When the Preview feature is accessed, users can now simulate what recipients in a certain segment will see by toggling Display conditions on and off.

Display conditions and user roles & permissions

When active, the feature is available to all users by default. You can manage who can see and/or do what by leveraging user roles and permissions.

When the feature is ON, new permissions are available for you to configure when you create or edit a Role.

A basic set up allows you to have 3 user levels:

1. Can only view & preview

   • None of the above options are selected

   • No widget will be shown unless the loaded message has display conditions assigned to one or more rows

   • If conditions are applied:

     • They are shown as ready-only

     • They can be applied in the Preview

2. Can only select

   • Only Can select conditions option is selected in the role settings (remove will be automatically selected too)

   • The widget shows and the user can select and apply any of the conditions specified in the editor configuration

   • The user cannot add a new condition

   • The user cannot edit a selected condition

3. Full control

   • All permissions are selected

   • The user can select and edit conditions (if provided) or add a new condition

Note: if there are no Display conditions passed in the configuration, and the user has the rights to access the feature, the editor will only show the Add condition action, which allows users to apply a new condition to a row by manually adding the condition’s syntax.

Additional information

Identifying a row with an applied display condition

It’s easy to identify a row to which a display condition has been applied. A bifurcation icon is added to the row’s “Structure” tag, which is shown as you mouse over the row. Here’s an example:

Custom conditions

When a default Display condition is edited – by a user that has permissions to do so – it becomes a custom condition. Custom conditions are easy to recognize because:

• A blue dot is added next to the condition’s name

• The “Change condition” button is no longer available: a custom condition can only be removed

• The cancel icon is replaced by a trash button because an edited condition, once remove, is lost: it cannot be re-added.

Why these different behaviors for custom conditions? Because Beefree SDK does not save them to the configuration (you passed that configuration to the application: we don’t have access to the repository where you save that information). So, custom conditions do not exist in the array of conditions that the user can search and/or browse.

HTML output

Conditional syntax and row content are isolated from each other in the HTML generated by Beefree SDK, so your system can delete, repeat or change elements inside the row without impacting other parts of the message. For example, the HTML of a row might look like this:

Extending Display Conditions

Here is an example of a custom builder of Display Conditions.

Overview

With Commenting, teams using your application can collaborate asynchronously on the same email, page or popup, in order to get their work done more quickly and reach approval for going live more efficiently.

When Commenting is enabled, your end-users (or contributors, as we’ll call them in this context) can:

• Add a new comment in any content block or row, so that the context of the discussion is always visible;

• Reply to an existing comment and start a thread;

• Mark existing threads as resolved, and reopen solved threads if necessary.

• Copy the text of a comment, and paste it back to the content area

• Preview comments by hovering over the comment icon

• Automatically highlight the row where a thread is posted

• Receive a notification straight in the builder when a new comment is added during a co-editing session (Superpowers users only).

Use cases

With Commenting, you enable asynchronous, visual collaboration when multiple collaborators are creating, editing, and reviewing content in the Beefree builders. This collaborative feature can prove extremely beneficial in different contexts, regardless if contributors are in the same team, in separate teams, or even in different companies (e.g. digital marketing agencies collaborating with their clients):

• have a single source of truth for feedback and requests on the content created with the builders;

• cut time-to-publish, reducing back and forth conversations, both online and offline;

• get sign-off for going live for email and web campaigns more efficiently.

How to activate it

Commenting – like most other features – is made available to Beefree SDK customers in an OFF state by default, and must be activated in the Beefree SDK Console.

To do so:

• Click Details next to the application you want to configure

  • We recommend you first familiarize with Commenting in a Development or QA application
• Click view more under Application configuration.

• Toggle Enable commenting ON and click the Save button to activate Commenting for the application.

To activate Commenting when launching your Beefree application, you will need to pass a username, userHandle, and a userColor in the configuration parameters. See this example:

How it works

Adding comments and starting threads

When opening an email, a landing page or a popup, a contributor can add a new comment to a content block or a row by clicking the “Balloon” icon, available in two spots:

• in the row or block outline, inside the editing stage

• in the header of the Row properties or Content properties

Clicking one of these two icons will activate the commenting panel, which takes over the editor sidebar. From there, the user can insert a new comment. After the first comment, another contributor can start a thread by adding a second comment.

Mentioning someone in a comment

If you have implemented mentions, users can type @ to bring up a list of contributors and tag them in the comment. If the user starts typing, the list will be filtered If you’ve built a notification system around Commenting, you can use this piece of information to trigger a notification towards the mentioned person.

If you added a Content dialog for mentions, the action will be triggered by the button at the end of the list. You will define the CTA for this button as part of the Content dialog configuration (in this case, “Send an invite”).

Interacting with threads

If there has already been some activity, the editing stage shows whether a content block or row has any comments by displaying a small comment icon. The sidebar instead indicates the number of existing comments for the selected row or content block, three in this case.

Activating the Commenting panel will bring up the thread. In this case, it will show the three comments.

Existing comments can be edited or deleted by the contributor that added them. Contributors may also resolve comments when they have reached a consensus and completed any pending task.

Improved accessibility to in-line threads. Hover the mouse over the comment icon to see a preview of the last comment added.

Browsing threads and closing the commenting panel

Clicking on < All comments in the top section will bring up a list of all comment threads, indicating which ones have been resolved and which ones are still open. Contributors can search inside comments and filter out solved threads, or threads that were part of deleted content. Deleted and hidden comments will be filtered automatically.

To go back to the editor sidebar, contributors can close the Commenting panel by clicking the X icon in the upper right, or they can just click on another row or content block in the stage.

Quickly reopen resolved threads by adding a new comment, expand threads with a click, and show a comment thread preview straight from the content area.

Copy comment text and paste it to content area

Suggest edits in seconds, and save time with the copy/paste feature. Copy text from the comment body and paste it directly into the content area.

Real-time notifications when a new comment is added

The Reviewer Role

With the Reviewer role, you can now allow users to collaborate on your projects without changing the design. This role helps provide peace of mind by allowing inexperienced users to work with the team on their designs, without fear of accidentally changing it.

In short, this new role has the following characteristics:

• Can’t apply changes to the message

• Can add comments and start threads

• Can edit their own comments

• Can view other comments

This new role can be easily enabled by passing the following parameter in your configuration:

Once you turn on the feature in the Beefree SDK Console, you may want to disable Commenting for some customers. You can do so via the client-side configuration document that you feed to your Beefree application when initializing the editor.

Why? Because you may decide to make the feature available to customers of your application:

• depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use Commenting);

• depending on the purchase of an optional feature (same);

• only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.

Here’s how to do so:

• Enable Commenting in the Beefree SDK console, as mentioned above.

• Add the configuration parameter commenting to the beeConfig document

• Set it to false for all users that cannot comment.

Here is a simple example:

Managing notifications

You can build a notification system around commenting by triggering a callback for events in the Commenting layer. When these events happen, the Beefree system triggers the onComment callback.

You can react to that callback by taking the information provided in it (e.g. the user that created the comment, the text of the comment, any mentioned user, date & time of the comment, etc.) and send notifications.

You are free to define:

• which events will trigger a notification

• how it is sent (e.g. Email, In-app, Slack, etc.)

• what exactly it says

Again, remember that the Beefree platform only triggers the callback, and it’s up to you to react, if you want. Below you can find the technical details on the comments schema and the onComment callback.

Sample code for email notifications

• Define an array to hold the list of mentioned users in the comment payload.

• Loop through the comment payload and add any strings matching a regex to the array

• Compare each value in the array with the ‘handle’ property of each user (as defined by the host application), to grab the active users

• Loop through your array and pull the respective email address for the handle matches (for use in notifications)

• Send the notification through email (via ajax), slack, etc… (you decide and implement how to send the notification)

The following JSON is saved as part of the template:

You may want to save multiple copies of a template, e.g. to create a history/revision or a draft feature.

In such cases, you may decide to store the comments in a database, and add the schema back to the template when it’s loaded. Alternatively, you can keep the comments inside the template, and it will become a static part of the history.

Comments can also be added dynamically, but it’s an advanced task, which requires matching the comment schema to the target content by its “elementId”.

Commenting Callback

When a thread or comment changes, the Beefree system triggers the onComment callback. The callback returns the following details:

change

• JSON contains all the details on the change

comments

• JSON array of the entire comments schema, as described in the previous section.

threadUsers

• JSON contains the contributors array with all users in a thread.

Change Schema

type

• NEW_COMMENT

• COMMENT_THREAD_RESOLVED

• COMMENT_THREAD_REOPENED

• COMMENT_EDITED

• COMMENT_DELETED

payload

JSON contains all the details of the change

Example of new comment payload

Adding mentions

You can activate a mention dialog for comments by adding a data source to the Beefree application configuration. You can use the “Hooks” data source method to fetch data from your application and pass it to the Beefree system in real-time.

To configure a hook data source, define the hooks section in your bee config and implement the getMentions method.

You can also extend the default mention dialog via Content Dialog. For example, you can enable end-users to to invite an external user not available in the data source.

To configure a hook content dialog, define the contentDialog section in your Beefree application configuration and implement the getMention method.

You can generate a link to a specific comment, which can be used to notify the user. Common use cases include sending a link via email, Slack, API, or via in-app messaging. To implement this action use the onComment callback combined with a new instance method called showComment.

Here’s how it works:

The onComment callback contains the comment’s id and a new section called “mentions” containing an array of mentioned users’ uid values.

With the uid, your application can look-up the user’s contact details. The Beefree platform does not track any sensitive information, such as user emails!

Similarly, since mentions can trigger events and the uid can generate notifications, you can match uid to userHandle.

Next, using the comment’s id, your app can generate a link back to the email containing the comment. The new showComment instance method can be invoked from Beefree’s onLoad callback to send the user directly to the comment as soon as the editor is fully loaded and ready.

Note: In the sample below, getParameterByName is a function that takes the commentId from the browser’s URL query string.