README
post-frame
Tiny Javascript library for handling one-way cross-window communication between an iframe element and its parent window
Installation
Using npm
npm install post-frame --save
Usage
const postFrame = require('post-frame')
Methods
send( targetOrigin, events )
Registers event listeners in the embedded window for a given list of events. The event target is the Document
. A postMessage to the specified origin is subsequently sent when a registered event is detected.
Note: This function must be invoked by the embedded window.
Parameters:
targetOrigin
: The origin where message should be sent- Type:
string
- Type:
events
: list of events that will invoke postMessage method- Type:
array
of strings - Note: The 'events' array should contain strings referencing common DOM Event types i.e. 'click' , 'mouseover'
- Type:
Returns:
- Type:
function
that removes all previously registered event listeners.
- Type:
Example:
const postFrame = require('post-frame')
postFrame.send('http://someTargetOrigin.com', ['click', 'mouseover', 'wheel'])
receive( validOrigins, validEvents, fn )
Registers a 'message' event listener in parent window and invokes provided callback when a valid message from a valid origin is received.
The event target is the Window
.
Note: This function must be invoked by the parent window.
Parameters:
validOrigins
: list of origins from which postMessages can be accepted- Type:
string
- Type:
validEvents
: list of events to listen for in child window- Type:
array
of strings
- Type:
fn
: callback function to be invoked after message event has been validated- Type:
callback
- Note: An event argument (type
string
) indicating the type of event fired by child window can be optionally passed to callback
- Type:
Returns:
- Type:
function
that removes the registered 'message' event listener.
- Type:
Example:
const postFrame = require('post-frame')
const validOrigins = [
'http://someValidOrigin.com',
'http://anotherValidOrigin.com'
]
postFrame.receive(validOrigins, ['click', 'mouseover', 'wheel'], event =>
console.log(`Detected iframe event: ${event}`)
)