Reference
The reference documentation provided in the following sections describes the Widget SDK structure and methods, and the widget UI definition.
The Widget SDK returns an object with the following properties and methods:
Debug Console
SingularWidget {init: ƒ, getStyle: ƒ, instantiate: ƒ, sendCustomMessage: ƒ}
> compositionId: "-NIqFVJ1rRnNsiUQJing"
> createTimeControl: ƒ ()
> init: ƒ (hash)
> instanceId: undefined
> instantiate: ƒ (compName, domTarget, instantiateCallback)
> sendCustomMessage: ƒ (obj)
> widgetId: 4215
> widgetVersion: 1
The widget object has the following properties:
Name | Type | Example | Description |
---|---|---|---|
compositionId | String | "-NIqFVJ1rRnNsiUQJing" | The ID of a (sub)composition. |
instanceId | String | | The ID of a widget composition instance. |
widgetId | Number | 4215 | The ID of a widget template. |
widgetVersion | Number | 1 | The version of a widget. |
The widget object has the following methods:
Method | Return type | Description |
---|---|---|
Object | Creates a Singular timer object. | |
- | Registers callback functions for onInit , onValue , onButtonClicked , onEditComp , and onAnimation events. | |
- | Creates an instantiate of a widget composition. | |
- | Sends a custom message to a composition script. |
Returns a Singular timer control object.
Use
createTimeControl()
to manage timers and synchronize them globally in all composition and output instances. none
object
: Time control objecttimeControl: {tc: {…}, allowBackwardsJump: false, roundToInterval: true, intervalID: null, timeoutID: null, …}
> allowBackwardsJump: false
> getCurrentTime: ƒ ()
> intervalID: null
> intervalTime: 1000
> offsetToServerTime: 0
> oldRunningTime: 0
> roundToInterval: true
> setAllowBackwardsJump: ƒ (v)
> setIntervalTime: ƒ (time)
> setOffsetToServerTime: ƒ (time)
> setRoundToInterval: ƒ (v)
> setTimeControl: ƒ (tc)
> setUpdateCallback: ƒ (callback)
> tc: {UTC: 0, isrunning: false, value: 0}
> timeoutID: null
> updateCallback: null
Initializes and registers callback functions.
/**
* initialize the Singular widget object and define callback functions
*/
SingularWidget.init({
onInit: onSingularInit,
onValue: onSingularValue,
onButtonClicked: onSingularButtonClicked,
onEditComp: onSingularEditComp,
onAnimation: onSingularAnimation
});
The
init()
function defines callback functions for events in a JSON object.Event | Description |
---|---|
onInit | Called when loading a composition, adding a widget, or closing a widget composition. |
onValue | Called when changing a value in a widget UI field. |
onButtonClicked | Called when clicking a button in a widget UI. |
onEditComp | Called when starting to edit a widget composition. Creates and initializes widget nodes in this callback. |
onAnimation | Called when a widget supports custom widget animations and a user selected using the widget animation in the animation timeline. |
none
Creates an instance of a composition and initializes it. This function is only required when a widget supports widget compositions.
// The code below creates a new composition instance
// compositionId returned by the onValue() callback
const domElement = document.getElementById("container");
// check if compositionInstance exists
if (compInstance != null) {
compInstance.destroy();
compInstance = null;
}
SingularWidget.instantiate(compositionId, domElement, function cb(comp) {
// returns a composition instance
compInstance = comp;
});
Name | Type | Description |
---|---|---|
compositionID | string | A Composition ID returned by the onValue() function. |
domElement | html | An HTML dom element. |
cb | function | The callback function. |
object
: Composition InstancecompInstance: {onAirRefId: '56344bcd-9b83-43e2-863b-a5e5fde60c4f', getDuration: ƒ, is2Timeline: ƒ, …}
> animate: ƒ (t)
> destroy: ƒ ()
> getDuration: ƒ ()
> is2Timeline: ƒ ()
> jumpTo: ƒ (t)
> onAirRefId: "56344bcd-9b83-43e2-863b-a5e5fde60c4f"
> playTo: ƒ (t,i)
> resize: ƒ (t,e)
> seek: ƒ (t,i)
> setControlNode: ƒ (t)
> setWidgetNode: ƒ (t)
> stop: ƒ () -> ask Khing
Sends a custom message to the composition script. Registers a message listener in composition script to receive and process the message object.
// define custom message object
const message = {
"type": "json",
"timestamp": Date.now(),
"tableJson": jsonData
};
// send custom message object
SingularWidget.sendCustomMessage(message);
Name | Type | Description |
---|---|---|
message | string, number, object | A message object. |
none
Last modified 8mo ago