A boolean on a JSDO and its table references that indicates if record objects are sorted automatically on the affected table references in JSDO memory at the completion of a supported JSDO operation.
When set to true, and after you have specified a sorting method for each affected table reference, record objects are sorted after the JSDO operation completes its update of JSDO memory. When set to false, or if no sorting method is specified for a given table reference, no automatic sorting occurs after the JSDO operation completes. The default setting is true for all table references of a JSDO.
When set on a JSDO, the property setting affects the sorting of record objects for all table references in the JSDO. When set on a single table reference, the property setting affects the sorting of record objects only for the specified table reference. For example, to set this property to true on only a single table reference in the JSDO:
1. Set the value on the JSDO to false, which sets false on all its table references.
2. Set the value on the selected table reference to true, which sets true on only the this one table reference.
In order to activate automatic sorting for an affected table reference, you must invoke one of the following JSDO methods to specify a sorting method for the table reference:
setSortFields( ) — Identifies the sort fields to use in the record objects and whether each field is sorted in ascending or descending order according to its data type. Any string fields specified for a table reference are sorted using letter case according to the setting of the caseSensitive property (false by default).
Note: Changing the value of the caseSensitive property triggers an automatic sort if the autoSort property is also set to true for the affected table reference.
setSortFn( ) — Identifies a sort function that compares two record objects according to the criteria you specify and returns a value that indicates if one record sorts later than the other in the sort order, or if the two records sort at the same position in the sort order. The caseSensitive property setting has no effect on the operation of the specified sort function unless you choose to involve the setting of this property in your criteria for comparison.
If you specify both sort fields and a sort function to sort the record objects for a table reference, the sort function takes precedence. You can also call the setSortFields( ) and setSortFn( ) functions to clear one or both settings of the sort fields and sort function. However, at least one setting must be active for automatic sorting to occur on a table reference.
The following supported JSDO operations trigger automatic sorting on any affected table references before they complete their updates to JSDO memory:
Invoking the add( ) method — Sorts the record objects of the affected table reference.
Invoking the addRecords( ) method — Sorts the record objects of either the single affected table reference or all affected table references in the JSDO. (Unaffected table references do not participate in the sort, including those for which autoSort is false, those for which no sort fields or sort function are set, or those other than the single JSDO table reference on which addRecords( ) is called, if it is called only on a single table reference.)
Invoking the addLocalRecords( ) method — Sorts the record objects of all affected table references in the JSDO. (Unaffected table references do not participate in the sort, including those for which autoSort is false and those for which no sort fields or sort function are set.)
Invoking the assign( ) method (JSDO or UIHelper class) — Sorts the record objects of the affected table reference.
Assigning a value to a field reference directly on the working record of a table reference ( jsdo-ref.table-ref.field-ref = value ) — Sorts the record objects of the affected table reference.
Note: Assignment to a field referenced on the data property never triggers automatic sorting (for example, jsdo-ref.table-ref.data.field-ref = value)
Changing the value of the caseSensitive property — Sorts the record objects of the affected table reference, or of all affected table references if the property value is changed on the JSDO.
Invoking either the acceptChanges( ) or rejectChanges( ) method — Sorts the record objects of all affected table references in the JSDO. (Unaffected table references do not participate in the sort, including any table references for which autoSort is false, or for which no sort fields or sort function are set.)
Invoking either the acceptRowChanges( ) or rejectRowChanges( ) method — Sorts the record objects of the affected table reference.
Invoking the fill( ) method — Sorts the record objects of all affected table references in the JSDO. (Unaffected table references do not participate in the sort, including any table references for which autoSort is false, or for which no sort fields or sort function are set.)
Note: Invoking the remove( ) method does not trigger an automatic sort and has no effect on any existing sort order established for the table reference. However, if there is a sort order that depends on the presence or absence of the record object you are removing, and you want to establish the appropriate sort order when this record object is absent, you must manually sort the remaining record objects using the sort( ) method by passing it the same sort function that you used to establish the sort order when this record object was present.
Caution: Because automatic sorting 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 any action that can sort a large record set to alert the user that the app is working.
Example
In the following code fragment, automatic local sorting is turned off for all table references of the dsCustOrds JSDO by setting its autoSort property to false. Automatic sorting is then turned on for the eCustomer table reference of the JSDO by setting its autoSort value to true and using the setSortFields( ) method to set its Name field as the single, descending sort field:
When the fill( ) method executes on the JSDO, all the referenced tables are loaded from the AppServer into JSDO memory with their record objects already sorted in case-insensitive, primary key order (by default). The record objects for eCustomer are then sorted locally in case-insensitive, descending order of the Name field.
setSortFields( ) — Identifies the sort fields to use in the record objects and whether each field is sorted in ascending or descending order according to its data type. Any string fields specified for a table reference are sorted using letter case according to the setting of the caseSensitive property (false by default).