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.variablesToEdit

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.

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_back' }]
    },
    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
*/
editorConfig.hooks.onEditImage = ({ originalImg }) => {
    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 editorConfig.textInsertPluginButtons array

Has to resolve:
- value: The string you want to insert.
*/
editorConfig.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.
*/
editorConfig.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();

close

Closes the variable editor.

await variableEditorInstance.close();