Sorting rows

TreeGrid documentation

Rows in TreeGrid can be sorted by one or more columns. Up to three columns are supported by defaults.
Only variable body rows can be sorted.
The values can be sorted as numbers or as strings, see NumberSort.
Strings can be sorted case sensitive or insensitive. Can be also sorted according to actual browser language or by special settings. See comparing strings.

Sorting can be changed by a user by click to header, see also SortIcons.
Sorting can be preset by <Cfg Sort /> attributes. This attribute is saved to cookies.
Sorting can be changed by API method ChangeSort.
If rows in grid can be sorted.
If set to 0, a user cannot sort grid, also the sort icons in header are hidden.
If sorting is enabled by a user.
A user can enable / disable sorting by click to sort icon on toolbar (Button named Sort).
If a user can sort rows according to this column.
If set to 0, the column can be still set to Sort by API, but its sorting icon is not visible.
Specifies column that will be sorted when sorting action is called for this cell.
Useful for spanned header cells to sort another column than the main spanned cell.
Predefined or actual sorting.
Array of column names (comma separated), according to them are rows sorted, in this order.
By default are column sorted ascending, to sort by column descending, list its name with minus sign, e.g. Sort='Col1,-Col2,Col3' - the second column is sorted descending.
If the first column(s) in this array have set Visible=0 and CanHide=0, a user cannot change sorting for these columns and they will stay the first forever - use this case to predefine some sorting behavior.
A column according to that is grid sorted when no other sorting is set or as the last sort column to pre-set row positions to some default state.
This column can be hidden (Visible='0' CanHide='0'). When it is visible, only two columns (see MaxSort) for sorting are available, this default column is always as the third.
Since 13.0 It can be set to 1 or to not existing column name to create new hidden column (named "_DefaultSort" for 1) with actual rows positions to restore initial sort position. New rows are sorted on end, copied rows by their source rows.
Since 16.0 The default value is set to 1 and it shows on Toolbar DefSort button instead Sort (on/off) button.
To display on Toolbar Sort (on/off) button instead DefSort when set DefaultSort, set <Toolbar SortVisibleFormula="1" DefSortVisibleFormula="return 0"/>
Maximal count of columns according to grid can be sorted. The more columns the slower sorting.
Different icons are only for first three sorting columns, next columns have the same icon as the third column.
If set SortIconsNumbers, there are defined 9 different sort icons and MaxSort should not be higher than 9.
In this count are not included invisible columns (Visible=0 and CanHide=0).
How a user can set sorting and icons are displayed in all headers
0 - hides icons and sorts ascent by click to cell, descent by double click,
1 - shows icons and sorts ascent by click to cell, descent by double click,
2 - sorts by click to icon only, bottom icon ascent, upper icon descent,
3 - sorts by click to cell, bottom part ascent, upper part descent,
To change direction meaning set ReversedSortIcons attribute.
If and which sort icons will be shown on the header.
If set to 1, the sort icons for ascending and descending sorting are swapped.
If set to 1, it displays sort icons with number 1 - 9 for sort position instead of different colors.
In this case MaxSort should not be set higher than 9.
It is only for responsive CSS styles, it is ignored if used compatible CSS style.
If set to1, row is automatically sorted (moved) after value is changed by user's edit.
Row can be moved only inside its page.
This attribute is filled in Request XML as request for re-sorting grid after sorting has been permitted by user.

Controlling sort position

If row's immediate children can be sorted (to suppress sorting for root rows, you can set this parameter in <Root> tag).
If set, suppresses sorting of this row and places it always to specified position independently on sorting state.
Positive number places the row from beginning, negative number places the row from end.
Therefore rows with SortPos will be placed in this way: 1,2,3, ... ,all sorted rows without SortPos, ... , -3, -2, -1
If more rows have the same SortPos, they will be sorted inside the group only.
Set it to 0 to always sort root rows or row's children according to the column values as strings.
Set it to 1 to always sort root rows or row's children according to the column values as numbers.
If not set, the number sort is chosen for columns of types Int, Float and Date and for all the others is used string sort.
Set it to 1 for Bool type if you want to distinguish between 0 and "", when CanEmpty is set to support three states Bool.
(new 15.0) Set it to 2 to choose the number sort according to child values - uses number sort if all child values contain number or are empty. Can slow down sorting.
By default for 0 it sorts values formatted according to its Type and Format.
Set it to 1 to sort directly by the unformatted cell value. For Enum with and set by EnumKeys it sorts by the key name.
Set it to 2 for Enum type to sort it by position in Enum / EnumKeys array. It is slower than setting Enum values by index and sorting them as numbers (with NumberSort='1'). Value used for compare when sorting and grouping instead of cell value.
Useful for special non editable cells like Html, Icon, List.
Value used for compare when done descending sorting instead of cell value.
Useful to set if you want to preserve row position when sorting by the column.
Called to get value for sorting and grouping, val is predefined value, returns val or new value.
desc is true for descending sorting, group is true when called while grouping.

