This section of the composition scripting documentation includes essential cheat sheets for the following:
The
The
Composition scripting fundamentals
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.
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.
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.
Object types, properties, and methods
The composition object
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.
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];
findGroup()
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];
findWidget()
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];
getPayload()
Returns the control node content from the composition as an array of key value pairs.
A custom global object including variables, objects, and functions.
utils.createDataStream()
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();
}
}
};
})();
> Singular window name: app_output or app_control or script_editor
Event listener
comp.addListener(eventType, callbackFunction)
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.
payload_changed
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
