Client-Side Programming

The use of client-side events can improve application performance because they do not require round trips to the server.

Interrupting default event handlers

In most cases, an event that is triggered in a PowerBuilder Web Forms application calls a default JavaScript event handler that posts back to the server and triggers the same event on the server side control. However, when you code a client-side event for a DataWindow control, the call to the default JavaScript event handler for that event is aborted and the round trip to the server can be avoided.

Note: JavaScript event handlers can enhance performance by allowing users to make modifications without a postback to the server.

To code for a client-side event at design time, you must enclose an event handler assignment in a conditional compilation code block in a PowerBuilder painter Script view. The start tag for the code block includes a symbol to indicate that the code inside the block is for a .NET Web Forms application. The event handler assignment is a hook into a JavaScript file that you also assign in a conditional compilation code block.

Although coding for a client-side event normally interrupts postbacks to the server, you can explicitly code for a postback in your customized JavaScript event handler by calling Document.Form.Submit or by calling a default event handler for the triggered event.

Example code for an event handling script

This example of a customized, client-side JavaScript event handler for the ItemChanged event of a DataWindow determines whether the item changed is in the first or second column of the DataWindow. If the item is in one of the first two columns, this event handler calls the default JavaScript event handler that rejects item changes. In this case, the default event handler does not cause a postback. If the item changed is not in the first or second column, no client-side action is taken, and the server-side action is delayed until a postback is triggered by a different event or function call:

//Start MyScriptFile.js
function MyItemChanged(sender, rowNumber, columnName, newValue)
{
  if(columnName == “column1” || columnName == “column2”)
  {
    // The default function is invoked
    return PBDataWindow_ItemChangedReject(sender,rowNumber, columnName, newValue)
  }
  else
  {
   //do nothing
  }
}
//End MyScriptFile.js

The hook into the customized JavaScript event handler is added at design time in a conditional compilation code block:

#IF DEFINED PBWEBFORM THEN
 dw_1.JavaScriptFile = “MyScriptFile.js”
 dw_1.OnClientItemChanged = “MyItemChanged”
#END IF

Default event handlers and postbacks

The default event handlers for the ItemChanged and ItemError events do not trigger postbacks. If active, the default ItemChanged event handler returns immediately to reject the entered value or causes the Web Forms application to wait for a cascade of user events to occur before a postback is allowed. The cascade of events that must occur before a postback is triggered is: ItemChanged, Clicked, RowFocusChanging, RowFocusChanged, and ItemFocusChanged.

Some versions of the default Clicked event handler set a timer for postbacks because the DHTML DoubleClicked event also triggers the Clicked event.

If a DataWindow object’s HTMLGen.PagingMethod property is set to XMLClientSide!, postbacks are not called until an Update is issued, since the data is stored in its entirety in the client browser cache. Also, if the corresponding server-side event does not contain any script, the default event handlers do not cause a postback or cause client-side Web Forms to be re-rendered.