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
  • 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'

• Returns:

  • Type: function that removes all previously registered event listeners.

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
  • validEvents: list of events to listen for in child window
    • Type: array of strings
  • 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

• Returns:

  • Type: function that removes the registered 'message' event listener.

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}`)
)