HapYak Addons are invoked from annotations within the video frame to manipulate on-page elements and data outside of the video frame.
For example, a video can contain a call-to-action that says "Click here to load the diagram." When clicked, the call-to-action can invoke a HapYak Addon that will load the diagram onto the page, outside of the video frame.
Another example, a video can contain an OnTime annotation that will invoke a HapYak Addon to load a Twitter Feed widget onto the page, outside of the video frame, when the video reaches 30 seconds in the video.
The HapYak Addon API is used by developers to write custom javascript that will live on your webpages. The developer of the Addon will define the behavior, design, look and feel.
hapyak.addon(name, {
init: function () {
}
});
The hapyak.addon
call accepts two mandatory arguments - name
and actions
. They are described as follows:
string - mandatory
The namespace for all events triggered on the addon.
JSON - mandatory
Each property and its value should adhere to the following:
key - string
The name of the event to be triggered.
value - function
The callback function to be called when the event is triggered. The function accepts a single argument which contains the related JSON data.
The return value for a hapyak.addon
call will be a reference to the created instance.
The context for all events (both user-created and otherwise) will have a context where this
will be a reference to the addon instace.
The init
event is automatically triggered once the addon has been setup within HapYak. Setting up a handler for this event is optional.
These methods are attached to the instance returned by the hapyak.addon
call
Cleans up all event listeners setup for the addon instance. The actions
property on the instance is also cleared out. destroy
accepts no arguments.
The HapYak Message API is used internally by the HapYak Addon API and enables communication to and from HapYak components. In addition to invoking HapYak Addons this API may be used to pass messages to and from custom annotations built with the Extension API.
hapyak.message.addEventListener(name, callback, context);
hapyak.message.removeEventListener(name, callback);
hapyak.message.send(frame, event, data);
hapyak.message
provides a way for users to setup and manage handlers to communicate with addons. This communication can be done on the same page or with an iframe on the parent page.
Register a handler to be called when an event of the specified name
is triggered.
function myFunc(data) {
console.log('test fired', data);
}
hapyak.message.addEventListener('test', myFunc, 'hapyak');
name - string - mandatory
The name of the event to be triggered
callback - function - mandatory
A callback function to be run after the event has fired
context - string - optional
Can be used to provide an additional level of specification for the event. Any message that is triggered must contain a context that matches the handlers (if one exists).
Remove a registered event handler with a specified name and function reference
hapyak.message.removeEventListener('test', myFunc);
name - string - mandatory
The name of the event to be removed
callback - function - mandatory
A reference to the callback function used
Allows a user to trigger an event handler for a given event
on either the current page or an iframe.
hapyak.message.send(window, 'test', {
'foo': 'bar'
});
frame - window object - mandatory
A reference to either the current window or a reference to an iframes contentWindow
event - string - mandatory
The name of the event to fire
data - JSON - optional
An optional JSON blob to pass data with
The following example shows how we can communicate with an iframe from the main parent page using our addon to register event handlers.
document.addEventListener("DOMContentLoaded", function () {
var span = document.getElementById("span");
// Setup an addon to listen for events from the iframe annotation
hapyak.addon("color-change-listener", {
init: function () {
console.log("This is a message from init. Perform any setup needed here.");
},
"notify-color": function (e) {
span.innerHTML = "Iframe background is " + e.data.color;
}
});
document.getElementById("button").addEventListener("click", function () {
// Broadcast a message to all iframes on the page
Array.prototype.forEach.call(document.querySelectorAll("iframe"), function (iframe) {
// Send a message to the iframe annotation telling it to change its color to red
hapyak.message.send(iframe.contentWindow, "change-color", {
"color": "red"
});
span.innerHTML = "Iframe background is red";
});
}, false);
}, false);
(function () {
document.addEventListener('click', function () {
document.body.style.backgroundColor = 'blue';
// We need to pass a custom context so only addons we with the name `color-change-listener` act on the event
hapyak.message.send(window.parent, 'notify-color', {
customerContext: 'color-change-listener',
color: 'blue'
});
}, false);
hapyak.message.addEventListener('change-color', function (e) {
document.body.style.backgroundColor = e.data.color;
});
}());
This example is the same as Addon above, except that we're registering all of the message handlers ourself using hapyak.message
methods.
document.addEventListener("DOMContentLoaded", function () {
var span = document.getElementById("span");
// Add an event listener for the notify-color event from our iframe annotation
hapyak.message.addEventListener("notify-color", function (e) {
span.innerHTML = "Iframe background is " + e.data.color;
})
document.getElementById("button").addEventListener("click", function () {
// Broadcast a message to all iframes on the page
Array.prototype.forEach.call(document.querySelectorAll("iframe"), function (iframe) {
// Send a message to the iframe annotation telling it to change its color to red
hapyak.message.send(iframe.contentWindow, "change-color", {
"color": "red"
});
span.innerHTML = "Iframe background is red";
});
}, false);
}, false);
(function () {
document.addEventListener('click', function () {
document.body.style.backgroundColor = 'blue';
hapyak.message.send(window.parent, 'notify-color', {
color: 'blue'
});
}, false);
hapyak.message.addEventListener('change-color', function (e) {
document.body.style.backgroundColor = e.data.color;
});
}());