An Adelia event processing block can be inserted into a tag on an HTML page in order to trigger a particular process whose code is declared in the Adelia program to which the page belongs.
There are four types of Adelia event processing block that can be associated with a Javascript event trigger:
Important: In the HTML code, the above strings MUST be enclosed between quotation marks ("), not between single quotes (').
Reversible / irreversible / dummy Adelia event processing blocks
When the WADELIA program was created with browser Previous / Next button support enabled, an event can either be reversible, irreversible or dummy. If Previous/Next button support is disabled, all the Adelia events are irreversible.
The user can cancel a reversible event by clicking on the browser's Previous button.
The user cannot cancel an irreversible event; clicking on the browser's Previous button has no effect. Irreversible events are identified by the addition of the parameter: BACK=0.
Examples:
::ADELIA_EVT( :BACK=0)
::ADELIA_ROLLUP(TBL_1, :BACK=0)
A dummy event does not enable the browser's Previous button. If this button was already enabled before executing a dummy event, clicking on it cancels the last event triggered before the dummy event (if this was reversible). A dummy event must be an Ajax event. Irreversible events are identified by the addition of the parameter: BACK=2.
Exemples :
::ADELIA_EVT( :BACK=2,:AJAX,:ASYNC,:COMP=1)
::ADELIA_EVT(MY_EVENT,:BACK=2,:AJAX,:ASYNC,:COMP=2,:TIMER=10S)
Adelia AJAX event processing block
Each type of Adelia event processing block has a counterpart in AJAX mode. AJAX events are identified by the addition of the :AJAX parameter.
Examples:
::ADELIA_EVT (:AJAX,:COMP=1)
::ADELIA_EVT_NOVALID(Ident, :AJAX,:COMP=1)
In addition, an AJAX event can be customized by defining certain parameters:
:COMP
Defines the strategy followed in the event of simultaneous execution requests for the event.
This strategy must be able to resolve execution cases such as the following:
- double-clicking on a button (with an Onclick event),
- using the mouse wheel to select a value in a list box (with an Onchange event),
- entering characters in an input field (with a Keypressed event),
- etc.
Several types of behavior are possible:
Behavior no. 1 (:COMP=1):
Proceed as for two different events and follow the rule defined for different queries (cf. SIMULTANEOUS_DIFFERENT_REQUESTS_RULE in Parameters of the AWSAjax.properties file ).
Behavior no. 2 (:COMP=2):
Cancel the previous event (physically breaking the HTTP connection if the previous event is running, or removing it from the queue if it is pending execution).
Canceling an event in progress does not interrupt its processing on the web application server, but cancels the browser's reception of the response.
This behavior may be used to process two onchange events on a list box, or two cyclical events.
Behavior no. 3 (:COMP=3):
Ignore the second event, regardless of the state of the first event (i.e. running or pending).
This behavior can be used in response to a double-click on a button.
The :COMP parameter is mandatory in the definition of an AJAX event.
:ASYNC
Specifies asynchronous execution for an event. An asynchronous event does not block the user interface. The interface continues to respond while the event is being processed on the Web application server.
The :ASYNC parameter is optional in the definition of an AJAX event. The absence of this parameter indicates that the event is synchronous.
:TIMER
Defines the wait time between successive executions of the same event. The presence of this parameter indicates that the event is cyclical: once executed, it is automatically repeated indefinitely.
The possible values are as follows:
- XXMS: sets a number (XX) in milliseconds,
- XXS: sets a number (XX) in seconds,
- XXM: sets a number (XX) in minutes,
- XXH: sets a number (XX) in hours.
This value must not exceed the life of an HTTP session (as specified in the file web.xml).
The :TIMER parameter is optional in the definition of an AJAX event.
:PRIORITY
Sets an event's priority when it is placed in the queue. This priority defines the order of execution of the events in the queue.
This value must be between REQUEST_MIN_PRIORITY and REQUEST_MAX_PRIORITY.
The :PRIORITY parameter is optional in the definition of an AJAX event. Its absence is equivalent to REQUEST_DEFAULT_PRIORITY.
Examples of AJAX events:
::ADELIA_EVT( :AJAX, :ASYNC, :COMP=1) |
Asynchronous event with behavior 1. |
::ADELIA_EVT_NOVALID(:AJAX, :COMP=2,:PRIORITY=6) |
Synchronous event with behavior 2 and priority level 6. |
::ADELIA_EVT_NOVALID(OBJ, :AJAX, :ASYNC, :COMP=1, :TIMER=10S) |
Asynchronous cyclical event with behavior 1, repeated every 10 seconds. |
In the blocks below, conventional events can be replaced with their AJAX counterparts.
:INVIS
Hides the progress bar when this event is triggered.
This parameter is only processed if PROGRESS_INDICATOR_SHOW_ALL_STARTED_REQUEST is set to "N".
1. ::ADELIA_EVT, ::ADELIA_EVT(Ident)
Important note: The explanation for these two event processing blocks also applies to ::ADELIA_EVT_NOVALID and ::ADELIA_EVT_NOVALID(Ident) which concern Adelia objects that are used without testing the validity of the fields in the HTML page (Event w/o validation radio button selected in the object insertion box).
::ADELIA_EVT
The "::ADELIA_EVT" string can be used to implicitly link an Adelia event processing block with an Adelia object or any HTML tag that can be identified with a name attribute.
Case one: Association with an Adelia object
We are going to link an Adelia event processing block for the EventName event of the Adelia object called ObjName:
<adelia:object><HTMLtag name="ObjName" OnEventName="::ADELIA_EVT" /></adelia:object>
When the HTML page is saved, the WORK WITH EVENTS paragraph in the relevant page's Adelia source is enriched with an OBJNAME:ONEVENTNAME block in the OBJNAME block.
Case two: Association with any HTML tag identified by a name attribute
We are going to link an Adelia event processing block for the EventName event of the tag (object) called ObjName:
<HTMLtag name="ObjName" OnEventName="::ADELIA_EVT" />
When the HTML page is saved, the WORK WITH EVENTS paragraph in the relevant page's Adelia source is enriched with an OBJNAME:ONEVENTNAME block in the OBJNAME block.
With HTML tags that do not support the name attribute, and by extension, in any context where implicit object referencing is not possible, the ::ADELIA_EVT(Ident) directive must be used instead.
::ADELIA_EVT(Ident)
The "::ADELIA_EVT(Ident)" string can be used to explicitly link an Adelia event processing block with a pseudo-object identified by Ident.
We are going to link an Adelia event processing block for the EventName event of the pseudo-object called Ident:
<... OnEventName="::ADELIA_EVT(Ident)" ...>
When the HTML page is saved, the WORK WITH EVENTS paragraph in the relevant page's Adelia source is enriched with an IDENT:ONEVENTNAME block in the IDENT block.
The "::ADELIA_EVT(Ident)" string can also be used in javascript code.
This means that it is possible to dynamically define HTML code that requires an Adelia event processing block to be called. It is even possible to dynamically define the javascript event trigger that calls the Adelia event processing block.
2. ::ADELIA_ROLLUP
<adelia :object ...>
<... name="ObjName" OnEventName= "::ADELIA_ROLLUP(ListName)"...>
</adelia:object>
This directive is used to declare a rollup handler for the ListName list. The rollup call is generated in response to the EventName event of the ObjName object.
When the HTML page is saved, the WORK WITH EVENTS paragraph in the relevant page's Adelia source is enriched with a LISTNAME:ONROLLUP block in the LISTNAME block.
3. ::ADELIA_ROLLDOWN
<adelia :object ...>
<... name="ObjName" OnEventName= "::ADELIA_ROLLDOWN(ListName)"...>
</adelia:object>
This directive is used to declare a rolldown handler for the ListName list. The rolldown call is generated in response to the EventName event of the ObjName object.
When the HTML page is saved, the WORK WITH EVENTS paragraph in the relevant page's Adelia source is enriched with a LISTNAME:ONROLLDOWN block in the LISTNAME block.
4. ::ADELIA_EVT_UPL, ::ADELIA_EVT_UPL(Ident)
::ADELIA_EVT_UPL
The "::ADELIA_EVT_UPL" string can be used to implicitly link an Adelia event processing block with an Adelia object or any HTML tag that can be identified with a name attribute. If the form contains any Adelia Upload objects, this event triggers the uploading of the selected file(s).
Case one: Association with an Adelia object
We are going to link an Adelia event processing block for the EventName event of an Adelia object called ObjName:
<adelia:object><HTMLtag name="ObjName" OnEventName="::ADELIA_EVT_UPL" /></adelia:object>
When the HTML page is saved, the EVENT MANAGEMENT paragraph in the relevant page's Adelia source is enriched with an OBJNAME:ONEVENTNAME block in the OBJNAME block.
Case two: Association with any HTML tag identified by a name attribute
We are going to link an Adelia event handler for the EventName event of the tag (object) called ObjName:
<HTMLtag name="ObjName" OnEventName="::ADELIA_EVT_UPL" />
When the HTML page is saved, the EVENT MANAGEMENT paragraph in the relevant page's Adelia source is enriched with an OBJNAME:ONEVENTNAME block in the OBJNAME block.
With HTML tags that do not support the name attribute, and by extension, in any context where implicit object referencing is not possible, the ::ADELIA_EVT_UPL(Ident) directive must be used instead.
::ADELIA_EVT_UPL(Ident)
The "::ADELIA_EVT_UPL(Ident)" string can be used to explicitly link an Adelia event handler with a pseudo-object identified by Ident. If the form contains any Adelia Upload objects, this event triggers the uploading of the selected file(s).
We are going to link an Adelia event processing block for the EventName event of the pseudo-object called Ident:
<... OnEventName="::ADELIA_EVT_UPL(Ident)" ...>
When the HTML page is saved, the EVENT MANAGEMENT paragraph in the relevant page's Adelia source is enriched with an IDENT:ONEVENTNAME block in the IDENT block.
The "::ADELIA_EVT_UPL(Ident)" string can also be used in the javascript code.
This means that it is possible to dynamically define HTML code that requires an Adelia event handler to be called. It is even possible to dynamically define the javascript event trigger that calls the Adelia event processing block.