Microstrategy SDK - Events

microstrategy-sdk

microstrategy-sdk-javascript

Important:
https://community.microstrategy.com/t5/SDK/TN44860-How-to-Change-the-History-List-Link-Sent-from-SendNow/ta-p/194586
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/ReferenceFiles/bean%20appIndex.html
https://lw.microstrategy.com/msdz/MSDL/902/docs/Event_and_Event_Handler_Interfaces.htm
https://lw.microstrategy.com/msdz/MSDL/902/docs/Creating_a_Custom_Event.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/930/docs/mergedProjects/websdk/topics/scenarios/Creating_a_Custom_Bean_and_Event_Handler.htm

https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/webarch/Web_Beans_Layer.htm#Web_Beans_and_events - done reading
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/scenarios/WEBSDK134.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/scenarios/WEBSDK133.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/scenarios/WEBSDK132.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/wiz/WCE_Custom_Event-Handler_Creation_Wizard.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/custtasks/WCE_Modifying_an_Existing_Event.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/custtasks/WCE_Modifying_Properties_of_an_Event.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/custtasks/WCE_Creating_a_New_Event_Handler.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/custtasks/WCE_Adding_an_Event_Handler_to_a_Bean.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/Adding_extra_arguments_to_an_existing_event.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/Causing_MicroStrategy_Web_to_Return_a_Grid_when_Drilling_on_a_Graph.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/custtasks/WCE_Creating_a_New_Event.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/Creating_a_Custom_Event_for_Grid_Manipulations.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/references/Event_Handlers_Reference.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/custtasks/WCE_Adding_an_Event_Map_to_a_Page.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/Event_Maps.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/Events_and_Event_Handling.htm - done reading
https://lw.microstrategy.com/msdz/MSDL/902/docs/Event_Definitions.htm
https://lw.microstrategy.com/msdz/MSDL/931/docs/ReferenceFiles/bean%20appIndex.html

https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/webarch/Processing_Events_during_Page_Execution.htm
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/webarch/Overview_of_Page_Execution.htm
https://lw.microstrategy.com/msdz/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/app/EventMap.html
http://lw.microstrategy.com/MSDZ/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/app/EventMap.EventMapArgument.html
https://lw.microstrategy.com/msdz/MSDL/902/docs/topics/webcusteditor/wiz/WCE_New_Event_Map_Wizard.htm
https://lw.microstrategy.com/msdz/MSDL/812/docs/Event-related_XML_files.htm
https://lw.microstrategy.com/msdz/MSDL/10/docs/ReferenceFiles/bean%20web.beans.SubscriptionBean.html

https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/default.htm#topics/addons/Deciding_Between_Using_Custom_Add-ons_and_Custom_Events.htm?Highlight=report
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/default.htm#topics/events/Customizing_Events.htm?Highlight=report
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/Content/topics/events/Customizing_Events.htm
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/default.htm#topics/events/Events_and_Event_Handling.htm?Highlight=report
https://lw.microstrategy.com/msdz/MSDL/812/docs/Javascript_Node.htm
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/default.htm#topics/scenarios/WEBSDK077.htm?Highlight=path
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/default.htm#topics/events/Event_Maps.htm?Highlight=path
https://lw.microstrategy.com/msdz/MSDL/_CurrentGARelease/docs/projects/WebSDK/default.htm#topics/events/Event_Definitions.htm?Highlight=report

https://lw.microstrategy.com/msdz/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/beans/WebEventHandler.html
https://lw.microstrategy.com/msdz/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/beans/WebComponent.html
https://lw.microstrategy.com/msdz/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/beans/AggregatedEventHandler.html

How can we add extra arguments to an existing event?

