Start transitions and special events

In other scenarios, we might define a dialog that starts if a special start event is being emitted from a specific source or from an arbitrary source.

This special start event is identified by the following QName:

{http://www.ibm.com/xmlns/prod/websphere/portal/v6.1.0/portal-pcm}StartDialog

Its payload needs to implement the interface DialogStartPayload.

This special start event provides some additional means to start dialogs or screen flows. For example, by implementing the methods of that interface, we can programmatically control the name of the dialog to be started.

Code sample 16 shows a dialog definition that uses the special start event. In this sample, if a portlet emits the special start event, the dialog with the name returned by the getDialogDefinitionName() method is started.

The central idea of the IBM UX Screen Flow Manager is to control transitions based on the declarative model. Therefore, use this more programmatic approach with care and only if we cannot implement the goal by other means.

Code sample 16:

01  <transition type="start">
 02      <source>
 03          <transition-endpoint nameref="*">
 04              <event qname="{http://www.ibm.com/xmlns/prod/websphere/portal/v6.1.0/portal-pcm}StartDialog"/>
 05          </transition-endpoint>
 06      </source>
 07      <target>
 08          ...
 09      </target>
 10  </transition>

As we can start dialogs by specifying dedicated transitions endpoints, undetermined transition endpoints, dedicated events, or special start events, several combinations are possible. To gain a better understanding of the behavior and interplay of these combinations, see code sample 17.

Code sample 17:

01 <dialog name="dialog1">
 02  <transition type="start">
 03      <source>
 04          <transition-endpoint nameref="*">
 05              <event qname="{http://www.ibm.com/xmlns/prod/websphere/portal/v6.1.0/portal-pcm}StartDialog"/>
 06          </transition-endpoint>
 07      </source>
 08      ...
 09  </transition>
 10 </dialog>
 11
 12<dialog name="dialog2">
 13  <transition type="start">
 14      <source>
 15         <transition-endpoint nameref="*">
 16              <event qname="eX"/>
 17          </transition-endpoint>
 18      </source>
 19      ...
 20  </transition>
 21 </dialog>
 22
 23 <dialog name="dialog3">
 24  <transition type="start">
 25      <source>
 26          <transition-endpoint nameref="portlet3">
 27              <event qname="{http://www.ibm.com/xmlns/prod/websphere/portal/v6.1.0/portal-pcm}StartDialog"/>
 28          </transition-endpoint>
 29      </source>
 30      ...
 31  </transition>
 32 </dialog>
 33
 34 <dialog name="dialog4">
 35  <transition type="start">
 36      <source>
 37          <transition-endpoint nameref="portlet4">
 38              <event qname="eX"/>
 39          </transition-endpoint>
 40      </source>
 41      ...
 42  </transition>
 43 </dialog>
  

In the following example, x, y, and z work as follows: source x emits event y. If y refers to the special start event, z contains the name of the dialog to be started:

1. The portlet5, StartDialog causes dialog1 to be started

2. The portlet3, StartDialog causes dialog3 to be started

3. The portletY, StartDialog(dialog3) causes dialog3 to be started

4. The portlet5, eX causes dialog2 to be started

5. The portlet4, eX causes dialog4 to be started

Rationale

Case 1: The engine first checks whether the emitted event matches the special start event. In the example, this check evaluates to true.

The event payload does not specify the dialog that is to be started. Therefore, the dialog that is to be started needs to be derived from the declarative model.

The portlet5 is not specified as the source of a defined transition. Therefore, the engine checks whether a wildcard using source might apply. This action is the case with dialog1 and dialog2. As the event of dialog1 matches the event that is emitted, dialog1 is started.

Case 2: The engine first checks whether the emitted event matches the special start event. In the example, this check evaluates to true. The event payload does not specify the dialog that is to be started. Therefore, the dialog that is to be started needs to be derived from the declarative model.

The portlet3 is specified as the source of the start transition of dialog3. As the event of dialog3 matches the event that is emitted, dialog3 is started.

Case 3: The engine first checks whether the emitted event matches the special start event. In the example, this check evaluates to true. The event payload specifies the dialog to be started. Therefore, dialog3 is started.

Case 4: The engine first checks whether the emitted event matches the special start event. In the example, this check evaluates to false.

The portlet5 is not specified as the source of a defined transition. Again, the engine checks whether a wildcard using source might apply. This action is the case with dialog2 and dialog1. As the event of dialog2 matches the event that is emitted, dialog2 is started.

Case 5: The engine first checks whether the emitted event matches the special start event. In the example, this check evaluates to false. The portlet4 is specified as the source of the start transition of dialog4. As the event of dialog4 matches the event that is emitted, dialog4 is started.

Parent topic: Transitions