Skip to content

constgen/cross-channel

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

72 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

| Android Browser >=4.1| ✓ | ✓ | ✓ |

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

About

Cross origin messaging channel

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages