@chamaileon-sdk/plugin-interface
v1.1.1
Published
**This project is a postMessage interface that creates and maintains the communication between window objects**, like a web page and an iframe inside it.
Downloads
1,649
Readme
Chamaileon plugin interface
This project is a postMessage interface that creates and maintains the communication between window objects, like a web page and an iframe inside it.
Chamaileon.io built and maintains this open-source project to provide a secure and standardized way to use its plugins. We use it in our plugins: email editor, preview, gallery, etc. You can visit our website for more information: chamaileon.io.
Installation and Initialization
npm i @chamaileon-sdk/plugin-interface
The package provides three functions, initFullscreenPlugin
, initInlinePlugin
and providePlugin
.
A plugin initaialization consists of two parts:
On the parent side, you have to run either
initFullscreenPlugin
orinitInlinePlugin
, based on the usage. The function creates an iframe, and starts loading the plugin based on the src given to it.Inside the plugin, you have to call the
providePlugin
function on opening. This function responds to the parent side init mechanisms, and returns the interface.
Fullscreen plugin
Initialization
To initialize a fullscreen plugin, you have to call the initFullscreenPlugin
function with the following parameters:
initFullscreenPlugin(
{
data: Object,
settings: Object,
hooks: Object,
},
{
id: String,
src: String,
parentElem: String | HTMLElement,
beforeInit: Function,
timeout: Number,
}
);
Parameters in the first object
The parameters in the first object will be sent to the plugin directly.
- data: you can pass static data to your plugin.
- settings: you can pass down custom settings that modify the look and operation of the plugin.
- hooks: you can pass down functions that the plugin will call at certain actions or events.
Parameters in the second object
The initFullscreenPlugin
function creates and iframe based on the src
provided, and appends it to the parentElem
. The second parameter object contains information for the library to create the iframe and append it to your application DOM.
id: is the id which will represent the iframe.
src: this is the iframe source as a string.
parentElem: this is a query selector or HTMLElement that you want the plugin iframe to be inserted into. Default is
document.body
beforeInit: this function will run after the iframe is created and the container and iframe both can be reached inside of this.
beforeInit({ container, iframe }) { // your code here }
timeout: this is a number in milliseconds. This defines how long should the init function wait for an answer from the providePlugin before throwing an error.
Interface
In the returned object you will get the following properties:
{
_container: HTMLElement,
_src: String,
methods: Object,
showSplashScreen: Function,
hideSplashScreen: Function,
show: Function,
hide: Function,
destroy: Function,
}
- _container: is and HTML element containing the plugin iframe
- _src: is the source of the plugin iframe
- methods: through the methods object you can reach the plugins declared methods
- destroy: this function removes the iframe from the container
Splashscreen
If the settings
param provided in the initialization object contains a splashScreenUrl
, the plugin will have a separate iframe appended to the container, which you can show and hide with the provided showSplashScreen
and hideSplashScreen
functions.
Show / Hide
You can show and hide your created plugins with the provided show
and hide
. While using these functions, the plugin won`t be destroyed, it will keep its state while hidden.
Animations
The show
can be called with the following parameters:
show({ x = "-100vw", y = "0px", opacity = 0.5, scale = 1, time = 500 })
The show
function provides an easy way to customize your show animation. With the provided parameters, you can set the default hidden state, described by coordinates, opacity, and scale of the plugin, along with the time of the animation. When the function is called, the plugin will move to a fullscreen view from that hidden position. The animation uses the translate3d
css function. Likewise, the hide
function moves the plugin back to its set hidden state.
The default hidden state is moved to the left, so the show
function will move the plugin to view form the left. See the content editor example for more configuration.
Inline plugin
To initialize an inline plugin, you have to call the initInlinePlugin
function with the following parameters:
initInlinePlugin(
{
data: Object,
settings: Object,
hooks: Object,
},
{
src: String,
container: String | HTMLElement,
beforeInit: Function,
timeout: Number,
}
)
Parameters in the first object
The parameters in the first object will be sent to the plugin directly.
- data: you can pass static data to your plugin.
- settings: you can pass down custom settings that modify the look and operation of the plugin.
- hooks: you can pass down functions that the plugin will call at certain actions or events.
Parameters in the second object
The second object contains information for the library to create the iframe and append it to your application DOM.
src: this is the iframe source as a string.
container: the element you want the plugin to append to.
beforeInit: this function will run after the iframe is created and the container and iframe both can be reached inside of this.
beforeInit({ container, iframe }) { // your code here }
timeout: this is a number in milliseconds. This defines how long should the init function wait for an answer from the providePlugin before throwing an error.
Interface
In the returned object you will get the following properties:
{
_container: HTMLElement,
methods: Object,
destroy: Function,
}
- _container: is and HTML element containing the plugin iframe
- methods: through the methods object you can reach the plugins declared methods
- destroy: this function removes the iframe from the container
providePlugin
When your plugin is loaded from the provided src, your script in the iframe has to call the providePlugin
function, in order to respond to the plugin-interface initialization
providePlugin({
hooks: Array,
methods: Object,
validator: Function,
});
- hooks: This is an array of hook names that the plugin accepts and uses
- methods: These are functions can be called from outside and are used to interact directly with the plugin from the outside
- validator: Is a function that will run when the provided
data
,settings
andhooks
arrive from the parent side
Interface
The providePlugin function should resolve to an object containing these fields:
{
data: Object,
settings: Object,
hooks: Object,
terminate: Function,
}
- data: The data that was sent at the init stage
- settings: The settings that were sent at the init stage
- hooks: Hooks that were sent at the init stage and were filtered with the list of hooks that are accepted by the plugin
- terminate: A function designed to terminate the communication between the window objects.
Update hooks
The updateHooks method can be defined in the plugin side. It can be used to update the hooks that were defined on initialization. We provide two options that you can see on the example below.
Starting context
const onSave = () => {};
const onDelete = () => {};
const onFail = () => {};
const activeHooks = [];
const pluginInterface = await initFullscreenPlugin(...);
// For this example let's say that we sent
// the "onFail" hook with the init function
const pluginInstance = await providePlugin({
hooks: ["onSave", "onDelete", "onFail" ],
methods: {
updateHooks(hooks) {
activeHooks = hooks;
},
},
validator: () => {},
})
pluginInstanceMethods.updateHooks = (hooks) => {
activeHooks = hooks;
}
Update the hooks while keeping the already defined ones
await pluginInterface.methods.updateHooks({ hooks: { onSave } });
// after the method call the activeHooks should be equal with ["onSave", "onFail", "error"];
Update the hooks and only keep the new ones
await pluginInterface.methods.updateHooks({ hooks: { onDelete }, resetHooks: true });
// after the method call the activeHooks should be equal with ["onDelete", "error"];
Example
You can run the examples, with static server
$ npm -g install static-server
$ static-server -c "*" -zp 8080