Configuring the editor

Once you have initialized BEE Plugin, you can pass a series of configuration parameters to it.

Here is a brief description of the parameters:

Parameter What it does Required?
uid

An alphanumeric string that identifies the user and allows the plugin to load resources for that user (e.g. images). Learn more about the UID parameter.

  • Min length: 3 characters
  • Can contain letters from a to z (uppercase or lowercase), numbers and the special characters "_" and "-"
Yes
container Identifies the id of div element that contains BEE Plugin Yes
autosave Integer that defines every how many seconds the message should be auto-saved. Minimum value: 15. No, defaults to "false"
language 4-letter language identifier (e.g. "en-US"). No, defaults to "en-US"
specialLinks An array of custom links that may be used in the message (e.g. unsubscribe). See example. No
mergeTags An array of merge tags that may be used in the message (e.g. first name of the recipient). See example. No
mergeContents An array of content elements that may be used in the message (e.g. small blocks of HTML). See example. No
preventClose Whether an alert should be shown when the user attempts to leave the page before saving. No, defaults to "false"
roleHash Identifies the user role (see roles & permissions).
  • Min length is 8
  • Max length is 30
  • Can contain letters and numbers
  • No white spaces
  • No special characters such as "_" and "-"
No

 

In addition, you can specify functions to handle saving a message, saving the message as a template, sending a test, and handling errors.

The default configuration for BEE Plugin will therefore be something like the following:

