Grouping rows to tree

TreeGrid documentation

TreeGrid supports grouping rows according to the same values in some column(s) to tree like in Pivot tables.
It is also possible group rows in existing tree - creating new levels.
Only variable rows can be grouped.
Strings can be grouped case sensitive or insensitive. Can be also grouped according to actual browser language or by special settings. See comparing strings.

Grouping can be changed by a user in special Group row.
Grouping can be preset in XML by <Cfg Group/> attribute.
Grouping can be changed by API by DoGrouping method.

The created group rows can be controlled by <D Group='1'/> default rows.
If grouping in grid is permitted.
Setting it to 0 disables all grouping functions.
If grouping is enabled by user.
A user can enable / disable grouping by click to Group row left panel.
If rows can be grouped by this column, its caption can be dragged to drop area for custom sorting in group row.
0 cannot be grouped, 1 can be grouped, 2 can be grouped, but column is not hidden when grouping.
Predefined or actual grouping.
Array of column names (comma separated), according to them are rows grouped, in this order.
Column where to show tree when rows are grouped.
Used only for plain tables; for tree is used always MainCol.
Used only if GroupMain is not set in chosen default <D> row.
If set, it shows the group tree in individual grouped columns instead of one main col.
It should be used only in plain grids without MainCol, because the MainCol is hidden when grid is grouped.
If set to 1, the expand button is shown left side, if set to 2, it is shown right side.
If set to 3 or 4, the group cell will be editable and its change will change all its children. 3 shows the button left side, 4 right side.
If set, moves grouped columns (in Group array) to the specified position. To be the tree correctly position.
It can be column name to move the columns right to this column (this column should not be possible to group by).
Or number of column section (0,1,2) to place it as the first column in the section.
If set to 1 when grouping, always sorts according to main column ascending.
If set to 2 when grouping, always sorts according to main column descending.
If set to 1 restores sorting state after ungrouping that was before grouping.
Maximal count of immediate children in grouped row. If the count is higher, the grouping row is divided to more rows with the same value in the main column.
Since 7.0 it has default value 0 as disabled.
Changes all required cell values when row is moved to another group or newly added into group (to be correctly grouped).
If not set, rows cannot be moved to group created by another column than source parent group.
If set to 2, rows can be moved or added also as children to other data row and switch the data row to group row. In this case DefParent and DefEmpty should be set to change default to group or data row when it gets or looses children.
For 0 it creates the group row ids as GroupIdPrefix + ascending number
For 1 it creates the group row ids as column name + GroupIdPrefix + grouping value
For 2 it creates the group row ids as column name + GroupIdPrefix + first child row id
For 3 it creates the group row ids as row Level + GroupIdPrefix + grouping value
For 4 it creates the group row ids as row Level + GroupIdPrefix + first child row id
A name for default row for group row when grouping according to this column.
It is used instead of default "Group" but not instead of chosen default row according to GroupCols and / or GroupCol.
A width of column when it shows the tree with grouped rows.
You can specify this width to change column width when it becomes main column while grouping - to resize column to accommodate the tree.
When grid is ungrouped or it shows the tree in another column, the column width returns to previous setting.
Since 7.0, if set to 1, the width of the column will be automatically increased by the widths of columns hidden by grouping.

Creating groups

If row can be grouped.
If set to 0 the row will not be moved to grouping row. But if contains children, all its children will be grouped inside.
In tree you can control by this attribute the level where will be grouping applied or even for every node you can choose different level.
When grouping, only the root rows are grouped.
If you want to group another level in tree, set CanGroup of the root (and next level(s)) rows to 0.
If there will be created grouping for empty and zero values
0 - Zero and empty values are not grouped
1 - Only zero values are grouped, empty values are not grouped
2 - Empty and zero are grouped
If set to 0, does not create grouping row with only one child row - if the cell value is unique in the column.
If set to 0, does not create single grouping row - when all rows have the same value in the column.
Since 11.0 if set to 2, it creates only one single group if more single groups are created in the tree.
If set to 0, does not group deleted rows. Only when are shown (ShowDeleted='1'), otherwise deleted rows are not grouped anyway.
It is possible to create more or all grouping levels from one column. Specify GroupChar as separator.
It can be used for example to group by directory paths, set GroupChar='/'
The cell value is split by the GroupChar and is grouped by all the parts.
Remember, by default also empty values and parts are grouped by, see GroupEmpty.
Maximum characters from strings to compare. It should be set only for string columns. It can be used to group by according to first few characters.
It can contain more values to create more group levels according to given parts of the values.
When used MaxChars, it is better to not hide the grouped column, by setting it as GroupMain or by setting its CanGroup='2'.
Value used for compare when sorting and grouping instead of cell value.
Useful for special non editable cells like Html, Icon, List.
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.

