Fragment Events

Fragments support several lifecycle events defined by the system. In addition, fragments also support custom events that can be handled by listeners defined in the fragment, and further propagated to the listener bound on the fragment container.

Lifecycle Events

When the lifecycle event is raised, the framework calls the event listener with the name of the event. Fragments can fire these events when the fragment artifacts load, when the fragment state is activated, or when the fragment is disposed. Other lifecycle events are currently not supported by fragments.

Table 1-2 Fragment Event Parameters

Name	Description	Returns
vbEnter	Dispatched when the fragment state is activated. Variable scopes available: $application: All application variables $extension: All extension variables $fragment: All local variables in the fragment	None
vbExit	Dispatched when the fragment is disposed (generally by navigating away from a page or the page is disposed).	None

Name

Description

Returns

vbEnter

Dispatched when the fragment state is activated. Variable scopes available:

$application: All application variables
$extension: All extension variables
$fragment: All local variables in the fragment

None

vbExit

Dispatched when the fragment is disposed (generally by navigating away from a page or the page is disposed).

None

Framework Events

vbNotificationEvent is an example of a framework event that raises a notification for further processing by a parent container and to display the notification message. This is a special event that is automatically bubbled up to the parent container(s) without any need for binding the event on the fragment component. Other specialized types of notification events, such as SDP vbDataProviderNotification events, also have the same behavior.

Component Events

The behavior and usage of component events in fragments is similar to that in other components. See Component Events.

Custom Events

Custom events can be declared in fragments under the "events" property. There are two types of custom events in fragments:

Event Type	Description
Events that can be handled by the same fragment and its extensions	This type of event is similar to other Visual Builder custom events, and is handled similarly. For details, see Custom Events.
Events that 'emit' a custom event to the fragment container	This type is expressly used for the purpose of propagating to the outer container component (the oj-vb-fragment component). For details, see below.

Event that 'emits' a custom event to the fragment container

By setting the "propagationBehavior" property of a custom event to "container", the event will 'emit to the container" when fired, allowing the fragment's parent container (oj-vb-fragment) to listen to the custom event.

For example, if you want to use a fragment event to call an action chain to perform some business logic, or to save data to a REST backend, you would fire a custom event that 'emits to the container' so that a listener on the parent can handle the event and trigger the action chain.

Property Description

propagationBehavior

Property	Description
propagationBehavior	When this property is set to `container`, the fragment component (`oj-vb-fragment`) can listen to the fragment event, but fragment listeners cannot listen to the event. When this property is not set, the default value is "self", implying the event can only be handled by the fragment listeners. Note: This property is only supported by fragment events.

When this property is set to container, the fragment component (oj-vb-fragment) can listen to the fragment event, but fragment listeners cannot listen to the event.

When this property is not set, the default value is "self", implying the event can only be handled by the fragment listeners.

Note:

This property is only supported by fragment events.

Example 1-64 A fragment event that is listenable by the parent container

The following code describes a "saveincident" event, where the propagationBehavior is set to "container" .

{
  "description": "An incident form fragment",
  "title": "Incidents Form Fragment",
  "events": {
    "saveincident": {
      "description": "fired when an incident has to be saved. The mutated incident data provided in payload",
      "propagationBehavior": "container",
      "payloadType": {
        "data": {
          "id": "string",
          "problem": "string",
          "priority": "string",
          "status": "string",
          "customer": {
            "id": "string"
          }
        }
      }
    }
  }
...
}

This allows the oj-vb-fragment component that loads the fragment to bind an event listener to the same event, as shown below:

<oj-vb-fragment name="incident-form" id="[[ $page.functions.fragmentUniqueId ]]" bridge="[[ vbBridge ]]"
    on-saveincident="[[ $page.listeners.saveIncident ]]">

   <oj-vb-fragment-param name="currentIncident"
    value="[[ $page.variables.currentIncident ]]"></oj-vb-fragment-param>
</oj-vb-fragment>

WARNING:

Note the 'on-saveincident' attribute. It is important that the event name be lowercase or camelCase with no hyphens as defined by Web Component DOM event naming conventions.

Auto-wire custom events from fragment to container

When a custom fragment event can be emitted to its parent container (with the "propagationBehavior" property set to "container"), the custom fragment event can be automatically wired to an event listener on its immediate parent container and/or its extension. To do this, a fragment author can add the autoWire property to the event that is to be propagated to the parent container.

For a custom fragment event to be auto-wired to a listener on the parent container, the autoWire property must be added:

On the fragment event to specify the name of the event listener it expects the parent container to have (for example, "autoWire": "performSaveIncident")
On the parent event listener to enable auto-wiring and further clarify its behavior.
The autoWire event listener property can be set to:
- none (default): Disables automatic wiring of an event listener.
- full: Setting autoWire to full on the fragment's base parent container event listener allows this event listener to be invoked when the auto-wired event is fired from a fragment that is part of the extended parent container. For example, if an auto-wired event listener is defined on a page, and the page is extended and in turn contains a fragment, when the fragment fires an auto-wired event, the base page's event listener is invoked. If both the fragment's base parent container and extended parent container have an auto-wired event listener defined, both are invoked.
- selfOnly: Setting autoWire to selfOnly limits the event listener invocation to the one defined on the immediate parent alone.

Example 1-65 Auto-wiring a fragment event and eventListener

The following code shows how a fragment declares an auto-wired event:

{
  "description": "A incident form fragment",
  "title": "Incidents Form Fragment",
  "interface": {
     "events": {
       "saveincident": {
        "description": "fired when an incident has to be saved. The mutated incident data provided in payload",
        "autoWire": "performSaveIncident",
        "propagationBehavior": "container",
        "payloadType": {
          "data": {
            "id": "string",
            "problem": "string",
            "priority": "string",
            "status": "string",
            "customer": {
              "id": "string"
            }
          }
        }
      }
    }
  },
  "chains": {
    "fireSaveIncidentChain": {
      "variables": {
        "incidentPayload": {
          "type": "fragment:incidentEventPayload",
          "description": "the payload of the incident data to send with event",
          "input": "fromCaller",
          "required": true
        }
      },
      "root": "fireCustomSaveIncidentEvent",
      "actions": {
        "fireCustomSaveIncidentEvent": {
          "module": "vb/action/builtin/fireCustomEventAction",
          "parameters": {
            "name": "saveincident",
            "payload": {
              "data": "{{ $variables.incidentPayload }}"
            }
          }
        }
      }
    }
  },
  "eventListeners": {
    "fireSaveIncident": {
      "chains": [
        {
          "chainId": "fireSaveIncidentChain",
          "parameters": {
            "incidentPayload": {
              "id": "{{ $variables.currentIncident.id }}",
              "problem": "{{ $variables.currentIncident.problem }}",
              "priority": "{{ $variables.currentIncident.priority }}",
              "status": "{{ $variables.currentIncident.status }}",
              "customer": {
                "id": "{{ $variables.currentIncident.customer.id }}"
              }
            }
          }
        }
      ]
    }
  },
...
}

Here's the code for page-x, an extended parent container which uses the above fragment:

<oj-vb-fragment name="incident-form" :id="[[ $page.functions.fragmentUniqueId ]]">
  <oj-vb-fragment-param name="currentIncident"
    value="[[ $page.variables.currentIncident ]]"></oj-vb-fragment-param>
</oj-vb-fragment>

Here's the code for page, the base parent container of the above fragment that defines the auto-wired listener:

...
"eventListeners": {
 "performSaveIncident": {
   "autoWire": "full",
   "chains": [
     {
       "chainId": "performSaveIncidentChain",
       "parameters": {...}
     }
   ]
 }
}
...

In this example, when the fragment fires the saveincident auto-wired event, the performSaveIncident auto-wired event listener from the base page container is invoked because its autoWire property is set to full.

Let's say the base page container defined the auto-wired listener with autoWire set to selfOnly as shown here:

...
"eventListeners": {
 "performSaveIncident": {
   "autoWire": "selfOnly",
   "chains": [
     {
       "chainId": "performSaveIncidentChain",
       "parameters": {...}
     }
   ]
 }
}
...

In this case, no auto-wired listener is invoked because the fragment's immediate parent is the extended page container that does not have an auto-wired listener defined, while the base page container's performSaveIncident auto-wired event listener is set up to be invoked only if the base page container is an immediate parent of the fragment.