Tree

TreeGrid documentation

Rows in TreeGrid can be placed into tree.
TreeGrid supports unlimited levels of tree.
In XML can be rows placed in tree of <I> tags like <I A='1'> <I A='1-1'> <I A='1-1-1'/> <I A='1-1-2'/> </I> <I A='1-2-1'> <I A='1-2-2'/> <I/> </I> <I A='1-2'/> <I A='1-3'/> </I> <I A='2'/>
The tree lines and expand/collapse buttons are placed into MainCol.
The row's children can be expanded, collapsed or not expandable / not collapsible, see Expanded and CanExpand.
The width of icons and indent in tree is defined in styles in Grid.css.

The rows can be also placed into tree automatically by Grouping feature.
Set this attribute to show TreeGrid instead of plain table. Let it empty to show only plain table.
It is name of main column with tree. The column must exist in the grid, but can be also hidden.
In this column will be displayed the tree with expand / collapse icons.
Only one main column is possible to be in grid. See also Button='Expand' to show the tree in more columns.
If set, the column should exist and be visible, otherwise a user cannot see the rows parent / children relationship.
Changes MainCol to given column.
If set noshow, does not call RenderBody to display changes.
If the tree icons and lines in MainCol are shown or hidden.
0 - Icons and lines are shown.
1 - Icons and lines are hidden.
2 - Icons and lines are hidden and are not exported.
3 - Icons and lines are hidden, are not exported and the setting cannot be changed.
Sets value of HideTree and updates the view.
For noshow = 1 does not update the view and requires rerender.
If set, hides tree lines and buttons if all rows are root without children. The tree can be shown back in configuration menu or by SetHideTree.
0 - it shows standard tree from top, children are below their parent
1 - it shows MS Excel summary outline tree, from bottom, children are above their parent
Sets value of ReversedTree and renders body.
For noshow = 1 does not render body and requires rerender.
If row shows icon to expand / collapse and the row can be expanded or collapsed.
0 - Row cannot be expanded or collapsed. The Expand/collapse button is not shown. Row's children are always shown or hidden, depending on Expanded.
1 - Row can be expanded and collapsed to show and hide its children. The Expand/collapse button is shown. Expanding sets Expanded to 1.
2 - Since 7.0 row can be expanded or collapsed, but the Expand/collapse button is not shown. Use to expand / collapse the row by another way.
3 - Since 14.0 row can be expanded or collapsed and the Expand/collapse button is shown. The children are expanded to the same level as the parent. Expanding sets Expanded to 3.
If row is expanded and how displays its children.
If ChildPaging is set to 3, only rows with Expanded='0' will take effect of the server ChildPaging and can download its children on expand.
0 - Row is collapsed and the children are not displayed.
1 - Row is expanded and the children are displayed on next tree level. The children are hidden if the row is not visible.
2 - reserved
3 - new 14.0 Row is expanded and the children are displayed on the same level. The children are displayed also if the row is not visible.
Custom tree icons for specified row state (icons for expand/collapse).
X = 0 - not expandable, 1 - last not expandable, 2 - expand (+), 3 - last expand (+), 4 - collapse (-), 5 - last collapse (-).
(Since 12.0) X = 6 line through, used only with custom icons 0 - 5, 7 no line through, used only if defined also 6, 8 - wait expand (+), 9 - last wait expand (+).
(Since 12.0) X = 10 - drag above, 11 - last drag above, 12 - drag into, 13 - last drag into, 14 - drag below, 15 - last drag below, 16 - no drag, 17 - last no drag.
If set NoTreeLines, only values 0, 2, 4, 8, 10, 12 and 14 are used.
The last is the last row inside its parent's children - its line does not continue.
For example: <I TreeIcon2='SpecialExpand.gif' TreeIcon4='SpecialCollapse.gif'/>
The height of the icon is always set to height of the row, the width is set to standard Tree icon or to TreeWidthX.
Custom widths of tree icons and indent. Are used only if set SpannedTree='1'.
X = 0 - tree level indent. 1 - width of leaf or not expandable button, 2 - width of expand / collapse button.
Since 12.0 it can be used with any value of NoTreeLines, but for tree lines only with custom TreeIconX.
To show right side Expand button set Button="Expand".
It can be used to show the tree button in different column than in the main column.
To hide expand icon in the main column, you can set row attribute CanExpand='2'.
To show left side Expand button set Icon="Expand".
It can be used to show the tree button in different column than in the main column.
To hide expand icon in the main column, you can set row attribute CanExpand='2'.
It can be set only in Header row in MainCol column.
If set, it displays buttons for tree levels, like in MS Excel outline. After click to the button, it expands / collapses the rows to show up to the selected level.
If set to 1, the button count is equal to the maximal tree level in grid (= max Level + 1).
If set to >1, it displays maximally given button count.
The count of level buttons is updated after grouping changes. It is also increased, but not decreased, after moving or adding rows.
If set, shows minimally this count of Levels buttons. Useful in server paging, when the tree depth is unknown.
Hides the first line in tree (root items are without any line).
Root rows become not expandable, so they should be all Expanded.
Set it to 1 if some MainCol cell is spanned between columns (has set Span attribute).
Set it to 1 along with NoTreeLines to control widths of the tree icons and indent by TreeWidthX.
If set to 1, it shows tree icons in included <table> tag and slows down rendering.
Cannot be used when the main column cells have set RowSpan.
Set it for automatic calculation of main column width to always show the whole tree.
Set it to width (in px) of the text part of the main column. The resulted column width is calculated as AutoTreeWidth plus highest lever multiplied by tree line width plus tree icon width.
It ignores custom widths set by TreeWidthX.
If set to 1, it does not show connecting lines in tree, shows only expand / collapse buttons.
Use especially for custom icons or tree indent widths.
If set to 1, it does not show connecting lines in tree when printing, shows only expand / collapse buttons.
If set to 2, it is set to 1 in Chrome/Safari and to 0 in other browsers, as the WebKit has problems with printing tree lines.
If empty, uses value of NoTreeLines.
Sets value of the NoTreeLines and re-renders grid.
Row level in auto row tree. 0 means root row, 1 first level, 2 second level, ...
If the rows are not nested in input data, they can have set the Level attribute and TreeGrid will nest the rows automatically according to the Level value.
The Level attribute can be maximally by 1 higher than Level of previous row (in ReversedTree of next row).
Row's level in tree. Only for variable rows.
-1 = page, 0 root row, 1 first level children, 2 second level children, ...
Returns true if row has some visible children (shows icon expand/collapse).
Returns row's position in its parent. It counts only visible rows.
If set to 1, saves expanding / collapsing state of all rows to cookies. All rows must have set id attribute.
If set to 2, saves the state of only rows that differs from their default row's Expanded state.
Remember, cookies are limited to 4096 bytes for the whole page, so use this setting only for very small tables or use PersistentCfg.
Also use the smallest ids as possible (the amount of space is used: id+1 bytes per row).
Cannot be used with server side child paging. Cannot be used for automatically created group rows.
All rows (comma separated ids) that will be expanded, all other rows will be collapsed if the attribute is present.
It is done on start and also after every page / child page load in server paging.
If defined both Expanded and Collapsed attributes, even empty, the row expanded state is changed only if the row is present in one of the lists.
It overrides the states saved by SaveExpanded.
All rows (comma separated ids) that will be collapsed, all other rows will be expanded if the attribute is present.
It is done on start and also after every page / child page load in server paging.
If defined both Expanded and Collapsed attributes, even empty, the row expanded state is changed only if the row is present in one of the lists.
It overrides the states saved by SaveExpanded.
If set to 0, TreeGrid scrolls down if the children are not shown all.
If set to 1, when expanding row, does not scroll into view the row's children - the icon always stays under mouse cursor.
Since 7.0 the default value is 1.
Removes all rows with given def as their default row Def.
def can be also comma separated list of the Def names to remove the row containing any of the listed names in their Def.
If def is null or empty, it removes all parent rows with some child.
Children of removed rows are placed instead of their removed parents.
The removed rows are stored and can be restored by RestoreParents.
If there were already some rows removed by the RemoveParents previously, all these rows are first restored by the RestoreParents and next the required rows are removed.
If set norender it does not re-render the body and the Render / RenderBody call will be required.
Returns true for success, false for no rows to remove.
Restores all the rows removed by RemoveParents. The rows are placed to the same location they are removed from.
Moves all the previous children back to the restored parent rows as their children.
If the grid rows were modified (moved / removed) during the rows were removed, the exact location of the restored rows is unsure!
If set norender it does not re-render the body and the Render / RenderBody call will be required.
Returns true for success, false for no rows to restore.