There may be instances in which you want to customize an existing event by adding extra arguments, or parameters. For example, you might want to add new parameters to the report's Execute event to restrict the number of rows/columns that can be viewed in a report grid at run-time. In this customization scenario, you modify the Report Execution page so that a user can specify the maximum number of rows and/or the maximum number of columns through parameters in the request.

  1. Launch the Web Customization Editor.
  2. Create a new plug-in and give it a meaningful name. For example: AddingArgumentsToEvent.
  3. Exit the Web Customization Editor.
  4. Use the Eclipse IDE to create a custom enumeration, EnumCustomReportBeanEvents, that provides names for the custom event arguments you defined (for the REPORT_EVENT_EXECUTE event). The sample, EnumCustomReportBeanEvents.java, contains the entire code for this custom enumeration. This custom enumeration contains the following custom names for the custom argument definitions that you added in the custom event definition file. See below.
  5. Compile EnumCustomReportBeanEvents.java and place the class file inside the classes folder of this customization plug-in adhering to the package structure. For example: plugins\AddingArgumentsToEvent\WEB-INF\classes\com\microstrategy\sdk\samples\events.
  6. If the Web Customization Editor is closed, launch it again and access your plug-in.
  7. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  8. Click on Pages to expand the list of pages used in MicroStrategy Web.
  9. Right-click report (Report Execution) and select Create New Add-on. This launches the Add-on Creation wizard.
  10. Click Browse to select the source folder for the project.
  11. Enter com.microstrategy.sdk.samples.addons in the Package text field.
  12. Enter ReportMaxRowsColsAddOn in the Name text field.
  13. Enter Restricts number of rows-columns to be viewed in report grid at run-time in the Add-onDescription text field.
  14. Click Next.
  15. Click Finish. ReportMaxRowsColsAddOn.java opens in the editor. The sample, ReportMaxRowsColsAddOn.java, contains the entire code for this custom add-on.
  16. Save your changes.
  17. Navigate to MicroStrategy Web Configuration->Events->Event Handler Type (4)->ReportExecuteEvent.
  18. Double-click ReportExecuteEvent to launch the Event and Arguments editor in the right frame.
  19. Click Add.
  20. Enter 4020 and maxGridRows in the fields for Argument ID and Argument Name respectively.
  21. Click Add.
  22. Enter 4021 and maxGridCols in the fields for ArgumentID and Argument Name respectively.
  23. Save your changes.
  24. Launch MicroStrategy Web to view the customization.
// Integer values for maximum rows and columns arguments
int REPORT_EVENT_ARGUMENT_GRID_MAX_ROWS = 4020;
int REPORT_EVENT_ARGUMENT_GRID_MAX_COLUMNS = 4021;

How can we customize the behavior of an existing event?

The default behavior when you drill on a MicroStrategy graph report is to return a graph view of the drilled report. However, there may be instances when you want to change the default drilling behavior— for example, to make it easier to analyze the results. In this customization scenario, you modify default drilling behavior so that when a user drills on the graph view of a report, the drilled-to report is automatically returned as a grid. You accomplish this by customizing the behavior of an existing event.

  1. Launch the Web Customization Editor.
  2. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  3. Click on Pages to expand the list of styles used in MicroStrategy Web.
  4. Navigate to report (Report Execution)->Beans.
  5. Click the frame bean to expand the child beans under it.
  6. Right-click rb (Type=ReportBean) and select New Event Handler. This launches the Custom Event Handler Creation wizard.
  7. Click Browse to select the source folder for the project.
  8. Enter com.microstrategy.sdk.samples.events in the Package text field.
  9. Enter CustomReportHandlerForGraphDrillOnly in the Name text field.
  10. Select the radio button for Use Existing Event.
  11. Click Next.
  12. Click Finish. CustomReportHandlerForGraphDrillOnly.java opens in the editor. The sample, CustomReportHandlerForGraphDrillOnly.java, contains the entire code for this custom transform.
  13. Save your changes.
  14. Launch MicroStrategy Web to view the customization.

How can we modify an existing event?

  1. Launch the Custom Event Handler Creation Wizard.
  2. Click Browse to navigate to the source folder for MicroStrategy project.
  3. Click Browse to navigate to the package.
  4. Enter a name for the event handler in the Name text field.
  5. To modify an existing event, select the radio button Use Existing Event. Then select the appropriate ID from the drop-down menu for Event ID.
  6. Click Add to specify arguments for the event.
  7. Click the Click here… text in the Argument ID column to enter the argument ID.
  8. Check the box next to the argument ID, if the argument is a required argument.
  9. Click the Click here… text in the Argument Name column to enter the name for the argument.
  10. Click Next.
  11. Click Finish. This opens up two files for editing — one file that contains code for the event handler and the other that contains code for the enumeration. Note: The new event handler gets added to the bean. It is listed in the Event Handler text field for the bean under the Properties section.
  12. Modify the code for the event handler as appropriate.
  13. Modify the code for the enumeration as appropriate.
  14. Save your changes.

