TreeGrid Tree Tutorial
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 arrea 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 compary 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.