Event Handler Builder

 

In this topic ... Quick Tips Specifying Inputs Related Topics ... Overview: Handling Events How to Use the Event Declaration Builder Firing Events Handling Events

The Event Handler builder allows you to specify an action to perform when a specified event occurs. Use an event handler to handle any events you declare with an Event Declaration builder or one of the following Webapp events:

• OnWebAppLoad - Automatically fired when the WebApp's main method or action executes.

• OnRequest - Automatically fired when the Factory servlet receives a request for an instance of the Web App

• OnUnHandledError - Automatically fired for errors that occur that are not handled by an Error Handler builder call

• OnPageLoad (one event of this type for each page in the model ) - Automatically fired when a page in the model is displayed

 

More About These Events

The OnWebAppLoad event is fired when a WebApp is Loaded. This is usually the first time that WebApp instance is loaded for that user or session.

The OnRequest event is fired on a request. This is usually (at the beginning of each request to that WebApp.

The OnUnHandledError event is fired when an un-handled error is encountered. For example,  this case might arise at the end of a model action if there was an Exception that is not caught by an action or method, and the exception makes its way up to the Factory controller / WebApp Runner level.

The OnPageLoad is fired when a page is loaded. For example, when a Page in the application is hit by the user and loaded into the session, this event is fired.

In general, the order these events are run in an application is as follows:

1. OnWebAppLoad is triggered by the first request to the WebApp.

2. OnRequest is fired on every subsequent request to the WebApp

3. [OnUnHandledError] is optional and, and ideally never!

4. OnPageLoad - when a page is loaded.

In a portlet application, once a portlet is loaded the chain of events is in most cases limited to the OnPageLoad event. When the user switches portal pages, the portlet merely re-renders existing pages using the OnPageLoad event and does not re-run any other events or actions.

See Overview: Event Handling for more information about creating and handling your own events.

 

Quick Tips

• Keep Event Declarations, Event Handlers, and related actions organized with a naming convention -- Use some naming convention such as MyEventDeclaration, MyEventHandler, and MyEventAction for the builder call names. Doing so allows you to identify the Event Handler for a particular Event Declaration and distinguishes methods that handle events from the other methods in your model.

 

Specifying Inputs

The Event Handler builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see Using the Builder Call Editor.

Input name	Description
Name	Enter a name for this builder call. The designer tool displays this name in the builder call list.
Event Name	Choose one of the events you declared with an Event Declaration builder call or one of the following system events: OnWebAppLoad OnRequest OnUnHandledError OnPageLoad (one event of this type for each page in the model)
Action	Use the Action Chooser to specify the action to execute when the specified event occurs.