1. Sorting rows

Sorting rows according to one ore more columns

• TreeGrid supports sorting rows by one or more columns ascending or descending.

• Sort definition

  
  The predefined sort is set by Cfg attribute

  Sort

  as comma separated list of column names.
  If the column is sorted descending, it is listed with minus prefix, like "-col1".
  There can be set also default column to sort by when there is no predefined sorting or more rows have the same values in all sorting column, it is set Cfg attribute DefaultsSort. It cannot be changed by users.
  

• Sort permitions

  
  
  • Cfg attribute

    Sorting

    ='0' disables sorting in grid by users. It can be still changed by API.
    
  • Cfg attribute

    Sorted

    ='0' temporary disables sorting in grid, but permits users to change the sort columns without resorting the grid.
    The Sorted value can be changed by actions SortOff and SortOn.
  • Column can have set its attribute

    CanSort

    ='0' to not let users to sort by this column. It is still possible to do it by API.
    
  • Row can have set its attribute

    CanSort

    ='0' to not sort its children.
    To not sort the root rows set this attribute to Root tag.
    It affects every sorting, including API.

• Sort options

  
  
  • Row can be fixed on beginning or end of its parent or root by its

    SortPos

    attribute. Set it to positive value to fix the row on beginning and negative value to fix it to the end.
    There can be more fixed rows on both sides, they are sorted according to their SortPos value.
  • For numbers there are two basic sorting types, number and string sort. The number sort is used by default for column types Int, Float and Date.
    You can explicitly choose the number or string sort by column or parent cell attribute

    NumberSort

    .
  • By default are strings sorted formatted according to its Type and Format. To sort them by the direct cell value set column or parent cell attribute

    RawSort

    ='1'. It will speed up the sorting.
  • Enum values are sorted by default by the visible string.
    To sort them by key value (EnumKeys) set column or parent cell attribute RawSort='1'.
    To sort them by position inside the Enum/EnumKeys set RawSort='2'.
    To sort them by index set NumberSort='1'. The Enum values must be set by the index in this case.
    
  • Column / parent cell attribute

    CaseSensitive

    to compare the strings case sensitive. By default is on.
  • Column / parent cell attribute

    LocalCompare

    to compare the strings according to browser's locale settings. By default is off.
    It is done only for first 1920 Unicode characters. For higher Unicode characters like Chinese, Korean or Japanese you must define CharCodes instead.
  • Column / parent cell attribute

    WhiteChars

    as list of characters to ignored when comparing. The strings are compared after these values are removed from them.
  • Column / parent cell attribute

    CharCodes

    as list of character pairs to replace the first character by the second one in all strings before comparing them. Useful for example to compare strings without punctuation in many languages.

• Cell value for sorting

  
  Every cell can have set special value by

  SortValue

  to use it for sorting instead of the cell value.
  It can have also different value for descending sorting set by SortDescValue, useful to preserve row position when sorting by the column.
  The value can be also dynamically created by JavaScript in API event OnGetSortValue.
  

• Change sort behavior

  
  To change sorting behavior use

  OnGetSortValue

  API event, here you can return the value to sort by according to your conditions.
  For example to sort selected rows always on top define:
  Grids.OnGetSortValue = function(G,row,col,val,desc,group){ return (row.Selected ? desc : !desc) ? "1_"+val:"0_"+val; }

• User interface (<Header>)

  
  Users can change sort settings by clicking to <Header> cell. There can be more headers in grid, the sorting can be individually permitted for them.
  
  • The header shows sorting icons according to the actual sorting state. The icons can be changed for all columns (if set Header attribute SortIcons='1') or only for active sorting columns (SortIcons='2').
    
  • The header can have disabled sorting actions and icons by its SortIcons='0'.
    
  • All the sorting icons can be reversed (up / down) by Cfg attribute ReversedIcons='1'.
    
  • There are four possible behaviors for clicking to header cell and sorting icons controlled by Cfg attribute

    SortIcons

    .
    0 - Simple, no icon - Icons are not visible, first click to header sorts ascending, next descending.
    1 - Simple - Icons are visible, first click to header sorts ascending, next descending.
    2 - Directional, icons only - Only icons can be clicked, top half to sort ascending, bottom half descending.
    3 - Directional - The whole header can be clicked, top half to sort ascending, bottom half descending.
    

• Sorting actions

  
  It is possible to control how the sorting column will be chosen by users. It can be done by assigning sorting actions to header sort events in Actions tag, for example <Actions OnClickSort='SortAsc OR SortDesc'.
  

  • Events

    
    There is basic event

    OnClickSort

    called when set Cfg SortIcons to 0 or 1, called for both directions.
    Or two events

    OnClickSortUp

    and

    OnClickSortDown

    called when set Cfg SortIcons to 2 or 3, called for the individual direction.
    There are the actions with key or button prefixes or their combinations, Right and Middle for mouse buttons and Shift, Alt and Ctrl for control keys. For example OnShiftRightClickSort or OnCtrlClickSort.
    

  • Actions

    
    

    • SortAsc

      ,

      SortDesc

      add the clicked column as the first column in sorting. The old columns are shifted to next positions.
      If the column is already the first in sorting, it changes its direction if it has different.
      If the sorting count reaches MaxSort, the last column is removed.
      

    • SortAscOne

      ,

      SortDescOne

      sort only by this column, all old sorting is removed.

    • SortAscAppend

      ,

      SortDescAppend

      add the column to the end of the sorting.
      If the sorting count reaches MaxSort, they do nothing.
      If the column is already present in the sorting and has different direction, they changes it.
      

    • SortAscAdd

      ,

      SortDescAdd

      add the column to the end of the sorting if there was another click to some column header within last two seconds.
      If the sorting count reaches MaxSort, they do nothing.
      If the column is already present in the sorting and has different direction, they changes it.
      If there was no click to column header within two seconds, it sorts by this column and all old sorting is removed.
      

    • NoSort

      removes the clicked column from sorting.
      

    • DefaultSort

      clears the sorting and restores Sort attribute that was set when the grid was loaded.
      

• Auto sort

  
  Row can be automatically sorted to right place when user changes the row value in some sorting column. For this behavior set Cfg attribute AutoSort='1'.
  

• API

  
  Before sorting start it is called OnSort API event. It can return true to provide own sorting and not the default one.
  After sorting finishes, it is called OnSortFinish API event.
  The grid can be re-sorted after some external change by SortRows method.
  The individual row can be re-sorted after external change by SortRow method, only if AutoUpdate='1'.
  The sorting can be changed by ChangeSort method.