Documentation

Description

Iframe allows embedding any HTML content into a lesson. It is possible to link an online website or to upload an HTML file and all its resources so that offline playback is also possible.

See also: Iframe animation controlled by Advanced Connector

(On this page you will find a description of how to create an "avatar", an animated character that can react to the user's answers, give feedback, or provide hints to an activity, and how to control an animation inside the Iframe module.)

Online mode

If you want your content to be accessible only online, you can simply provide a link to your site that will be displayed in the lesson in the "Iframe URL" property. Modules configured this way will not work in offline applications like mLibro.

Offline mode

For the Iframe to work offline:
1. Upload the resources in the "File list" property (if there are any),
2. In the main HTML file, change the URLs of your resources to the paths from the "File list dictionary".
3. Upload the main HTML file to the "Index file" property.
When using this method, please leave the "Iframe URL" property empty.

Uploading a ZIP file

It is possible to upload a ZIP file in the "Zip file" property and the contents will be extracted and added to the presentation automatically. Once the extraction process is finished, the user is notified by email. During the lesson's export, all contents are automatically added to the exported package and can be viewed on an LMS platform like mCourser or in an offline application like mLibro. It is also possible to specify the index file of the package, which can be different than index.html. This means that the same ZIP package can be used in many Iframe modules, and a different index file can be used in those modules – they can share the same common set of files.
Example: Your package can have multiple folders, and the main file is named "start.html" located in the "example" folder. For the module to work properly, you must fill the "Index html location" property with "example/start.html". If the same package also contains another folder e.g. "demo" with a different set of files, you can use the same ZIP file in another module (you can copy and paste or duplicate the page) and simply change the "Index html location" property to "demo/init.html" etc.

Communication with the Player

Your HTML site can communicate with the player, send and receive messages, react to the Check Answers Button, etc. using JavaScript. More details are presented below in the API section.
Please make sure that your HTML and JavaScript code meet the HTML5 standards and are free of errors before uploading them to mAuthor.

Memory and browser stability

Wrong usage of DOM operations or event listeners in scripts may cause memory leaks or browser crash. The script authors are responsible for memory leaks and browser stability.

Fixing memory leaks

The best way to detect page changes and free the memory is to use MutationObserverService and release the memory.

In the run method, add the following call:

MutationObserverService.createDestroyObserver(presenter.destroy);
MutationObserverService.setObserver();

Ensure that the addon includes a cleanup method; otherwise, the call is unnecessary.

Properties

The list starts with the common properties, learn more about them by visiting the Modules description section. The other available properties are described below.

Supported commands

Events

The Iframe module sends a ValueChanged event when the state has been updated.

API

To validate the communication, the site must send messages and scores with a strict structure.

1. IframeScore structure

1.1 IFrame score example

{
    pageCount: 3,
    checks: 5,
    errors: 1,
    mistakes: 4,
    score: 23,
    maxScore: 30,
    scaledScore: 23 
}

2. Message Structure

2.1 Message without params

{
    id: someCommunicationID,
    actionID: "STATE_REQUEST",
    params: {}
}

2.2 Message with params

{
    id:  someCommunicationID,
    actionID:  "STATE_ACTUALIZATION",
    params: {
        iframeScore: exampleIFrameScore,
        iframeState: {
            imagePosition: 2
        }
    }
}

2.3 Action id list:

Iframe to module communication examples:

3.1 State actualization example:

{
    id: someCommunicationID,
    actionID: "STATE_ACTUALIZATION",
    params: {
        iframeScore: exampleIFrameScore,
        iframeState: imageIndex
    }
}

3.2 State request example:

{
    id: someCommunicationID,
    actionID: "STATE_REQUEST",
    params: {}
}

3.3 File dictionary request example:

{
    id: someCommunicationID,
    actionID: "FILE_DICTIONARY_REQUEST",
    params: {}
}

Module to Iframe communication examples:

4.1 State actualization example:

{
    id: someCommunicationID,
    actionID: "STATE_ACTUALIZATION",
    params: {
            iframeScore: exampleIFrameScore,
            iframeState: imageIndex 
            }
}

4.2 Set work mode example:

{
    id: someCommunicationID,
    actionID: "SET_WORK_MODE",
    params: {}
}

4.3 Set show errors mode example:

{
    id: someCommunicationID,
    actionID: "SET_SHOW_ERRORS_MODE",
    params: {}
}

4.4 Reset example:

{
    id: someCommunicationID,
    actionID: "RESET",
    params: {}
}

4.5 Show answers example:

{
    id: someCommunicationID,
    actionID: "SHOW_ANSWERS",
    params: {}
}

4.6 Hide answers example:

{
    id: someCommunicationID,
    actionID: "HIDE_ANSWERS",
    params: {}
}

4.7 Dictionary example:

{
    id: someCommunicationID,
    actionID: "FILE_DICTIONARY_ACTUALIZATION",
    params: {
        fileDictionary: {
        "Ball : "/file/1234124/",
        "Car" : "/file/5311341/"
        }   
    }
}

4.7 Custom event example:

{
    id: someCommunicationID,
    actionID: "CUSTOM_EVENTS",
    params: "SOME_EVENT"
}

AC code:

EVENTSTART
Value:SOME_EVENT
Item:CUSTOM_EVENT
SCRIPTSTART

  code();

SCRIPTEND
EVENTEND

Other Examples

5.1 Start listening for messages:

window.addEventListener("message", function (event) {
    receiveMessageFunction(event);
}, false);

5.2 Send message function:

function getOpener () {
    var parent = null;
    if (window.parent != null && window.parent.postMessage != null) {
        parent = window.parent;
    }
    if (window.opener != null && window.opener.postMessage != null) {
        parent = window.opener;
    }
    return parent;
}

function sendMessage (messageID, actionID, params){
    var parent = getOpener();
    if (parent != null) {
        if(params == undefined) {
            params = {};
        }
        var newMessage = {id : messageID, actionID : actionID, params:params};
        parent.postMessage(newMessage,'*');
    }
}

Demo presentation

Demo presentation showing how to use the Iframe module.
Example code contains an example of index.html, resources, and scripts presenting how the module can be used (Please save as a .zip file).
Example code 2 contains an example of index.html with scripts presenting the possibility of saving the addon's state.