WAM Filter and Command Handler Anatomy
Applies to WAM only.
WAM filters and command handlers:
- Can only be used if you are using LANSA 10.5 (or later)
- Are usually visual in nature
- Uses vlf_layout or vlf_layout_v2 as it's layout weblet. The vlf_layout_v2 weblet is used to enable the use of Weblets with the jQuery UI design theme.
- Can have their forms painted by using the WAM editor.
- Execute on the server system
- Cannot maintain their state because they are web browser based
Structurally the basic anatomy of a WAM function looks like this:
There are five important things you need to understand about the structure of WAM filters and command handlers:
|
|
All WAM filters and command handlers extend (i.e.: inherit from) a base class named #PRIM_WAM. The base classes provide a set of pre-defined behavior to the WAM. |
|
|
There is always a web map that defines what is sent out as the web page. In this example the push buttons #UB_SAVE and #UB_SEARCH are sent. |
|
|
There is always a single WEBROUTINE defined that does two important things: – It registers all the events that the filter or command handler can handle and associates them with an event handling routine. In this example the click events for the #UB_SAVE and #UB_SEARCH buttons are registered and associated with event routines (the blue and brown arrows show the associations). – It Indicates to the Framework manager that the Framework can be initialized and executed. The only code you should ever add to the uHandleEvent routine is avRegisterEvent method invocations. All other logic should be put into the appropriate uInitialize, uExecute, uTerminate or uWAMEvent_N event handling routines. |
|
|
Filters and command handlers can have optional uInitialize, uTerminate and uExecute event handlers. Since WAM routines are created and destroyed every time they are executed, the uInitialize and uTerminate routines are executed every time the WAM is invoked. Therefore they should only contain code that you want to execute at the start and/or end of every single WAM interaction with the client. uExecute is only ever executed when the WAM is executed (that is, when a filter is started or a command handler is executed). When events occur inside an active WAM (for example a button click) uExecute is not signalled, just the registered uWAMEvent_N event. |
|
|
Most filters and command handlers also have their own unique event handling routines. The example WAM used here has registered events (UB_SAVE.Click and UB_SEARCH.Click) so it has 2 event routines defined to handle the respective click events. |
Routines execute in a WAM for VLF for Web in this order:
1. uHandleEvent (Note that messages from routine uHandleEvent will be sent last even though it executes first)
2. uInitialize
3. uExecute (first time logic)
4. User WAM Events
5. uTerminate
Writing WAM filters or command handlers is much like writing any other WAM program except that the Framework manages how, when and where the filter or command handler is created, displayed and destroyed.
Normally you generate your WAM by using the Program Coding Assistant initially and then when you need to add another event simply:
- Register the event and associate it with an event handling routine.
- Add in a new event handling routine to handle the event.
The most important thing to remember is that whenever your WAM filter or command completes handling an event it then ceases to exist.