You can use this plugin to preview our email document JSON object as a mock HTML document. This plugin also provides multiple previews like mobile or desktop and also has a dark mode preview as well.
With this you can open a preview on an Email editor hook or you can preview the whole email without opening the Email editor.
You can initialize this plugin with the following function call:
const previewConfig = {
plugin: "preview",
data: { document },
settings: {
hideHeader: false, // hides the header
showDarkModePreview: false, // shows a dark mode preview as well
defaultView: "mobile", // sets the default view when the plugin is displayed. Accepts "mobile" or "desktop"
buttons: {
header: [], // an array of objects describing the top right corner buttons of the preview plugin
},
},
hooks: {}, // an object of available hooks (for example onHeaderButtonClicked)
}
// Fullscreen
const previewInstance = await chamaileonPlugins.createFullscreenPlugin(previewConfig);
// Inline
const previewInstance = await chamaileonPlugins.createInlinePlugin(
previewConfig,
{
container: "#email-preview", /* 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 = {
showDarkModePreview: true,
defaultView: "desktop",
}
await previewInstance.methods.updateSettings(newSettings);
Updates the data inside the plugin instance on the fly.
await previewInstance.methods.updateData({ document });
Updates the hooks inside the plugin instance on the fly.
You can read more about the updateHooks method here.
await previewInstance.methods.updateHooks({ hooks, resetHooks });
Shows the preview instance iframe. Fullscreen mode only.
You can read more about the optionalParams object here.
await previewInstance.show(optionalParams);
Hides the preview instance iframe. Fullscreen mode only.
await previewInstance.hide();
Shows the splash screen inside the preview instance. Fullscreen mode only.
await previewInstance.showSplashScreen();
Hides the splash screen inside the preview instance. Fullscreen mode only.
previewInstance.hideSplashScreen();
Destroys the preview instance.
await previewInstance.destroy();
| Property | Type | Description |
|---|---|---|
| data | object | The initial data of the plugin instance |
| 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 previewConfig.hooks section. |
The data object has the following properties:
| Property | Type | Description |
|---|---|---|
| document | object | The email document. |
The settings object has the following properties:
| Property | Type | Description |
|---|---|---|
| buttons | object | The configuration of the header buttons. |
| showDarkModePreview | boolean | Shows a toggle button that switches between dark mode and normal preview modes |
| defaultView | string | Toggles default view. Default is mobile. |
| 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 preview. You can set up their icons, labels and ids. If a user clicks on them, then the onHeaderButtonClicked hook will be called with the id of the button. With this option, you can add custom functionality to the preview. For example, you can create custom dialogs. You can also configure dropdowns and add badges to the buttons as well.
Example
previewConfig.settings.buttons.header = [
{
id: "preview",
type: "button",
icon: "eye", // icons from https://pictogrammers.github.io/@mdi/font/6.7.96/ without the mdi- prefix
label: "Preview",
color: "#aaaaaa",
style: "text", // filled, depressed (no shadow filled), outlined, text, plain
badge: {
color: "#bbbbbb",
icon: "lock",
},
},
{
type: "dropdown",
icon: "dog",
label: "Dropdown",
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",
},
{
id: "request-review",
label: "Request a review",
icon: "comment-eye",
},
],
},
];
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.
previewConfig.hooks = {
onHeaderButtonClicked,
close,
};
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 previewConfig.settings.buttons.header array
Has to resolve: nothing.
*/
previewConfig.hooks.onHeaderButtonClicked = ({ buttonId }) => {
return new Promise(resolve => {
// Here, you can implement your custom dialog or any custom logic
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.
*/
previewConfig.hooks.close = () => {
return new Promise(resolve => {
previewInstance.hide();
resolve();
});
};
We put together a demo and you can check out the code here.
You can also check out the email preview plugin on the Chamaileon SDK Playground.