Comment on page
Fundamentals
This section of the composition scripting documentation includes essential cheat sheets for the following:
The initialization of composition scripts works from the bottom up and starts from the lowest child up to the root.
All composition scripts have an
init() and a close() function. Initialize your custom code and variables in the init() function and use the close() function to clean up memory and clear timeouts and intervals.Global Script
(function() {
return {
init: function(context) {
// ...
},
close: function() {
// ...
}
};
})();
The
init function is called after the script is evaluated. The context provides access to common objects, including global storage and utility functions.The
close function is called when the script is unloaded, for example when a browser tab is closed. Use it to clean up memory and clear timeouts, intervals, XHR requests, etc.Root & sub-composition Script
(function() {
return {
init: function(comp, context) {
// ...
},
close: function(comp, context) {
// ...
}
};
})();
The
init function is called after the script is evaluated. The comp argument contains the composition object the script is attached to. The context provides access to common objects, including custom global objects and utility functions.The
close function is called when the script is unloaded, e.g. when closing the browser tab. Use it to clean up memory and clear timeouts, intervals, XHR requests, etc.The composition object provides methods to navigate through the composition structure, read and update content, transformation and effects parameters, access the DOM element, and trigger animations.
The most frequently used methods are:
Composition object properties and methods
> find: ƒ ()
> findGroup: ƒ ()
> findWidget: ƒ ()
> getPayload: ƒ ()
> getPayload2: ƒ ()
> getState: ƒ ()
> getSubcompositionById: ƒ (t)
> id: "1234-5678-abcd-efgh"
> jumpTo: ƒ (i)
> listSubcompositions: ƒ ()
> name: "subCompName"
> parent: ƒ ()
> playTo: ƒ (i)
> setPayload: ƒ (i)
Returns an array of composition objects that matches the defined search string.
// We use the first composition with the matching name
const compClock = comp.find("Clock")[0];
Returns an array of group objects that matches the defined search string.
// We use the first group with the matching name
const groupLowers = comp.findGroup("Lowers Group")[0];
Returns an array of widget objects that matches the defined search string.
// We use the first widget with the matching name
const wiTitle = comp.findWidget("Title")[0];
// Find the first matching widget in a group
const wiTeam1Name = comp.findWidget("Team1 Group", "teamName")[0];
const wiTeam2Name = comp.findWidget("Team2 Group", "teamName")[0];
Returns the control node content from the composition as an array of key value pairs.
const payload = comp.getPayload();
console.log(payload);
Debug console
> [
> {
> "key": "Title",
> "value": "The Title"
> }
> ]
Returns the control node content from the composition as a JSON object.
const payload = comp.getPayload2();
console.log(payload);
Debug console
> {
> "Title": "The Title"
> }
Returns the animation state of the composition.
Animation state | Description |
|---|---|
In | Timeline at In state |
Out | Timeline at Out state |
Out1 | Timeline 1 at Out state |
Out2 | Timeline 2 at Out state |
const animState = comp.getState();
console.log(animState );
Debug console
> In
Returns the composition object defined by its ID.
const compClock = comp.getSubcompositionById("ceedfea8-c060-6d2e-2199-c5f794dcbd16");
The composition ID.
console.log(compClock.id);
Debug console
> ceedfea8-c060-6d2e-2199-c5f794dcbd16
Jumps to the specified animation state.
comp.jumpTo("In");
Returns an array of JSON objects containing sub-composition names and IDs.
const subcomps = comp.listSubcompositions();
Debug console
> [
> {
> "id": "-NHTgDrKFKdlaexZeerp",
> "name": "Clock"
> }, {
> ...
> }
> ]
The composition name.
console.log(compClock.name);
Debug console
> Clock
Returns the parent composition object.
const compParent = comp.parent();
Plays the animation to the specified state.
comp.playTo("In");
Sets the control node content of the composition.
const payload = {"Title": "The Title"};
comp.setPayload(payload);
The widget object provides methods to read and update widget specific properties, transformation and effects parameters, and access the
Dom element. The most frequently used methods are:
Widget Object Properties and Methods
> getDomElement: ƒ (t)
> getPayload: ƒ ()
> getPositionX: ƒ (o)
> getPositionY: ƒ (o)
> getRotateZ: ƒ (o)
> getSizeX: ƒ (o)
> getSizeY: ƒ (o)
> getVisibility: ƒ (o)
> id: "262ec4f4-3a1d-43ee-90c5-20116e8b2e49"
> setPayload: ƒ (o)
> setPositionX: ƒ (o)
> setPositionY: ƒ (o)
> setRotateZ: ƒ (o)
> setSizeX: ƒ (o)
> setSizeY: ƒ (o)
> setVisibility: ƒ (o)
Returns the HTML
Dom element for the widget.const wiDom = wiText.getDomElement();
console.log(wiDomco);
Debug console
> <div data-singular-type="widget" data-singular-name="Text" id="onair262ec4f4-3a1d-43ee-90c5-20116e8b2e49"
> style="position: absolute; left: 25%; top: 42.5%; height: 15%; width: 50%; visibility: inherit; z-index: -1; pointer-events: none; opacity: 1;">
> ...
> subComp</div></div></div>
Returns the widget type specific properties as a JSON object.
const propsText= wiTitle.getPayload();
console.log(props.Text);
Debug console
> {
> "color": {...},
> "font": {...},
> "indent": 0,
> "letterSpacing": 0,
> "lineHeight": "normal",
> "lineHeightCustom": 115,
> "maximumOfLines": 1,
> "minimumOfLines": 1,
> "overflow": "adjustLetterWidth",
> "paddingActive": false,
> "paddingBottom": 0,
> "paddingLeft": 0,
> "paddingRight": 0,
> "paddingTop": 0,
> "shadowActive": false,
> "shadowBlur": 2,
> "shadowColor": {...},
> "shadowDirection": 45,
> "shadowDistance": 3,
> "text": "The Title",
> "transform": "none",
> "verticalAdjustment": 0,
> "verticalAlignment": "baseline",
> "wordSpacing": 0
> }
Returns the
positionX or positionY value in a percentage.const posX = wiText.getPositionX();
const posY = wiText.getPositionY();
console.log("posX = %d, posY = %d", posX, posY);
Debug console
> posX = 50, posY = 50
Returns the
rotationZ value in degrees.const rotZ = wiText.getRotationZ();
console.log("rotZ = %d", rotZ);
Debug console
> rotZ = 90
Returns the sizeX or sizeY value in a percentage.
const sizeX = wiText.getSizeX();
const sizeY = wiText.getSizeY();
console.log("sizeX = %d, sizeY = %d", sizeX, sizeY );
Debug console
> sizeX = 25, sizeY = 80
Returns the visibility as a boolean.
const isVisible = wiText.getVisibilty();
console.log("isVisible =", isVisible );
Debug console
> isVisible = true
Returns the widget ID.
console.log(wiText.id);
Debug console
"262ec4f4-3a1d-43ee-90c5-20116e8b2e49"
Sets one or multiple widget specific properties.
wiText.setPayload({"text": "The new title"});
Sets the
positionX or positionY value in a percentage.wiText.setPositionX(75);
wiText.setPositionY(50);
Sets the
rotationZ value in degrees.wiText.setRotationZ(180);
Sets the
sizeX or sizeY value in a percentage.wiText.setSizeX(50);
wiText.setSizeY(25);
Sets the visibility as a boolean.
wiText.setVisibility(false);
{
"global": {},
"utils": {
createDataStream: ƒ (t,e,i)
createMoment: ƒ i()
createTinyColor: ƒ c(e,t)
getSingularWindow: ƒ ()
}
}
A custom global object including variables, objects, and functions.
Creates a data stream listener.
Create and close a Data Stream
(function() {
// https://support.singular.live/hc/en-us/articles/360056901272-Data-Stream-Manager
const data_stream_public_token = "your-data-stream-public-token";
// we define the datas tream variable in the global scope
let datastream = undefined;
return {
init: function(comp, context) {
// we create the data stream object using the public token
datastream = context.utils.createDataStream(data_stream_public_token,
(status, payload) => {
switch (status) {
case "message":
console.log("we have received data:", status, payload);
break;
case "connecting":
case "connect":
case "open":
case "close":
case "disconnect":
console.log("status:", status);
break;
case "error":
console.error("error:", status);
break;
}
});
},
close: function(comp, context) {
// we close the data stream connection
if (datastream != undefined) {
datastream.close();
}
}
};
})();
Returns the render window name.
const singularWindow = context.utils.getSingularWindow();
console.log("Singular window name:", singularWindow);
Debug console
> Singular window name: app_output or app_control or script_editor
The
addListener() method attaches an event handler to the composition without overwriting existing event handlers. You can add multiple event handlers for the same event type.The first parameter defines the type of the event. Event types include:
The second parameter is a function that you call when an event occurs.
This event occurs when the control nodes of the composition or a sub-composition changes.
The callback function receives three parameters:
- event: the type of the event
- msg: a JSON object containing the composition ID, name, and payload
- e: an event handle
comp.addListener('payload_changed', (event, msg, e) => {
console.log("listen to:", event);
console.log("msg:", msg);
e.stopPropagation();
});
Debug console
> listen to: payload_changed
> msg: {
> "compId": "...",
> "compName": "subComp",
> "compositionId": "...",
> "compositionName": "subComp",
> "payload": {
> "Title": "The Title."
> }
> }
This event occurs at the end of an animation when the animation state of the composition or a sub-composition changes.
The callback function receives three parameters:
- event: the type of the event
- msg: a JSON object containing the composition ID, name, and new animation state
- e: an event
comp.addListener('state_changed', (event, msg, e) => {
console.log("listen to:", event);
console.log("msg:", msg);
e.stopPropagation();
});
Debug console
> listen to: state_changed
> msg: {
> "compositionId": "...",
> "compositionName": "subComp",
> "state": "In", "Out", "Out1", "Out2"
> }
This event occurs at the start and end of an animation of the composition or a sub-composition.
The callback function receives three parameters:
- event: the type of the event
- msg: a JSON object containing the composition ID, name, and timeline event details
- e: an event
comp.addListener('timeline_event', (event, msg, e) => {
const message = msg.message;
console.log("listen to:", event);
console.log("timeline event:", message.event);
console.log("msg:", msg);
e.stopPropagation();
});
Debug console
> listen to: timeline_event
> timeline event: start
> msg: {
> "compositionId": "...",
> "compositionName": "subComp",
> "message": {
> "event": "start",
> "direction": "forward",
> "timeline": "In",
> "currentTime": 0,
> "duration": 0.8,
> "targetState": "In"
> }
> }
> listen to: timeline_event
> timeline event: stop
> msg: {
> "compositionId": "...",
> "compositionName": "subComp",
> "message": {
> "event": "stop",
> "duration": 0.8,
> "currentTime": 0.8,
> "direction": "forward",
> "timeline": "In",
> "targetState": "In"
> }
> }
This event occurs when a data node of the composition or a sub-composition changes.
The callback function receives three parameters:
- event: the type of the event
- msg: a JSON object containing the composition ID, name, and data node details
- e: an event
comp.addListener('datanode_payload_changed', (event, msg, e) => {
console.log("listen to:", event);
console.log("msg:", msg);
e.stopPropagation();
});
Debug Console
> listen to: datanode_payload_changed
> msg: {
> "compId": "...",
> "compName": "subComp",
> "compositionId": "...",
> "compositionName": "subComp",
> "payload": {
> ...
> }
> }
This event occurs when the graphics SDK, widgets, and interactive events send custom messages to the comp or a sub comp.
The callback function receives three parameters:
- event: the type of the event
- msg: a JSON object containing the composition ID, name, details and payload
- e: an event
comp.addListener('message', (event, msg, e) => {
console.log("listen to:", event);
console.log("msg:", msg);
e.stopPropagation();
});
The following logs show the
msg object returned by interactive events.Debug console
> listen to: message
> msg: {
> "params": {
> "type": "widget", or "group"
> "name": "bgButton",
> "id": "e9a3f5e5-7c19-6f83-8a0e-ecc43dca3997",
> "compId": "-NHgm9qQim1PjR0Ecnxa",
> "event": {
> "button": 0,
> "shiftKey": false,
> "altKey": false,
> "ctrlKey": false,
> "metaKey": false,
> "screenX": 848,
> "screenY": 370,
> "clientX": 344,
> "clientY": 269,
> "offsetX": 334,
> "offsetY": 2,
> "layerX": 307,
> "layerY": 109,
> "movementX": 0,
> "movementY": 1,
> "pageX": 344,
> "pageY": 269,
> "x": 344,
> "y": 269
> },
> "info": ""
> },
> "type": "mouseenter" or "mousedown" or "mouseleave" or "mouseenter"
> }
Last modified 5mo ago