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.

``bash
npm install @contentstack/advanced-post-message
`

`bash
pnpm install @contentstack/advanced-post-message
`

`bash
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.


`javascript
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.

`javascript
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!" }
});
`

$3

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.

`javascript
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.

`javascript
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;
});
`

$3

You can enable the debug mode to log the messages to the console.

`javascript
import EventManager from "@contentstack/advanced-post-message";

const iframe = document.getElementById("iframe");
const eventManager = new EventManager("channel-id", {
target: iframe.contentWindow,
debug: true,
});
`

$3

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.

`javascript
import EventManager from "@contentstack/advanced-post-message";

const iframe = document.getElementById("iframe");
const eventManager = new EventManager("channel-id", {
target: iframe.contentWindow,
suppressErrors: true,
});
`

$3

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.

`javascript
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,
});
`

$3

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.

`typescript
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("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.