How can we modify the properties of an existing event?

  1. Launch the Web Customization Editor.
  2. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  3. Click on Pages to expand the list of pages used in MicroStrategy Web.
  4. Double-click the page for which you wish to modify properties to the event.
  5. Click the Events Javascripts tab.
  6. Select the appropriate event under the Event Maps section. The properties for the event are listed next to it.
  7. Modify the properties as appropriate.
  8. Save your changes.

How can we add an event handler to a bean?

  1. Launch the Custom Event Handler Creation Wizard.
  2. Click Browse to navigate to the source folder for MicroStrategy project.
  3. Click Browse to navigate to the package.
  4. Enter a name for the event handler in the Name text field.
  5. To create a new event, select the radio button Create New Event. Then specify an ID and name for the new event in the Event ID and Event Name text fields respectively. To use an existing event, select the radio button Use Existing Event. Then select the appropriate ID from the drop-down menu for Event ID.
  6. Click Add to specify arguments for the event.
  7. Click the Click here… text in the Argument ID column to enter the argument ID.
  8. Check the box next to the argument ID, if the argument is a required argument.
  9. Click the Click here… text in the Argument Name column to enter the name for the argument.
  10. Click Next.
  11. Click Finish. This opens up two files for editing — one file that contains code for the event handler and the other that contains code for the enumeration. Note: The new event handler gets added to the bean. It is listed in the Event Handler text field for the bean under the Properties section.
  12. Modify the code for the event handler as appropriate.
  13. Modify the code for the enumeration as appropriate.
  14. Save your changes.

How can we launch the Custom Event Handler Creation Wizard?

The Custom Event Handler Creation Wizard creates an event handler that gets automatically added to a bean.

  1. Launch the Web Customization Editor.
  2. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  3. Click on Pages to expand the list of MicroStrategy Web Pages.
  4. Click the MicroStrategy Web Page that contains the bean to which you want to add the event handler.
  5. Click on Beans to expand the list of beans contained in that MicroStrategy Web Page.
  6. Right-mouse click the bean to which you want to add the event handler and select New Event Handler to launch the Custom Event Handler Creation Wizard.

How can we create a new event?

  1. Launch the Custom Event Handler Creation Wizard.
  2. Click Browse to navigate to the source folder for MicroStrategy project.
  3. Click Browse to navigate to the package.
  4. Enter a name for the event handler in the Name text field.
  5. To create a new event, select the radio button Create New Event. Then specify an ID and name for the new event in the Event ID and Event Name text fields respectively.
  6. Click Add to specify arguments for the event.
  7. Click the Click here… text in the Argument ID column to enter the argument ID.
  8. Check the box next to the argument ID, if the argument is a required argument.
  9. Click the Click here… text in the Argument Name column to enter the name for the argument.
  10. Click Next.
  11. Click Finish. This opens up two files for editing — one file that contains code for the event handler and the other that contains code for the enumeration. Note: The new event handler gets added to the bean. It is listed in the Event Handler text field for the bean under the Properties section.
  12. Modify the code for the event handler as appropriate.
  13. Modify the code for the enumeration as appropriate.
  14. Save your changes.

How can we create a custom event?

