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:
|
None |
vbEnter |
Dispatched when the fragment state is activated. Variable scopes available:
|
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 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.