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));

More complete examples can be found in the examples folder. The files iframe.html and window-open.html can both be opened locally.

Documentation

paperglider

A module for communication between window objects.

{PaperGlider}

• {PaperGlider}
  • ~PaperGlider
    • new PaperGlider(self, other, ownOrigin, targetOrigin)
    • .isConnected() ⇒ boolean
    • .send(action, args)
    • .receive(action, callback) ⇒ function
    • .replyOn(action, callback) ⇒ function
    • .request(action, args, callback)
    • .dispose()

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

paperGlider.isConnected() ⇒ boolean

Returns true if a connection was established.

Kind: instance method of PaperGlider

paperGlider.send(action, args)

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

Kind: instance method of PaperGlider

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

paperGlider.receive(action, callback) ⇒ function

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

Kind: instance method of PaperGlider
Returns: function - end will end receiving the action.

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

paperGlider.replyOn(action, callback) ⇒ function

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

Kind: instance method of PaperGlider
Returns: function - end will end replying to the action.

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

paperGlider.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.

Kind: instance method of PaperGlider

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.

paperGlider.dispose()

Removes all pending event listeners from the window object.

Kind: instance method of PaperGlider