beeConfig: {
uid: 'CmsUserName', // [mandatory] identifies the set of resources to load
container: 'bee-plugin-container', // [mandatory] the id of div element that contains BEE Plugin
autosave: 30, // [optional, default:false] in seconds, allowed min-value: 15
language: 'en-US', // [optional, default:'en-US'] if language is not supported the default language is loaded (value must follow ISO 639-1  format)
specialLinks: specialLinks, // [optional, default:[]] Array of Object to specify special links
mergeTags: mergeTags, // [optional, default:[]] Array of Object to specify special merge Tags
mergeContents: mergeContents, // [optional, default:[]] Array of Object to specify merge content
preventClose: false, // [optional, default:false] if true an alert is shown before browser closure
onSave: function(jsonFile, htmlFile) { /* Implements function for save */ }, // [optional]
onSaveAsTemplate: function(jsonFile) { /* Implements function for save as template (only JSON file) */
}, // [optional]
onAutoSave: function(jsonFile) { /* Implements function for auto save */ }, // [optional]
onSend: function(htmlFile) { /* Implements function to send message */ }, // [optional]
onLoad: function(jsonFile) { /* Implements function to perform an action once the template is loaded */}, // [optional] onError: function(errorMessage) { /* Implements function to handle error messages */ } // [optional] }
 

 

Events as callbacks

The top toolbar displayed by default within the BEE editor contains buttons that trigger certain actions. These are the callsbacks that are triggered when the buttons are clicked.

onSave: caught when the Save button is clicked. Returns JSON and HTML documents.

onSaveAsTemplate: caught when Save as template is clicked. Returns JSON document.

onAutoSave: called by BEE automatically based on beeConfig.autosave value. Returns JSON document.

onSend: caught when the Send a test button is clicked. Returns HTML document.

onError: caught every time an error occurs. Returns error message.

 

Controlling the editor from your UI

If you use a paid plan, you can hide the top toolbar and control the editor from your application's user interface. For example, it's up to you at that point to have buttons above or below the editor.

Here is what you can do with buttons located in your UI:

Display a preview. Use the beePluginInstance.preview() method to trigger the message preview behavior within the editor.

Show/hide the message structure. Use the beePluginInstance.toggleStructure() method to control the visibility of the structure outlines in the message editing portion of the editor.

Save the message. Use the beePluginInstance.save() method to trigger the "Save" action and invoke the onSave callback. The plugin will return two files:

  • A JSON file - the structure of the message. Store it to allow for later editing of the message.
  • An HTML file - the ready-to-send version of the message.

Save the JSON template. Use the beePluginInstance.saveAsTemplate() method to save the JSON of the message via the onSaveAsTempated callback. Since the JSON is not parsed to obtain the HTML, this is much quicker than the save() method.

Send. This is typically used to send a test message. Use the beePluginInstance.send() method to trigger the "Send test" action and invoke the onSend callback. It returns only the HTML version of the message, so you can display a "Send a test" user interface and send it.

---

Next: learn how you can extend the editor, loading custom merge tags, for example (e.g. to start a message with "Dear John," instead of "Dear customer").

Have more questions? Submit a request

Comments

  • Avatar
    Jason Navarro

    Hello Again!

    When working with onSave function I am able to download the template.html file no problem but I am wondering what happens to the images that I upload. I see they are stored at eu-bee-resources.s3.amazonaws.com, How long are these images stored? My only concern is that it may be possible that a client may not want their images up in a public space and may want to host their own.

    Also when using onSave with the plugin is there a way for the plugin to create a ZIP of the resources instead of just an HTML file just as it does on the main site or is that something we will have to build into script.

    Thank you!

    Jason

  • Avatar
    Massimo Arrigoni

    Hi Jason: thanks for the comments! Images will be stored indefinitely up to the allotted amount, if you are using the FREE plan. If you are using a Premium plan, there is no storage limit. The Premium plans (see http://help.beefree.io/hc/en-us/articles/203054451-How-much-is-BEE-Plugin-) will also include the ability for you to use your own file system.

    At this time, there is no built-in functionality to output a zip file with the HTML and the images. That's what we do on our showcase site https://beefree.io: the site is a client of the plugin, so you could certainly do the same in your application that embeds the plugin.

    Hope this helps!

  • Avatar
    Jason Navarro

    Thank you Massimo! This is great. I found out how to insert an image without having to upload one. By right clicking inside of the Text Content area it gives a few more useful options.

  • Avatar
    Jarosław Królewski

    Big problem. I can not save configuration (silver plan) :(

    I got: Failed to update configuration

  • Avatar
    Massimo Arrigoni

    Hi Jaroslaw, not sure what the problem might be. It's working correctly in our tests. We've escalated your request. In the future, please open a support ticket from within the account management area at developers.beefree.io. Thank you!

  • Avatar
    Jarosław Królewski

    Hi,

    Screen with issue after saving options.

    I can not find "the account management area at developers.beefree.io"

    thanks for quick reply

  • Avatar
  • Avatar
    Guille Padilla

    We added a new method to show or hide the message structure outlines from your own UI.
    Just trigger beePluginInstance.toggleStructure() from a button or other UI element.

  • Avatar
    Alex Browne

    Is is possible to assign a function to the callback after it has been initialised?

  • Avatar
    Samuele Verzi

    Hi Alex
    No we don't have it right now, but we have it on the roadmap for the future. We are going to keep you updated on it

  • Avatar
    Nitish Singh

    On setting preventClose: true in beeConfig,
    the browser is giving me alert every time I want to leave the page, even if it is saved.

  • Avatar
    Nitish Singh

    Also can there be an onChange event.?

  • Avatar
    Nitish Singh

    Is there any option, to get the current JSON of email template.?

  • Avatar
    Guille Padilla

    Hi Nitish, the 'onSaveAsTemplate' event returns the JSON only, if this is what you mean.

  • Avatar
    Guille Padilla

    About your precedent questions, the preventClose won't be triggered when the Save action is configured to close the editor.

  • Avatar
    Nitish Singh

    Okay.
    We have implemented the editor, such that if the user just saves the template, we save the data and still remain on the same page, then the user can choose to again change or send the mail.
    In case there are unsaved changes, before window unload I just want to compare the current JSON with the last saved JSON, I have the last saved JSON, but if I use the OnSaveAsTemplate or any other event, the browser just kills the thread and unloads.
    If the current JSON would have been available locally in the browser, then I could just compare it and warn the user of loss of unsaved changes.

  • Avatar
    Guille Padilla

    Hi Nitish, the OnSaveAsTemplate callback is designed to be used several times during the editing work, so is performed in background.
    It will returns the current status of the JSON (as all the other methods).

    If I correctly understood your workflow, you can perfectly use the onSave callback perfectly (using beePluginInstance.save() as trigger), perform a JSON diff, alert the user if needed, decide what to do with both files (JSON and HTML).
    Hope this helps.

  • Avatar
    Chris Blair

    Just discovered your wonderful editor and am testing the sample code for a client. I'm not a full-time programmer (or really even a trained programmer) but I build websites and implement and customize PHP applications quite a bit. I've got the sample code installed and working and am able to save templates and html...but I can't figure out the function to send a test email. I've tried a few configurations but can't get it working. Are there any examples on your site or any resources that could point me in the right direction? This is an app that I believe I could easily sell to some of our clients along with Mautic, which we're preparing to switch some clients into for their email and marketing automation.
    Thanks, Chris Blair
    VP, Creative Dir.
    Magnetic Image, Inc.
    Evansville, IN

  • Avatar
    Massimo Arrigoni

    Hi Chris, that function does not give you a ready-to-go "Send a test" feature, but rather allows you to pass the HTML of the message to some script that will take care of the task on your side. It could be a form loaded in a modal window, or alike.

    The code for that form is entirely up to you. There are lots of samples on the Internet: from a quick search, for instance, I found this for PHP: https://bootstrapbay.com/blog/working-bootstrap-contact-form/

    Whichever form you decide to use, instead of asking the user to create the message to be sent (e.g. by showing a textarea field), you will hide that field and instead use the HTML received from the editor.

    We hope this helps!

    Edited by Massimo Arrigoni
  • Avatar
    Chris Blair

    Yes I was originally trying to send the output to a PHP script that uses sendmail on the server. But I must have something coded incorrectly. So thanks for the pointer!

    Chris

  • Avatar
    Ivelin Ivanov

    Hello,
    onSaveAsTemplate: function (jsonFile) { // + thumbnail?
    saveTemplate(jsonFile);
    },

    We save JSON to our server so, we can create a gallery with user templates, but how we can get thumbnail without pressing SAVE button, because, we use this for other stuffs.

  • Avatar
    Massimo Arrigoni

    The editor does not generate a thumbnail. To generate a thumbnail you indeed need to save the HTML and then do so on your side.

  • Avatar
    Ivelin Ivanov

    Thank you Massimo, but how can i get HTML code, without pressing SAVE button, because we want, when our users pressed Save as template button to get thumbs for their drafts later for edits

  • Avatar
    Massimo Arrigoni

    Hi Ivelin, to obtain the HTML, the system needs to parse the JSON and turn it into HTML code. That task is somewhat time consuming (a few seconds). For this reason, the process is not included - for example - when an autosave happens.

  • Avatar
    anurag

    Hi Massimo,

    I just started using this plugin and having a good experience overall. I have a query though can we customize the ui for e.g. adding a separate button to 'Save as Template' adjacent to existing 'Save' button.

    Can we somehow get htmlfile too in 'onSaveAsTemplate' callback.

    Edited by anurag
  • Avatar
    Guille Padilla

    Hi Anurag, You can hide completely the Toolbar and add your own UI. Take a look to: http://help.beefree.io/hc/en-us/articles/204783822-Customizing-the-toolbar

    If you need the JSON and the HTML, use the .save() method described in the last section, if you only need the JSON "template", use the .saveAsTemplate().

  • Avatar
    stukak

    Hello! Could you provide "onBeforeSave" method to handle unsaved states that less that 15s intervals. Also good to have ability to prevent savings or closings when user have unsaved changes. Thanks in advance. Alex

  • Avatar
    Guille Padilla

    Hi stukak, the preventClose param described in the above article trigger an alert when the user browses out. I'm not sure to understand what's the purpose of an "onBeforeSave" method. What event may trigger it? Why not using the already existing saveAsTemplate when you need it?

  • Avatar
    stukak

    Hi Guille, We open editor in modal window, so we want be sure that user have unsaved changes before modal will destroyed. 15s autosave is too much time to trigger properly and preventClose method is ignored in modal state and we got any luck with methods that we have for now. It would be more comfortable to have methods that will parse current state on demand and method that will be triggered before saving.

    Edited by stukak
  • Avatar
    Guille Padilla

    In this case, the answers in this thread may help you: http://help.beefree.io/hc/en-us/community/posts/209673069-Detect-if-unsaved-work-is-present

    Would be hard for the plugin to catch application events (for all the web-applications, with different workflows and technologies). By the other hand, your application knows these events (when the user clicks on the close link or void space) so can trigger a saveAsTemplate before closing the modal, this is a fast action and will return you the JSON. You can also trigger the save action to get the HTML, but it's not as immediately as retrieving only the JSON.
    Then, the flow to understand if the message has been edited or not, is described in the post linked above.
    Hope this helps.