iFrameAPI

s-c edited this page Mar 5, 2014 · 2 revisions
Clone this wiki locally

iFrame API

The iFrame API enables the communication with the Klynt player using the HTML5 cross-origin communication API postMessage.

More specifically, it allows :

  • Sending commands to the player.
  • Receiving notifications from the player.
  • Sending requests to the player and receiving a response.

Description

Sending commands

The iframe API allows sending the player commands that it executes.

Syntax

The syntax to send a command to the player is the following:

KlyntAPI.commands.commandName(param);

where commandName is the name of the command and param is an optional parameter.

Available commands

Command Params Description / Example
openUrl url Opens a link
KlyntAPI.commands.openUrl("http://www.klynt.net");
openWidget widgetId Opens the widget defined by its id
KlyntAPI.commands.openWidget("A738CC06-B1E2-BB7B-6409-1CC98CC5165E");
share Shows a modal view with sharing options
KlyntAPI.commands.share();
toggleMute Toggles between the mute and unmute states of the player
KlyntAPI.commands.toggleMute();
mute Mutes the player
KlyntAPI.commands.mute();
unmute Unmutes the player
KlyntAPI.commands.unmute();
toggleFullScreen Toggles between the fullscreen state and normal state of the player
KlyntAPI.commands.toggleFullScreen();
enterFullScreen Enters the fullscreen state in browsers that support the fullscreen functionality
KlyntAPI.commands.enterFullScreen();
exitFullScreen Exists the fullscreen state
KlyntAPI.commands.exitFullScreen();
togglePlayPause Toggles between the play and pause states of the player
KlyntAPI.commands.togglePlayPause();
play Starts or resumes playing the current sequence
KlyntAPI.commands.play();
pause Pauses the current sequence
KlyntAPI.commands.pause();
openSequence seqId Opens the sequence defined by its id*
KlyntAPI.commands.openSequence("5E8535EE-BB42-7C98-38A1-1619C07E1B36");
openOverlay seqId Opens the sequence defined by its id* as an overlay
KlyntAPI.commands.openOverlay("5E8535EE-BB42-7C98-38A1-1619C07E1B36");
closeOverlay Closes the current overlay
KlyntAPI.commands.closeOverlay();

* The id of a sequence can be found in its properties panel in the storyboard. Alternatively, the sequence can be identified by its alias instead of its id. The alias can be found in the url of the navigator when the sequence is displayed in the player.

Listening to notifications

Syntax

The syntax to send a request to the player is the following:

KlyntAPI.notifications.addEventListener(eventName, eventHandler);

where eventName is the name of the event and eventHandler is a callback function that will be called when the event is received.

Available notifications

There is only one built-in notification (fullscreen) in the current version of the player, but other notifications may be implemented in future versions.

Sending requests

Requests are like commands except that they have a callback function as a parameter. This callback is called when the player finishes processing the request.

Syntax

The syntax to send a request to the player is the following:

KlyntAPI.query(requestName, param, responseHandler);

where requestName is the name of the request, param is a parameter, and responseHandler is a callback function that will be called when the response is received.

Available requests

No built-in requests are implemented in the current version of the player, but they may be implemented in future versions.

Usage

First, import KlyntAPI.js into the iframe:

<script src="Player/js/api/KlyntAPI.js" type="text/javascript"></script>

Sending commands

Example:

<button onclick="KlyntAPI.commands.openSequence({
    targetSequence: 'Sequence_2',
    transition: 'fade'
});">Sequence 2</button>

Listening to notifications

Example:

KlyntAPI.notifications.addEventListener('fullscreen', function (event) {
    console.log('fullscreen!');
});

Sending requests

Example:

KlyntAPI.query('sequenceName', {}, function (result) {
    console.log('Current sequence: ' + result);
});

Examples

Communication with an iframe contained in a sequence

In this example, a custom iframe is added to a sequence in the Klynt editor. This iframe contains a basic menu that can play/pause the player.

<!DOCTYPE html>
<html>
    <head>
        <title>An html page that embeds a klynt Player</title>
        <script src="Player/js/api/KlyntAPI.js" type="text/javascript"></script>
    </head>
    <body>
        <button onclick="KlyntAPI.commands.togglePlayPause();">Play/Pause</button>
        <script>
            KlyntAPI.notifications.addEventListener('fullscreen', function (event) {
                console.log("Fullscreen changed!");
            });
        </script>
    </body>
</html>