The iFrame widget (added to course pages Integrations > Embed tools > iFrame) supports a postMessage API for resizing, sharing, completion, and configuration.

 

postMessage Format

To maximise compatibility with most devices, the postMessage API sends and receives stringified JSON data, e.g.

function(data) {
  // send "data" object to OpenLearning window
  window.parent.postMessage(JSON.stringify(data), '*');
}

Resize

Sending the following message signals the frame to resize to a specified height:

{
  "action": "resize",
  "height": 640
}

Completion

The widget can be marked as completed by sending the following message:

{
  "action": "complete"
}

Note that the completion settings of the widget must be set to: Completed when "complete" message is received.

---

---

Sharing

The widget on OpenLearning can be sent attachments which the learner can then share as posts. These attachments can be (absolute) URLs to HTML pages in your app, or any other media URL.

{
  "action": "share",
  "attachments": [{
    "url": "https://www.example.com",
    "title": "Example Attachment",
    "contentType": "text/html",
    "height": 640
  }],
  "thumbnail": "https://via.placeholder.com/420"
}

Sending the above message will create a new attachment framing the URL "https://www.example.com". This appears below the framed content ready for the learner to share:

---

---

The learner can click "Next" to publish this in the class:

 

When the learner posts this for sharing or submission, the given thumbnail will be used in the gallery:

Content Types:

• "text/..." displays in an iFrame
• "image/..." displays in an image viewer
• "video/..." delivered in a video player
• "audio/..." delivered in an audio player
• Anything else is displayed as a link to the media URL

Setup and Configuration

In the iFrame widget setup, there is a provision for specifying a "setup" document. This can be used to set properties which OpenLearning will store as the widget's "setup data". This setup data can then be accessed by receiving the "init" action in your app. It is recommended to only listen to the first "init" event, e.g.

 

let isInitialised = false;
window.addEventListener('message', function (event) {
  const data = JSON.parse(event.data);

  if (data.action === "init" && !isInitialised) {
    initMyApp(data.setup);
  }
});

Init Data

{
  "action": "init",
  "setup": { ... }
}

Setup

In the iFrame widget setup there is an option: "Supports custom setup":

 

---

---

 

If your iFrame is using an external URL, this will allow you to specify another URL for the "setup" of your app. If your iFrame is an uploaded ZIP package, you can select a setup document from the list of files. 

 

The setup document will also receive the "init" event described above to load existing configuration settings. It is also able to send messages with the "set" action to change a setting. e.g.

{
  "action": "set",
  "name": "myVariable",
  "value": 42
}

The next time the "init" action is received by either the setup view or the learner's view, the "setup" data will contain:

{
  "myVariable": 42
}

Summary

Learner's View

Send actions:

• "resize" to change height
• "complete" to set the widget as completed (if the "Completed when "complete" message is received." completion setting is set)
• "share" to push attachments to OpenLearning for the learner to post

Receive actions:

• "init" to receive "setup" data

Setup View

Send actions:

• "resize" to change height
• "set" to update a setting

Receive actions:

• "init" to receive "setup" data

Code Examples

function sendMessage(message) {
  window.parent.postMessage(JSON.stringify(message), '*');
}

function onResize() {
  sendMessage({
    action: 'resize',
    height: document.documentElement.offsetHeight
  });
}

window.addEventListener('resize', onResize);

let isInitialised = false;

window.addEventListener('message', function (event) {
  let message = JSON.parse(event.data);

  if (message.action === 'init' && !isInitialised) {
    console.log(message.setup.mySetting);

    isInitialised = true;
    onResize();
  }
});

 

Learner's View

const setCompletedButton = document.getElementById('setCompletedButton');
setCompletedButton.addEventListener('click', function () {
  sendMessage({
    action: 'complete',
  });
});

const shareButton = document.getElementById('shareButton');
shareButton.addEventListener('click', function () {
  sendMessage({
    action: 'share',
    attachments: [{
      url: 'https://www.example.com',
      title: 'Example Attachment',
      contentType: 'text/html'
    }],
    thumbnail: 'https://via.placeholder.com/420'
  });
});

 

Setup View

const settingInput = document.getElementById('settingInput');
settingInput.addEventListener('input', function () {
  sendMessage({
    action: 'set',
    name: 'mySetting',
    value: settingInput.value
  });
});