EJS TreeGrid documentation
Sorting rows
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.
<Cfg> bool Sorting [1] .
If rows in grid can be sorted.
If set to 0, a user cannot sort grid, also the sort icons in header are hidden.
<Cfg> bool Sorted [1] Saved to cookies, to not load it, set SortedLap=’1’ .
If sorting is enabled by a user.
A user can enable / disable sorting by click to sort icon on toolbar (Button named Sort).
<C> bool CanSort [1] .
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.
<Cfg> string [] Sort [“”] Saved to cookies, to not load it, set SortLap=’1’ chg 6.0.
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.
<Cfg> string DefaultSort renamed 6.0.
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.
<Cfg> int MaxSort [3] renamed 6.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.
In this count are not included invisible columns (Visible=0 and CanHide=0).
<Cfg> int SortIcons [1] Saved to cookies, to not load it, set SortIconsLap=’1’ .
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.
<Header> int SortIcons [1] new 6.4.
If and which sort icons will be shown on the header.
0 the sort icons are hidden and the caption is inactive, columns cannot be sorted by clicking
1 all sorting icons are shown and captions are active
2 shows only icons for sorted columns, but all captions are active
<Cfg> bool ReversedSortIcons .
If set to 1, the sort icons for ascending and descending sorting are swapped
<Cfg> bool AutoSort Saved to cookies, to not load it, set AutoSortLap=’1’ .
If set to1, row is automatically sorted (moved) after value is changed by user’s edit.
Row can be moved only inside its page.
<Cfg> bool ReSort Server paging, output attribute only .
This attribute is filled in Request XML as request for re-sorting grid after sorting has been permitted by user.
<I> <Root> bool CanSort [1] .
If row’s immediate children can be sorted (to suppress sorting for root rows, you can set this parameter in <Root> tag).
<I> int SortPos .
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.
<C> <cell> bool NumberSort [null] new 6.0.
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.
<C> <cell> int RawSort [0] new 7.0.
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’).
<cell> string SortValue upd 6.0.
Value used for compare when sorting and grouping instead of cell value.
Useful for special non editable cells like Html, Icon, List.
<cell> string SortDescValue upd 6.0.
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.
API event string OnGetSortValue (TGrid grid, TRow row, string col, type val, bool desc, bool group) .
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
You can also specify these settings for whole grid in default column <Def><D Name=’C’/></Def>.
<C> <cell> bool LocaleCompare [0] new 6.0.
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.
<C> <cell> bool CaseSensitive [1] new 6.0.
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.
<C> <cell> string WhiteChars chg 6.0.
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.
<C> <cell> string[*] CharCodes upd 6.0.
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 ‘,’
– it means that when comparing strings does not differ between letter ‘y’ and ‘i’, both cases and also does not differ between comma and point.
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.
By default TreeGrid sorts according to the last clicked column as the first, the default settings are:
<Actions OnClickSort="SortAsc OR SortDesc" OnClickSortUp="SortAsc" OnClickSortDown="SortDesc"/>
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
<Actions OnClickSort="SortAscAdd OR SortDescAdd" OnClickSortUp="SortAscAdd" OnClickSortDown="SortDescAdd"/>
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
<Actions OnClickSort="SortAscOne OR SortDescOne" OnClickSortUp="SortAscOne" OnClickSortDown="SortDescOne"/>
<Actions OnShiftClickSort="SortAscAppend OR SortDescAppend" OnShiftClickSortUp="SortAscAppend" OnShiftClickSortDown="SortDescAppend"/>
<Actions> SortAsc ...F Attached to events OnClickSort and OnClickSortUp .
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
<Actions> SortDesc ...F Attached to events OnClickSort and OnClickSortDown .
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
<Actions> SortAscOne ...F Not attached to any event new 6.1.
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.
<Actions> SortDescOne ...F Not attached to any event new 6.1.
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.
<Actions> SortAscAdd ...F Attached to events OnCtrlClickSort, OnCtrlClickSortUp .
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.
<Actions> SortDescAdd ...F Attached to events OnCtrlClickSort, OnCtrlClickSortDown .
Adds the actual or focused column to sorting to the end and sorts it descending, see the SortAscAdd.
<Actions> SortAscAppend ...F Not attached to any event new 6.1.
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.
<Actions> SortDescAppend ...F Not attached to any event new 6.1.
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.
<Actions> NoSort ...F Not attached to any event .
Removes the actual or focused column from sorting and re-sorts grid
<Actions> DefaultSort Not attached to any event .
Restores the sorting settings set in input XML data.
If no Sort attribute was set in input XML, it does not do anything.
<Actions> SortOn Attached to event OnClickButtonSort .
Enables sorting in grid and re-sorts grid. It fails if sorting is already enabled.
<Actions> SortOff Attached to event OnClickButtonSort .
Disables sorting in grid. It fails if sorting is already disabled.
API event int OnSort (TGrid grid, string col, string sort) upd 6.1.
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; } }
API event void OnSortFinish (TGrid grid) .
Called after grid was re-sorted, all changes are already displayed.
Called only for sorting on client, not for server paging.
API method void ChangeSort (string sortcols) chg 6.0.
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.
API method void SortClick (string col, bool desc = null) .
Simulates click to sort icon in the given column.
desc can be 0 for ascending and 1 for descending sorting.
API method void SortRow (TRow row, string col = null, bool show = false) .
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.
API method void SortRows ( ) .
Sorts all rows, according to sort settings and paging type, asynchronous.
Shows all changes.