Documentation

Iframe

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 how to create an "avatar", an animated character that can react to 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.
In this method please leave the "Iframe URL" property empty.

[NEW!] Uploading a ZIP file

It is possible to upload a ZIP file to 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 lesson 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 to 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 "example" folder. For the module to work properly, you have to 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 recieve messages, react to Check Answers Button, etc. using javasctipt. 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 add event listener onDomNodeRemved and release the memory.

view.addEventListener('DOMNodeRemoved', destroy);
destroy = function () {
    if (event.target !== this) {
        return;
    }
    view.removeEventListener('DOMNodeRemoved', destroy);
    window.removeEventListener("message",getMessage);
};

Properties

Property name Description
IFrame URL An address of a site to be loaded. This site is loaded to iframe and has a greater priority than the Index File.
ZIP File A ZIP file with html contents to be extracted and loaded.
Index html location If the Zip file was provided in the ZIP file property, this property has to determine the location of the main file that will be loaded in the iframe. E.g. "start.html" or "examples/demo.html" etc.
Index File A site file to be loaded. The Index File is loaded to iframe if its URL is empty.
File List A list of files used in iframe source.
Property name Description
File Enables adding the iframe site resources.
ID A unique file id.
Communication ID ID used to communicate between the addon and iframe (must be unique in a lesson).

Supported commands

Command name Params Description
show --- Shows the addon.
hide --- Hides the addon.

Events

The IFrame addon sends ValueChanged event when the state has been updated.

Field name Description
Item N/A
Value N/A
Score N/A

API

In order to validate the communication, the site must send messages and scores with a strict structure.

1. IFrameScore structure

Name Description
pageCount Page Count.
checks Actual checks count.
errors Actual errors count.
mistakes Actual mistakes count.
score Actual gained score.
maxScore Maximum score to gain.
scaledScore Score after scaling.

1.1 IFrame score example

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

2. Message Structure

Name Description
id Communication ID.
actionID Action name.
params Send strict parameters by addon or iframe.

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:

Name Description
SET_WORK_MODE Set work mode.
SET_SHOW_ERRORS_MODE Show errors.
RESET Reset.
STATE_ACTUALIZATION State update with iframe score and iframe state.
STATE_REQUEST Request for state.
SHOW_ANSWERS Show answers.
HIDE_ANSWERS Hide answers.
FILE_DICTIONARY_REQUEST Request for file dictionary.
FILE_DICTIONARY_ACTUALIZATION File dictionary update.

IFrame to Addon communication examples:

Action id Description Response action id
STATE
_ACTUALIZATION
Send the actual iframe state to the addon.
If iframeState is undefined, the addon updates only the iframeScore.
No response
STATE_REQUEST Request state from the addon. STATE
_ACTUALIZATION
FILE_DICTIONARY
_REQUEST
Request file path dictionary from the addon. FILE_DICTIONARY
_ACTUALIZATION

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: {}
}

Addon to IFrame communication examples:

Action id Description
STATE_ACTUALIZATION Send the actual state from the addon to iframe.
If the addon doesn't have the iframeState, the iframeState is undefined during update.
SET_WORK_MODE IFrame should start the work mode.
SET_SHOW_ERRORS_MODE IFrame should show all errors.
RESET IFrame should reset itself.
SHOW_ANSWERS IFrame should show answers.
HIDE_ANSWERS IFrame should hide answers.
FILE_DICTIONARY_ACTUALIZATION Send actual paths dictionary with id (don’t use paths from the file list property!).
CUSTOM_EVENT Send custom event to handle events from iframe in Advanced Connector.

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 contains examples showing how this addon can be used.
Example code contains an example of index.html, resources and scripts presenting how the addon can be used (Please save as .zip file).