Developer Portal
Quick StartsComposition scriptingAPIs and SDKsSupport
  • Portal overview
  • Quick start
  • REST API
    • Introduction
    • Rate limits
    • Authorization
    • How-to guides
      • Get a control app's API token
      • Get a composition's sub-composition IDs and names and their payload structures
      • Get a control app's model
      • Get a control app's metadata
      • Update a sub-composition's content
      • Update a sub-composition's animation state
      • Update a sub-composition's content and animation state in one call
      • Update multiple sub-compositions in one call
    • API reference
      • Get control app details
        • Get a control app's metadata
        • Get a control app's model
        • Get a control app's control data
      • Send data to a control app
        • Update a control app's content
        • Update a control app's animation state
      • Take out all of an app's output
  • Data stream API
    • Introduction
    • Rate limits
    • Authorization
    • How-to guides
      • Create a data stream
      • Link a data stream to a composition
      • Send data to an app using the data stream API
    • API reference
  • Composition scripting
    • Introduction
    • Overview
    • Quick start
      • Find sub-compositions and widgets
      • Read and update control nodes
      • Set text widget text properties
      • Read and update widget properties
      • Read control nodes and update widget properties
      • Set image widget URL property
      • Set table widget content property
    • Cheat sheets
      • Fundamentals
      • Interactive overlays
      • Best practices
    • Use cases
      • Read control nodes and generate HTML text
      • Read control nodes, generate HTML text with background
      • Text Ticker - Start ticker on "In" animation
    • Composition script editor reference
  • Software development kits
    • Graphics SDK
      • Getting started
      • Reference
        • SDK functions
        • Composition object
        • Sequencer object
      • Guides and examples
        • Load a composition with its token
        • Load a composition with its URL
        • Get the composition URL of an app instance
        • Sequencer VOD example
        • Control local preview of app
        • Load app instance output
    • Overlay SDK
      • Getting started
      • SDK functions
      • Use case examples
    • Widget SDK
      • Preparing your environment
      • Getting started
      • Reference
        • Widget UI definition
        • Widget callback functions
        • Time control object
        • Composition instance
      • Guides and examples
        • Widget example: CSS patterns
    • App SDK
  • Singular Basics
    • Overview of Singular
    • Managing overlays in the Dashboard
      • How to create a new composition
      • How to open a new app template
      • How to create an app for a composition
      • How to extract a composition from an app
      • How to find an app's shared app token and shared API URL
      • Dashboard reference
    • Building overlays in Composer
      • How to build a composition
      • How to set up layer logic to automate overlay transitions
      • How to set up control nodes to make widget properties available to a control app
      • Animating overlays
        • How to create timeline animations
        • How to create behavior animations
        • How to create update animations
      • How to make overlays interactive
      • How to adapt overlays to various screen sizes
      • Composer reference
    • Controlling overlays in Studio and UNO
      • How to use Studio
      • Studio reference
      • UNO reference
  • Support
    • Singular status
    • Support resources
    • Singular terminology
    • Performance Testing
Powered by GitBook
On this page
  • Properties
  • Methods
  • createTimeControl()
  • init()
  • instantiate()
  • sendCustomMessage()

Was this helpful?

  1. Software development kits
  2. Widget SDK

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

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.

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

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

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

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

PreviousGetting startedNextWidget UI definition

Last updated 2 years ago

Was this helpful?

Time control object
Boilerplate example
Composition instance
createTimeControl()
init()
instantiate()
sendCustomMessage()