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 = PaperGlider.connectIframe(iframe, '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 = PaperGlider.connectParent('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}

• {PaperGlider}
  • ~PaperGlider
    • new PaperGlider(self)
    • instance
      • .init(target, [targetOrigin])
      • .isConnected() ⇒ boolean
      • .send(action, args)
      • .receive(action, callback) ⇒ function
      • .replyOn(action, callback) ⇒ function
      • .request(action, args, callback)
      • .dispose()
      • .onConnect(callback)
    • static
      • .connectIframe(iframe, [iframeOrigin]) ⇒ PaperGlider
      • .connectChild(child, [childOrigin]) ⇒ PaperGlider
      • .connectParent([parentOrigin]) ⇒ PaperGlider

{PaperGlider}~PaperGlider

Kind: inner class of {PaperGlider}

• ~PaperGlider
  • new PaperGlider(self)
  • instance
    • .init(target, [targetOrigin])
    • .isConnected() ⇒ boolean
    • .send(action, args)
    • .receive(action, callback) ⇒ function
    • .replyOn(action, callback) ⇒ function
    • .request(action, args, callback)
    • .dispose()
    • .onConnect(callback)
  • static
    • .connectIframe(iframe, [iframeOrigin]) ⇒ PaperGlider
    • .connectChild(child, [childOrigin]) ⇒ PaperGlider
    • .connectParent([parentOrigin]) ⇒ PaperGlider

new PaperGlider(self)

Creates an object to communicate with another windows.

Param	Type
self	Window

paperGlider.init(target, [targetOrigin])

Sets up the communication to another window. The target origin can be omitted in which case it is set to '*', which normally should be avoided.

Kind: instance method of PaperGlider

Param	Type	Default
target	Window
[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

paperGlider.onConnect(callback)

The given callback will be executed as soon as PaperGlider has connected.

Kind: instance method of PaperGlider

Param
callback

PaperGlider.connectIframe(iframe, [iframeOrigin]) ⇒ PaperGlider

This is a simple helper to connect to a iframe. It waits for the contentWindow if neccessary.

Kind: static method of PaperGlider

Param	Type	Default
iframe	HTMLIFrameElement
[iframeOrigin]	string	"'*'"

PaperGlider.connectChild(child, [childOrigin]) ⇒ PaperGlider

This is a simple helper to connect to a child window (iframe, window.open)

Kind: static method of PaperGlider

Param	Type	Default
child	Window
[childOrigin]	string	"'*'"

PaperGlider.connectParent([parentOrigin]) ⇒ PaperGlider

This is a simple helper to connect to a parent window (window.top or window.opener)

Kind: static method of PaperGlider

Param	Type	Default
[parentOrigin]	string	"'*'"