frame-messenger
v1.0.5
Published
a promise-friendly class for communicating between browser frames
Downloads
16
Readme
Frame Messenger
A tiny JavaScript class to simplify communication between different browser frames, supporting both promises and callbacks.
Installation
npm install frame-messenger
Documentation
new FrameMessenger(options)
var messenger = new FrameMessenger({
frame: window,
targetFrame: window.parent,
name: 'iframe',
targetName: 'topFrame',
Promise: window.Promise // optional
});
Options
frame
{Window} required
Frame should be a reference to the current window (i.e., window
)
name
{String} required
An arbriary name to assign to the current frame. Other frames must use this name when initiating communication.
targetFrame
{Window} required
A reference to the frame we will be communicating with (e.g., parent
, top
, opener
, iframeEl.contentWindow
)
targetName
{Window} required
An arbriary name to assign to the other frame we want to communicate with. The other frame must use this same name to reference itself (see examples below).
Promise
{Promise constructor} optional
A promise constructor to use for creating promises. When not passed, regular node-style callbacks will be used.
messenger.postMessage()
Send a message to the other frame:
var messenger = new FrameMessenger({
frame: window,
targetFrame: parent,
name: 'iframe',
targetName: 'topFrame'
});
messenger.postMessage('Hello top frame!');
Pass in a callback to process the response from the other frame:
messenger.postMessage('Hello top frame!', function(err, data) {
if (err) {
throw new Error(err);
}
console.log('The other frame replied with: ' + data);
});
Alternately, postMessage
will return a promise if FrameMessenger
was invoked with a Promise
property:
var messenger = new FrameMessenger({
frame: window,
targetFrame: window.parent,
name: 'iframe',
targetName: 'topFrame',
Promise: RSVP.Promise // choose your favorite promise library
});
messenger.postMessage('Hello top frame!').then(function(data) {
console.log('The other frame replied with: ' + data);
}, function(err) {
// Process error
});
You can maintain an open communication with the other frame by utilizing the callback
argument that is passed to the postMessage
callback:
messenger.postMessage('Hello top frame!', function(err, data, callback) {
if (err) {
throw new Error(err);
}
console.log('The other frame replied with: ' + data);
// Like node callbacks, the first parameter passed to the callback
// should be either an error object/message or null (if there are no errors)
callback(null, 'Thanks for the response!');
});
messenger.onMessage(data, callback)
Handle messages from the other frame with onMessage
:
messenger.onMessage(function(data) {
console.log('The targetFrame sent me: ' + data);
});
The other frame can send a response back by utilizing the callback argument passed to onMessage
:
messenger.onMessage(function(data, callback) {
if (data === 'Knock knock') {
callback(null, "Who's there?")
} else {
callback(new Error('I only know knock knock jokes.'));
}
});
See the tests for other examples.
Tests
Running the tests:
npm install
npm test
License
This project is distributed under the MIT license.