Created group rows <D Group='1'/>

The rows created as parent rows when grouping are preset by default row <D Group='1'/>.
From this row are filled all attributes in rows created when grouping. It contains also attributes Name and Def and all other attributes in <D> tag.
For other <D> attributes see Default rows.

It is possible to define more default rows (<D Group='1') and use them for different grouping.
By default there is only one default row defined in Defaults.xml named "Group" that is used for all created grouping rows.

How the appropriate grouping default row is chosen? When grouping starts:
1) There are searched all default rows with Group='1' and tested their GroupCols attributes if passes the actual <Cfg Group/> are chosen.
2) If any of found default rows in point 1) have set GroupMain, this value is set to MainCol. If some row have set OnGroup action, this action is called.
3) Grouping is done for every column in <Cfg Group/> - e.g. if there are three columns, three levels of rows will be created and every level can have different default
If set to 1, this default row will be used for grouping.
Also when ungrouping all rows that have its Def set to default with Group='1' are deleted and their children are ungrouped.
Specifies, for which grouping will be this default row used.
This default row will be used if <Cfg Group/> attribute contains any string in this array.
The string can contain "*" as wildcard for any substring.
When GroupCols is not set, the default can be used for any grouping.
When GroupCols is empty, the default will never be used for grouping automatically.
When more than one default row pass the actual grouping, one of them will be used by random, but always have precedence the defaults with GroupCols set and def named exactly "Group" is tested as the last.

For example "|*B,C|*X*|A" means all grouping with the last two columns B,C or any grouping containing column 'X' or grouping by only column A.
Specifies, for which grouping column will be this default row used, when GroupCols passed more default rows.
This default will be used only when creating groups according to column in this (comma separated) array.
In the array can be listed column name or its position in <Cfg Group/>. The position can be 0 for first, 1 second, -1 last, -2 last but one and so on.

For example <D Group='1' GroupCols='|A,B' GroupCol='A' ... /> <D Group='1' GroupCols='|A,B' GroupCol='B'/>
For example <D Group='1' GroupCols='|A*' GroupCol='-1'/> ... <Cfg GroupCols='A,B,C'/>
A column where the grouping tree will be displayed. Changes MainCol when this default is used.
When more than one default row passed the GroupCols (but not GroupCol!), the first found GroupMain attribute is used for setting MainCol.
A column caption that will be set to the main column when grouping by this default.
When more than one default row passed the GroupCols (but not GroupCol!), the first found GroupMainCaption attribute is used.
Called to get default row for the group when grouping according to column col.
col is column name, def is chosen name of default. Return new name of default or def.
Changes CDef of parent node. To change adding new rows to parent when it contains group rows.
Changes AcceptDef of parent node. To change dragging rows to parent when it contains group rows.
Comma separated list of columns that will be editable in group row and will change all values in the group children.
In this list can be present only columns where the actual grouping results all values the same.
Can contain special value "Main" that means main grouping column that will be mirrored to column according to the grouping is done.
If set to 1 and row's parent calculates some aggregate functions on its children,
this row calculates its children instead of itself - behaves like its children was directly in its parent.
Remember, it is cell attribute!
Maximum characters from strings to compare. It should be set only for string columns. It can be used to group by according to first few characters.
(Since 7.0) It can contain more values to create more group levels according to given parts of the values.
When used MaxChars, it is better to not hide the grouped column, by setting it as GroupMain or by setting its CanGroup='2'.
Standard default row or Actions attribute containing JavaScript code.
It is run when this default is chosen by the GroupCols. The action is run only once per whole grouping, before grouping is started.
When more than one default row passed the GroupCols (but not GroupCol!), only the first not empty Action is run.
Example: <D Group='1' OnGroup='Grid.Editing=0;'/>
Standard Actions attribute containing JavaScript code.
It is run when grid is ungrouped - GroupCols are set to empty.
Example: <Actions OnUngroup='Grid.Editing=1;'/>
Called before grouping grid after user action. Group is new value that will be set for Group.
Called also before ungrouping grid with Group = "".
Called also after Grouped is changed with Group = null, but before the grid is re-grouped. (Before 7.1 was called always with Grouped=1)
It is not called on start even if grid is grouped.
Return true to suppress the action.
Called after grid was re-grouped in data, but before changes are visible in grid.

