Work With Events and Event Listeners

Events trigger actions when a user or the browser interacts with your application. For example, when a user clicks a button to navigate to the application's home page, Visual Builder raises an event that triggers the navigate action.

There are many types of events: lifecycle events, variable events, component events, even custom events. Event types are more about how they occur and are all used to execute action chains in your application. The application reacts to events through event listeners, which declaratively specify the action chain to execute when the event occurs.

Define Events in Your Application

An event occurs when something happens in your application. Some examples are when a page loads (a lifecycle event), a button is clicked (a component event), and when the value stored in a variable changes (a variable event). There are different event types, and the type depends on how it is triggered. For example, changes in a button component would trigger a component event.

For some event types, for example, component events, you can choose from many predefined events, and the events that are applicable will depend on the component. An event like ojAction that is applicable to a button might not be applicable to a text field. For other event types, for example, variable events, you can only define one event (onValueChanged) for the variable.

How you define events and event listeners in the Designer will depend on the type and scope of the event. This table describes how to define different types of events.
Type of Event Description How to Define
Variable event

A variable event occurs when the value of a variable changes. The only applicable event for a variable is onValueChanged.

You define a variable's event and create its event listener in the Variables editor. See Start an Action Chain When a Variable Changes.

Component event

A component event occurs when a component in a page (including components in dynamic UI components) triggers an event, for example, an ojAction event for a button. You can choose which events a component triggers.

You define a component's event and event listener in the component's Properties pane in the Page Designer. See Start an Action Chain From a Component.

Custom event

A custom event helps communicate between the different layers of the app (page, flow, application) and is only triggered by the Fire Event action (fireCustomEventAction) in an action chain.

Custom events can be used to trigger an action chain from another action chain or JS function, and to navigate between flows in your application.

You can create a custom event in the Action Chain editor or in the Events editor of a page, flow, or application. You create event listeners for custom events in the Event Listeners editor. See Start an Action Chain From an Action Chain.

Lifecycle event

Lifecycle events are predefined events that occur during a page's lifecycle.

You create event listeners for the predefined lifecycle events in the Event Listeners editor. See Start an Action Chain From a Lifecycle Event.

Create Event Listeners for Events

When an event such as a button click occurs in a page, it can start one or more action chains if an event listener is "listening" for it. When you create an event listener, you select the event it should listen for and the action chains you want it to trigger. You can create event listeners for events that you define as well as for predefined lifecyle events.

An action chain can be started by multiple event listeners, so you might have a SaveData action chain that can be started by two different event listeners listening for two different events.

To create an event listener:

  1. Open the Event Listeners tab for an artifact or page, then click + Event Listener.
  2. In the Create Event Listener wizard, select the event you want to trigger an action chain. Click Next.

    The Select Event step in the Create Event Listener wizard displays a list of events. Depending on where you're creating the listener, the list might include page events, flow events, custom events, and component events in addition to lifecycle events.
    Description of create-event-listener-1.png follows
    Description of the illustration create-event-listener-1.png

  3. Select the action chain you want to trigger. Click Finish.

    The Select Action Chain step in the wizard displays the action chains that can be triggered by the listener. If you want to create a new action chain now, you can click Add Action Chain iconand enter an ID for the new action chain, which you can edit later in the editor. While an event listener can trigger multiple action chains, you can add only one action chain at a time in the wizard.
    Description of create-event-listener-2.png follows
    Description of the illustration create-event-listener-2.png

You can add additional action chains to an event listener at any time by clicking Add Action Chain for the event listener in the Event Listeners tab. Moving your cursor over the name of an action chain in the tab displays a link you can use to open the Action Chain editor.

If you want to delete an event listener, or remove an action chain triggered by an event listener, you can select it in the list in the Event Listeners tab and then click Delete in the options menu in the Properties pane. Deleting an action chain in the Event Listeners tab means it will no longer be triggered by the listener, but it won't delete the actual action chain.
Description of delete-event-listener.png follows
Description of the illustration delete-event-listener.png

Choose How Custom Events Call Event Listeners

Each custom event has a behavior type that defines how the event listeners will be called in relation to each other, whether the result for the listener is available, and what form the result would take.

The behavior type does not define the order in which listeners are called, but whether the listener is called serially or in parallel, that is, whether the action that raised the event waits for a listener resolution, and what the "result" of the listener invocation looks like. So in this case, "serially" means:
  • For a single event listener (in a container), all the event listener chains are called sequentially, in a declared order. This means that a listener action chain is not called until the previous action chain has finished (and resolved, it returns a Promise)
  • The event listeners for the next container's listeners are not called until the listener action chains for any previous container's event listeners have finished (and resolved, it returns a Promise)

You can choose the behavior type of a custom event in the Properties pane of the Events editor.
A custom event's Properties pane with the Behavior field highlighted

A custom event will have one of the following behavior types:

Behavior Type Description
Notify

Parallel: The event is triggered but the application does not wait for the extension to process it.

Chain results are not available to the Action (or helper) that fired the event (because the listeners are called without waiting). This is the default behavior.

NotifyAndWait

Serial: Each action chain listener must complete (and resolve any returned Promise, if any), before another event listener action chain is called.

Chain results are not available to the Action (or helper) that fired the event.

CheckForCancel

Serial: Each action chain listener must complete (and resolve any returned Promise, if any), before another event listener action chain is called.

If any of the listeners Chains returns a "success" with a payload of { "stopPropagation": true }, the application will stop calling event listeners.

Chain results are not available to the Action (or helper) that fired the event.

Transform

Serial: Each action chain listener must complete (and resolve any returned Promise, if any), before another event listener action chain is called.

Chain results are available to the Action, and the Action can modify the Chain's results before passing it back to another Action following it.