Extending the editor

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 at the time 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.

Technically, special links are passed to the plugin in the configuration file as follows...

specialLinks: [{
 type: 'Subscription',
 label: 'Unsubscribe',
 link: 'http://[unsubscribe]/'
}, {
 type: 'Subscription',
label: 'Subscribe',
link: 'http://[subscribe]/' }];

To the user, they become available as a special button in the expanded text toolbar.

Group links 

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

In the example bellow we grouped the more used links under the same type, so the user will find them quickly:

specialLinks: [{
 type: 'Frequently used',
 label: 'Unsubscribe',
 link: 'http://[unsubscribe]/'
}, {
type: 'Frequently used',
label: 'Subscribe',
link: 'http://[subscribe]/'
}, {... 

 

 

Merge tags and merge content

As mentioned above, when you initialize the plugin, 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 as an image.

Here is an example of creating 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}'
}];

Let's dig a bit deeper.

 

Merge tags

Merge tags can be inserted into a block of text by clicking on the "Merge tags" button in the expanded text block toolbar. The button is not shown if no merge tags were submitted to the plugin 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 editor in the configuration file.

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

 

Merge content

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 some syntax that will be replaced at send time with an image (e.g. a dynamic banner ad by a service like LiveIntent): that image is a content element in the message, and needs to be treated as such.

Therefore, when merge content elements are submitted to plugin 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 this example, 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 panel, or duplicate the existing content element...

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

... and then drag it elsewhere in the message.

NOTE: you can now handle dynamic images also with a different feature that was created specifically for that task. See: add dynamic images to your emails.

Limitations

Merge tags and Merge content are meant to be placeholders that will be replaced at the time the message is saved or sent. There are a couple of limitations.

You cannot use HTML code in the text strings passed to the editor 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.

Next step

Initializing the editor: create, start and load.

Have more questions? Submit a request

