You can use this plugin to convert any HTML file into our email document JSON format. Then, you can directly load it into any of our other plugins or save it in your system.
You can initialize this plugin with the following function call:
const importConfig = {
plugin: "import",
settings: {
hideHeader: false, // hides the header
buttons: {
header: [], // an array of objects describing the top right corner buttons of the import plugin
},
},
hooks: {}, // an object of available hooks (for example onReplaceImages)
};
// Fullscreen
const importInstance = await chamaileonPlugins.createFullscreenPlugin(importConfig);
// Inline
const importInstance = await chamaileonPlugins.createInlinePlugin(
importConfig,
{
container: "#email-import", /* HTML Element */
dimensions: {
width: 1000, // default 100%
height: 720, // default 100%
scale: 1 // default 1
}
}
);
These will be returned after a successful plugin initialization.
These are methods provided by the plugin instance.
Updates the settings inside the plugin instance on the fly.
const newSettings = {
buttons: {
header: [
{
id: "export",
type: "button",
icon: "download",
label: "Export",
color: "#aaaaaa",
style: "text",
badge: {
color: "#bbbbbb",
icon: "lock",
},
},
],
},
};
await importInstance.methods.updateSettings(newSettings);
Updates the hooks inside the plugin instance on the fly.
You can read more about the updateHooks method here.
await importInstance.methods.updateHooks({ hooks, resetHooks });
Shows the import instance iframe. Fullscreen mode only.
You can read more about the optionalParams object here.
await importInstance.show(optionalParams);
Hides the import instance iframe. Fullscreen mode only.
await importInstance.hide();
Destroys the import instance.
await importInstance.destroy();
| Property | Type | Description |
|---|---|---|
| settings | object | The initial settings of the plugin instance |
| hooks | object | You can define functions that will be called on different events that occur inside the plugin. For more, please check out the importConfig.hooks section |
The settings object has the following properties:
| Property | Type | Description |
|---|---|---|
| buttons | object | The configuration of the header buttons. |
| hideHeader | boolean | Hides the plugin header. In inline mode you may want to hide it. |
You can configure the buttons in the top right corner of the plugin header. You can set up their icons, labels and ids. If a user clicks on them, then the onButtonClicked hook will be called with the id of the button. With this option, you can add custom functionality to the plugin. For example, you can create custom dialogs. You can also configure dropdowns and add badges to the buttons as well.
Example
importConfig.settings.buttons.header = [
{
id: "export",
type: "button",
icon: "download", // icons from https://pictogrammers.github.io/@mdi/font/6.7.96/ without the mdi- prefix
label: "Export",
color: "#aaaaaa",
style: "text", // filled, depressed (no shadow filled), outlined, text, plain
badge: {
color: "#bbbbbb",
icon: "lock",
},
},
{
type: "dropdown",
icon: "dots-vertical-circle-outline",
label: "More options",
color: "secondary",
style: "outlined",
items: [
// if the button has an items array defined it will generate a dropdown button and only the items inside it will trigger the hook
{
id: "share-email",
label: "Get shareable link",
icon: "share",
},
{
id: "send-test-email",
label: "Send test email",
icon: "email",
},
],
},
];
Each and every hook should be an asynchronous process, so all of the hook handler functions have to return Promises.
In most cases you just have to resolve the promise when the async operation is done without any params, but in some cases, you will have to resolve certain objects with properties that the plugin can use. Similarly to the parameters, we always expect an object to be resolved, even if it only has one property. (This way it will be easier to add new properties later on if needed.)
If any errors occurred on your side, you can reject the promise with an instance of Error. In this case, the error message will be shown in a snackbar inside the plugin instance.
function handler(params) {
return new Promise((resolve, reject) => {
// You can put the logic here.
// Resolve the promise when everything is okay
// Reject the promise on error
if (!error) {
resolve(dataToResolve); // In some cases, you don't have to resolve any data. You can resolve the promise without a parameter.
} else {
reject(new Error("Your error message"));
}
});
}
Note that, with the async syntax, the unexpected errors will be also displayed:
async function handler(params) {
// Unexpected errors will also cause promise rejections in this case
// For example, if you get a timeout error, that will also be displayed in a snackbar in the editor.
// Any exception will be caught by the SDK and the message property of the error object will be shown in a snackbar.
return dataToResolve;
}
Below are the list of hooks that you can use. Read more about them in the following sections.
importConfig.hooks = {
cancel,
close,
onButtonClicked,
onReplaceImages,
onImportReady,
};
This hook is called when the bottom right cancel button is clicked. You should hide the plugin with this and you can add any custom logic that runs after the plugin is hidden.
/*
Params: nothing.
Has to resolve: nothing.
*/
importConfig.hooks.cancel = () => {
return new Promise((resolve) => {
importInstance.hide();
resolve();
});
};
This hook is called when the top left back button is clicked. You should hide the plugin with this and you can add any custom logic that runs after the plugin is hidden.
/*
Params: nothing.
Has to resolve: nothing.
*/
importConfig.hooks.close = () => {
return new Promise((resolve) => {
importInstance.hide();
resolve();
});
};
If you have set up header buttons in the config, you can use this hook to implement anything you like. (Most likely you will pop up a dialog.)
/*
Params:
- buttonId: string id of the button from the importConfig.settings.buttons.header array
Has to resolve: nothing.
*/
importConfig.hooks.onButtonClicked = ({ buttonId }) => {
return new Promise((resolve) => {
// Here, you can implement your custom dialog or any custom logic
resolve();
});
};
After the request has responded, you should resolve the hook promise with it.
This hook is invoked after the onImport hook has been resolved. If the replaceImages setting was set to true, this should resolve an array of objects that contain the old and the new image URLs that replaces it. The parameter array contains every image URL present in the document.
The purpose of this hook is to store the images from the HTML wherever you'd like, for example in your gallery or private server.
/*
Params:
- urls: array of strings, image URLs extracted from the HTML
Has to resolve:
- replaceObjects: array of objects, to replace the images old URL with a new one
- each object has to contain:
- oldSrc: string, received from the params
- newSrc: string, to replace the old URL
*/
importConfig.hooks.onReplaceImages = (urls) => {
return new Promise((resolve) => {
// Here, you can save the images on your own and return the array of objects
resolve(replaceObjects);
});
};
This hook is invoked after the HTML has been imported, the images have been replaced (or not) and the user clicks on the next button. This returns the document in our JSON format.
/*
Params:
- result: the JSON document imported to our format
Has to resolve: nothing.
*/
importConfig.hooks.onImportReady = (result) => {
return new Promise((resolve) => {
// Here, you can save the result in your system or load it into any of our plugins.
resolve();
});
};
For the plugin, you can check it out on the Chamaileon SDK Playground.