https://github.com/constgen/cross-channel
Cross origin messaging channel
https://github.com/constgen/cross-channel
ipc
Last synced: 15 days ago
JSON representation
Cross origin messaging channel
- Host: GitHub
- URL: https://github.com/constgen/cross-channel
- Owner: constgen
- License: mit
- Created: 2016-05-10T22:48:43.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2017-10-23T22:02:53.000Z (over 8 years ago)
- Last Synced: 2025-12-10T20:31:13.449Z (7 months ago)
- Topics: ipc
- Language: JavaScript
- Size: 217 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CrossChannel
Cross origin messaging channel. Sends messages between different JavaScript contexts.
## Installation
In a **Browser** environment:
```html
var channel = new CrossChannel('name')
channel.on('message', handler)
channel.postMessage(message)
```
In a **CommonJS** environment first install it from NPM:
```
$ npm install cross-channel
```
then in the source code use
```js
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
```js
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 ``;
- 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 | - | - | - | - |