Events

There are several types of events, all of which the application can react to, using the event listener syntax.

There are several types of events in the runtime: page events, flow events, system events, custom or developer-defined system events, component (DOM) events, and variable events. Event types are all handled by executing action chains.

The application reacts to events through event listeners, which declaratively specify action chains to execute when the event occurs.

Event Listener Syntax

An event listener is an object with the following properties:

• "chains": an array of action chains to execute; includes "chainId" and optional "parameters".

• "stopPropagation": optional, used only by custom and component events. An expression that is evaluated immediately; if true, the event will not propagate to the current hander's container's parent.

• "preventDefault": optional, used only by component events. Like "stopPropagation", it is evaluated immediately. If true, The default (DOM) handling is not executed.

The "chainId" refers to an action chain to trigger when this variable changes. Optional parameters can be sent to the action chain in response to the event (see the next section for more details). To gain access to the old or new values, these are exposed in the $event implicit object, where $event.value is the new value and $event.oldValue is the old value.

The following example defines three event listeners; one for the vbNotification built-in event, a custom event listener, and a component listener. The syntax for all three is the same, though how they are invoked is different:

• The built-in vbNotification event is called when that event is fired by the system. No explicit wiring of the listener is required. The name identifies which action should invoke this listener.

• The custom myCustomEventOne, is called when the application explicitly fires that event. As with vbNotification, no explicit wiring of the listener is required.

• onButtonClicked is a component event, and is explicitly bound to a component action.

"eventListeners": {
  "vbNotification":
    "chains": [
        {
          "chainId": "application:logEventPayloadChain",
          "parameters": {
            "message": "{{ $event.message }}"
            "type": "{{ $event.type }}"
          }
        }
    ]
  },
  "myCustomEventOne": {
    "stopPropagation": "{{ $event.type === 'error' }}",
    "chains": [
      {
        "chainId": "application:fireEventChain",
        "parameters": {
          "name": "customEventOne",
          "payload": {
            "value1": "some value",
            "value2": 3
          }
        }
      }
    ]
  },
  "onButtonClicked": {
    "chains": [
        {
          "chainId": "application:logEventPayloadChain",
          "parameters": {
            "eventPayload": "{{ $event }}"
          }
        }
      ],
   }

The following HTML example shows explicit component event binding:

<oj-button href="#" id='myButton'
           disabled="[[true]]"
           chroming='half'
           on-click='[[$listeners.onButtonClicked]]'>My Button!!!</oj-button>