@contentstack/advanced-post-message

Contentstack Advanced Postmessage

A promise based library to communicate between frames using the native PostMessage API.

Table of contents

• Contentstack Advanced Postmessage
• Installation
• Basic Usage
  • Returning values from the listener
  • Debug mode
  • Supress error
  • Multiple channels
  • Typescript
• License

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.