1. Extending Oracle Cloud Applications with Visual Builder Studio
  2. Build an App UI or Fragment
  3. Work With Fragments
  4. Pass Data Between a Fragment and Its Parent Container
  5. Create Custom Events that Emit to a Fragment's Parent Container

Create Custom Events that Emit to a Fragment's Parent Container

One way to pass data from a fragment to its parent container (say, a page or another container like a different outer fragment) is by raising custom events that "emit" to the container.

Let's extend the employee contacts use case to see how to do this. Here, the employee contact information fragment lets you specify whether home is the employee's preferred work location. A user who toggles the Work from home? switch in the fragment will see a notification that the employee's preferred work location has been set to home:
Description of fragment-data-email-scenario-test.png follows
Description of the illustration fragment-data-email-scenario-test.png

Behind the scenes, when the user toggles the Work from home? switch, an action chain defined on the fragment fires an event that "emits" the event's payload to the fragment container. An event listener on the fragment container, watching for this fragment event to fire, triggers a page-level action chain to perform some action—which, in our example, is firing a notification that the selected employee's work location preference has been set to home.

  1. Configure your fragment to raise a custom event that the parent container listens to. Here's an example of a page that pulls in the employee-contact-details fragment:
    1. From the fragment's Properties pane on the page, click Go to Fragment to access the Fragment Designer. You can also click the Fragment edit icon icon that appears next to the fragment name on the canvas.
    2. Drag and drop a Switch component in your details fragment.
    3. In the Properties pane, change the Label Hint text in the General tab to Work from home?.
    4. Switch to the component's Events tab, then click + Event Listener and select On 'value'.
    5. In the SwitchValueChangeChain action chain, drag and drop a Fire Event action.
    6. Click Create next to Event Name in the Properties pane.
    7. With the Scope set to Fragment, enter an ID (for example, wfhPreferenceSet), and select Emit event to container. Make sure the event name starts with a lowercase letter, though camel case is allowed. Hyphens are not supported. Click Create.
    8. When the new event is created, click Go to Custom Event under the new event to go to the Events editor and define the event's payload.
    9. In the wfhPreferenceSet event's Properties pane, click Add Parameter next to Payload. In the Add Payload Parameter dialog, enter an ID (say, shouldWfh), select the type as Boolean, and click Create.
    10. Under Triggered by, click SwitchValueChangeChain to return to the action chains editor. Switch to Design view.
    11. In the Fire Event action's Properties pane, hover over the shouldWfh property under Parameters, click Select Variable to open the Variables picker, and select value under Input Parameters.
  2. Configure your page's fragment container to receive and process the fragment's custom event.
    1. In the Page Designer, select the fragment, then in its Properties pane's Events tab, click + New Event and select the On 'wfhPreferenceSet' custom event.
    2. Drag and drop a Fire Notification action to the FragmentWfhPreferenceSetChain action chain.
    3. Enter a summary in the Properties pane, something like Work location preference set to home office, then select Info as the Notification type.
    4. Now drag and drop an Assign Variable action under the Fire Notification event.
    5. In the action's Properties pane, click Create next to the Variable property. In the Create Variable dialog, add a new page-level variable (for example, containerParam) of type Boolean and click Create.
    6. Hover over the Value property and click Select Variable to open the Variables picker, then select shouldWfh under Input Parameters.
  3. Now return to the Page Designer, click Live in the toolbar, select an employee, and toggle Work from home?. You'll see a message that the employee's work location preference is set.