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 contacts fragment lets you specify whether email is an employee’s preferred means of communication. A user who toggles the Emails Allowed? switch in the fragment will see a notification that their communication preference has been set to email:

Behind the scenes, when the user toggles the Emails Allowed? 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 email preference has been set.

1. Configure your fragment to raise a custom event that the parent container listens to.

   1. Drag and drop a Switch component to your contacts fragment, then in its Properties pane, change the Label Hint in the General tab to Emails Allowed?.

      

      Description of the illustration fragment-data-designer-switch.png

   2. Switch to the component’s Events tab, then click + Event Listener and select On ‘value’.

      

      Description of the illustration fragment-data-emailpreferenceset-event.png

   3. In the SwitchValueChangeChain action chain, drag and drop a Fire Event action.

   4. Click Create next to Event Name in the Properties pane.

   5. With the Scope set to Fragment, enter an Event ID (for example, emailPreferenceSet), select the Emit event to container option, and click Create. Make sure the event name starts with a lowercase letter, though camel case is allowed. Hyphens are not supported.

      

      Description of the illustration fragment-data-emailpreferenceset-fireevent.png

   6. Click Go to Custom Event under the new event to go to the Events editor, where you can define the event’s payload.

   7. In the emailPreferenceSet event’s Properties pane, click Add Parameter next to the Payload property. In the Add Payload Parameter dialog, enter an ID (say, shouldEmailBeSent), select the type as Boolean, and click Create.

      

      Description of the illustration fragment-data-emailpreferenceset-fireevent-payload.png

      Tip: To simplify the process of creating a listener for this event on the fragment’s parent container, you can choose to enter an Auto Wire Event ID (for example, emailPreferenceSetAutoWire). This option enables the emailPreferenceSet event to be listed under Fragment Events when you create an event listener from the Event Listeners tab on pages that use the fragment. See Automatically Wire a Fragment’s Custom Event to the Parent Container.

   8. Under Triggered by, click SwitchValueChangeChain to return to the action chains editor, and switch to Design view.

   9. In the Fire Event action’s Properties pane, use the Variables picker next to shouldEmailBeSent under Parameters and select value under Input Parameters.

      

      Description of the illustration fragment-data-emailpreferenceset-fireevent-payload-mapping.png

2. Configure your page’s fragment container to receive and process the fragment’s custom event.

   1. In the Page Designer, select the particular fragment in Structure view, then in the fragment Properties pane’s Events tab, click + Event Listener and select the On ‘emailPreferenceSet’ custom event.

      

      Description of the illustration fragment-data-container-emailpreferenceevent.png

   2. Drag and drop a Fire Notification action to the FragmentEmailPreferenceSetChain action chain.

   3. Enter a summary in the Properties pane, something like Communication preference is set to Email, then select Info as the Notification type.

      

      Description of the illustration fragment-data-container-actionchain-firenotification.png

   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.

      

      Description of the illustration fragment-data-container-actionchain-assignvariable.png

   6. Hover over the Value property and click to open the Variables picker, then select shouldEmailBeSent under Input Parameters.

      

      Description of the illustration fragment-data-container-actionchain-assignvariable-mapping.png

3. Now click the Preview icon in the header, select an employee, and toggle the Emails Allowed? switch. You’ll see a message that the employee’s email preference is set.