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>

Event Prefix

An event prefix is a way for event listeners to define which custom event they are listening to. Two aspects of the event listener are represented in the reference: the extension where the event is defined, and the scope. The syntax for the scope is the same in the base and in the extension. The extension reference is placed before the scope, and is separated with a slash (/).

Inside base (Local)

The syntax is myScope:myEventName where myScope can be omitted if it refers to an event defined in this object.

Inside extension (Export)

The syntax is extension/myScope:myEventName where extension can be omitted if it refers to an event defined in the base object.