README/Courier.md
#Overview
Courier is a cross iFrame implementation of an event bus using [postMessage](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) and [MessagChannel](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel) APIs.
It contains all three Event types we support in this Chronos: [Events](Events.md), [Commands](Commands.md) and [ReqRes](ReqRes.md).
Courier exists in the <b>/dist/</b> folder and the <b>/dist/min/</b> folder in two version:
1. <b>PostMessageCourierNoDep.js</b> - without it's dependencies included (Channels, Events, Commands, ReqRes)
2. <b>PostMessageCourier.js</b> - as a complete package with all dependencies
####Courier functions in two main ways:
1. Spawning it's own private events engine
2. Receiving an event engine ([Channels](Channels.md) externally) it can share across iFrames / same Page Apps (*see [Channels](Channels.md) for <b>externalProxy</b> flag)
It is important to note the use case you want when creating a Courier instance.
Example (Private events channel):
```javascript
var courier = new new Chronos.PostMessageCourier({ target : targetConfiguration });
```
Example shared Events channel:
```javascript
var channel = new Chronos.Channels(); //Shared instance you can pass around to other couriers and share Events triggers
var courier = new new Chronos.PostMessageCourier({
eventChannel: channel,
target : targetConfiguration
});
```
##How to set up iFrames with Courier
Both parent page and child iFrame need to include the <b>PostMessageCourier.js</b> from the dist directory (there is a minified, compressed version in the <b>min</b> directory).
In order to set up iFrames you have two options:
1. Create your own iFrame and pass it in to Courier
2. Pass in a URL and let Courier create it for you
##Creating your own iFrame
```javascript
function createIFrame(options) {
var src ,
frame = document.createElement("IFRAME");
for(var key in options.attributes){
frame.setAttribute(key, options[key]);
}
for(var attr in options.styles){
frame.style[attr] = options.styles[attr];
}
frame.addEventListener("load", function() {
if (typeof options.callback === "function") {
options.callback(options.context);
}
}.bind(this), true);
document.body.appendChild(frame);
if (options && options.target && options.target.url) {
src = options.url + (0 < options.url.indexOf("?") ? "&bust=" : "?bust=");
src += (new Date()).getTime();
src += ("&host=" + document.location.protocol + "//" + document.location.host);
frame.setAttribute("src", src);
}
return frame;
}
```
After you have created your own iFrame you need to create a courier instance and pass it to the Courier.
```javascript
var frame = createIFrame({
url: "https://mysite.com/integration/index.html",
attrs: {
id: "MyId",
title: "MyTitle",
name: "MyName",
tabindex : 0
},
styles : {
position: "fixed",
top: "5px",
left: "5px",
width: "50%",
height: "300px"
}
});
var courier = new Chronos.PostMessageCourier({
target: frame,
targetOrigin: protocol + hostname + port
});
```
The other option is to let Courier create the iFrame and pass it back to you.
###Please note if you dont set any attributes the iFrame will be hidden from view.
```javascript
var courier = new Chronos.PostMessageCourier({
target: {
url: protocol + hostname + port + "/MYPATH/index.html",
style: {
width: "100px",
height: "100px"
},
attributes :{
name : "name"
}
}
});
```
##Configuration for Courier
The configuration supports the following properties in the target attribute:
| Parameter | Type | Description | Defaults |
| --- | --- | --- | --- |
| url | String | The URL of your iFrame | None |
| bust | Boolean | If to use a cache bust parameter when adding the iFrame | true |
| container | DOM Element | The element you want the iFrame in | document.body |
| style | Object | The style attributes you'd like to set on the iFrame | ```{ width :"0px", height : "0px", position :"absolute", top : "-1000px", left : "-1000px" }``` |
| attributes | Object | The attributes you'd like to set on the iFrame | ```{"id": name, "name" :name, "tabindex": "-1", "aria-hidden": "true", "title": "","role": "presentation","allowTransparency":"true"}```|
| callback | Function | A function to be called after the iFrame has loaded | None|
| context | Object | The execution context for the callback | None |
Example:
```
{ target :{
url: ...,
style: { ... },
attributes :{ ... }
container: ...,
callback: function() { ... },
context : ...
}
}
```
Other configuration options:
| Parameter | Type | Description | Defaults |
| --- | --- | --- | --- |
| onready | Object with callback and context | A function to be called when the handshake with the iFrame has been completed | None |
| serialize | Function | Function for serializing data into the iFrame | JSON.stringify |
| deserialize | deserialize | Function for deserializing data from the iFrame | JSON.parse |
| targetOrigin | String | the domain of the iFrame being added <b>*must be supplied in case of external iFrame</b> | None |
| handshakeInterval | milliseconds | Number of milliseconds before handshake retry | 5000 |
| handshakeAttempts | int | Maximum attempts at handshake | 3 |
Example:
```
{
target :{ ... }
onready : {
callback: function(){},
context : ...
},
serialize : function() { ... },
deserialize : function() { ... },
targetOrigin: ...,
handshakeInterval : ...,
handshakeAttempts : ...
}
```
##How to use Courier
Once you have a courier instance you can use all the methods supported just like events:
```javascript
// Initialize a new Courier
var courier = Chronos.PostMessageCourier({
target: {
url: "http://www.crossdomain.com/"
}
});
///// ---- BINDINGS ------ ////
courier.bind({
appName: "host",
eventName: "multiply",
func: multiply
});
courier.comply({
appName: "host",
cmdName: "square",
func: square
});
courier.reply({
appName: "host",
reqName: "divide",
func: divide
});
///// ---- INVOCATION ------ ////
courier.trigger({
appName: "frame",
eventName: "got_it",
data: data * 2
});
courier.command({
appName: "frame",
cmdName: "expect",
data: data
}, function(err) {
if (err) {
console.log("Problem invoking command");
}
});
courier.request({
appName: "frame",
reqName: "askBack",
data: data
}, function(err, data) {
if (err) {
console.log("Problem invoking request");
return;
}
// Do Something with the data
console.log(data);
});
```