Application Event Model
Overview
Events are sent to the user interface framework whenever an end user
clicks a toolbar button in the application toolbar, selects an action
listed in the Select Action menu, clicks a push button within the user
interface, or selects an option from a menu next to a field. Many other
types of user interactions also send events to the user interface
framework, but those widgets previously listed are the ones that
application developers are mostly likely to configure.
This article explains what events are sent to the user Interface
framework when your end users interact with those types of widgets. We
will also explain how the user interface event handling framework
handles those events. This article should allow you adjust your user
interface to use a wide variety of widgets to fire and handle events to
best meet your end users usability needs.
Toolbar Button Events
Example "Save" Toolbar Button
Find the Signature Option that corresponds to the Save button
Select Action Menu Events
Example Menu Action “Duplicate Action”
Choosing a Select Action menu item causes the user Interface framework
to receive an event that matches the Signature Option id associated with
this Select Action menu item. In the example above, the user
Interface framework would receive an event called “DUPLICATE” based on
the details of the configured Signature Option as shown below.
Translating a Select Action to the Underlying Event
Configuring Push Button Events
Example Select Members Push Button
You can associate a push button with an event using the “Event” field
in Application Designer or using the “mxevent” attribute in the
presentation xml. You can optionally specify the ID of a control that
processes the event using the “Target ID” field in Application Designer
or “targetid” in the presentation xml.
When an end user clicks the button, the event ID specified in that
panel above “selectmembers” is received by the user interface event
handling framework.
Popup Menu Events
Each field-level popup menu has underlying mxevents associated with each of the menu choices.
Example Popup Menu
Configuration of Popup Menu for this Field
Actual Popup Menu for this Field (from Menus.xml)
Notice the events listed for each of the choices shown. That event
string is the event that gets sent to the underlying user Interface
framework when this menu choice is clicked.
User Interface Framework Event Handling
The user interface framework processes the event received in this order:
-
First the framework checks to see if the event matches a signature option (sigoption) ID.
-
If the event does match, the user interface framework checks to see if the user has privileges for that signature option.
-
If they do have security privileges, the framework checks to see if
there is a special flag set to handle the Signature option in an
Advanced way. If the Signature option does have a flag the user
interface handles that flag accordingly. So if the Signature Option is
flagged as an Action then the User Interface invokes that action. Here
is an example of a menu option that would start a System
Configuration->Platform Configuration->Action called “INSERT” for
the Action object instead of firing the default INSERT event.
Setting Advanced Options to point a Signature option to an Action
The Underlying Action that would get called by the Advanced Sigoption Metadata Above
-
If there is not an “Advanced” Flag for this sigoption then the
framework checks the target control/component to see if it handles such
an event (by implementing a method that matches the event name.) Events
sent from Select Action and Toolbar buttons will rarely match this
check as the target control/component for the Select Action and Toolbar
buttons is the Application Toolbar, and it rarely handles the event
directly.
-
If the control or component doesn’t have a method that matches then
the framework will check to see if the DataBean or ApplicationBean
associated with the target component/control has such a method; if it
does then that method will be called. The Select Action or Toolbar
buttons are bound to the ApplicationBean, so will check there for a
method that matches. Buttons and Button groups can be bound to other
Databeans based on where they are placed within the application.
-
If a targetid is not configured in the Application Designer for the
events, the framework will check the Application Bean for the
application to find a matching method.
Example Application Bean method to handle the INSERT signature option event
-
If the Application Bean doesn’t contain a matching method, the Mbo and
MboSet of the DataBean will be checked for a matching method as well.
-
If no such method exists or the method returns the integer constant
for EVENT_CONTINUE, the framework will then check to see if there is a
dialog in the current application with a dialog id that matches the
event name. If such a dialog exists then that dialog will be displayed.
-
Finally the framework will check to see if there is a dialog in the
System Libraries that has a dialog ID that matches the event, and it
will display the dialog in that case.
If all of these checks fail, NOTHING will happen when the event is received by the user Interface framework.
Example
So putting all this information together, let’s go through the use case
where an Application Developer may want to add a button to the user
interface that would expose a functionality that is also exposed in the
Select Action menu. For example, in the Inventory application, let’s
add a button on the main Inventory tab that would trigger the 'Adjust
Current Balance' that is typically available only from the Select Action
menu.
First we’ll look at the Sigoptions defined in the Inventory application in Application Designer to find the right event:
Event is CURBALADJ
Drag and drop a button group and push button onto the main Inventory
tab and set the event to CURBALADJ to match the signature option above.
Configuring the Pushbutton Event and Label
Save the Application.
Now from within the Available Balance section, your end users can click
the Adjust Current Balance button and pop up that dialog.
Current Balance Adjustment window
With all the information you learned above, you could even put a
field-level menu next to the current balance that let you fire this
event (rather than a push button.)
Hopefully this explanation of the event model will help you enhance your user interfaces to meet your end user requirements.
More Detailed Information
Technically when the end user interacts with each of those widgets
above, a click event is sent to the component, and the component
translates that click event into a queued event that matches the
description given above. Sometimes to help debug issues in the field,
the user interface team might turn on javascript event tracking and you
might see these click events being sent from the client.