There may be instances in which you want a custom action to be performed. For example, you might want to place a custom button on a MicroStrategy Web page, which triggers a custom grid manipulation when it is clicked. To accomplish this, you need to create a custom event that causes the custom action to be performed. In this customization scenario, you create a new event which allows a user to move all template units from the rows axis of a cross-tabbed report to the columns, resulting in a tabular report. You place a link associated with this new event— called "Make tabular!" in this scenario— on the bottom of the Report Execution page so that a user can execute the associated functionality with a single click. This particular action is part of the out-of-the-box MicroStrategy Web functionality, but it provides a good example of how to create a new event to achieve a result such as this. To add other custom actions that are not included out-of-the-box, simply extrapolate from the instructions and code samples in this scenario.

  1. Launch the Web Customization Editor.
  2. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  3. Click on Pages to expand the list of pages used in MicroStrategy Web.
  4. Double-click the report(Report Execution) page to edit it.
  5. Click the Template Properties tab at the bottom in the right frame to make changes to the Default page template.
  6. Right-click the content page-section and select Edit current file.
  7. Click the Yes button in the prompt to edit the Report_Content page section file.
  8. In the code that is displayed for Report_Content, add the code shown below at the end of the existing code. This new code adds a link (identified by the test "Make tabular!") that triggers the new custom event. See below.
  9. Expand the report(Report Execution) page.
  10. Expand Beans.
  11. Expand frame (Type=ReportFrameBean).
  12. Right-click rb (Type=ReportBean) and select New Event Handler.
  13. On the Custom Event Handler Creation Wizard, browse to the source folder and click OK.
  14. Enter com.microstrategy.sdk.samples.events as the package name.
  15. Enter CustomReportHandlerForRowToColsOnly as the Name of the event handler.
  16. With the Create New Event radio button selected, enter 4501 as the Event ID and MOVEALLATTSTOCOLUMN as the Event Name.
  17. Click Next
  18. Click Finish
  19. EnumCustomReportHandlerForRowToColsOnlyEvents.java opens in the editor. It contains the definition of your new event: int BEAN_EVENT_MOVEALLATTSTOCOLUMN = 4501;
  20. Click the CustomReportHandlerForRowToColsOnly.java tab and it opens in the editor. The sample, CustomReportHandlerForRowToColsOnly.java, contains the entire code for this custom event handler. Copy the sample code and paste it over the newly created CustomReportHandlerForRowToColsOnly.java in the editor.
  21. Save your changes.
  22. Launch MicroStrategy Web to view the customization.
<web:urlEvent eventID="com.microstrategy.sdk.samples.events.EnumCustomReportHandlerForRowToColsOnlyEvents.BEAN_EVENT_MOVEALLATTSTOCOLUMN" baseBean="rb">Make tabular!</web:urlEvent>

How can we launch the New Event Map Wizard?

The New Event Map Wizard specifies an event map for an event.

  1. Launch the Web Customization Editor.
  2. Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
  3. Click on Pages to expand the list of MicroStrategy Web Pages.
  4. Double-click on the MicroStrategy Web Page to which you want to specify the event map. This displays the Basic Properties for that MicroStrategy Web Page.
  5. Click the Events and JavaScripts tab at the bottom of the editor.
  6. Click the Add Event button under the Event Maps section to launch the New Event Map Wizard.

How can we add an event map to a page?

  1. Launch the New Event Map Wizard.
  2. Select the appropriate radio button yes or no to indicate whether the event should be mapped only if the source is a servlet.
    1. If you select yes, enter the following information:
      1. Select from the drop-down list, the name of the source event which will be mapped. This is the event that is originated by the source bean. Normally this event is processed by the source bean itself; however, the event map will modify this behavior and delegate the processing of the source event to a different bean (target bean).
      2. Select a target bean from the drop-down list. This bean will handle the execution of the event originated by the source servlet bean.
      3. Select from the drop-down list, the name of the target event. This is the user action to which the source event will be mapped to.
    2. If you select no, enter the following information:
      1. Click on the … button to select the source bean. This is the bean that actually originates the event. The event map will delegate the execution of the event from this web bean to a different bean (target bean). You can directly enter the name of the bean in the Enter type name text box or enter a ‘?’ to see a list of all beans currently available.
      2. Select from the drop-down list, the name of the source event which will be mapped. This is the event that is originated by the source bean.
      3. Select a target bean from the drop-down list. This bean will handle the execution of the event originated by the source bean.
      4. Select from the drop-down list, the name of the target event. This is the user action to which the source event will be mapped to.
  3. Click Next.
  4. Click Add to select arguments that will be mapped.
  5. This allows you to specify the event mapping at the argument level. You can map specific arguments in the source event to arguments in the target event.
  6. Click the Click here… text in the Source Arguments column to select the argument to be mapped. This is the argument in the source event that has to be mapped to a target argument.
  7. Click the Click here… text in the Target Arguments column to select the argument to be mapped to. This is the argument in the target event to which the source argument has to be mapped to.
  8. Click Next.
  9. Click Finish. The new event gets added to the list of events for the page under the Event Maps section.
  10. Save your changes.

