CrossChannel

Cross origin messaging channel. Sends messages between different JavaScript contexts.

Installation

In a Browser environment:

<script src="path/to/connexionjs/dist/cross-channel.min.js"></script>
<script>
    var channel = new CrossChannel('name')
    channel.on('message', handler)
    channel.postMessage(message)
</script> 

In a CommonJS environment first install it from NPM:

$ npm install cross-channel

then in the source code use

var CrossChannel = require('cross-channel')
var channel = new CrossChannel('name')
channel.on('message', handler)
channel.postMessage(message)

Reference

channel.name: String

The name of a channel

channel.postMessage(message: Object)

Sends a message to all other channel instances with the same name. Message can't be a DOM element or contain a DOM element. The message is cloned between different execution contexts.

channel.on('message', handler: Function)

Attaches listener to a 'message' event. The handler is called only when message is sent from another instances with the same channel name, but not called when postmessage() is called on the same instance. The callback is executed with a single argument of MessageEvent object. The event interface:

MessageEvent {
    type: String
    data: Object|Boolean|String|Number|Null|Undefined
    timeStamp: Number
    origin: String
    sourceChannel: String
}

channel.once('message', handler: Function)

Attaches listener that is executed only once for the very first 'message' event.

channel.addEventListener('message', handler: Function)

The alias to channel.on(). Necessary for a compatibility with BroadcastChannel API when used as a polifyll.

channel.removeEventListener('message', handler: Function)

Removes an event handler of a 'message' event.

channel.removeAllListeners('message')

Removes all event handlers of a 'message' event.

channel.close()

Removes all channel event handlers and closes a channel to reveal memory.

Examle

var channelGreen1 = new CrossChannel('green')
var channelGreen2 = new CrossChannel('green')
 
channelGreen1.postMessage({text: 'message'})
channelGreen2.on('message', function(event){
    console.log(event.data) // -> {text: 'message'}
})

Use cases:

• need a BroadcastChannel polifyll;
• developement of a multiple screen expirience in a browser;
• development of a JavaScript API for media players that are embedded in an <iframe>;
• need an unified messaging channel in browser extensions;
• messaging between all frames with any origins in a browser window;
• messaging between all windows/frames and background processes on NWJS platform;
• messaging between "Node" and "Webkit" context on the Node-webkit platform;
• messaging across tabs of the same origin

Compatibility

Browsers

Browsers	self	frames	tabs
Firefox	✓	✓	✓
Android Firefox	✓	✓	✓
Chrome	✓	✓	✓
Android Chrome	✓	✓	✓
Opera <=9	-	-	-
Opera <=12	✓	✓	✓
Opera >=15	✓	✓	✓
Android Opera >=15	✓	✓	✓
Opera mini	✓	✓	✓
Safari >=5	✓	✓	✓
Safari on iOS >= 8	✓	✓	✓
<!--	Chrome on iOS	✓	✓
<!--	Firefox on iOS	✓	✓
Android Browser >=4.1	✓	✓	✓
<!--	IE <=8	-	-
IE >=9	✓	✓	~
Mobile IE >=10	✓	✓	-
Edge	✓	✓	✓
Worker

Extensions

Browsers	self	background	content	popup	options
Chrome extension	✓	✓	✓	✓	✓
Firefox WebExtension	✓	✓	✓	✓	✓
Edge WebExtension
Safari extension	-	-	-	-	-

Applications

Platforms	self	frames	tabs	webview	background	NodeJS
Node-webkit <=0.11	✓	✓	-	o	o	✓
NWJS >=0.13	✓	✓	✓		✓	-
Electron
Chrome app
Windows Universal app
Cordova
Firefox OS app

Server side

Platforms	self	children	parallel	forks
NodeJS	-	-	-	-