How to… configure actions & events

Actions are used to define the behaviour of a CommonTime Infinity application. They can be used to carry out a wide range of functionality within an app, such as changing pages, taking photos or calling an API.

Whilst Actions are used to define what the application does, Events determine when the actions are executed.

Events can be triggered under a number of circumstances, such as interaction from a user, external systems or as a result of the application loading a page. Some items have automatic events built into them, whilst others provide you with a selection of event types which can be set to suit the purpose of your application. For example, a button item will only trigger an event when it is pressed by a user, whilst a Text item has 7 different events including Key down, Enter and Click.

Topics covered in this article

1. Actions
2. Events

1. Actions

To cater for a wide variety of applications, CommonTime Infinity provides a range of actions which can be used in response to an event. These are available via the Toolbox and can be viewed using the menu icon at the top to change to the ‘Actions’ list.

For ease of navigation, the Actions are grouped into several sections, including Integration, Scripting, Navigation and Media. The search box at the top of the Toolbox can also be used to quickly find a specific actions.

In some cases, the action is used to call an item which has been configured via the App Config screen. For example, the details used by an API, function or variable are all set via the config, whereas actions are used to interact with them.

1a. Action Locations

Actions can be added to a number of different places within CommonTime Infinity. Whilst there are slight differences in the method used to configure/call the actions, once triggered the actions will behave in exactly the same way.

‘Actions’ Tab

If you expand the settings for an item which can be used to trigger an event, the item will contain an ‘Actions’ tab. Any actions added to this tab will listen for events triggered by the associated item, allowing you to build up different behaviours based on what the item is designed to do.

In some cases this the event will be triggered in response to user interacting with the item (e.g. pressing a button), whereas others (e.g. Call API) will automatically trigger an event when they used within the application.

If the action can be used to trigger multiple events (e.g. Key up, Key down, Enter), each action in the tab will include a droplist which can select the event it should be triggered by.

Actionflows

Actionsflows can be used to group together a collection of actions which can be called from multiple locations in the same application. They are executed using the ‘Call Actionflow’ action which can be added to an ‘Actions’ tab, On-Load event or even another Actionflow.

‘On-Load’ and ‘On-Loaded’ Events

The ‘On-Load’ and ‘On-Loaded’ events are a special items which can be configured to the Page Config screen. They are designed purely to hold a list of actions which will be triggered when the page begins/completes loading.

Only one instance of each item can be added to each Page Config, though Logic can be used to carry out different actions based on a condition.

An additional ‘On-Load’ event is also available for the entire application, which is configured via the App Config screen.

1b. Managing Actions

New actions can be added to an application simply by dragging them from Toolbox and dropping them to your chosen location. Where the action can be triggered by multiple events, it will be necessary to use the droplist at the top of the action to specify which event it should listen for.

Each action location includes a standard set of controls to duplicate, move and delete an action. These appear at the top of the Actionflow editor, whereas in the case of the ‘Actions’ tab and On-load style events, a separate set of controls are provided just above the list of items.

1c. Flow of Actions

It is possible to create a more complex behaviour by adding multiple actions within an ‘Actions’ tab, Actionflow or On-Load Event. In each case, the actions are placed one after another and will be carried out in the order they are listed. If for any reason the flow of actions is stopped (e.g. an action fails) then no further actions in the flow will be executed.

Where the data from one action in a flow must be passed to the next action, an object called $data is used. The usage of this object varies dependant on the type of actions used. Some actions (e.g. Call API) automatically assign values to this object, such as the result of the action, or a value (e.g. true/false) based on the action’s outcome or behaviour. Other actions (e.g. Show Notification) will simply pass the previous value for $data, whereas asynchronous functions require you to manually specify the value within the brackets of the $success call.

$data is a JSON object and can therefore hold a wide variety of values. To reference the contents of the object within the following action, simply type $data. Where an $data is used to store an object, this reference can also include the object structure to reference particular values. e.g. $data.user.firstname

Within a flow, the $data value is designed to pass data from one action to the action which is located directly below. It can therefore not be assumed that a value set by the first action will be available for the third action to use, as the action in the middle may overwrite the value held in $data. If the data should be accessible for all actions, it is recommended that a variable is used instead as this will be available throughout the flow.

2. Events

Events are used to specify when actions will be triggered by an application. The amount and style of events will differ depending on the location where the actions are being held. For example, a button has a single predefined event which will be activated when the user presses it, whereas a Text item provides 7 different events based on different ways the user can interact with the field.

Whilst the list of events changes from item to item, a selection of the most common events are noted below:

Name Triggered…
Click When a user clicks the mouse or touches the screen
Focus In response to the item becoming the active element on the screen
Blur In response to the item losing focus on the screen
Change When the selected item is changed
Enter When the ‘Enter’ button is pressed

2a. Set Event Type

If an item provides multiple events, it is necessary to specify which should cause the action to be carried out. This is set on a per-action basis using a drop down list at the top of each action.

If this drop down list does not appear within an action, it is likely that it resides in a location which only has a single event type.

It is not possible to specify multiple events for the same action. If the same action should be triggered by multiple events, it will be necessary to duplicate the action and change the event in the drop down list.

Note that if the ‘Call Actionflow’ action is added to the ‘Actions’ tab of an item, a single event is used to trigger all actions in the Actionflow.