Composition script editor reference

Get to know the composition script editor

The composition script editor is the place to write and edit composition scripts.

Composition script editor modes

There are two ways to run the composition script editor:

Normal mode
Safe mode

Accessing the composition script editor

Normal mode can be accessed in Composer by selecting the </> button above the property panel.
Safe mode can be accessed by selecting the ambulance button. This is available so that if a script contains a bug or sets off an infinite loop, you can close the browser and fix the bug in safe mode before returning to the normal mode editor again.

Both open the composition script editor in a new browser tab.

Composition script editor layout

The composition script editor provides a code editor, composition navigator, and output preview in a single view.

In addition, the menu bar offers a boilerplate script template that provides access to the composition's SingularPlayer object and starter code for the object's most commonly integrated events (message, state_changed, payload_changed, datanode_payload_changed, error).

Save all scripts: compiles and executes all the composition scripts in the editor. The latest version of the composition scripts are also uploaded to the composition.
Reload composition: updates the incoming link from the composition so that the composition script access shows the current state of the composition.
Beautify JavaScript: beautifies/reformats code in the code editor.
Script Library: provides JavaScript boilerplate code for each type of composition script that describes its structure and available event listeners.
Developer resources: provides links to the following:
- Singular graphics SDK documentation
- Singular overlay SDK documentation
- Code editor keyboard shortcuts
Code editor settings: provides option to customize the look of the code editor. Options include tab and font size, toggling the dark theme on and off, line numbers, wrap lines, indent with tabs, and render whitespace.
Toggle interactive zones: toggles a composition's interactive zones if any have been set up.
Output orientation: Toggles between landscape and portrait mode.
Screen size: Provides options for setting the output to the screen size of various devices.
Support: Opens a support window.

2. Code editor

This is the place to write composition scripts.

The + button

Selecting the + button opens a drop-down list of possible composition scripts to add to a composition. They include:

An overlay script
A global script
A script for the root composition
One script for each sub-composition

The mark next to the name also conveys valuable information:

Circle: a composition script has been created.
Checkmark: the composition script is error-free.
Red circle: the composition script contains an error.

Error checker

The bottom left of the code editor shows any errors in the code and displays OK when there are none.

3. Preview panel

This panel displays a preview of the composition scripts' effect on the sub-composition.

4. Composition navigator

The compostion navigator contains various information about compositions that are needed to write composition scripts.

From left to right, the panels are:

Composition control panel

The composition control panel shows information about the composition's root composition and sub-compositions that are needed when writing composition scripts.

The left side of the panel shows the sub-composition's assigned logic layer and current In-Out state.

The right side of the panel shows additional information in the following tabs:

Fill-in form: the editable text and its positioning of the selected root or sub-composition. When changed, the payload updates.
Sub-comp info: the sub-composition's name and ID, as well as the ID, name, type, and current value of the elements of the sub-composition that have been made editable though a control node.
Model: the model of the app in JSON, which is required for specific use cases.
Payload: the JSON data for the selected sub-composition, which is needed in many Singular REST API requests.

Globals panel

The globals panel contains the composition's screen size, layout, text direction, interactive status, and language. Globals are required for adaptive graphics and other specific use cases.

The widget explorer shows all the widgets used in a composition, including their name, ID, version, and status. It also shows the ID, name, and type of each widget's editable fields.

Widgets can be updated to the published version in Composer by selecting the widget in the composition tree panel. This opens a drop down menu that shows available widget versions.