3. Grouping rows to tree

Grouping rows according to the same values in selected columns

• Actual grouping can be predefined by Cfg attribute

  Group

  as list of the column names to group the grid by.
  Grouping does not modify any data rows. It adds new temporary group rows and places the rows as their children. These rows are automatically removed when the Group setting changes.
  

• User interface

  
  The Group setting can be changed by users in Space row with Kind Group defined by

  <Group>

  tag inside <Solid> tag.
  The Group row provides three special / optional cells:
  • List as list of predefined grouping settings to choose one of them.
    In List attribute array define item names shown in the List combo and in Cols attribute array define the individual groupings as strings set to the Group Cfg attribute.
    
  • Custom as area to drag columns here for user defined list to group by them. The custom area is shown when set Custom='1'.
  • Panel as checkbox to temporary disable actual grouping without changing it. It is shown when set Panel='1', it is shown by default.
    The checkbox changes Cfg attribute Grouped.

• API

  
  
  • The grouping settings can be changed also by API method DoGrouping and switched on / off by actions GroupOn / GroupOff.
  • Before grouping start there is called event OnGroup. It is not called on grid loading. It is called from method DoGrouping.
    After grouping is done, but before the changes are shown there is called event OnGroupFinish. It is not called on grid loading.
    

• Controlling creating groups

  
  Here are various attributes to control the group creation, when and how the groups will be created.
  • Column / cell attribute

    GroupEmpty

    controls if there will be created group row for empty and / or zero values. Default is both on.
  • Column / cell attribute

    GroupSingle

    controls if there will be created single group row (in its parent) = when all the data rows has the same value in the grouping column. Default is on.
  • Column / cell attribute

    GroupSole

    controls if there will be created group row for signle data rows = when the data row has unique value in the grouping column. Default is on.
  • Column / cell attribute

    GroupDeleted

    controls if there will be created group row also for deleted rows or they remain in root. Default is on.
  • Column attribute

    GroupChar

    to create more groups for one grouping column. It splits cell value in that column by the given GroupChar and creates new level for every part.
  • Columns attribute

    MaxChars

    to compare only part of the values.
    Is also possible to input more values into MaxChars to create more groups by one grouping column, it will split the cell value to parts of length given by MaxChars and creates new level for every part.
  • Column / cell attribute

    CaseSensitive

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

    LocalCompare

    to compare the strings according to browser's locale settings. It has sense especially for case insensitive comparing. By default is off.
  • Column / cell attribute

    WhiteChars

    as list of characters to ignored when comparing. The strings are compared after these values are removed from them.
  • Column / 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 grouping

  
  Every cell can have set special value by

  SortValue

  to use it for grouping instead of the cell value.
  The value can be also dynamically created by JavaScript in API event OnGetSortValue.
  
• The

  grouping tree

  is shown in main column set by Cfg attribute

  MainCol

  .
  If the grid does not have tree yet (no main column) the tree is shown in column set by Cfg attribute

  GroupMain

  .
  The tree column can be also different according to grouped columns, the GroupMain can be set also in Group default row.
  The group tree can be shown also independently for every grouping column instead of MainCol, set Cfg attribute

  GroupTree

  to 1 or 2. 1 Shows the tree left side, 2 right side. To move the group columns to some position in grid to be adjacent and the tree correctly positioned set GroupTreeCol Cfg attribute.
  
• The

  main column width

  can be resized when showing tree to size set by column attribute

  GroupWidth

  or, if it is set to 1, it resizes by width of all columns hidden by grouping.
• The main column can be automatically

  sorted

  by when grouped, if set Cfg attribute GroupSortMain='1'.
  And the original sorting can be restored when set Cfg attribute GroupRestoreSort='1'

• Created group rows and defaults

  
  The created group rows are controlled by default row named "Group" it works as standard default.
  It can be predefined like <Def><D Name='Group' .... /></Def> and define various settings for the group row.
  It can for example change color or style of the main column values, hide or retype the other column or calculate summaries for the other columns.
  It is also possible to define and assign different defaults for particular grouping (e.g. grouping by A and B can have different default then grouping by B and A) and also for particular column or grouping level. It is controlled by the default attributes GroupCols and GroupCol. For more information see documentation.

• Editing in group

  
  By default is main column cell in created group row editable and if it is changed, it changes all the children cells in the source column.
  Also when moved children from one group to another, it changes its cells to be related to the new grouping.
  Similarly rows or copied to some group gets filled its cells according to the grouping.
  The dragging groups can be more controlled by Cfg attribute GroupMoveFree and GroupChangeMoved.