@aics/browsing-context-messaging

This is a facade on top of the browser's Channel Messaging API.

Install

npm install --save @aics/browsing-context-messaging

Usage

This library is intended to be pulled into two browsing contexts. For example, a parent document and an iframe rendered into that parent document. You must decide which of the two browsing contexts will be responsible for initializing the communication. For the purpose of the API of this library, the context responsible for initializing the communication is referred to as the MessageInitializer; the other, non-initializing context is referred to as the MessageTarget.

|---------------------------------------------|
|                                             |
| PARENT DOCUMENT                             |
| // create a new MessageInitializer          | 
|                                             |
|    |----------------------------------|     |
|    |                                  |     |
|    |  NESTED BROWSING CONTEXT         |     |
|    |  (e.g., an iframe)               |     |
|    |  // create a new MessageTarget   |     |
|    |                                  |     |
|    |----------------------------------|     |
|                                             |
|                                             |
|---------------------------------------------|

MessageInitializer

A MessageInitializer should be created in only one of the browsing contexts.

# BrowsingContextMessaging.MessageInitializer(targetContext, onMessage, settings = {}) Construct a new MessageInitializer.

The constructor has two required arguments:

• targetContext - must be an element valid for use with the Channel Messaging API. Currently, only HTMLIFrameElement is supported.
• onMessage - callback to be run when MessageTarget posts a message. The callback is called with an instance of a MessageEvent.

Additionally, the constructor accepts an optional settings object. Available settings:

• targetOrigin (str): the target origin of the MessageTarget; defaults to "*". If the scheme, hostname, or port of the targetContext do not match targetOrigin, the event will not be dispatched. Refer to postMessage documentation for further explanation.

import { MessageInitializer } from "@aics/browsing-context-messaging";

function onMessage(messageEvent) {
    updateURLQueryString(messageEvent.data);
}
const iFrame = document.getElementById("#my-iframe");

const messenger = new MessageInitializer(iFrame, onMessage);

# MessageInitializer.postMessage(message) Post a message to MessageTarget. Can be of any basic data type; multiple items can be sent as an array.

messenger.postMessage("Hello from the MessageInitializer");
messenger.postMessage({ foo: "bar", bar: "foo" });
messenger.postMessage([34, { foo: "bar" }, true]);

MessageTarget

A MessageTarget should be created in only one of the browsing contexts.

# BrowsingContextMessaging.MessageTarget(onMessage) Construct a new MessageTarget. It takes a single, required argument onMessage, which is a callback to be run when MessageInitializer posts a message. The callback is called with an instance of a MessageEvent.

import { MessageTarget } from "@aics/browsing-context-messaging";

function onMessage(messageEvent) {
    this.updateState(messageEvent.data);
}

const messenger = new MessageTarget(onMessage);

#MessageTarget.postMessage(message) Post a message to MessageInitializer. Can be of any basic data type; multiple items can be sent as an array.

messenger.postMessage("Hello from the MessageInitializer");
messenger.postMessage({ foo: "bar", bar: "foo" });
messenger.postMessage([34, { foo: "bar" }, true]);

Description of Gradle tasks:

| script | comments | | ------ | -------- | | build | create CommonJS, ES module, and UMD builds | | bundle | run Webpack to create a UMD bundle | | clean | remove generated artifacts | | format | run prettier on src directory | | generateTypes | generate type declarations | | lint | run eslint on src directory | | transpileCommonJs | run babel on src directory; transpile import/export statements for a CommonJS compatible build | | transpileES | run babel on src directory; do not transpile import/export statements for an ES module compatible build (used by bundlers for tree-shaking) | | test | run mocha; searches for any files matching the pattern "src/**/*.test.js" | | typeCheck | run tsc in type-check only mode |