Deciding Between Using Custom Events and Custom Add-ons

Both events and add-ons can be used when the data stored within a Web Component needs to be manipulated or when the way the data is collected from the source component must be modified. For example, add-ons are used to govern what data should be retrieved from the MicroStrategy Intelligence Server when the ReportBean collects its data, and events are used to manipulate that data once it is retrieved. Since both components offer similar functionality, it is often difficult to decide which to use. You can use the information provided below to help determine which component you should use for your customization.

When to use add-ons

Add-ons allow you to inject custom code into the query flow just prior to the point when Web components on the page collect the data, as well as just after the Web components have collected their data. Add-ons are configured though the Page Configuration file where each page has a collection of add-ons that must be executed. Unlike events, add-ons cannot be directly referenced through the URL. However, it is possible for the add-on to access information in the URL via the RequestKeys collection, but the developer who needs to retrieve information from the URL should consider whether the scenario can be better addressed by using a custom event.

Add-ons should be used in the following specific situations:

Add-ons are executed every time a MicroStrategy Web page is requested from the Web server. As a result, they should be used for customization scenarios which require an action to occur every time the page is loaded. An example of this is modifying the result flags for the Report Bean.
Add-ons are also useful for situations requiring object-specific behavior such as modifying the style of a report based on the objectID of the report. Since the custom code is required to run every time a particular page is executed in this particular situation, an add-on is the correct choice to address this requirement.
Add-ons are capable of executing after the collection of data. Since events do not support this scenario, add-ons should always be used when custom logic needs to be inserted after data collection.
Add-ons provide a generic infrastructure for adding code that may not fit in with the rest of the architecture.

A few common customizations that are best performed using add-ons are listed below.

Changing the report style based on object ID
In this case, no matter how the report is executed or what events are executed, you want the report style to be set correctly. Thus, an add-on is the correct place to place this logic since it is executed with every request.
Changing the features implementation for a Web Component
In this case, you want the correct WebFeatures implementation to be used no matter which event has been requested by the user. Since this is not event-specific, an add-on should be used.
Modifying the execution logic after the bean has collected data from Intelligence Server
Since only add-ons can be used to execute custom logic after the Web Components on a page have collected data, the custom code should be placed in an add-on.

When to use events

Events are structured requests for performing an action either on a particular Web component in the page such as a bean or on the page itself. Events define the rules regarding what information must be passed along with the request in the form of event arguments. Unlike add-ons, events can be directly referenced through the URL.

Events are a good choice for performing actions that require a modification to a particular Web component, such as the pivot event on the ReportBean or change page event on the Servlet Web component.
Events should be used when the action to be taken is specific to a particular Web Component and does not need to occur in every single request to the page.

A few common customizations that are best performed using events are listed below.

Modifying the behavior of an existing action such as Refresh
If you want to modify how an existing action behaves, an event handler is the correct place to handle the logic. The event handler looks for the same event ID as the original action and performs the new action.
Adding a new action such as “Saving a custom extended property based on user action”
In this case, the code needs to be executed only when the user requests this action and not for every single page request. As a result, a new event should be added and the scenario should be handled by a custom event handler.