Email Variable Editor Plugin

If you already have an document object with defined variables, that you saved from the editor, you can open the variable editor by the following function call:

const variableEditorInstance = await chamaileonPlugins.editVariables({
    document: {}, // email JSON - required
    settings: {},
    hooks: {},
});

Variable editor configuration

There are three properties on the config object:

• document - the JSON document itself
• settings - an object with the settings options
• hooks - callbacks

const variableEditorConfig = {
    document: {},
    settings: {
        variablesToEdit: ['varName1', 'varName2'],
        buttons: {
            header: {
                left: [],
                right: [],
            },
            footer: {
                left: [],
                right: [],
            },
            textInsertPlugin: [],
		},
    },
    hooks: {
        onEditImage,
        onTextInsertPluginButtonClicked,
        onButtonClicked,
    }
};

variableEditorConfig.settings

The settings object has the following properties:

Property	Type	Description
variablesToEdit	array	This is an array of strings, in which you have to define which variables you want your users to edit. The string values must be the names of the variables.
buttons	object	The configuration of the header buttons, footer buttons and textInsert buttons.

variableEditorConfig.settings.buttons

As you can see from the example above, you can configure multiple buttons when you initialize the variable editor. You can put multiple buttons in the header and the footer, in both cases to the left and right hand side.

This way, you can even easily configure the variable editor to be a step in a wizard.

Every object in the arrays has to have the following properties:

Property	Type	Requred	Description
id	string	yes	The id of the button. You will be able to use it in the onButtonClicked hook.
icon	string	no	You can customize the icon of the button, you can use the icon names from material icons.
label	string	no	The label of the button.

Although the icon and the label properties are not required, you will have to use at least one of those options, otherwise your button will not be visible.

You can also add custom buttons to the CKEditor when a text variable is currently edited. You have to add similar objects to the textInsertPlugin array, the only difference is that the icon has to be an actual image.

Example:

variableEditorConfig.settings.buttons = {
    header: {
        left: [{ id: 'close', icon: 'arrow-left' }]
    },
    footer: {
        left: [{ id: 'prev', label: 'Prev' }],
        right: [{ id: 'next', label: 'Next' }]
    },
    textInsertPlugin: [{ id: 'merge-tags', label: 'Merge Tags', icon: 'https://raw.githubusercontent.com/ckeditor/ckeditor4/major/skins/kama/icons/paste.png' }],
};

variableEditorConfig.hooks

Hooks work in the same way as they do in the email editor. You will have to create functions that return a promise. Read more about the hook configuration in the email editor section.

variableEditorConfig.hooks.onEditImage

This hook is called when the user wants to select an image from your gallery.

/*
Params:
 - originalImg: string, shows that a user wants to edit an image

Has to resolve:
 - src
*/
variableEditorConfig.hooks.onEditImage = () => {
    return new Promise(resolve => {
        // Eventually, you will have to resolve an object with an src prop
        resolve({ src });
    });
};

variableEditorConfig.hooks.onTextInsertPluginButtonClicked

This hook is called when the user clicks on the merge-tag button when editing a text element.

/*
Params:
 - buttonId: string id of the button from the variableEditorConfig.textInsertPluginButtons array

Has to resolve:
- value: The string you want to insert.
*/
variableEditorConfig.hooks.onTextInsertPluginButtonClicked = ({ buttonId }) => {
    return new Promise(resolve => {
        // Here, you can implement your custom dialog
        resolve({ value: "Your inserted text." });
    });
};

variableEditorConfig.hooks.onButtonClicked

You can create custom actions with this hook, based on your button configuration.

/*
Params:
 - buttonId: string id of the button from the variableEditorConfig.

Has to resolve: nothing.
*/
variableEditorConfig.hooks.onDropdownButtonClicked = ({ buttonId }) => {
    return new Promise(resolve => {
        // Here, you can implement your custom dialog
        resolve();
    });
};

Variable editor instance functions

There are a few variableEditorInstance functions.

getDocument

This function will resolve the current state of the document as a JSON object. You can save it and reload the editor (or the preview) with this JSON later on. You can also invoke our generator with this JSON object from your backend.

const emailJson = await variableEditorInstance.getDocument();

setDocument

This function will replace the current document in the variable editor with a new one. You can for example update the document on a hook that you configured in the header or the footer.

await variableEditorInstance.setDocument(emailJson);

updateSettings

This function will replace the current settings object in the variable editor with a new one. The format of the settings object is the same that you pass when you open the variable editor. It means that you can reconfigure on the fly what variable you want to edit and what buttons to show.

You can update the settings when your user clicks one of the previously configured buttons. With this in mind, you can create something like the email series wizard that we implemented. Check out the code here.

await variableEditorInstance.updateSettings(newSettings);

Examples

We put together a demo and you can check out the code here.

There is an advanced example that shows you how you can use the variable editor to create an email creation wizard with which you can easily customize a whole series of emails. Code.

You can also check out the email variable editor plugin on the Chamaileon SDK Playground.