framebus

What is framebus?

Framebus is a lightweight JavaScript library for cross-frame communication. It allows you to send and receive messages between different browsing contexts, such as iframes, windows, or tabs, using a simple event-based API.

What are framebus's main functionalities?

Publishing Events

This feature allows you to publish events to other frames. The `emit` method sends an event with a specified name and data payload to any listeners in other frames.

const framebus = require('framebus');

framebus.emit('eventName', { key: 'value' });

Subscribing to Events

This feature allows you to subscribe to events from other frames. The `on` method listens for an event with a specified name and executes a callback function when the event is received.

const framebus = require('framebus');

framebus.on('eventName', (data) => {
  console.log(data); // { key: 'value' }
});

Unsubscribing from Events

This feature allows you to unsubscribe from events. The `off` method removes a previously registered event listener, preventing the callback from being executed when the event is emitted.

const framebus = require('framebus');

const callback = (data) => {
  console.log(data);
};

framebus.on('eventName', callback);

// Later, to unsubscribe
framebus.off('eventName', callback);

Other packages similar to framebus

post-robot

Post-robot is a library for cross-domain iframe communication. It provides a robust API for sending and receiving messages between different windows or iframes, with support for promises and error handling. Compared to framebus, post-robot offers more advanced features like message validation and security checks.

jschannel

JSChannel is a library for secure cross-domain communication between iframes. It uses a message-passing mechanism to enable communication between different browsing contexts. Compared to framebus, JSChannel focuses more on security and provides a structured protocol for message exchange.

crossmessaging

Crossmessaging is a library for cross-origin communication between iframes and windows. It provides a simple API for sending and receiving messages, similar to framebus. However, crossmessaging includes additional features like message queuing and retry mechanisms.

README

Framebus

Framebus allows you to easily send messages across frames (and iframes) with a simple bus.

In one frame:

var bus = require('framebus');

bus.emit('message', {
  from: 'Ron',
  contents: 'they named it...San Diago'
});

In another frame:

var bus = require('framebus');

bus.on('message', function (data) {
  console.log(data.from + ' said: ' + data.contents);
});

API

target(origin): framebus

returns: a chainable instance of framebus that operates on the chosen origin.

This method is used in conjuction with publish, subscribe, and unsubscribe to restrict their results to the given origin. By default, an origin of '*' is used.

framebus.target('https://example.com').on('my cool event', function () {});
// will ignore all incoming 'my cool event' NOT from 'https://example.com'

Argument	Type	Description
origin	String	(default: '*') only target frames with this origin

publish('event' [, arg...] [, callback]): boolean

aliases: pub, trigger, emit

returns: true if the event was successfully published, false otherwise

Argument	Type	Description
event	String	The name of the event
arg	any	The data to give to subscribers
callback(data)	Function	Give subscribers a function for easy, direct replies

subscribe('event', fn): boolean

alises: sub, on

returns: true if the subscriber was successfully added, false otherwise

Unless already bound to a scope, the listener will be executed with this set to the MessageEvent received over postMessage.

Argument	Type	Description
event	String	The name of the event
fn([arg...] [, callback])	Function	Event handler. Arguments are from the publish invocation
↳ this	scope	The MessageEvent object from the underlying postMessage

unsubscribe('event', fn): boolean

aliases: unsub, off

returns: true if the subscriber was successfully removed, false otherwise

Argument	Type	Description
event	String	The name of the event
fn	Function	The function that was subscribed

include(popup): boolean

returns: true if the popup was successfully included, false otherwise

var popup = window.open('https://example.com');

framebus.include(popup);
framebus.emit('hello popup and friends!');

Argument	Type	Description
popup	Window	The popup refrence returned by window.open

Pitfalls

These are some things to keep in mind while using framebus to handle your event delegation

Cross-site scripting (XSS)

framebus allows convenient event delegation across iframe borders. By default it will broadcast events to all iframes on the page, regardless of origin. Use the optional target() method when you know the exact domain of the iframes you are communicating with. This will protect your event data from malicious domains.

Data is serialized as JSON

framebus operates over postMessage using JSON.parse and JSON.stringify to facilitate message data passing. Keep in mind that not all JavaScript objects serialize cleanly into and out of JSON, such as undefined.

Asynchronicity

Even when the subscriber and publisher are within the same frame, events go through postMessage. Keep in mind that postMessage is an asynchronous protocol and that publication and subscription handling occur on separate iterations of the event loop (MDN).

Published callback functions are an abstraction

When you specify a callback while using publish, the function is not actually given to the subscriber. The subscriber receives a one-time-use function that is generated locally by the subscriber's framebus. This one-time-use callback function is pre-configured to publish an event back to the event origin's domain using a UUID as the event name. The events occur as follows:

1. http://emitter.example.com publishes an event with a function as the event data

   var callback = function (data) {
       console.log('Got back %s as a reply!', data)
   }
   
   framebus.publish('Marco!', callback, 'http://listener.example.com');
   

2. The framebus on http://emitter.example.com generates a UUID as an event name and adds the callback as a subscriber to this event.

3. The framebus on http://listener.example.com sees that a special callback event is in the event payload. A one-time-use function is created locally and given to subscribers of 'Marco!' as the event data.

4. The subscriber on http://listener.example.com uses the local one-time-use callback function to send data back to the emitter's origin

   framebus.target('http://emitter.example.com')
     .on('Marco!', function (callback) {
        callback('Polo!');
     });
   

5. The one-time-use function on http://listener.example.com publishes an event as the UUID generated in step 2 to the origin that emitted the event.

6. Back on http://emitter.example.com, the callback is called and unsubscribed from the special UUID event afterward.

Development and contributing

See CONTRIBUTING.md