Event Declaration Builder

 

In this topic ... Quick Tips Specifying Inputs   Related Topics ... Overview: Handling Events Event Handler Builder Client Event Handler Builder Firing Events Handling Events

The Event Declaration builder adds a <declaration /> element to the _EventDeclarations variable and adds a fireEventName method to the WebApp. Other methods in your model can call the fireEventName method for any user-defined events when a particular action occurs or when some condition exists. You add an Event Handler builder call to your model for each Event Declaration builder call.

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

 

Events in portals

We can use this builder to fire events within the context of a portal. Portal events fired by this builder share session data and can be handled within the context of the portal, providing all models communicating via these events are contained within the same WAR file.

When using Factory Events fired by this builder in a portal, do not fire events on the model's initial load. In a portal setting you cannot guarantee the order that portlets are loaded, so the target models may have not been instantiated yet. When using Factory Events in a portal do not make direct access to the session or request objects. These objects will be related to the event originator.

 

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 Declaration 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 displays this name in the builder call list.
Event Name	Enter a name for this event. This name appears in the builder call list and in the list of events to handle in the Event Handler's builder call editor.
(optional) Arguments	To define arguments that will be passed to the action specified by an Event Handler, name those arguments and specify their data type here.
Client-Side Event Delivery
Use Client-Side Delivery	Check this option to designate this event for client-side delivery. You must also create a handler for the event using the client event handler builder. If this option is not checked (default), the event is delivered on the server and the full page is refreshed.
Fire Event On Server	Check this option to invoke the event on the server, without a full page refresh, before firing the event on the client. If this option is checked, create a handler on the server side using the event handler builder.
Event Prefix	Enter a prefix to be prepended to the event name to ensure that the name is unique on the client side. This is necessary to prevent name collisions when multiple models are on the same page. All uses of a particular client-delivered event need to agree about that prefix for the event to be shared among them. The best practice pattern, whether for server or client side events, is to put the event declaration builders into a model and import that model into all models that use those events. Example: com.example.modelName