You can edit or delete the event by selecting the event and clicking on the edit event or delete event button respectively.

What is the relationship between web bean and event handlers?

Every Web bean has a default event handler assigned to it that contains a list of valid events for that particular bean. For example, the list of valid events for a ReportBean includes actions such as execute, pivot, sort, drill, and refresh, while the list of valid events for a PromptBean includes add elements and remove elements. A complete list of event handlers associated with each type of bean can be found in the Event Handlers Reference. In MicroStrategy Web, the initial numeral in an event ID represents the type of event handler with which the event is associated. For example, folder event IDs begin with "2" and report event IDs begin with a "4". An event whose ID is "2001" would be a folder event, while an event whose ID is "4001" would be a report event. Likewise, the initial numeral in an event argument ID also represents the type of event handler with which the argument's event is associated. So, for example, an event argument whose ID is "2001" would be an argument for a folder event, while an event argument whose ID is "4001" would be an argument for a report event.

What is an event map?

I need to complete this question. See https://lw.microstrategy.com/msdz/MSDL/902/docs/Event_Maps.htm

How can we delegate the execution of an event from a web bean in a particular page to another web bean on a different page?

I need to complete this question. See https://lw.microstrategy.com/msdz/MSDL/902/docs/Event_Maps.htm

How can we delegate the execution of an event from one Web bean to another within the same page?

I need to complete this question. See https://lw.microstrategy.com/msdz/MSDL/902/docs/Event_Maps.htm

What is an event?

An event is an object containing code for handling user's interaction. It also contains properties that encapsulate or describe the nature of the particular interaction.

Every request to MicroStrategy Web corresponds to a specific event, which in turn represents a specific user action— such as folder browsing, pivoting, or sorting— that must be performed. An event is defined by an ID, a name, and the set of the arguments that are used in processing the action. MicroStrategy Web uses events to identify both the actions that must be performed and the component that should execute the actions. These actions modify the state of the beans and, ultimately, the page that is displayed to the user.

Each event (that is, each WebEvent) comes with an associated list of required and optional parameters that define the specific request. Within a request, an event is identified by the evt parameter whose value represents the event ID. For example, in the parameter name/value pair, evt=4001, 4001 is the ID of the event that needs to be handled. The Event Handlers Reference contains a comprehensive list of the default names and IDs for all valid events.

In MicroStrategy Web, every possible user action— that is, each clickable link and user response in the application— corresponds to a unique event, defined in MicroStrategy Web as a WebEvent. These unique events (or user actions) are processed by event handler objects, defined in MicroStrategy Web as WebEventHandlers, which are categorized by event handler type. When events are processed, they modify the state of beans and, ultimately, the page that is displayed to the user.

What is the relationship between events and event handlers?

An event handler contains a collection of available WebEvents that are associated with the appropriate HTML hyperlinks in MicroStrategy Web. When a link that calls an event is clicked, the bean coordinates specific actions to be taken based on the type of event requested.

What is the relationship between bean types and event handler types?

There is a one-to-one relationship between a bean type and an event handler type, as well as a one-to-one relationship between an instance of a bean type and an instance of an event handler type. When a bean receives a request to process a specific user action, the request is delegated to the event handler associated with that kind of bean.

How can we add new event or modify existing event?

  1. New events can be added and existing ones modified simply by customizing an event definition file

What can we do with events?

MicroStrategy Web has an array of out-of-the-box events and event arguments, but you can add new arguments to existing events, edit existing arguments in existing events, and add new events with or without arguments. The Web Customization Editor available with the SDK provides a Custom Event Handler Creation Wizard that guides you in the following tasks:

  1. Modifying an existing event by modifying an existing argument and/or adding a new argument
  2. Creating a new event
  3. Creating enumerations to redefine events

What can we use the Custom Event Handler Creation Wizard for?

The Web Customization Editor available with the SDK provides a Custom Event Handler Creation Wizard that guides you in the following tasks:

  1. Modifying an existing event by modifying an existing argument and/or adding a new argument
  2. Creating a new event
  3. Creating enumerations to redefine events

