Creating a Custom Event

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:

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

The Custom Event Handler Creation Wizard creates an event handler that handles a new or an existing event. The two characteristics that a custom event handler must always have are:

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

Event Definitions

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.

</arguments>

</event>

</arguments>

</event>

</arguments>

</event>

</events>

</eventHandler></eventHandlers>

Modifying 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.
- 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".
- 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".

See also:

Creating 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>

See also:
- Creating a New Event
- Creating a Custom Event for Grid Manipulations
Creating 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.

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.