Infor Technology

« | Main | »

Working with Events in LSO Scripting: Part 1

June 18, 2012

Nearly every script you create for S3 in Lawson Smart Office will involve event handling. Understanding events and how to properly handle them is crucial to writing efficient script. In this, the first of 2 articles on the topic, I will describe the basics.

Events are at the core of Windows programming. Events are in effect a notification that some action has occurred. For example, when a user clicks a button, a ‘Click’ notification occurs. Different controls provide many different types of notifications and not all controls implement the same events. The S3 LSO scripting model as documented in the S3 Object Browser, which is available from the Help menu in the S3 Scripting tool, provides many ‘pseudo’ events. That is, there are notifications you can handle, but are not the direct result of an action. For example, when the user clicks the Change button in the S3 form toolbar, the actual event is the button click, but this will result in a call to the application server to perform a Transaction Change request. In that case, S3 LSO provides a notification that a transaction is about to occur – BeforeTransaction. Similarly there is an AfterTransaction notification once the Transaction service provides a response.

Accessing the S3 Object Browser

Script1-1

Form Events

Script1-2

So, how does one handle or respond to one of the form notifications or other control events? It involves a 3 step process in your script:

  • Attach a handler function to the form or control.
  • Implement the handler function.
  • Cleanup as the form is unloading by releasing the memory associated with the handler.

Attaching a handler function to the form or control

The S3 scripting template already contains an example of how to do this. When you create a new script, your Init function will look like this:

public function Init(element: Object, args: Object, controller: Object, debug: Object)
{
try {
form = controller;
formGrid = form.FormGrid;
console = debug;
// TODO Add your code here
form.add_BeforeUnload(OnBeforeUnload);
} catch (e) {
console.WriteLine(ScriptUtil.FormatException("Init", e));
}
}

The line with the code form.add_BeforeUnload(OnBeforeUnload)attaches the BeforeUnload notification to the form. Notice that this also specifies the script function, OnBeforeUnload that is to receive the event notification. This function name is not required and can be anything you want, however a good practice is to name the handler “On<event name>” and if some of the processing is to be off-loaded to another function (something described in Part 2), to call that function “Handle<event name>”. If you use the Helpers described below, that is that name that will be used. So, assuming you want to implement a handler for BeforeTransaction, you would add the code form.add_BeforeTransaction(OnBeforeTransaction). Once you become familiar with the form events available, it might be easy to key the statements in the script editing window. However, there are also helpers available in the toolbar that allow you simply to insert the code.

Event Handler Helpers

Script1-3

In addition to the form events available, it is possible to attach event handlers to any standard control using similar syntax: <control>.add_<event name>. For example, to attach the Button Click event to a handler:

    var button = CreateButton();
button.add_Click(OnButtonClick);

To use any of the built-in control events you will have to consult an online reference for what is available and what the handler parameters are. The Microsoft MSDN site is the best reference for that information. And when referring to MSDN documentation, keep in mind that LSO is built on the Windows Presentation Foundation (WPF), the controls of which are defined in the System.Windows.Controls namespace (http://msdn.microsoft.com/en-us/library/system.windows.controls.aspx). Earlier .NET applications where built on controls in the System.Windows.Forms namespace.

Implement the handler function

An event handler in Jscript has the following requirements: a) it must be a public function and b) it must accept 2 parameters, the sender object and an event argument object (the type of which depends on the event). The sender object is the control which triggers the event and is always declared as sender: Object. Again, sender as the name is not required, but used as convention. The event argument object (“eventargs”) by convention is named “e” followed by its type declaration. The “pseudo” events of the form require different eventargs and are documented in the object browser. Back to our example of handling the BeforeTransaction event, its function signature is:

public function OnBeforeTransaction(sender: Object, e: CancelTransactionEventArgs)

An empty function handler for the various form events can be inserted using the helpers. The eventargs object will have different properties available depending on the object and are likewise documented in the object browser. This particular eventargs object has a Cancel property that if set to true will prevent the transaction from occurring. This is useful if you are doing some data validation and your business requirements are not met, the transaction can be cancelled. Here is a sample BeforeTransaction handler that does some validation of Add and Change transactions:

public function OnBeforeTransaction(sender: Object, e: CancelTransactionEventArgs)
{
// only concerned with Add and Change
if (e.FunctionCode != "A" && e.FunctionCode != "C")
return;
if (!PassesValidation())
{
form.ShowMessage("Does not pass validation. Change not processed.");
e.Cancel = true;
}
}

If you are implementing a button Click handler, its signature looks like this:

public function OnButtonClick(sender: Object, e: RoutedEventArgs)

The sender is the button object and RoutedEventArgs has a property named Handled that often is set to true to indicate no further processing should occur for this event. One caution about setting e.Handled = true: a particular event can have multiple handlers attached to it and in some circumstances you may want the additional processing to occur. Again, for the non-form events, you will have to refer to MSDN for what type of eventargs object is required and what properties are available on the object. Two good rules of thumb for event handers: a) keep the amount of code to a minimum and exit as quickly as possible and b) do not do time consuming processing. More on both of these points in Part 2, specifically how to make asynchronous server calls and execute work on a background thread.

Cleanup in BeforeUnload

We’ve seen how easy it is to attach event handlers, but equally important to the process is to remember to detach or remove them. The reason for doing this is that if controls are left with event handlers attached, the .NET garbage collection process which frees up memory will not free the controls and memory consumption can quickly creep up the more the script is used. The script template implements the BeforeUnload event handler for you. The example below shows how we would add a method call to remove our BeforeTransaction handler.

public function OnBeforeUnload(sender: Object, e: FormEventArgs)
{
// perform cleanup
form.remove_BeforeTransaction(OnBeforeTransaction);
form.remove_BeforeUnload(OnBeforeUnload);
}

If you are adding custom controls to a form and attaching event handlers, it is not necessary to keep a global reference to those controls in your script so as to have them available for the BeforeUnload handler. Instead, you can ask the form for a reference to the control:

    form.GetCustomElement("MyButton").remove_Click(OnButtonClick);

Summary

Handling events provide the real power behind what you can do with scripts for S3 forms in LSO. In this article we have covered the basic steps in how to implement and cleanup event handlers. In Part 2, we will look at tips on how to use asynchronous and background processing to prevent the UI from being locked up during event handling.

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *



About this Blog

The latest on Infor Technology





Copyright Notice

© Copyright . Infor. Unauthorized use and/or duplication of this material without express and written permission from this blog’s author and/or owner is strictly prohibited. Excerpts and links may be used, provided that full and clear credit is given to Infor and blogs.infor.com/technology with appropriate and specific direction to the original content.