rowquery

note

This article is about the rowquery UDB event handler.

rowquery

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

Event	Applies to	Occurs when
rowquery	Data source objects (UdbDataSource)	Before row selection moves to a different row, but only when the navigation call passes a query source option

This event is triggered by the UdbRowSet class, from its setCurrentRow() method — but only when the caller passes a query option (as e.g. a next/previous/goto navigation action does). It does not fire on every row-selection change; for an event that fires unconditionally before a new row is selected, see rowpreselect.

Purpose

You can use this event to prevent the user from moving on to a different row, perhaps because a specific value must be supplied or changed in the currently selected row. Unlike most other *pre* events, rowquery has no success flag: to keep the current row selected, you instead reset options.rowIdNew back to options.rowIdOld inside the handler.

How to use

Find or create an Event Listener object with Event Type = rowquery. 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 row navigation to be prevented, override the target row, and give an error message in an alert box. This pattern looks like this:

if ( *condition-not-satisfied* ) {
  options.rowIdNew = options.rowIdOld;
  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.rowIdNew = options.rowIdOld;
  alert( 'Please supply a valid age before moving to another row.' );
}

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*   ::=  {
     source:    *source*,
     rowIdOld:  *rowIdOld*,
     rowIdNew:  *rowIdNew*
}

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

This syntax means that you can access an option by scripting

options.*option*

Source is the value of the query option passed to the navigation call that triggered this event (e.g. 'next', 'previous').

rowIdOld is the row ID of the row that is currently selected.

rowIdNew is the row ID of the row that selection is about to move to. You can override this value in your handler: the row that ends up being selected is re-derived from your (possibly modified) rowIdNew. To keep the current row selected, set options.rowIdNew = options.rowIdOld;