paperglider

paperglider

Minimal library for common communication tasks between different window objects.

Installation

npm install paperglider

The PaperGlider class can be included via AMD, commonjs or a script tag.

Example

We assume a main frame with origin http://main.example.com and a child frame with origin http://child.example.com.

Main frame:

    const PaperGlider = require('paperglider');
    
    const com = new PaperGlider(window, iframe.contentWindow, 'http://main.example.com',
      'http://child.example.com');

    com.replyOn('someaction', (a, b) => a === b);

Now everytime the paperglider object in the main frame receives a message with the action 'someaction' with the proper targetOrigin, it responds by comparing both sent parameters.

Child frame:

    const PaperGlider = require('paperglider');
    
    const com = new PaperGlider(window, window.parent, 'http://child.example.com',
      'http://main.example.com');

    com.request('someaction', [2, 2], result => console.log(result));

Documentation

new PaperGlider(self, other, ownOrigin, targetOrigin)

Sets up the communication between two window objects. The origins can be omitted in which case they are set to '*", which normally should be avoided.

Param	Type
self	Window
other	Window
ownOrigin	string
targetOrigin	string

frameCom.send(action, args)

Sends the action and the given arguments to the other window.

Param	Type	Description
action	string	identifier
args	Array.<any>	arguments that get passed to the receiving callback. Should not contain functions or DOM elements.

frameCom.receive(action, callback) ⇒ function

Whenever the window receives the given action, the callback is executed with the sent arguments.

Param	Type	Description
action	string	identifier
callback	function	will receive all sent arguments as arguments to the call.

Returns: function - end will end receiving the action.

frameCom.replyOn(action, callback) ⇒ function

Whenever the window receives the action, send back the data returned by the callback with the same associated action identifier.

Param	Type	Description
action	string
callback	function	will receive all sent arguments as arguments to the call.

Returns: function - end will end replying to the action.

frameCom.request(action, args, callback)

Sends the action to the other window and waits for the same action and executes the callback once with the returned data.

Param	Type	Description
action	string	identifier
args	Array.<any>	arguments that get passed to the receiving callback. Should not contain functions or DOM elements.
callback	function	gets passed the (single) answer to the request.

frameCom.dispose()

Removes all pending event listeners from the window object.