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:
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.
Caution: Because the sort( ) method executes in JavaScript on the client side, sorting a large set of record objects can take a significant amount of time and make the UI appear to be locked. You might set a wait or progress indicator just prior to invoking the sort to alert the user that the app is working.
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:
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:
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:
ASC — Sorts ascending.