@contentstack/advanced-post-message
v0.0.2
Published
Inspired from post robot, this module is designed to provide a simple interface for cross domain communication for Contentstack's Live preview implementations.
Downloads
190
Readme
Contentstack Advanced Postmessage
A promise based library to communicate between frames using the native PostMessage API.
Installation
You can install the package using your preferred package manager.
npm install @contentstack/advanced-post-message
pnpm install @contentstack/advanced-post-message
yarn add @contentstack/advanced-post-message
Basic Usage
Initialize the EventManager
class with a channel id and the target window. You can use the send
method to send messages to the target window. You can use the on
method to listen to messages from the target window.
In the primary project, you can use the EventManager
class to send messages to the iframe.
import EventManager from "@contentstack/advanced-post-message";
const iframe = document.getElementById("iframe");
const eventManager = new EventManager("channel-id", {
target: iframe.contentWindow,
});
eventManager.send("message", { data: "Hello, world!" });
In the iframe, you can use the EventManager
class to receive messages from the primary project.
import EventManager from "@contentstack/advanced-post-message";
const eventManager = new EventManager("channel-id", {
target: window.parent,
});
eventManager.on("message", (event) => {
console.log(event.data); // { data: "Hello, world!" }
});
Returning values from the listener
You can return a value from the listener, which will be sent back to the target window.
In the primary project, you can use the EventManager
class to send messages to the iframe and receive a response.
import EventManager from "@contentstack/advanced-post-message";
const iframe = document.getElementById("iframe");
const eventManager = new EventManager("channel-id", {
target: iframe.contentWindow,
});
eventManager.send("sum", { num1: 10, num2: 11 }).then((sum) => {
console.log(sum); // 21
});
In the iframe, you can use the EventManager
class to receive messages from the primary project and send a response.
import EventManager from "@contentstack/advanced-post-message";
const eventManager = new EventManager("channel-id", {
target: window.parent,
});
eventManager.on("sum", (event) => {
return event.data.num1 + event.data.num2;
});
Debug mode
You can enable the debug mode to log the messages to the console.
import EventManager from "@contentstack/advanced-post-message";
const iframe = document.getElementById("iframe");
const eventManager = new EventManager("channel-id", {
target: iframe.contentWindow,
debug: true,
});
Supress error
When you are building a library or a plugin, you might want to suppress the error when the listeners are unavailable. You can set the suppressErrors
option to true
to suppress the error.
import EventManager from "@contentstack/advanced-post-message";
const iframe = document.getElementById("iframe");
const eventManager = new EventManager("channel-id", {
target: iframe.contentWindow,
suppressErrors: true,
});
Multiple channels
You can use the same EventManager
class to communicate with multiple iframes. You can create a new instance of the EventManager
class with a different channel id and target window.
Even if the events have the same type, they will not interfere with each other.
import EventManager from "@contentstack/advanced-post-message";
const iframe1 = document.getElementById("iframe1");
const eventManager1 = new EventManager("channel-id-1", {
target: iframe1.contentWindow,
});
const iframe2 = document.getElementById("iframe2");
const eventManager2 = new EventManager("channel-id-2", {
target: iframe2.contentWindow,
});
Typescript
This library is written in typescript, so it comes with its own types. You can use the types to get the type of the payload in the listener and the response from the send
method.
import EventManager from "@contentstack/advanced-post-message";
const eventManager = new EventManager("channel-id", {
target: window.parent,
});
eventManager.on<{ from: string }>("message", (event) => {
const data = event.data;
console.log(data.from); // Micheal
return `Hello ${data.from}!`;
});
eventManager
.send<string>("message", { from: "Micheal" })
.then((response) => {
console.log(response); // Hello Micheal!
});
License
This project is licensed under the MIT License - see the LICENSE file for details.