EventFrame

An event abstraction over browser window messaging.

EventFrame serves as an event-emitter between the current page and another iframe or window.

Installation

> npm install event-frame
 or
> bower install event-frame

Loading

CommonJS

var EventFrame = require('event-frame');
var bus = new EventFrame({ /* ... */ });

AMD

<script
  data-main="main.js"
  src="//cdnjs.cloudflare.com/ajax/libs/require.js/2.1.22/require.min.js"
></script> 

require(['event-frame'], function (EventFrame) {
  var bus = new EventFrame({ /* ... */ });
});

Browser

<script src="/path/to/event-frame.js"></script>
<script>
  var bus = new EventFrame({ /* ... */ });
</script> 

Api

constructor

new EventFrame(options: object) -> EventFrame

The constructor for EventFrame instances. It requires a reference to the frame or window that you want to connect with.

Parameter	Type	Description
options.frame	Window HTMLIFrameElement	The iframe, popup, or Window to create a connection with.
options.origin	string	Restrict events to an exact origin. An origin consists of the protocol, host, and port. Defaults to * which applies to any origin.

var eventFrame = new EventFrame({
    frame: document.querySelector('iframe#my-iframe-id'),
    origin: 'https://example.com'
});

start

start() -> EventFrame

Begin listening for incoming events. Normally you will not need to execute this method, as the constructor calls it implicitly.

Returns the EventFrame instance for chaining.

eventFrame.start();

stop

stop() -> EventFrame

Stop listening for incoming events. This is good for "teardown" purposes and quickly deactivating all listeners.

Returns the EventFrame instance for chaining.

eventFrame = new EventFrame({frame: popup});
eventFrame.stop();
// Sometime later, start listening again
eventFrame.start();
eventFrame.stop();

on

on(event: string, listener: function) -> EventFrame

Register a listener to handle an incoming event.

Returns the EventFrame instance for chaining.

Parameter	Type	Description
event	string	The name of the event to add a listener for.
listener	function	The function to handle the incoming event.

eventFrame.on('myEventName', function () {
  console.log('recieved the following arguments:', arguments);
});
 
// With a callback
eventFrame.on('myEventName', function (data, callback) {
  console.log('recieved the following data:', data);
  callback('Thank you very much for your data');
});

off

off(event: string, listener: function) -> EventFrame

Unregister a listener that handles an incoming event. The event and listener must exactly match those used with on.

Returns the EventFrame instance for chaining.

Parameter	Type	Description
event	string	The name of the event to remove a listener from.
listener	function	The function that handled the incoming event.

var event = 'myEventname'
var listener = function () {
  console.log('recieved the following arguments:', arguments);
}
eventFrame.on(event, listener);
eventFrame.off(event, listener);

emit

emit(event: string, [...arg: any], [callback: function])

emit an event, optionally with data. May include a callback as the last parameter that a listener can invoke.

Returns the EventFrame instance for chaining.

Parameter	Type	Description
event	string	The name of the event to emit.
argument	any	Zero or more arguments to pass along with the event.
callback	function	A callback that can be invoked from the listener on the receiving side of the event. The callback must be the last parameter given.

// Emit an event with no arguments
eventFrame.emit('just letting you know');
// Emit an event with some data
eventFrame.emit('My name is', name);
// Emit an event with a callback
eventFrame.emit('What did you have for dinner?', function (item) {
  console.log('They had', item, 'for dinner');
});
// Emit an event with data and a callback
eventFrame.emit('Here is my key. Can I have yours?', myFakeKey, function (theirKey) {
  console.log('Muahah, my key was fake. Here is theirs:', theirKey);
});