Event Maps

An event map allows you to have a particular Web bean handle an event that it did not originate, based on the information from another event. The path to the bean that originates an event is specified in the src parameter of the request URL. Normally, the Controller retrieves this parameter so the event can be processed by the same bean that submitted the event in the first place. However, you can use an event map to modify this behavior. Such a customization can be useful, for example, if you want to have a page generate (and display to the user) links to events that it does not handle.

Event maps for a MicroStrategy Web page are defined in the Page Configuration file. The event maps for each page are defined by the <event-maps> child node of that specific <page> node. The <event-maps> node has child <event-map> nodes, which in turn have child <argument> nodes. Each <argument> node has three required attributes:

an id attribute that specifies the ID of the original event
a map-id attribute that specifies the ID of the event to which the original event should be mapped
a target attribute that specifies the name of the bean that should handle the request

An optional root-only attribute checks for the source (root) where the event originated. If the value of root-only attribute is "true", the event is not mapped if the source (root) is the same as the target.

<event-maps>

<event-mapid="3032"map-id="128004"target="objectWebSubs">

...

</event-maps>

The <event-map> node maps two events so the correct set of arguments can be passed from one event to the other, allowing an incoming event to be converted to another event before it is processed.

Event maps are particularly useful in the following scenarios:

Delegating the execution of an event from a Web bean in a particular page to another Web bean on a different page

This can be useful if you want to have a page generate (and display to the user) links to events that it does not handle.
Delegating the execution of an event from one Web bean to another within the same page

This can be useful if you want specific events handled by a particular bean.

Delegating the execution of an event from a Web bean in a particular page to another Web bean on a different page

The Folder Browsing and Document Execution pages provide an example of how to use event maps to delegate an event from a Web bean on one page to another Web bean on a different page. When you click the Edit link for a document on the Folder Browsing page, the event is sent to the Document Execution page for editing. When the Document Execution page gets the event and its arguments, it maps that event to another event and passes the arguments so the mapped event is appropriately handled by the correct bean (RWBean) on the same Document Execution page.

The detailed workflow is as follows:

The Folder Browsing page is opened.
The Edit link for a document is clicked on the Folder Browsing page, causing the document editing event (event id = 3104) to be passed to the Servlet.
The Servlet tries to handle the event. From the event definition in events.xml, the Servlet knows that an event with id = 3104 (that is, the document editing event) should be passed on to the Document Execution page for editing. The following code sample from events.xml defines the document editing event.

<event id="3104" name="editRW" target="rwd">

   <arguments>

       <argument id="3001" name="objectID" />

       <argument id="3010" name="messageID" />

       <argument id="3017" name="rwDesignMode" />

       <argument id="3115" name="executionMode" />

   </arguments>

</event>

The value of the target parameter in this event definition is the name of the Document Execution page as defined in the Page Configuration file (that is, "rwd"). The Servlet sends an event with id = 3104 to the Document Execution page to be handled.
The Document Execution page tries to handle the document editing event (event id = 3104). It first looks to see if the incoming event is mapped to another event. If it finds an id match in the <event-map> node for the page, it changes the event id to the value of the map-id attribute, maps the individual arguments, and directs the event to the bean identified by the target attribute of the <event-map> node. The following code sample shows the event mapping details for the Document Execution page as defined in the Page Configuration file.

<page desc="Report Writing Documents" desc-id="" feature-id="" login-required="true" name="rwd" persist-mode="8" track="true">

   <addons>

   </addons>

   <event-maps>

      ...

      <event-map id="3104" map-id="2048001" target="rwframe.rwb">

         <argument id="3001" map-id="2048001" />

         <argument id="3010" map-id="2048002" />

         <argument id="3115" map-id="2048092" />

      </event-map>

      ...

   </event-maps>

   ...

</page>

The Document Execution page maps an event with id = 3104 to a new event with id = 2048001 and passes it along with the arguments to the RWBean (that is, rwframe.rwb) to handle it.

The RWBean handles the event with id = 2048001 (and its arguments) and displays the document for editing on the Document Execution page.

The workflow outlined above describes how an incoming event (from the Folder Browsing page) is converted to another object's event (RWBean on the Document Execution page) before an event is processed. The Folder Browsing page (that is, the FolderBean) originates the document execution event, but it does not actually handle the event. Instead, it generates and displays links to events that are handled by the Servlet and redirected to a different page (the Document Execution page) where the event is handled by a different bean (the RWBean).

Delegating the execution of an event from one Web bean to another within the same page

The following two examples illustrate how to delegate the execution of an event from one Web bean to another on the same page.

The Document Execution page provides an example of how to use event maps to delegate an event from one Web bean to another on the same page.

The code sample below is part of the definition of the Document Execution page in the Page Configuration file.

<page desc="Report Writing Documents" desc-id="" feature-id="" login-required="true" name="rwd" persist-mode="8" track="true">

   <addons>

   </addons>

   <event-maps>

      <event-map id="2048001" map-id="2048001" target="rwframe.rwb">

         <argument id="2048001" map-id="2048001" />

         <argument id="2048002" map-id="2048002" />

         <argument id="2048003" map-id="2048003" />

         ...

      </event-map>

      ...

   </event-maps>

   ...

</page>

In the <event-map> node (shown in bold in the code sample above), a generic event with id = 2048001 is mapped to a new event with the same id and passed to the RWBean (that is, rwframe.rwb) to handle. The value of the target attribute specifies the target bean (in this case, RWBean) that will be handling the new event. The arguments are also mapped from the original event to the new event.

It is possible to have the same ID for both the events if all you want to do is delegate the handling to another bean.

The following code sample from events.xml shows the definition for the event with id = 2048001.

<events>

  <event id="2048001" name="execute">

    <arguments>

       <argument id="2048001" name="objectID" />

       <argument id="2048020" name="objectName" />

       <argument id="2048002" name="messageID" />

       ...

    </arguments>

  </event>

</events>
The Subscriptions page provides an example of how to use event maps to delegate one event to several beans on the same page.

The code sample below is part of the definition of the Subscriptions page in the Page Configuration file. This is the page that is displayed when you are adding subscriptions or schedules for objects.

<page desc="My Subscriptions" desc-id="mstrWeb.1077" feature-id="object-subscriptions" login-required="true" name="objectSubs" persist-mode="8" track="false">

   <addons>

   </addons>

   <event-maps>

     <event-map id="3032" map-id="128004" target="objectWebSubs">

       <argument id="3001" map-id="128005" />

       <argument id="3007" map-id="128006" />

     </event-map>

     <event-map id="3032" map-id="128004" target="objectNcEmailSubs">

       <argument id="3001" map-id="128005" />

       <argument id="3007" map-id="128006" />

     </event-map>

     <event-map id="3032" map-id="128004" target="objectNcFileSubs">

       <argument id="3001" map-id="128005" />

       <argument id="3007" map-id="128006" />

     </event-map>

     <event-map id="3032" map-id="128004" target="objectNcPrintSubs">

       <argument id="3001" map-id="128005" />

       <argument id="3007" map-id="128006" />

     </event-map>

   </event-maps>

   ...

</page>

In this case, the My Subscriptions page maps the Servlet event with id = 3032 to a new event with id = 128004 and passes it along with the arguments to multiple beans (objectWebSubs, objectNcEmailsSubs, objectNcFileSubs, and objectNCPrintSubs) on the same page for execution. Typically, all beans that receive the event will handle the event, but it is up to each bean to determine what to do with the event. A bean can choose not to handle an event.