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.
<Cfg> bool
Grouping
[1]
If grouping in grid is permitted.
Setting it to
0 disables all grouping functions.
<Cfg> bool
Grouped
[1] Saved to cookies, to not load it, set GroupedLap='1'
If grouping is enabled by user.
A user can enable / disable grouping by click to
Group row left panel.
<C> int
CanGroup
[1]
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.
new 15.0 <Cfg> int
GroupHideCols
[1]
If hides columns when grouping by them.
0 - no,
1 if it have set
CanGroup=1,
2 - always.
renamed 6.0 <Cfg> string[ ]
Group
[""] Saved to cookies, to not load it, set GroupLap='1'
Predefined or actual grouping.
Array of column names (comma separated), according to them are rows grouped, in this order.
<Cfg> string
GroupMain
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.
new 7.0 <Cfg> int
GroupTree
[0]
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.
new 7.0 <Cfg> string
GroupTreeCol
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.
renamed 6.0 <Cfg> int
GroupSortMain
[0]
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.
renamed 6.0 <Cfg> bool
GroupRestoreSort
[0]
If set to
1 restores sorting state after ungrouping that was before grouping.
chg 7.0 <Cfg> int
MaxGroupLength
[0]
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.
new 6.4 <Cfg> bool
GroupChangeMoved
[1]
Changes all required cell values when row is moved to another group or newly added into group (to be correctly grouped).
new 6.4 <Cfg> int
GroupMoveFree
[1]
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.
new 8.0 upd 15.0 <Cfg> int
GroupIdValue
[0]
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
(new 15.0) For
5 it creates the group row ids as parent id + "$" + column name +
GroupIdPrefix + grouping value
(new 15.0) For
6 it creates the group row ids as parent id + "$" + column name +
GroupIdPrefix + first child row id
(new 15.0) For
7 it creates the group row ids as parent id + "$" + row Level +
GroupIdPrefix + grouping value
(new 15.0) For
8 it creates the group row ids as parent id + "$" + row Level +
GroupIdPrefix + first child row id
<C> string
GroupDef
[""]
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.
upd 7.0 <C> int
GroupWidth
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
<I> bool
CanGroup
[1]
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.
renamed 6.0 <C> <cell> int
GroupEmpty
[2]
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
new 6.0 <C> <cell> bool
GroupSole
[1]
If set to
0, does not create grouping row with only one child row - if the cell value is unique in the column.
renamed 6.0 upd 11.0 <C> <cell> int
GroupSingle
[1]
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.
renamed 6.0 <C> <cell> bool
GroupDeleted
[1]
If set to
0, does not group deleted rows. Only when are shown (
ShowDeleted='1'), otherwise deleted rows are not grouped anyway.
new 6.4 <C> string
GroupChar
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.
new 7.0 <C> int[ ]
MaxChars
[0]
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.
For example MaxChars='1,2,3,4' creates up to four levels by the first four characters.
For example MaxChars='2,6' creates up to two levels, the first by first two characters, the second by next four characters.
When used
MaxChars, it is better to not hide the grouped column, by setting it as
GroupMain or by setting its
CanGroup='2'.
upd 6.0 <cell> string
SortValue
Value used for compare when
sorting and
grouping instead of cell value.
Useful for special non editable cells like Html, Icon, List.
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.
Comparing strings
You can also specify these settings for whole grid in default column
<Def><D Name='C'/></Def>.
new 6.0 <C> <cell> bool
LocaleCompare
[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.
new 6.0 <C> <cell> bool
CaseSensitive
[1]
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.
chg 6.0 <C> <cell> string
WhiteChars
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.
upd 6.0 <C> <cell> string[*]
CharCodes
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.
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
a) For every column in <Cfg GroupCols/> (= for every level in grouping tree) are searched the defaults found in point 1) and the first one that passes by its
GroupCol is used for the level.
b) If no default row passes the point a), it is used default row set by <C
GroupDef />.
c) If no default row is found, it is used
<D Name="Group"/> defined in Defaults.xml.
<D> bool
Group
[0]
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.
<D> string[*]
GroupCols
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.
<D> string[ ]
GroupCol
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'/>
When grouping, for first group rows created for column A will be used the first <D>, for the second group rows created for column B will be used the second <D>
For example
<D Group='1' GroupCols='|A*' GroupCol='-1'/> ... <Cfg GroupCols='A,B,C'/>
This default will be used for groups created for column 'C' - the last column in <Cfg Group/>
<D> string
GroupMain
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.
new 6.0 <D> string
GroupMainCaption
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.
API event string
OnGetGroupDef
(TGrid grid, string col, string def)
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.
<D> string
ParentCDef
Changes
CDef of parent node. To change adding new rows to parent when it contains group rows.
new 6.0 <D> string
ParentAcceptDef
Changes
AcceptDef of parent node. To change dragging rows to parent when it contains group rows.
<D> string[ ]
EditCols
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.
<D> bool
AggChildren
[0]
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.
upd 7.0 <D> <cell> int[ ]
MaxChars
[0]
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.
For example MaxChars='1,2,3,4' creates up to four levels by the first four characters.
For example MaxChars='2,6' creates up to two levels, the first by first two characters, the second by next four characters.
When used
MaxChars, it is better to not hide the grouped column, by setting it as
GroupMain or by setting its
CanGroup='2'.
renamed 6.0 <D XML event>
OnGroup
(TGrid Grid, TRow default)
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;'/>
renamed 6.0 <Actions>
OnUngroup
(TGrid Grid)
Standard Actions attribute containing JavaScript code.
It is run when grid is ungrouped - GroupCols are set to empty.
Example:
<Actions OnUngroup='Grid.Editing=1;'/>
chg 6.0 upd 7.1 API event bool
OnGroup
(TGrid grid, string Group)
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.
API event void
OnGroupFinish
(TGrid grid)
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'/>.
<Group> string[*]
List
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.
<Group> string
ListCustom
Value displayed in
List cell for custom grouping not in
Cols. It can contain HTML code.
<Group> string[ ][*]
Cols
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" |
<Group> bool
Custom
[0/1]
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.
<Group> int
Space
[1]
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.
<Group> int
Panel
[1]
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.
<Group> string[ ]
Cells
["List" / "Custom"]
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
<Actions>
GroupBy ...FACO
Not attached to any event
Groups by actual or focused column as the first column, fails if grid is already grouped by this column.
<Actions>
GroupByLast ...FACO
Not attached to any event
Groups by actual or focused column as the last column, fails if grid is already grouped by this column.
<Actions>
UngroupBy ...FACO
Not attached to any event
Removes the actual or focused column from grouping, fails if grid is not grouped by this column.
<Actions>
GroupOn
Attached to event OnClickPanelGrouped
Enables grouping in grid and re-groups it according to actual settings. It fails if groupings already enabled.
<Actions>
GroupOff
Attached to event OnClickPanelGrouped
Disables grouping in grid and un-groups it. It does not clear actual grouping settings. It fails if groupings already disabled.
<Actions>
DropColMove
Attached to event OnDragDropCol, can be attached only to OnDrag... actions
Starts moving column in DropCols (usually in Group row).
API method void
DoGrouping
(string Group)
Re-groups grid according given settings. If
Group is null, it un-groups grid.
Group is new value for
Group.
new 6.4 API TRow var. string
GroupCol
Variable of created group row, it contains column name according to it was the group created.
new 7.0 API TRow var. int
GroupPos
Variable of created group row, it contains row position (from 0) when there are created more groups for one columns by
GroupChar or
MaxChars.
new 6.4 upd 8.0 API event void
OnCreateGroup
(TGrid grid, TRow group, string col, string val)
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.
new 6.4 API event void
OnRemoveGroup
(TGrid grid, TRow group, bool ungroup)
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.
Buy
Try it free
TreeGrid
Gantt chart