TreeGrid v6.0

Grouping rows to tree

TreeGrid documentation index

 

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.

 

<Cfg>                string[]  Group                     [“”]         Saved to cookies, to not load it, set GroupLap=’1’                             renamed 6.0  .

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.

 

<Cfg>                int          GroupTree         [0]                                                                                                                                new 7.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.

 

<Cfg>                string    GroupTreeCol                                                                                                                                   new 7.0 .

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.

 

<Cfg>                int          GroupSortMain         [0]                                                                                                          renamed 6.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

 

<Cfg>                bool       GroupRestoreSort              [0]                                                                                             renamed 6.0  .

If set to 1 restores sorting state after ungrouping that was before grouping

 

<Cfg>                int          MaxGroupLength   [0]                                                                                                                    chg 7.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.

 

<Cfg>                bool       GroupChangeMoved       [1]                                                                                                      new 6.4 .

Changes all required cell values when row is moved to another group or newly added into group (to be correctly grouped).

 

<Cfg>                int          GroupMoveFree       [1]                                                                                                                  new 6.4 .

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.

 

<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.

 

<C>                   int          GroupWidth                                                                                                                                          upd 7.0 .

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.

 

<C> <cell>        int          GroupEmpty                [2]                                                                                                          renamed 6.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

 

<C> <cell>        bool       GroupSole                      [1]                                                                                                                    new 6.0 .

If set to 0, does not create grouping row with only one child row – if the cell value is unique in the column

 

<C> <cell>        bool       GroupSingle                [1]                                                                                                          renamed 6.0  .

If set to 0, does not create single grouping row - when all rows have the same value in the column

 

<C> <cell>        bool       GroupDeleted             [1]                                                                                                        renamed 6.0  .

If set to 0, does not group deleted rows. Only when are shown (ShowDeleted=’1’), otherwise deleted rows are not grouped anyway.

 

<C>                   string    GroupChar                                                                                                                                             new 6.4 .

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.

 

<C>                   int[]        MaxChars           [0]                                                                                                                                  new 7.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’.

 

<cell>                string    SortValue                                                                                                                                                 upd 6.0 .

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>.

 

<C> <cell>        bool       LocaleCompare        [0]                                                                                                                   new 6.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.

 

<C> <cell>        bool       CaseSensitive             [1]                                                                                                                   new 6.0 .

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.

 

<C> <cell>        string    WhiteChars                                                                                                                                            chg 6.0 .

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.

 

<C> <cell>        string[*] CharCodes                                                                                                                                             upd 6.0 .

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.

 

<D>                   string    GroupMainCaption                                                                                                                      new 6.0 .

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.

 

<D>                   string    ParentAcceptDef                                                                                                                             new 6.0 .

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.

 

<D cell>            int[]        MaxChars           [0]                                                                                                                                 upd 7.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’.

 

<D XML event>             OnGroup                          (TGrid Grid, TRow default)                                                                 renamed 6.0  .

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;’/>

 

<Actions>                      OnUngroup      (TGrid Grid)                                                                                                       renamed 6.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;’/>

 

API event          bool       OnGroup            (TGrid grid, string Group)                                                                            chg 6.0; upd 7.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.

 

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. See this tutorial.

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 ...F                 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 ...F    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 ...F          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.

Cols is new value for Group

 

API TRow var. string    GroupCol                                                                                                                                                new 6.4 .

Variable of created group row, it contains column name according to it was the group created.

 

API TRow var. int          GroupPos                                                                                                                                               new 7.0 .

Variable of created group row, it contains row position (from 0) when there are created more groups for one columns by GroupChar or MaxChars.

 

API event          void       OnCreateGroup       (TGrid grid, TRow group, string col, string val)                                           new 6.4 .

Called for every created group while grouping grid.

The group is already set and placed in grid, but does not have its children yet.

 

API event          void       OnRemoveGroup   (TGrid grid, TRow group, bool ungroup)                                                    new 6.4 .

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.