rowpreselect

note

This article is about the rowpreselect UDB event handler.

rowpreselect

The rowpreselect event may be called from web pages developed in Web Designer and processed by a USoft page engine service.

Event	Applies to	Occurs when
rowpreselect	Data source objects (UdbDataSource)	Before a record is selected

This event is triggered by the UdbRowSet class, from its select() method. It is skipped in two cases: when the target row is already the current row (unless the always option is set), and when the selection change is a side effect of a record delete (i.e. options.source === 'deleteRecord').

Purpose

You can use this event restrictively to keep the user from moving on to a different record if some precondition is not satisfied.

How to use

Find or create an Event Listener object with Event Type = rowpreselect. Event Listeners are in the Web Designer Controls catalog:

Insert the event listener into the data source object. Insert a callClientScript action into the event listener. Use this action's Script property to code the behaviour that you want to see when the event occurs. For example, for restrictive action, a typical pattern is to specify the condition under which you want the selection change to be prevented, block processing, and give an error message in an alert box. This pattern looks like this:

if ( *condition-not-satisfied* ) {
  options.success = false;
  alert( *message* );
}

You are implicitly associating the event with an event handler function. This function has an options parameter. For available options, see the Options section at the end of this help topic:

function(*event*, *options*){ ... }

Or you can create the event handler more explicitly by calling $.udb('data-source').on().

Example

if ( this.rows('current').cols('AGE').val() < 18 ) {
  options.success = false;
  alert( 'Cannot leave this record before supplying a valid age.' );
}

Options

When the event occurs, the following event handler function is called. You can use this function's options parameter in your event scripting.

function( *event*, *options* )

*event*     ::=  jQuery.Event
*options*   ::=  *event-options*

*event-options*   ::=  {
     success:  *success*,
     options:  *caller-options*
}

*success*  ::=  { [true] | false }

Event contains the run-time details of the triggered event, of the event type stated above.

This syntax means that you can access the success option by scripting: options.success. If you set success to false, processing is interrupted. As a result, the row selection will not take place.

caller-options is the options object passed to the row-selection call (Rows.select()); it can include always (force the event and selection to run even if the row is already current), pKeys (identifies the rowset the selection takes place in), and multiple (indicates whether the selection is a multi-row selection).