Cols.sortOrder()

note

This article is about the sortOrder() function of the Cols object.

Cols.sortOrder()

Sets or removes a sort definition for the columns in scope. A sort definition is a column or a list of columns by which data is sorted, as well as (in the case of a list of columns) the hierarchy of these sort columns, i.e., by which column the data is sorted first, second, and so on.

tip

To inspect the current sort order of a column instead of changing it, use .getOrder().

Returns a UdbPromise object with the Cols object as parameter.

Syntax

$.udb( *ds* ).cols( [columns] ).sortOrder( *options* | *order* | *sort-function* )
.then( ( *cols* ) => {
     // success
})
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

*options*   ::=  {
     [fn]:    *sort-function*,
     [order]: *order*,
     [reset]: *reset*
}

*order*  ::=  { 'ASC' | 'DESC' | 'TOGGLE' | '' }
*reset*  ::=  { true | [false] }

The required ds parameter is a data source selector.

The optional columns is a column selector. If omitted, all columns in scope are selected.

Options is a struct that can have the following items, all of which are optional. You can also pass sort-function or order directly as the argument to .sortOrder(), instead of as part of an options struct, as shown in Examples 2 and 3 below.

Sort-function is a function that overrides the default sorting functionality; the sorting will then be executed on the client. If set to null, the sorting function is removed.

Order is a string that specifies the sort order. Setting order explicitly to the empty string has a different meaning than not setting order at all:

Value	Description
'ASC'	Data is sorted with the lowest value first.
'DESC'	Data is sorted with the highest value first.
'TOGGLE'	The sort order on the column is toggled to the opposite 'ASC'/'DESC' value from the existing sort order. If no sort order exists, evaluates to 'ASC'.
'' (empty string)	The existing sort order is removed.

Reset is a boolean specifying whether this setting must replace the current sorting. The default is false.

Example 1

$.udb('EMP').cols('NAME').sortOrder({
   order: 'ASC',
   reset: true
}).then(() => {
    $.udb('EMP').executeQuery();
});

Example 2

In this example, sort-function is passed directly, instead of as part of an options struct:

$.udb('EMP').cols('NAME').sortOrder((r1, r2) => {
    return parseInt(r1.cols('DEPNO').val()) - parseInt(r2.cols('DEPNO').val());
}).then(() => {
    $.udb('EMP').executeQuery();
});

Example 3

In this example, order is passed directly, instead of as part of an options struct:

$.udb('EMP').cols('NAME').sortOrder('ASC').then(() => {
    $.udb('EMP').executeQuery();
});