Customizing Events

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. For a general introduction to event processing, see Processing Events in the Page Execution and Event Processing section of the MSDL.

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.

This section shows you how to customize events and event handling in MicroStrategy Web— either by adding new event definitions and event handlers to the application framework or by customizing existing events and event handlers.

New events can be added and existing ones modified simply by customizing an event definition file. A custom event handler can be created in one of the two following ways:

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.
By creating a new handler of a new type (for example, a custom event handler for a custom data component)

Events and add-ons offer similar functionality. Before creating custom events, you should first become familiar with add-ons. The topic, Deciding Between Using Custom Add-ons and Custom Events, provides information to help you determine which component you should use for your customization.

When and why to 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:

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.
The default handling of an existing event, or request for an action, is different from the one you desire. For example:
- 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.)
- 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.)
- Additional examples of common event customization scenarios:
  - Changing the drill action so that drilling on a graph automatically returns a grid
  - Adding a custom button on a MicroStrategy Web page, which triggers a custom grid manipulation when it is clicked
  - Extending the prompt-handling event to accept values from the URL
  - Implementing an interface to impose a maximum number of rows or columns
  Two of the examples above are different events handled by the same custom event handler. The handler is located in the samples directory. The file is called CustomReportHandler.java.