rowselect

note

This article is about the rowselect UDB event handler.

rowselect

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

Event	Applies to	Occurs when
rowselect	Data source objects (UdbDataSource)	A new record is selected in a multi-record control for the data source.
rowselect	Page objects (triggered globally on UdbApplication)	A new record is selected in a multi-record control for any of the data sources in the page.

This event is triggered by the UdbRowSet class, from its select() method: once on the affected data source, and (unless the selection is a side effect of a record delete) once more, globally, on UdbApplication. It is also triggered when a new record is created (from UdbRowSet.rowCreate()) and when a lookup control's current row is synchronized with its underlying data source.

This event occurs when a new row is selected in the data source in a multi-record UI control such as a GridControl, a TabularGridControl, or a ReplicatedColumnsControl. Such new row selection may be executed programmatically by calling Rows.select().

How to use

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

Insert the event listener into the multi-record UI control (for the data-source-scoped variant) or into the Page object (for the page-wide variant). 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.

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*,
     pKeys:    *pKeys*,
     multiple: *multiple*,
     rowIds:   *rowIds*,
     options:  *caller-options*,
     dsRef:    *dsRef*
}

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 a string indicating what caused the selection change, e.g. 'select'.

pKeys identifies the rowset the selection took place in.

Multiple, rowIds and caller-options are only present when the selection results from a multi-row selection change; rowIds then lists the row IDs whose selection state changed.

dsRef is only present on the page-wide (UdbApplication) variant, and identifies the id of the data source the selection occurred on.

Not all of the above options are present on every occurrence of this event; which ones are present depends on how the selection change was triggered.