About form event handlers

Form event handlers define units of work to be performed in response to a form event. These event handlers are defined for specific forms. They are not shared across forms.

Note: This topic presents information about the Mongoose form event model, as opposed to the Application Event System. The primary difference between the two is that form events and their handlers are operational only within a single form, whereas application events can be used application-wide.

Event handler sequence

Event handlers are identified by the name of the event that they are handling and by a sequence number. You can define multiple event handlers for any event. These event handlers execute in sequence number order. By default, if any event handler reports a failure, the remaining event handlers in the sequence are skipped. You can override this default by setting the Ignore Failure parameter. If you set this attribute, the event handler is always treated as successful.

Built-in responses

When you define additional event handlers for standard events that have built-in responses, the built-in responses always execute last. This means that you can effectively cancel the built-in responses by reporting failure from a custom event handler for the same event.

Event handler messages

For any event handler, you can define messages to be displayed when the event handler fails or succeeds. Use the Error Message and Success Message parameters to define each message. The message definition can contain a translatable string name and can also reference any of the standard substitution keywords. For example, you can use the %B substitution keyword to reference a message type parameter that is defined for an event handler of the Method Call response type.

By default, messages generated from event handlers are presented in pop-up message boxes. Alternatively, you can specify that they be presented in the application status bar. To do so, use the Message on Status Line parameter.

Restricting event handler execution to specific collections

By default, event handlers execute regardless of the currently active collection or the specific collection operation that generated the event. If you are using multiple collections on a form, you can create event handlers that are specific to each collection. To do so, use the event handler's Only When Current Collection Is parameter.

When you designate a specific collection for an event handler, form-based events are handled by this event handler only when the specified collection is active. Collection-based events are handled by this event handler only when the event is generated by an operation on the specified collection.