Data sources: Computed properties

Computed properties are one of the most powerful features of Ease Live. They give you the full power of JavaScript to create, combine and transform data for your UI's.

If you are familiar with JavaScript, computed properties are just functions that return a value, and are re-run any time any of their dependencies change.

But even if you have never scripted anything in your life, don't be deterred – all you need to know is if you write something like this...

return context.data.myName.toUpperCase();

...you can use that data property to override your text layers, safe in the knowledge that if myName ever changes, your all-uppercase data property will automatically stay in sync.

Never modify other data from a computed property

It is a good practice to always keep computed properties side-effect free. This means that their script should never affect anything else in the application. Think of them as recipes for deriving some value or data based on other data.

If you need to perform actions in response to data changes, you can do that by adding triggers to your data properties, or use watchers.

The context object

Notice context.data in the code above? That is how you access all the data for the same data source, whether it is an event, API, or storage source. But that is not all the context object contains. Behold:

Property	Description
data	The data source's other properties
sources	Other data sources, eg. sources['My event']
functions	Your functions, organized according to your function sets. Example: functions['My utils'].log('foo')
device	Information about the user's device, like its width, height and orientation
player	Information from the SDK about the video player, like the current time and whether the video is paused or playing
account	Information about your Ease Live account. Useful for getting the correct URL for API calls to the Ease Live platform
params	Any URL params, as defined in your preferences (cogwheel icon next to the save button)
application	The entire application object, with scenes, layers, etc.

Additional context for API sources

In addition to the properties above, computed properties on API sources have access to the following information:

Property	Description
isLoading	Whether it is currently waiting for data from the API
hasLoaded	Whether the data has successfully loaded
error	Information about errors, if the API call failed

Additional context for events

Property	Description
event	The full event object – ID, timestamp, metadata, etc. Your data properties are populated with the data from event.metadata.
states	All of the program's events, grouped by event name (e.g. LowerThird, Sidebar, etc). Each of those contain an events array, as well as a currentEvent object containing the last event as of the current timecode.

Example 1: Toggle layer if text is missing

Let's jump right to a more useful example. To toggle the visibility of a text box based on whether the producer entered any text for it, you might imagine a Lower Third event with this structure:

And in that "Show secondary box" computed property, you would simply type:

return Boolean(context.data["Secondary text"]);

This will return true if the Secondary text property on the same event contains anything, and false if it doesn't. That value can then be hooked up to the Visible switch for the layer containing the secondary text:

Voilà! Your secondary text box will now only be shown if it has content, as opposed to needing separate scenes and events for lower thirds with and without secondary text.

Example 2: Get stats for a given player

Another common use for computed properties is to look up or filter some data based on another property.

For example, if you want to click on a player in a lineup to show their stats in a popup, you can fetch that based on a property that holds the selected player's ID:

// ActivePlayerStats (computed property)
const { ActivePlayerId } = context.data;
const { Players } = context.sources.GameStats;

return Players[ActivePlayerId];

We can also use the technique from our lower third example to automatically show the popup when a player ID has been set:

// ShowPlayerPopup (computed property)
return Boolean(context.data.ActivePlayerId);

This illustrates the power of computed properties: now we only need a single trigger to set ActivePlayerId, and the popup would automatically appear with the correct data 🎉