Data sources: Event hooks

Whenever a producer sends an event to the client, all clients will just receive these events as-is. That is fine for most cases, but sometimes it would be nice to be able to modify the event even before it is handled by your UI.

This is where the beforeExecute event hook comes in. It is a JavaScript function that is executed on each end user's device as soon as an event arrives – before it is passed on to your data source.

How to use a hook

Go to your Event data source and click on the More icon in the element list (the three dots) and add a beforeExecute hook. It will be placed on the event root.

Writing a hook

When you select your hook you will see a script area in the inspector, similar to computed properties.

The difference is that hooks modify the event data directly, as opposed to returning a value like a computed property.

In addition to the context object available to all scripts, event hooks receive a property called event that you can modify. Note that it is the full event object, containing things like the UTC timestamp of when it was created. The data that corresponds to your event properties is found in the event.metadata object.

For example, if your event has a Title property, here is how you can convert it to uppercase:

event.metadata.Title = event.metadata.Title.toUpperCase();

Then save, and open up your project in Cockpit or Play to see the text become uppercase.

Options

The "Trigger" option lets you control how often to run the event hook:

• Only once: Only run the hook the first time an individual event is executed. So if the user jumps back and re-watches part of the broadcast, it will not process the same event twice.
• Every time: Run it every time the event is executed, even if the hook has already processed it before.

Advanced

Has beforeExecute already been triggered on this event?

If you're triggering beforeExecute every time the event is executed, you can check if it has been run before by using event.hasBeenExecuted.

Example:

if (!event.hasBeenExecuted) {
	// this code will only run once
	...
}
// while this code will run every time
...

Data flow diagram