Comments

  • Avatar
    Robert Egginton

    How are these links, tags and contents used in the editor? Are these placeholders that can be picked from a toolbar or menu, or are they entered as tags e.g. [tag1]? Can these be replaced with example content in the preview?

  • Avatar
    Massimo Arrigoni

    Hi Robert, to answer your questions:

    • Special links are added in various areas of the editor UI (this is still partially under construction).
    • Merge tags are available automatically by entering @ while writing text. A list of merge tags is shown dynamically when you do so. This allows you to quickly write "My [first_name]", with "[first_name]" being the merge tag name and syntax used by your application to identify the recipient's first name. Your application is the one that will do the parsing of the message at the time of sending. BEE simply creates the message.
    • No, the preview currently does not replace merge tags with sample content, but this is a great idea and something that we can certainly add in the future.

    Thanks for the questions and your feedback. Let us know if you need more details.

  • Avatar
    Robert Egginton

    Thanks for the response. I could not see these appear in the beta plugin, but I will take another look.

  • Avatar
    Massimo Arrigoni

    Hi Robert, I updated the reply above a bit to clarify how you access merge tags in the editor.

  • Avatar
    Robert Egginton

    Thanks - that's really helpful.

  • Avatar
    Jason Navarro

    Hello! I am able to get the merge tags dropdown menu to show with the @ symbol but I don't see a drop down menu for merge contents as well as special links. Just wondering how these work as well. Thanks!

  • Avatar
    Massimo Arrigoni

    Hi Jason, merge content is currently available by using the "!" key (exclamation mark) on the keyboard when editing a text block via the text editor.

    We are reconsidering this feature to make it work differently. The idea would be to separate the two so that:

    (a) Merge tags -> available in text editor (e.g. "Dear {first_name}" or alike)
    (b) Merge content -> available as content item (e.g. {latest_product_viewed} = image of latest product viewed by that person, which clearly does not belong in a text block)

    Please note that this has not been finalized. It's currently under discussion.

    We will post an update soon, but in the meantime please let us know if this new implementation would or would not address your needs.

    Thanks much!

  • Avatar
    Justin Wellesley-Smith

    Hi Massimo,
    Is it going to be at all possible to insert custom widgets onto the content tab? Something that can be dragged onto a template?

  • Avatar
    Massimo Arrigoni

    Yes, this is a feature that's already on our roadmap. There are different "flavors" of it that we are looking at. If you have specific use cases in mind, we'd love to hear more details.

  • Avatar
    Justin Wellesley-Smith

    We are a Real Estate Franchise group so we would have a 'Property' widget that when dropped would prompt the user to choose a property. When selected we would want to autofill content in the widget.
    Hope that makes sense.

  • Avatar
    Massimo Arrigoni

    Hi Justin: got it. To further clarify: would you want the user to drag into the message a "merge content tag" (e.g. {property_details}, replaced by your app at the time of sending the message, syntax of the tag totally up to you), or would you want the user to be able to see N properties (e.g. passed to the BEE as a JSON file), pick one and drag it into the message?

  • Avatar
    Justin Wellesley-Smith

    The later I think. We currently only have merge fields from the contact list.

  • Avatar
    mark

    Whats the status on the mergeTags functionality. I can't seem to get it working

  • Avatar
    Massimo Arrigoni

    Hi Mark, there should not be issues with the merge tags feature. What problems are you having? Can you confirm that you are using the correct syntax?

    var mergeTags = [{
    name: 'tag 1',
    value: '[tag1]'
    }, {
    name: 'tag 2',
    value: '[tag2]'
    }];

  • Avatar
    Devin Dixon

    @Robert, one solution for replacing tags is recursively iterating through the array and doing a find replace.

    var jsonFindReplace = function findAndReplace(object, value, replacevalue) {
                for (var x in object) {
                    if ( typeof object[x] == 'object') {
                        findAndReplace(object[x], value, replacevalue);
                    }
    
                    if (typeof object[x] === 'string' || object[x] instanceof String) {
                        object[x]= object[x].replace(value, replacevalue);
                    }
                }
            };
    

    BeePlugin.create(JSON.parse(attrs.accessToken), $rootScope.beeConfig, function(beePluginInstance) {
    bee = beePluginInstance;

                $http({
                    url : '/json/invite.json',
                    method : "GET"
                }).then(function(template) {
                    jsonFindReplace(template.data, '[community_name]', 'Bobs Community');
                    bee.start(template.data);
                }, function(response) {
                    console.log('Error');
                    // called asynchronously if an error occurs
                    // or server returns response with an error status.
                });
            });
    
  • Avatar
    Robert Egginton

    Thanks Devin for the example of how to replace the placeholder data after the template is saved. That is certainly useful but, just to be clear, my suggestion was to allow for example data that could be toggled for display within the editor.

    P.S. Thanks for the laugh from the original version of your reply ;)

  • Avatar
    Andre Santos
    Just downloaded the demo code and was trying to use merge content tags but I don't see any Dynamic Content tile being created. mergeContents is defined as such: var mergeContents = [{ name: 'content 1', value: '[content1]' }, { name: 'content 2', value: '[content1]' }]; is this not yet implemented in the production code or am I not seeing clearly?!? demo code was downloaded from: https://github.com/BEE-Plugin/ClientSIde-code-sample
  • Avatar
    Tom

    Having some issues with the Special Links, using the examples provided, the types are being turned into groups. How would I have links without groups? Thanks.

    Screenshot: http://i.imgur.com/fTwA8iG.png

    In the config I'm using the example provided:

    {
    specialLinks: [{
    type: 'unsubscribe',
    label: 'SpecialLink.Unsubscribe',
    link: 'http://[unsubscribe]/'
    }, {
    type: 'subscribe',
    label: 'SpecialLink.Subscribe',
    link: 'http://[subscribe]/'
    }],
    ...snip
    }

    Removing the 'type' parameter returns an error.

    Edited by Tom
  • Avatar
    Guille Padilla

    Hi Tom, the links need a type parameter, it will be used to group them.
    Currently there is no option to create links without groups.
    Sorry for the misleading example, I updated it to match the current behaviour.

    Edited by Guille Padilla
  • Avatar
    Tom

    Cheers, thanks for the fast reply.

  • Avatar
    Nick

    Hi,
    Anyway to group the merge tags like the group links.
    Thanks

  • Avatar
    Guille Padilla

    Hi Nick, not yet, but something we will add in the future.

  • Avatar
    Nick

    Hi,
    I'm using Beefree with Startup Plan.
    Is there any ways to put another field inside the editor ? Field "Subject" for example.

  • Avatar
    Guille Padilla

    Hi Nick, not inside the editor, but you can replace the entire top-bar of the editor with your own. In this case, UI and subject data is completely managed by your application.
    More info about the toolbar options in: http://help.beefree.io/hc/en-us/articles/204783212-Server-side-configurations

  • Avatar
    dave

    Hi, any progress on making Dynamic Content visible/available in preview mode?

    Seems quite limiting that you can add a content block but never see it until after it's been saved and used because the preview removes all HTML code.
    thanks

  • Avatar
    Marian Galik

    Hi, it would be very helpful if I could specify not only name and value for merge content, but also some user adjustable arguments, that the user could enter inside the UI of beefree.

    Something like this:
    ```
    var mergeContents = [{
    name: 'Similar products',
    value: '{similar-products product-id={product-id}}',
    params: {
    productId: {type: 'string'}
    }
    }, {
    name: 'Top selling products',
    value: '{top-selling-products count={count}}',
    params: {
    count: {type: 'number', min_value: 3, max_value: 10}
    }
    }];
    ```
    The only way around to do stuff like this is to create a separate merge content for every possible parameter combination, which is not very intuitive from UX perspective.

    Any chance, that similar feature will be implemented?

  • Avatar
    Massimo Arrigoni

    Hi Marian, thanks for your feedback. The problem is that there are so many use cases, that it's hard to handle them in a sensible way. For example, in your case the input would be just a numeric value. However, in other cases it could a selection from a drop down, a text input, etc.

    Still, your request makes perfect sense and it is something that we are looking at, along with the idea of allowing you to pass sample content, so that the dynamic block provides an actual preview of how the message will eventually look like when it's sent.

    If you have additional comments, requirements, etc. on this, certainly let us know.

  • Avatar
    Ty Rocca

    Is there a way to group merge tags like you group links?

  • Avatar
    Guille Padilla

    Not yet, but we know that would help in some cases, so it's something that we plan to add in the roadmap soon.

  • Avatar
    Jake

    Hi there... merge content is really powerful, but one of the biggest missing pieces for me is the ability to specify style parameters.

    When a user clicks on a text or image content block, for instance, they get given a set of style options for that block - colors, padding, etc. Similarly, if I've created a custom content block, I'd like my users to be able to customize certain aspects of its style. For instance, I might let them add a dynamic table of recent purcahses - we could let them customize the font, the cell padding, the border colors. Obviously we as developers would need a way to say what can be customized when specifying the merge content. (To Marian's comment, it would be AMAZING to specify parameters too, like "Number of purchases to include".)

    On another note, custom content blocks would be much more discoverable to the users if they looked and behaved more like the other content blocks... that is, they'd have their own icons in the CONTENT tab. Perhaps this tab could have a new group of blocks called "Dynamic Content", and we can specify icons and names for each of our merge content blocks listed there.

    Edited by Jake