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();
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);
});
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. |
eventFrame.emit('just letting you know');
eventFrame.emit('My name is', name);
eventFrame.emit('What did you have for dinner?', function (item) {
console.log('They had', item, 'for dinner');
});
eventFrame.emit('Here is my key. Can I have yours?', myFakeKey, function (theirKey) {
console.log('Muahah, my key was fake. Here is theirs:', theirKey);
});