Short for iframe-free-range-app-utilities, ifrau makes it easy to communicate from within an IFRAME cross-domain to a parent host. It wraps postMessage in an easy-to-use, promise-based API.
Install from NPM:
npm install ifrauOr include it in your application as UMD/CommonJs from the Brightspace CDN:
<!-- probably what you're looking for -->
<script src="https://s.brightspace.com/lib/ifrau/{version}/ifrau/client.js"></script>
<!-- actually hosting a FRA on your page? grab the host -->
<script src="https://s.brightspace.com/lib/ifrau/{version}/ifrau/host.js"></script>
<!-- the old bundle is still available too -->
<script src="https://s.brightspace.com/lib/ifrau/{version}/ifrau.js"></script>ifrau exposes two classes:
- Host: Created once for each FRA by the AppLoader within Brightspace.
It will build an
IFRAMEelement, point it at the FRA endpoint, and wait for the FRA to load and connect. It can then respond to events and requests from the FRA. - Client: Created by the free-range app, it will establish communication with the host and can then be used to send/receive requests and events.
To create a Host:
var Host = require('ifrau/host');
function parentProvider() {
return document.getElementById('myParentId');
}
var host = new Host(parentProvider, endpoint, options)
host.connect().then(function() {
console.log('connected to client');
});Parameters:
parentProvider: function which will return the parent HTML element into which to insert theIFRAMEendpoint: URL of the free-range app endpoint (thesrcof theIFRAME)optionsdebug: whether to enable console debugging,falseby defaultresizeFrame: whether theIFRAMEshould automatically resize to fit its content,trueby defaultsyncFont: whether to allow client to automatically sync its font size with the host,falseby defaultsyncLang: whether to allow client to automatically sync its language with the host,falseby defaultsyncPageTitle: whether the page title (in the<head>element) should be kept in sync automatically with the title of the FRA,falseby defaultheight: sets the iframe to a certain height, also disables automatic resizingid: sets the id of the iframeallowFullScreen: whether the frame can be placed into full screen mode,falseby default
Creating a Client is even simpler:
var Client = require('ifrau/client');
var client = new Client(options);
client
.connect()
.then(function() {
console.log('connected to host!');
});Parameters:
optionsdebug: whether to enable console debugging,falseby defaultresizeFrame: whether thisClientshould participate in automatic resizing.trueby defaultsyncFont: whether the font size should be automatically set to match the host page,falseby defaultsyncLang: whether the page's language tag should be automatically set to match the host page,falseby defaultsyncTitle: whether the host page's title andIFRAMEelement title should be kept in sync with the FRA's title,trueby default
Events are the simplest way to communicate between the host and client. They're an asynchronous "fire and forget" mechanism.
Let's say the host wanted a way to notify all clients that the user's session had expired. This example adds a handler for the sessionExpired event in the client:
var client = new Client();
client.onEvent('sessionExpired', function(who, when) {
console.log('session expired', who, when);
}).connect().then(function() {
console.log('connected to host');
});The handler should be added before the call to connect(), otherwise it could miss events.
From the host's perspective, events must be triggered after a connection is established:
var host = new Host(...);
host.connect().then(function() {
host.sendEvent('sessionExpired', 'user123', new Date());
});Although this example sends an event from the host to the client, both parties can register for and send events.
Requests are similar to events, but instead of "fire and forget", they use promises to pass along a response to the requester.
Just like events, request handlers should be set up before connecting:
var host = new Host(...);
host.onRequest('sayMyName', 'Heisenberg')
.connect().then(function() {
console.log('connected to client!');
});Request handlers can either be a static value like in the "sayMyName" example above, or a function which can take optional arguments and returns a value:
host.onRequest('addThesePlease', function(p1, p2) {
return p1 + p2;
});Finally, if the result isn't available immediately, the function can return a promise:
host.onRequest('addSlower', function(a, b) {
return new Promise(function(resolve, reject) {
setTimeout(function() {
resolve(a + b);
}, 1000);
});
});On the other side, making request()s uses a promise-based API:
var client = new Client();
client.connect()
.then(function() {
return client.request('addThesePlease', 2, 3);
}).then(function(val) {
console.log(val); // 5
});Building on the concept of requests, services can be registered by both the host and client. Services provide a way to wrap a set of methods in an API which can be versioned.
Again, services must be registered before connecting:
var host = new Host(...);
host.registerService('calculator', '1.0', {
add: function(a, b) {
return a + b;
},
subtract: function(a, b) {
return a - b;
}
});To support breaking changes to your APIs while maintaining backwards compatibility, multiple versions of a service may be registered by passing in different values for the version.
Note: service methods become static, so any reference to this inside your methods will refer to the method itself.
Calling service APIs after connecting is simple and promise-based:
var client = new Client();
client.connect()
.then(function() {
return client.getService('calculator', '1.0');
}).then(function(calculator) {
return calculator.add(1, 5);
}).then(function(result) {
console.log(result); // 6
});ifrau hosts and clients can be extended with plugins:
var myPlugin require('ifrau-someplugin');
var client = new Client()
.use(myPlugin);Please prefix plugin names with ifrau-* so that it can be easily found.
When setting up your event, request handlers and services on the host or client, they can be chained:
var client = new Client();
client.onEvent('jump', function() {
// handle "jump" event
}).onEvent('skip', function() {
// handle "skip" event
}).onRequest('time', new Date())
.onRequest('sayMyName', function() {
return 'Heisenberg';
}).registerService('myService', '1.2', {...});Contributions are welcome, please submit a pull request!
This repository is configured with EditorConfig rules and contributions should make use of them.