A powerful, simple, promise-based
postMessageiFrame communication library.
Postmate is a promise-based API built on postMessage. It allows a parent page to speak with a child iFrame across origins with minimal effort.
You can download the compiled javascript directly here
- Promise-based API for elegant and simple communication.
- Secure two-way parent <-> child handshake, with message validation.
- Child exposes a retrievable
modelobject that the parent can access. - Child emits events that the parent can listen to.
- Parent can
callfunctions within achild - Zero dependencies. Provide your own polyfill or abstraction for the
PromiseAPI if needed. - Lightweight, weighing in at ~
1.6kb(minified & gzipped).
NOTE: While the underlying mechanism is window.postMessage(), only iFrame is supported.
Postmate can be installed via NPM.
NPM
$ yarn add postmate # Install via Yarn$ npm i postmate --save # Install via NPMParent: The top level page that will embed aniFrame, creating aChild.Child: The bottom level page loaded within theiFrame.Model: The object that theChildexposes to theParent.Handshake: The process by which the parent frame identifies itself to the child, and vice versa. When a handshake is complete, the two contexts have bound their event listeners and identified one another.
-
The
Parentbegins communication with theChild. A handshake is sent, theChildresponds with a handshake reply, finishingParent/Childinitialization. The two are bound and ready to communicate securely. -
The
Parentfetches values from theChildby property name. TheChildcan emit messages to the parent. TheParentcancallfunctions in theChildModel.
parent.com
// Kick off the handshake with the iFrame
const handshake = new Postmate({
container: document.getElementById('some-div'), // Element to inject frame into
url: 'http://child.com/page.html', // Page to load, must have postmate.js. This will also be the origin used for communication.
name: 'my-iframe-name', // Set Iframe name attribute. Useful to get `window.name` in the child.
classListArray: ["myClass"] //Classes to add to the iframe via classList, useful for styling.
});
// When parent <-> child handshake is complete, data may be requested from the child
handshake.then(child => {
// Fetch the height property in child.html and set it to the iFrames height
child.get('height')
.then(height => child.frame.style.height = `${height}px`);
// Listen to a particular event from the child
child.on('some-event', data => console.log(data)); // Logs "Hello, World!"
});child.com/page.html
const handshake = new Postmate.Model({
// Expose your model to the Parent. Property values may be functions, promises, or regular values
height: () => document.height || document.body.offsetHeight
});
// When parent <-> child handshake is complete, events may be emitted to the parent
handshake.then(parent => {
parent.emit('some-event', 'Hello, World!');
});// parent.com or child.com
Postmate.debug = true;
new Postmate(options);| Name | Type | Description | Default |
|---|---|---|---|
debug |
Boolean |
Set to true to enable logging of additional information |
false |
// parent.com or child.com
Postmate.Promise = RSVP.Promise;
new Postmate(options);| Name | Type | Description | Default |
|---|---|---|---|
Promise |
Object |
Replace the Promise API that Postmate uses | window.Promise |
// parent.com
new Postmate({
container: document.body,
url: 'http://child.com/',
classListArray: ["myClass"]
model: { foo: 'bar' }
});This is written in the parent page. Creates an iFrame at the specified
url. Initiates a connection with the child. Returns a Promise that signals when the handshake is complete and communication is ready to begin.
Returns: Promise(child)
| Name | Type | Description | Default |
|---|---|---|---|
container (optional) |
DOM Node Element |
An element to append the iFrame to | document.body |
url |
String |
A URL to load in the iFrame. The origin of this URL will also be used for securing message transport | none |
classListArray |
Array |
An Array to add classes to the iFrame. Useful for styling | none |
model |
Object |
An object literal to represent the default values of the Childs model | none |
// child.com
new Postmate.Model({
// Serializable values
foo: "bar",
// Functions
height: () => document.height || document.body.offsetHeight,
// Promises
data: fetch(new Request('data.json'))
});This is written in the child page. Calling
Postmate.Modelinitiates a handshake request listener from theChild. Once the handshake is complete, an event listener is bound to receive requests from theParent. TheChildmodel is extended from themodelprovided by theParent.
Returns: Promise(handshakeMeta)
| Name | Type | Description | Default |
|---|---|---|---|
model |
Object |
An object of gettable properties to expose to the parent. Value types may be anything accepted in postMessage. Promises may also be set as values or returned from functions. |
{} |
// parent.com
new Postmate({
container: document.body,
url: 'http://child.com/'
}).then(child => {
child.get('something').then(value => console.log(value));
});Retrieves a value by property name from the
Childsmodelobject.
Returns: Promise(value)
| Name | Type | Description |
|---|---|---|
key |
String (required) |
The string property to lookup in the childs model |
// parent.com
new Postmate({
container: document.body,
url: 'http://child.com/'
}).then(child => {
child.call('sayHi', 'Hello, World!');
});Calls the function
sayHiin theChildModelwith the parameterHello, World!
Returns: undefined
| Name | Type | Description |
|---|---|---|
key |
String (required) |
The string property to lookup in the childs model |
data |
Mixed |
The optional data to send to the child function |
// parent.com
new Postmate({
container: document.body,
url: 'http://child.com/'
}).then(child => child.destroy());Removes the
iFrameelement and destroys anymessageevent listeners
Returns: undefined
new Postmate(options).then(child => {
child.get('height')
.then(height => child.frame.style.height = `${height}px`);
});The iFrame Element that the parent is communicating with
Promises provide a clear API for fetching data. Using an evented approach often starts backwards. if the parent wants to know the childs height, the child would need to alert the parent, whereas with Postmate, the Parent will request that information from the child in a synchronous-like manner. The child can emit events to the parent as well, for those other use-cases that still need to be handled.
Postmate.debug needs to be set in both the parent and child for each of them to log their respective information
Make sure that you have initialized Postmate.Model in your child page.
Postmate (by design) is restrictive in its modes of communication. This enforces a simplistic approach: The parent is responsible for logic contained within the parent, and the child is responsible for logic contained within the child. If you need to retrieve information from parent -> child, consider setting a default
modelin the parent that the child may extend.
This is specifically what the
callfunction is for.
By default, all
messageevents received by any (parent) page can come from any (child) location. This means that theParentmust always enforce security within its message event, ensuring that thechild(origin) is who we expect them to be, that the message is a response from an original request, and that our message is valid. The handshake routine solves this by saving the identities of the child and parent and ensuring that no changes are made to either.
The origin of the request, the message type, the postMessage mime-type, and in some cases the message response, are all verified against the original data made when the handshake was completed.
MIT
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent