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
vbBeforeEnter	Dispatched when the fragment artifacts load. Three variable scopes are available: $application: All application variables $extension: All extension variables $fragment: All local variables in the fragment	None
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	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-53 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.