Actions and API for expand / collapse

The row can be expanded or collapsed by a user by clicking to row's expand / collapse icon in tree. And also by pressing Ctrl+Enter by default.
Collapsing rows is immediate, but expanding rows can be slows and asynchronous, depending on how many children will be loaded / render, see various paging types.

All rows can be expanded or collapsed by clicking to toolbar buttons ExpandAll or CollapseAll.
The CollapseAll always collapses all rows in grid, but ExpandAll can expand only some rows to avoid dead lock when too many children are present, see ExpandAll... settings.
Expands actual or focused row, fails if row is already expanded or cannot be expanded or does not have children.
The expanding can be asynchronous and can finish after the action returned.
Collapses actual or focused row, fails if row is not expanded or cannot be expanded or does not have children.
Use "Expand OR Collapse" to invert expand state.
Tries to expand all rows.
The ExpandAll can be asynchronous and can finish after the action returned.
The ExpandAll action can be stopped by a user during the process.
Since 14.0 it can have also F suffix to expand all rows in focused nested grid.
If set to 1 in server child paging (ChildPaging=3) the ExpandAll expands only rows with already downloaded children.
Which levels will be expanded on ExpandAll.
0 - only one level, no sub nodes of actually expanding rows will be expanded.
1 - all already rendered children, the rest only one level
2 - all already downloaded children, the rest only one level
3 - all levels, the expanding can be done in more passing, because it waits for children to download.
If expand all will render the whole grid body instead of expanding the rows one by one.
"" / nothing - auto - the render body will be chosen automatically if there more rows to render than rendered rows.
0 - no - standard expanding, 1 - yes - render body, 2 - render body except when expanding one level.
Collapses all rows.
Since 14.0 it can have also F suffix to expand all rows in focused nested grid.
The CollapseAll can be asynchronous and can finish after the action returned.
Collapses all rows in the first expanded collapsible level. All rows in grid will look collapsed, but they could contain expanded children.
The CollapseAll can be asynchronous and can finish after the action returned.
If set to 0, the row is indented / outdented with their children. It does change tree position of other rows than the indented / outdented one
If set to 1, the row is indented / outdented alone without their children, it can loose or get children while indenting. It preserved row position in the table. It is closer to the MS Excel behavior.
If set to 2, it is similar to 1, but it indents / oudents also adjacent rows if required.
Increases level of actual or focused or selected rows. Moves every row as the last child of its previous row.
It never moves selected row as child of another selected row.
Since 15.0 it processes also focused and selected rows.
Replaced by action Indent.
Decreases level of actual or focused row. Moves the row below its parent row.
It never move the row if its parent is also selected.
Since 15.0 it processes also focused and selected rows.
Replaced by action Outdent.
Expands / collapses grid after click to Levels button.
Called before the row is expanded or collapsed. Return true to suppress action.
Test the actual state by row.Expanded.
Return true to cancel the action.
Expands row, for child paging is asynchronous.
Expands all parents to show the row. The row must not be hidden (must have Visible=1). For child paging is asynchronous.
Expands all rows in parent and shows their children.
If parent is null, expands all rows in grid.
loaded is ExpandAllLoaded, levels is ExpandAllLevels, render (since 14.0) is ExpandAllRender.
max (since 12.0) is maximal level to expand, 0 expands only root rows, 1 expands root rows and their immediate children, etc.
(since 12.0) if set test = 1, it does not do anything, just returns count of affected rows.
Remember, in grid with ChildPaging is not often possible to expand all rows, because rendering of thousands of rows is very slow.
Called after expanding all rows finished (cancelled = 0) or was interrupted (cancelled = 1).
cancelled is -1 if there were no rows to expand.
Note, in child parts it is called before the child parts are rendered.
Collapses row.
Collapses all rows.
Since 12.0 for root = 1 collapses only first expanded level.
Since 12.0 for text = 1 does not do any change, just returns count of the collapsible rows.
Since 12.0 returns count of collapsed rows.
Collapses / expands rows to show exactly given tree level. level is 1 for root level (collapses all), 2 for second level (expands the root rows), etc.