A promise based library to communicate between frames using the native PostMessage API.
Table of contents
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
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!" }
});
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;
});
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,
});
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,
});
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,
});
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!
});
This project is licensed under the MIT License - see the LICENSE file for details.