droopy-postmessage
v1.0.0
Published
Wraps HTML5 PostMessage API to support callbacks and promises
Downloads
11
Readme
Droopy PostMessage
Wrapper for HTML5 PostMessage api to add support for callbacks and promises.
##Why?
Let's say you have 2 web apps, and want to iframe App B inside of App A (maybe you have a Wordpress site and want to embed a widget hosted by a separate custom web application). For security reasons, windows can not communicate cross-origin. So your IFramed custom widget will not be able to access window.top
values. To solve this problem we have the HTML5 PostMessage API.
The native PostMessage API is very simple and only allows passing a message string and a target window. Droopy PostMessage builds on this native capability to allow sending javascript objects and handles querying another window and waiting for a response (through callbacks or promises). ##Install & Setup
Option 1: Node.js Prereq: Install Node.js, go for highest version.
#Install the droopy-postmessage module in your project
npm install --save droopy-postmessage
Option 2: Global Include
- Download the source code and include it on your page:
Last, you need to include droopyPostMessage.js on both pages, the parent page, and the iframed page.
##Methods
droopyPostMessage.subscribe(key, handler)
- allows a page to listen for a particular keydroopyPostMessage.unsubscribe(key, handler)
- disables the handler function that is bound to that keydroopyPostMessage.post(targetWindow, key, payload)
- sends a message to another window. If the targeted window has subscribed to thekey
, the targeted window's handler will receive the payloaddroopyPostMessage.postParent(key, payload)
- syntax sugar that calls.post()
withwindow.top
as the target windowdroopyPostMessage.query(targetWindow, key, payload, cb)
- sends a message to another window with the expectation that the target window is listening for that event key and will respond back. Thecb
function will be invoked when the target window responds. If the browser supports Promises, aPromise
will be returned as an alternative to a callbackdroopyPostMessage.queryParent(key, payload, cb)
- syntax sugar that calls.query()
withwindow.top
as the target window.
##Example Usage
Parent Window - has a global variable _privateNumber
, and an IFramed widget. The parent window trusts the IFramed widget and wants to allow it to get and set the _privateNumber
window._privateNumber = 0;
var handlers = {
setNumber: function(event, newNumber) {
// Update with a value passed from the IFramed Page
window._privateNumber = newNumber;
},
getNumber: function(event) {
// Send a response back to the IFramed page
event.respond(window._privateNumber);
}
};
// Listen for the iframed window to send a message
droopyPostMessage.subscribe("get-number", handlers.getNumber);
droopyPostMessage.subscribe("set-number", handlers.setNumber);
IFramed Window - The IFamed window wants to be able to send messages to the parent to get and set the private number
// This will throw an ERROR if cross-origin
var number = window.top._privateNumber
// Tell the parent window to update the number
droopyPostMessage.postParent("set-number", 5);
// Get the number from the parent window
droopyPostMessage.queryParent("get-number", null, function(num) {
console.log("This number should be 5: " + num);
})
// PROMISE instead of callback
droopyPostMessage.queryParent("get-number").then(function(num) {
console.log("This number should be 5: " + num);
})