Comparing strings

You can also specify these settings for whole grid in default column <Def><D Name='C'/></Def>.
If strings are compared according to browser's locale settings. For sorting, filtering and grouping.
It is done only for first 1920 Unicode characters.
For higher Unicode characters like Chinese, Korean or Japanese you must define CharCodes instead.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.
If strings are compared case sensitive. For sorting, filtering and grouping.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.
List of characters to ignore when sorting, filtering or grouping.
It can be set for example to " " (space) to ignore spaces (it means that for example "a b c" and "abc" strings are the same.
Setting this attribute can slow down sorting, grouping and filtering.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.
It changes characters in comparing strings for sorting, filtering and grouping.
It is first character separated array of pair of characters to replace the first character by the second when comparing strings.
For example "|y|i|Y|I|.|," - replaces 'y' by 'i', 'Y' by 'I' and '.' by ','
The first character must be one letter, but the second in fact can be any letter or string or even empty string, like "|a|xxx|b||c|ff"
If you use TreeGrid server DLL/SO, there must be the second character one letter only too.
Setting this attribute can slow down sorting, grouping and filtering.
If set to row cell, it affects row's children for sorting and grouping. For filter it can be set only to Filter cell and affects also all values in the column.

Sorting actions

By default TreeGrid sorts according to the last clicked column as the first, the default settings are:

To reverse the sorting order to have the first clicked column as the first sorting column set
When there are more than two seconds between clicks, the sorting is cleared and starts with clicked column

To have the same sorting behavior as MS Outlook or Excel, set
On click sorts only by one column, on shift click adds the column to the end of sorting
Sorts according to actual or focused column ascending - adds the column as the first to sorting.
Returns false if the column is already the first column and is sorted ascending otherwise sorts it ascending.
Sorts according to actual or focused column descending - adds the column as the first to sorting.
Returns false if the column is already the first column and is sorted descending otherwise sorts it descending.
Sorts according to actual or focused column only.
Returns false if the column is already the first column and is sorted ascending otherwise sorts it ascending.
Sorts according to actual or focused column only.
Returns false if the column is already the first column and is sorted descending otherwise sorts it descending.
Adds the actual or focused column to sorting to the end and sorts it ascending.
If the column is already sorted, returns false if it is sorted ascending otherwise sorts it ascending, but does not change its position in sorting.
If there are already three columns sorted, it returns false.
When between clicks are more than two seconds or a user clicks also outside header, it clears sorting and starts from first column again.
Adds the actual or focused column to sorting to the end and sorts it descending, see the SortAscAdd.
Adds the actual or focused column to sorting to the end and sorts it ascending.
If the column is already sorted, returns false if it is sorted ascending otherwise sorts it ascending, but does not change its position in sorting.
If there are already three columns sorted, it returns false.
The same as SortAscAdd, but without the two second limit.
Adds the actual or focused column to sorting to the end and sorts it descending, see the SortAscAppend.
The same as SortDescAdd, but without the two second limit.
Removes the actual or focused column from sorting and re-sorts grid.
Restores the sorting settings set in input XML data.
If neither Sort nor DefaultSort attribute was set in input XML, it does not do anything.
Enables sorting in grid and re-sorts grid. It fails if sorting is already enabled.
Disables sorting in grid. It fails if sorting is already disabled.

Sorting API

Called when user clicks to header for sort, before grid is sorted by the column.
Return -1 to suppress the action completely.
Return 1 to suppress sorting, provide your own sorting and let change sort icon.
col is clicked column that will be added to sorting, can be null if it was called from control panel (from SortOn action).
sort is the resulted Sort after the col will be added to the actual (added in 6.1).
Here you can call ChangeSort to modify sorting (in this case you have to return -1).

For example this code always sorts according to column named 'B' as second column:
Grids.OnSort = function (G,col){ if(col!='B') { G.ChangeSort((G.Sort.indexOf(col)==0?"-":"")+col+",B"); return -1; } }
Called after grid was re-sorted, all changes are already displayed.
Called only for sorting on client, not for server paging.
Sorts grid according to given columns. sortcols is new value for Sort.
If it is called from OnSort event, the event handler must return -1 for proper sort.
Simulates click to sort icon in the given column.
desc can be 0 for ascending and 1 for descending sorting.
Sorts (and moves) one row by actual sort settings.
If col is set, test only this sorting column for changes.
It is ignored when AutoSort is 0.
Sorts all rows, according to sort settings and paging type, asynchronous.
Shows all changes.