The Custom Event Handler Creation Wizard creates an event handler that handles a new or an existing event.

What are the two characteristics that a custom event handler must always have?

The two characteristics that a custom event handler must always have are:

  1. A constructor that assigns a type to this event handler
  2. A processRequest() method that takes the RequestKeys and retrieves the event.

How can we add a new custom event?

A custom event handler can be created in one of the two following ways:

  1. By creating a new handler of an existing type (for example, a custom event handler for an out-of-the-box data component such as a ReportBean). Existing event handler types are defined in EnumEventHandlerTypes.
  2. By creating a new handler of a new type (for example, a custom event handler for a custom data component)

Where is the event definition file?

The code sample below illustrates three ways to customize event definitions using a custom event definitions file. The event definitions file is called events.xml.

<eventHandlers><eventHandler type="z">
   <events>
      <event id="x" name="existingEvent">
        <arguments>
          <argument id="x1" name="newName"></argument>
          <argument id="x2" name="newArg"></argument>
        </arguments>
      </event>
      <event id="y" name="newEvent">
        <arguments>
          <argument id="y1" name="newArg1"></argument>
          <argument id="y2" name="newArg2"></argument>
        </arguments>
      </event>
      <event id="4501" name="newDisplayEvent">
        <arguments>
          <argument id="4501" name="newDisplayArgument"></argument>
        </arguments>
      </event>
    </events>
</eventHandler></eventHandlers>

How can we modify an existing event by modifying an existing argument and/or adding a new argument?

The first event definition illustrates how to modify an existing event by modifying an existing argument and adding a new argument. This custom event definition is read partly from the out-of-the-box event definition XML file and partly from the custom event definition XML file. It includes two arguments x1 and x2.

<event id="x" name="existingEvent">
    <arguments>
        <argument id="x1" name="newName"></argument>
        <argument id="x2" name="newArg"></argument>
    </arguments>
</event>

The existing event is named existingEvent and has an event ID of x. It is represented in the custom event definition file by an <event> node whose name attribute is set to "existingEvent" and whose id attribute is set to "x". The definition of event x includes two arguments — one which modifies an existing argument and another which is a new argument.

  1. The existing argument has an argument ID of x1. The name of this argument will be changed to newName. This modification is represented in the custom event definition file by an <argument> node whose name attribute is set to "newName" and whose id attribute is set to "x1".
  2. The new argument is called newArg and has an argument ID of x2. This modification is represented in the custom event definition file by an <argument> node whose name attribute is set to "newArg" and whose id attribute is set to "x2".

How can we create a new event?

The second event definition represents a new event. This custom event definition is read completely from the custom event definition XML file. It includes two arguments y1 and y2.

<event id="y" name="newEvent">
    <arguments>
        <argument id="y1" name="newArg1"></argument>
        <argument id="y2" name="newArg2"></argument>
    </arguments>
</event>

How can we create enumerations to redefine events?

Once you have defined a new event, including any new event arguments, in a custom event definition file, a custom Java enumeration class needs to be created in which you declare the IDs of the newly-defined event and arguments. Event handlers or transforms that perform some action based on the presence of your custom event and/or arguments implement this interface.

<event id="4501" name="newDisplayEvent">
    <arguments>
        <argument id="4501" name="newDisplayArgument"></argument>
    </arguments>
</event>

The code sample below illustrates a simple enumeration class for a custom event with a single argument.

package com.microstrategy.sdk.samples.customevents;
import com.microstrategy.web.beans.EnumReportBeanEvents;

public interface EnumCustomFolderBeanEvents extends EnumFolderBeanEvents {
    //Custom Event Definition
    int FOLDER_EVENT_NEW_DISPLAY_EVENT = 4501;
    int FOLDER_EVENT_ARGUMENT_NEW_DISPLAY_ARGUMENT = 4501;
}

The event ID (4501) and the argument ID (4501) correspond to the values of the id attributes of the <event> and <argument> nodes in a custom XML event definition file. The custom event handler that processes this event uses the values in this enumeration to reference event and argument IDs.

The Custom Event Handler Creation Wizard provided with the Web Customization Editor creates the enumeration class as a part of modifying an existing event or creating a new event.

