Events and Event Handling

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.

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.

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.

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.

To alter existing functionality or add new functionality to MicroStrategy Web, you can add new WebEvents and WebEventHandlers or you can customize existing ones. The definitions of out-of-the-box events are stored in an event definition XML file called events.xml. When you customize existing events or add new events, you use the Web Customization Editor to create a plug-in that contains your custom event definitions.

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.

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

• 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).  

• 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.

Event handlers are associated not only with Web beans, but also with MicroStrategy Web page objects and with the mstrWeb>servlet or ASP.NET file .