Have ideas to improve npm?Join in the discussion! »

cross-channel

0.6.2 • Public • Published

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

Install

npm i cross-channel

DownloadsWeekly Downloads

1

Version

0.6.2

License

MIT

Last publish

Collaborators

  • avatar