What is the convention for assigning ID for our event?

In MicroStrategy Web, the initial numeral in an event ID represents the type of event handler with which the event is associated. For example, folder event IDs begin with "2" and report event IDs begin with a "4". An event whose ID is "2001" would be a folder event, while an event whose ID is "4001" would be a report event. Likewise, the initial numeral in an event argument ID also represents the type of event handler with which the argument's event is associated. So, for example, an event argument whose ID is "2001" would be an argument for a folder event, while an event argument whose ID is "4001" would be an argument for a report event.

Custom events should follow the same convention of using the appropriate initial numeral in the ID. Additionally, since all event IDs and event argument IDs must be unique, custom event IDs and event argument IDs should begin after allowing for a reasonable number of pre-defined events. So, for example, if you are creating a report event, you might want to use "4501" as the custom event ID and '4501' as the first custom event argument ID.

To determine how to number the ID of a custom event, refer to the Event Handlers Reference. Look at the appropriate enumeration class, such as EnumReportBeanEvents or EnumRWBeanEvents.

What is the relationship between web beans and events?

The WebBeaninterface extends the WebComponent interface, and all WebComponent objects are capable of handling any number of events. An event represents some action that can be performed or handled by a WebComponent. For example, a ReportBean can handle an event for executing a report or for performing a pivot, while a FolderBean can maintain a Browse event. A specific type of Web bean event is generally exposed through the unique EventHandler associated with that Web bean by default. To enable a Web bean to perform a custom action, you can extend the bean's default EventHandler.

What is the relationship between transforms and events?

Transforms also use events to generate URL links and forms. Whenever a transform needs to generate a link or a form, it searches for the corresponding event and obtains a set of required and optional arguments from that event. The transform uses this information to construct a URL string or a form that encapsulates the request. If no event is found, then the transform does not generate any output for it. This prevents the transform from generating a request that cannot be fulfilled by the Web page components.

When a transform is applied to a bean and renders the output, it searches for desired events. If an event is found, the event collects a set of required and optional arguments from the transform and uses them to construct a string that encapsulates the request. If no event is found, the transform does not generate any output. This prevents the transform from generating a request that cannot be fulfilled by the Web page components.

One of the valid events for a ReportBean is a pivot action, which takes place as described below:

  1. When a ReportBean is rendered as an HTML grid through the use of a transform, the output can include hyperlinks to move an attribute from a row to a column (that is, to pivot the data displayed).
  2. If a user clicks the pivot hyperlink, the event is handled by the ReportBean. The WebEventHandler object for the ReportBean contains and exposes a WebEvent object corresponding to the pivot event type.

When and why should we customize events?

You customize events when the available events and/or the way they are handled do not meet your specific requirements. This is usually due to one of the following reasons:

  1. You want to add new functionality to the application and there is no existing event available to perform the set of tasks that are needed.
  2. The default handling of an existing event, or request for an action, is different from the one you desire. For example:
    1. The event does not initialize all properties of a bean, or the event uses a set of default values that you would like to override. (For a practical example of this situation, see Adding Extra Arguments to an Existing Event for Report Execution.)
    2. There is a need to perform some post-processing after the event is handled. (For a practical example of this situation, see Causing MicroStrategy Web to Return a Grid when Drilling on a Graph.)

What is the purpose of the WebEventHandler class?

This interface generates and handles a set of WebEvent. A WebEventHandler retrieves any event-related information, such as event id and argument values, from the RequestKeys object. A instance of WebEventHandler is usually attached to a WebComponent, the brick for building a Web application. Web applications are allowed to dynamically add a WebEvent to a WebEventHandler instance at the run time by providing the XML representation of the WebEvent. https://lw.microstrategy.com/msdz/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/beans/WebEventHandler.html

What is the purpose of the AggregatedEventHandler class?

I NEED TO COMPLETE THIS. https://lw.microstrategy.com/msdz/MSDZ_World2015/docs/ReferenceFiles/com/microstrategy/web/beans/AggregatedEventHandler.html

How can we determine a list of beans that a particular event handler is associated with?

An event handler is the name of your Java class. Open up the YourPluginFolder/WEB-INF/xml/pageConfig.xml and search for the name of your Java class.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License