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 ifrauifrau exposes three 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.
- SlimClient: A lighter-weight client created by components within free-range apps that may need to send/receive requests and events with the host. This assumes the parent app has already created a full client to manage syncing options.
To create a Host:
import { Host } from 'ifrau/host.js';
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, timezone, internationalization, and OSLO settings 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 defaultsyncCssVariable: whether css variables (in the<head>element) should be kept in sync automatically with the css variables 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 defaultallowMicrophone: whether the frame will allow access to the microphone,falseby defaultallowCamera: whether the frame will allow access to the camera,falseby defaultallowScreenCapture: whether the frame will allow access to record the screen,falseby defaultallowEncryptedMedia: whether the frame will allow access to encrypted media,falseby defaultallowAutoplay: whether the frame will allow access to autoplay,falseby defaultallowClipboard: whether the frame will allow access to the clipboard (copy/paste),falseby default
Creating a Client is even simpler:
import { Client } from 'ifrau/client.js';
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,trueby defaultsyncTitle: whether the host page's title andIFRAMEelement title should be kept in sync with the FRA's title,trueby defaultresizerOptions: pass iframe-resizer client options through to the iframe resizer client
Creating a SlimClient can be done in the same way:
import { SlimClient } from 'ifrau/client/slim.js';
var slimClient = new SlimClient(options);
slimClient
.connect()
.then(function() {
console.log('connected to host!');
});Parameters:
optionsdebug: whether to enable console debugging,falseby 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.
This repo is configured to use semantic-release. Commits prefixed with fix: and feat: will trigger patch and minor releases when merged to main.
To learn how to create major releases and release from maintenance branches, refer to the semantic-release GitHub Action documentation.