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

Properties

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.

Methods

The widget object has the following methods:

Method	Return type	Description
createTimeControl()	Object	Creates a Singular timer object.
init()	-	Registers callback functions for onInit, onValue, onButtonClicked, onEditComp, and onAnimation events.
instantiate()	-	Creates an instantiate of a widget composition.
sendCustomMessage()	-	Sends a custom message to a composition script.

createTimeControl()

Returns a Singular timer control object.

Use createTimeControl() to manage timers and synchronize them globally in all composition and output instances.

Parameter

none

Return

object: Time control object

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

See also

Time control object

init()

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
});

Parameter

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.

Also see

Boilerplate example

Return

none

instantiate()

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;
});

Parameter

Name	Type	Description
compositionID	string	A Composition ID returned by the onValue() function.
domElement	html	An HTML dom element.
cb	function	The callback function.

Return

object: Composition Instance

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

See also

Composition instance

sendCustomMessage()

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);

Parameter

Name	Type	Description
message	string, number, object	A message object.

Return

none