Overview

When you need to write more complex conditions or expressions than is possible with just the COGS UI tools, you can use "Computed Conditions" or "Computed Values".

Getting started

Anywhere it’s possible to use Computed Values or Computed Conditions, when you switch away from the UI template, the code input box will be populated with the code that is being used under the hood when using the UI tools. This is a good way to get started in understanding how to write Computed Values and Computed Conditions.

For example:

becomes

Examples

Computed Conditions vs Computed Values

There are two main places Computed Conditions and Computed Values can be used and they have slightly different uses:

Computed Conditions

Computed conditions are in the WHEN of a behaviour, in the condition section of an IF/THEN/OTHERWISE, or in a LOOP. You should write an expression that evaluated to true or false. In the case of a WHEN condition, the behaviour will run when the condition returns true but was previously false.

Computed Values

When writing computed values to display as values (such as in a scene dashboard widget), you should write an expression that returns a value of the correct type. e.g. for a “Text widget” on a dashboard, the expression should return a string type.

Syntax

COGS computed values are written in ECMAScript 2023 (a.k.a. Javascript).
All computed values must be synchronous. i.e. async/await and Promise are not supported.

ECMAScript/Javascript is widely used, for example in your web browser, and there are many resources for learning. We recommend starting with W3Schools or MDN Web Docs.

Global Values

When writing a computed value, COGS makes globals values available which allow you to refer to channels values, scene variables, etc.. What exactly is available is tied to the context, e.g. In a "Scene" behaviour you have access to scene with the current scene's context.

when Context

In behaviour actions, the global values for when a behaviour was triggered is available to the actions that run within that behaviour, prefixed with when..

For example, if you have a behaviour which is triggered when an OSC message is received, you can access the OSC message inside the behaviour actions with when.osc.message.*.

when. is only available inside behaviour actions (anything after the "DO..."). when. is not available inside the behaviour trigger condition (the "WHEN...") or for computed values.

Utility Functions

As well as the standard ECMAScript/Javascript functions, COGS includes several built-in functions for manipulating values. These are available in all contexts.

User Values

User values allow you to access metadata about the underlying value.

On/Off

Text

Number

Option List

Media Locations

Media locations are strings that represent the local machine or a Media Master.

Local audio output is represented as local:audio_player.
Remote media outputs are represented as remote:NAME where NAME is the name you have given the Media Master.

Migrating from JEXL

Upgrading your project to COGS 5.7 will automatically convert JEXL Computed Values and Computed Conditions to ECMAScript. When writing new Computed Values and Computed Conditions, keep in mind you are now writing ECMAScript.

Many of the JEXL operators in COGS 5.6 can be written simply in vanilla ECMAScript. For example:

Some JEXL utilities COGS 5.6 have been ported to ECMAScript. See Utility Functions.

Automated Migration

When upgrading your project to COGS 5.7, all JEXL Computed Values and Computed Conditions will be automatically converted to ECMAScript.

⚠️ Exceptions

JEXL supports indexing into the first object in an array by omitting the [0]. e.g:

[{ foo: 1 }, { bar: 2 }].foo // 1

is equivalent to:

[{ foo: 1 }, { bar: 2 }][0].foo // 1

However this is not the case using ECMAScript (COGS 5.7 and above). In ECMAScript will be undefined because foo is not a property of an array:

[{ foo: 1 }, { bar: 2 }].foo // undefined

During automatic migration COGS will not insert the [0] because the functionality may be ambiguous depending on the data. In this case COGS will leave the computed value as [{ foo: 1 }, { bar: 2 }].foo and you may need to check your expression logic is correct after upgrading your project.