1. Building Responsive Applications with Visual Builder Studio
  2. Develop Applications
  3. Work With Events and Event Listeners
  4. Raise Fragment or Layout Events that Emit to the Parent Container

Raise Fragment or Layout Events that Emit to the Parent Container

Layouts and fragments defined in your application are typically unaware of their parent container's context. This means that events defined within a layout or fragment are "listenable" only within the layout or fragment's scope. To make these events listenable on the parent container (say, a page or another container like a different outer fragment), you'll need to fire custom events that the parent can handle.

Consider the example of a fragment that defines a form with a Save button. Any time a user updates the form's data and clicks the button, an on-click event triggers a REST call action that saves the updates. To make the event listenable by a layout or fragment's parent container (say, a page or a dynamic container), you'll need a Fire Event action in your action chain to emit the event's payload to the parent container. This makes it possible for the page (or container) to listen for this custom event, bind an event listener to the same event, and process the payload further if needed.

When a new custom event is fired from the page, keep in mind that the custom event (unlike a page event) "bubbles" up the container hierarchy. Any event listeners in a given flow or page for the event are executed before looking for listeners in the container's parent. The order of container processing is:
  • The page from where the event is fired
  • The flow containing the page
  • The page containing the flow
  • Recursively up the container, ending with the application.
To make a layout or fragment event listenable on its parent container:
  1. Create a custom event that emits its payload to the parent container:
    1. In your layout or fragment's Events tab, click + Custom Event.
    2. Enter an event ID (say, emailPreferenceSet), then select the option to emit the event's payload to the parent container:
      • For a layout event, select Emit event to page.
      • For a fragment event, select Emit event to container.

      Click Create.

    3. In the event's Properties pane, click Add Parameter next to Payload in the Properties pane to specify the payload that will be passed to the parent container.
    4. Enter the payload parameter name, select its type, and click Create. In our fragment example, this is a boolean-type shouldEmailBeSent parameter:
      Description of emittocontainer-event.png follows
      Description of the illustration emittocontainer-event.png

    Tip:

    When working with fragment events, you can choose to enter an Auto Wire Event ID to simplify the process of creating a listener for this event on the parent container. This option enables the event to be listed under Fragment Events when you create a listener for the event from the Event Listeners tab on pages or layouts that use the fragment. See Automatically Wire a Fragment's Custom Event to the Parent Container.
  2. Create an action chain with the Fire Event action that will be triggered when the event occurs:
    1. Switch to the layout or fragment's Action Chains tab, click + Action Chain, enter a ID, and click Create to create a new action chain. You can also select an existing action chain.
    2. In your action chain, drag and drop a Fire Event action.
    3. In the Fire Event's Properties pane, select the event to be fired (for example, emailPreferenceSet).
    4. To pass in the payload parameter's value, click Select Variable next to shouldEmailBeSent under Parameters and select value under Input Parameters in the Variables picker.
      Description of emittocontainer-fireevent.png follows
      Description of the illustration emittocontainer-fireevent.png

  3. On the page that uses your layout or fragment, configure the layout or fragment's parent container to handle the custom event:
    1. Go to the Page Designer and select the component (for example, a fragment) to open its Properties pane, click the Events tab, then click + Event Listener and select the suggested custom event (for example, emailPreferenceSet).
    2. Build the action chain that must be triggered when the event occurs. For example, you might want a notification to appear on the page when a user toggles a Switch in a fragment. For a sample end-to-end scenario that illustrates this workflow, see Create Custom Events that Emit to a Fragment's Parent Container.