$.udb(ds).sortOrder()

note

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

$.udb(ds).sortOrder()

Sets or removes a sort definition. 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, third, and so on.

Returns a UdbPromise object with the UdbDsc object as parameter.

Syntax

$.udb( *ds* ).sortOrder( *options* )
.then( ( *dsc* ) => {
     // success
})
.catch(() => {
     // failure
})
.finally(() => {
     // executed after success / failure is handled
});

*options*  ::=  {
     [order]:      *order*,
     [resetOrder]: *reset-order*,
     [resetFn]:    *remove-fn*
}

*reset-order*  ::=  { 'none' | 'clear' | ['default'] }
*remove-fn*    ::= { true | [false] }

*order*        ::= Array[*sort-order*]
*sort-order*   ::= *column* | *order-object*

*order-object* ::= { col: *column*, order: *order-value*, fn: *sort-function* }
*order-value*  ::= 'TOGGLE' | 'ASC' | 'DESC'

The required ds is a data source selector.

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

Order is an array of sort-order objects that specify the sort definition. If the value 'TOGGLE' is used for order-value, then the existing sort order is 'flipped' from 'ascending' ('ASC') to 'descending' ('DESC') or vice versa. If a sort-function is specified, then the order-value for this column is ignored, and the column is sorted solely by the definition of the specified sorting function.

Reset-order is a string that specifies what should happen with the existing sort definition:

Value	Description
'none' (the default)	New sort columns are added in front of existing sort columns.
'clear'	The existing sort definition is removed.
'default'	The existing sort definition is replaced by the sort definition that was specified by setting the Sort Order property for the data object in Web Designer.

Remove-fn is a boolean that determines whether user-defined sorting functions must be removed. The default is false.

Examples

If the existing sort order was by NAME, the result of each of the following examples is that data is sorted first by DEPT_NO and then by NAME:

$.udb('EMP').sortOrder({
   order: 'DEPT_NO',
   resetOrder: 'none'
});

$.udb('EMP').sortOrder({
   order: ['EMP_NO', 'NAME'],
   resetOrder: 'clear'
});