trainmanjs

TrainmanJS - Cross-Origin Communication Library

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
trainmanjs
1620.5.15 years ago5 years agoMinified + gzip package size for trainmanjs in KB

Readme

version dependencies dev dependencies
TrainmanJS
TrainmanJS is Cross-Origin Communication Library. It's a wrapper for the native postMessage API.
It allows you to send bidirectional Topics and Messages between the iframes and wrapper (parent) window.
Trainman
The Trainman is an exile who created and operates Mobil Avenue and is a servant of another exile program known as the Merovingian.
source: http://matrix.wikia.com/wiki/TheTrainman

Features

- Topics and messages
You can listen to different kind of topics and message to it. You have control to which frame you would like to send
a message. What is also important, the parent frame knows exactly which child frame did send the message. Thanks to
that you can omit some topics from particular recipients inside your topic listener.
- Lazy loading
Thanks to the queuing mechanism and buffer you can start sending messages immediately.
You can send a message from the wrapper (parent) window to the child iframe even it's still loading.
Queued messages will be delivered once the connection is established.

- Reconnection
When the child frame will reload itself, Trainman will try to reconnect with it. During the reconnection, Trainman
will queue messages inside his buffer. Queued messages will be delivered once the connection is established again.

- Bulk operation (upcoming)
Post a message to all child frames at once. Don't need to specify an exact recipient. You can use the **'*'** symbol
for sending a message to all of the connect children frames.
 
- Debug mode
Easily turn on and off logging mechanism. Thanks to that you can debug your code and application in a much more simple
way. You can track and check whole Trainman and Passenger communication.
- F2F (upcoming)
Frame-to-frame direct communication. Allow to send and proxy messages directly between the child frames.

How to install

NPM and Yarn

You can install the library using NPM:
npm install trainmanjs -S
// or
yarn add trainmanjs

Next, you can import TrainmanJS module into your app:
import Trainman from 'trainmnanjs';

For the child pages (frames) you should import Passenger class:
import { Passenger } from 'trainmnanjs';
````

### Using CDN

You can also use the **CDN** service ex. [unpkg.com](https://unpkg.com/trainmanjs@0.5.0) or [npm-cdn.herrokuapp.com](http://npm-cdn.herokuapp.com/trainmanjs@0.5.0/lib/trainmanjs.js)

```html
<script src="https://unpkg.com/trainmanjs"></script>

<!-- or -->

<script src="http://npm-cdn.herokuapp.com/trainmanjs@0.5.0/lib/trainmanjs.js"></script>

Then you can access the Trainman and Passenger from the injected module:
(function(module) {
  const Trainman = module.Trainman;
  const Passenger = module.Passenger;
})(window.trainmanjs);

How to use it

TBA

Examples

Simple Example

  1. Check simple example how to use Trainman
  2. Here you can find the source code for the above example

Re-connection and Debug Mode

  1. Reconnection example
  2. Here you can find the source code for the above example