sort( ) method

Sorts the existing record objects for a table reference in JSDO memory using either specified sort fields or a specified user-defined sort function.

Return type: null

Applies to: progress.data.JSDO class, table reference property (JSDO class)

Syntax

jsdo-ref.sort ( { sort-fields | funcRef } )
jsdo-ref.table-ref.sort ( { sort-fields | funcRef } )

jsdo-ref

A reference to the JSDO. You can call the method on jsdo-ref if the JSDO has only a single table reference.

table-ref

A table reference on the JSDO.

sort-fields

An array of string values set to the names of record fields on which to sort the record objects, with an optional indication of the sort order for each field. This array can have the following syntax:

Syntax:

[ "field-name[:sort-order]" [ , "field-name[:sort-order]" ] ... ]

field-name

The name of a field in the record objects of the specified table reference. Any field-name must already exist in the JSDO schema and must have a scalar value (cannot be an array field).

sort-order

An indication of the sort order for the field, which can have one of the following case-insensitive values:

• ASC — Sorts ascending.
• ASCENDING — Sorts ascending.
• DESC — Sorts descending.
• DESCENDING — Sorts descending.

The default sort order is ascending.

When the sort occurs, the record objects are sorted and grouped by each successive field-name in the array, according to its JavaScript data type and specified sort-order. Fields are compared using the >, <, and = JavaScript operators. All string fields can be compared with or without case sensitivity depending on the caseSensitive property setting. However, note that date fields are compared as dates, even though they are represented as strings in JavaScript.

funcRef

A reference to a JavaScript sort function that compares two record objects for the sort and returns a number value. This function must have following signature:

Syntax:

function [ func-name ] ( jsrecord-ref1 , jsrecord-ref2 )

Where func-name is the name of a function that you define external to the sort( ) method parameter list, and jsrecord-ref1 and jsrecord-ref2 are two JSRecord objects that the function compares from the specified table reference. You can then pass func-name to the sort( ) method as the funcRef parameter. Alternatively, you can specify funcRef as the entire inline function definition without func-name.

Your funcRef code determines the criteria by which one of the two input record objects follows the other in the sort order, and returns one of the following values depending on the result:

• 1 — The jsrecord-ref1 object follows (is "greater than") the jsrecord-ref2 object in the sort order.
• -1 — The jsrecord-ref1 object precedes (is "less than") the jsrecord-ref2 object in the sort order.
• 0 — The two record objects occupy the same position (are "equal") in the sort order.

When you invoke the sort( ) method with a sort function, the sort uses this function to determine the sort order for every pair of records that it tests as it iterates through the record objects of the specified table reference.

Note: Any default JavaScript comparisons that you make with string fields in funcRef are case sensitive according to JavaScript rules and ignore the setting of the caseSensitive property.

Examples

In the following code fragment, the fill( ) method initializes JSDO memory with eCustomer record objects from the server in order of the table primary key (the default). The sort( ) method later sorts the record objects for eCustomer by the Country field ascending, then by the State field within Country ascending, then by the Balance field within State descending. The foreach( ) function then loops through these record objects in the new eCustomer sort order:

dsCustomer = new progress.data.JSDO( { name: 'dsCustomer' });
dsCustomer.fill();
. . .
dsCustomer.sort( [ "Country", "State", "Balance:DESC" ] );
dsCustomer.eCustomer.foreach( function( customer ){ . . . } );

In the following code fragment, the fill( ) method initializes JSDO memory with eCustomer record objects from the server in order of the table primary key (the default). The sort( ) method later sorts the record objects for eCustomer using the results of an inline function definition, which in this case compares the case-sensitive values of the Name fields from each pair of eCustomer record objects selected by the sort. The foreach( ) method then loops through these record objects in the new eCustomer sort order:

dsCustomer = new progress.data.JSDO( { name: 'dsCustomer' });
dsCustomer.fill();
. . .
dsCustomer.sort( function( rec1 , rec2 ) { 
  if (rec1.data.Name > rec2.data.Name) 
    return 1; 
  else if (rec1.data.Name < rec2.data.Name) 
    return -1; 
  else
    return 0;
  } );
dsCustomer.eCustomer.foreach( function( customer ){ . . . } );

If you want to compare the Name fields using a case-insensitive test, you can use the JavaScript toUpperCase( ) function in the inline function definition, as follows:

dsCustomer = new progress.data.JSDO( { name: 'dsCustomer' });
dsCustomer.fill();
. . .
dsCustomer.sort( function( rec1 , rec2 ) { 
  if (rec1.data.Name.toUpperCase() > rec2.data.Name.toUpperCase()) 
    return 1; 
  else if (rec1.data.Name.toUpperCase() < rec2.data.Name.toUpperCase()) 
    return -1; 
  else
    return 0;
  } );
dsCustomer.eCustomer.foreach( function( customer ){ . . . } );

See also:

autoSort property, caseSensitive property, setSortFields( ) method, setSortFn( ) method