Rows.select()

note

This article is about the select() function of the Rows object.

Rows.select()

Changes the selection state of one or more of the rows in scope.

tip

This selects a record, not the row set itself. To make a row set the active one, use Rowset.select() instead.

Returns a UdbPromise object.

The object passed along to the next .then() clause depends on whether or not the 'multiple' argument is used. If not, the UdbRows object is passed as a parameter.

If the 'multiple' argument is used, but without a value argument (the first syntax option shown below), the multiple selection value of the first row is returned instead. This value indicates whether the row is in the set of rows currently selected. If this is the case, the row is not necessarily the current row.

Syntax

$.udb( *ds* ).rows( [rowRef1], [rowRef2] ).select( 'multiple' )
$.udb( *ds* ).rows( [rowRef1], [rowRef2] ).select( 'multiple', *value* )
$.udb( *ds* ).rows( [rowRef1], [rowRef2] ).select( [options] )
.then( ( *rows* ) => {
     // success
})
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

*value*                  ::=  { *use-multiple-select* | *modify-multiple-select* }
*use-multiple-select*    ::=  { true | false }
*modify-multiple-select* ::=  { 'extend' | 'replace' | 'toggle' }

*options*  ::=  {
   [always]:       *always*,
   [lookupSelect]: *lookup-select*
}

*always*        ::= { true | [false] }
*lookup-select* ::= { [true] | false }

The required ds parameter is a data source selector.

The optional rowRef1, rowRef2 are row selectors. If omitted, all records in scope are addressed.

• If you pass the 'multiple' literal without a value, the selection state of the current row is queried.
• If you pass the 'multiple' literal with a value, the selection state of all the rows in scope is changed to value.
• If you pass options (or omit the argument entirely), the first record in scope is made the current record, thereby potentially changing the selection state of other rows in the row set.

The optional value can be passed as a boolean or a string:

Value	Description
true	Sets the selection state of all records in scope.
false	Unsets the selection state of all records in scope.
'extend'	Sets the selection state of all records in scope.
'replace'	Unsets the selection state of all records in scope.
'toggle'	Toggles the selection state of all records in scope.

Options is a struct that can have the following items, all of which are optional.

Always forces the selection to be (re)applied even if the record is already the current one. The default is false.

Lookup-select determines whether the lookup data sources of the newly selected record are synchronized. The default is true.

tip

Before the select operation is performed, the rowpreselect event is triggered. If the event handler sets the success member of the result object parameter to false, then the action is aborted and the current row will not change. Otherwise, the action is performed, after which the rowpostselect event is triggered as a final step.

Examples

This example changes the selection state of the current row:

$.udb('EMP').rows().select('multiple');

This example unsets the selection state of all selected rows:

$.udb('EMP').rows('selected').select('multiple', false);

This example sets the selection state of all rows in scope:

$.udb('EMP').rows([5, 6, 8, 10, 12]).select('multiple', 'extend');

Each of these examples selects the first record in the row set, thereby potentially changing the selection state of rows in the set:

$.udb('EMP').rows().select();
$.udb('EMP').rows(0).select();

Related events

Event	Applies to	Occurs when
fetchdata	Lookup data source objects	Before the framework fetches lookup values for a column, for a row set that does not yet exist locally
rowpostselect	Data source objects	After a record is selected
rowpreselect	Data source objects	Before a record is selected
rowselect	Data source objects	A new record is selected in a multi-record control for the data source
rowselect	Page objects (triggered globally)	A new record is selected in a multi-record control for any of the data sources in the page

note

fetchdata only occurs when the newly selected record has lookup data sources whose row set does not yet exist locally, and it is skipped when lookupSelect: false is passed. rowselect is skipped when the selection change is a side effect of a record delete (options.source === 'deleteRecord').