User interface to choose grouping

User interface for grouping is shown by solid space <Group> row. <Solid><Group ... /></Solid>
This row is not divided to any section and is never scrolled. It can contain any cells like Space row, but List cell and Custom area have special functions.
The group row can be also done by pure Space row with the cells Select and DropCols.
It can be placed in <Solid> tag. The position in grid is set by its Space attribute.
Note: when grouping, created grouping rows have default row "Group", to change this settings see <D Group='1'/>.
First character separated array of predefined grouping names. It can contain HTML code.
A user will choose one item from the list to select the grouping set by Cols attribute.
If it is empty, no cell with predefined grouping will be displayed.
This list has the same format as list for Button of type Defaults.
Value displayed in List cell for custom grouping not in Cols. It can contain HTML code.
First character separated array of comma separated arrays of column names as predefined Group for defaults in List.

Example:	List="|Group by A|Group by A, B and C|Group by C and D"
	Cols="|A|A,B,C|C,D"

If the custom grouping is permitted - if the drop area for column captions is displayed, cell type DropCols named Custom.
The text displayed in the area "To group by, drag column caption here..." can be changed by <Grid><Lang><Text GroupCustom=""/></Lang></Grid>, default located in Text.xml.
The Custom cell is by default displayed if no List and Cells are defined.
Position of the row in grid, specifies horizontal section of the grid.
If more solid rows has the same Space value, are placed in the order they are in data.
-1 - above grid, 0 - above header, 1 - under head rows, 2 - above foot rows, 3 - under foot rows, 4 - under vertical scrollbar, 5 - under grid
-1, 0, 4, 5 are spanned for whole grid, including vertical scrollbar and pager, 1, 2, 3 are spanned only for columns.
If the row displays left side panel, to show icon for enabling / disabling grouping.
If set to 1, the panel is displayed only if the grid left side panel is displayed.
If set to 2, the panel is displayed always.
Comma separated list of cells in the group row.
The Group row can have two special cells, List and Custom. These cells have also all other attributes as standard space row cells.
If the Cells attribute is not set, it contains List or Custom if List and / or Custom attribute is set.
If the Cells attribute is set, to show the List or Custom, include List and / or Custom name to the Cells list.

Grouping actions and API

Groups by actual or focused column as the first column, fails if grid is already grouped by this column.
Groups by actual or focused column as the last column, fails if grid is already grouped by this column.
Removes the actual or focused column from grouping, fails if grid is not grouped by this column.
Enables grouping in grid and re-groups it according to actual settings. It fails if groupings already enabled.
Disables grouping in grid and un-groups it. It does not clear actual grouping settings. It fails if groupings already disabled.
Starts moving column in DropCols (usually in Group row).
Re-groups grid according given settings. If Group is null, it un-groups grid.
Group is new value for Group.
Variable of created group row, it contains column name according to it was the group created.
Variable of created group row, it contains row position (from 0) when there are created more groups for one columns by GroupChar or MaxChars.
Called for every created group while grouping grid.
The group is already set and placed in grid, but does not have its children yet.
Since 8.0 it can change the group row id.
Called when the group is removed.
The group is still placed in grid and has its children.
Can be called also while grouping when the group is removed due some restriction like GroupSole. In this case is ungroup false.