Use Tree Data to display data that has parent / child relationships where the parent / child relationships are provided as part of the data. For example, a folder can contain zero or more files and other folders.This section introduces simple ways to work with Tree Data before covering more advanced use cases.
Tree Data Mode
In order to set the grid to work with Tree Data, simply enable Tree Data mode via the Grid Options using:
Supplying Tree Data
When providing tree data to the grid you implement the
to tell the grid the hierarchy for each row. The callback returns back a
string with each
element specifying a level of the tree. Below follows two examples presenting the hierarchy in different ways.
Configuring Group Column
There are two ways to configure the Group Column:
- Auto Column Group - this is automatically selected by the grid when in Tree Data mode, however you can override the defaults.
- Custom Column Group - you can provide your own custom column group definition which gives allows more control over how the Group Column is displayed.
Auto Column Group
When the grid is working with Tree Data there is no need to explicitly specify a Column Group as the grid will use the Auto Column Group. However you will probably want to override some of the defaults as shown below:
Custom Column Group
As noted above, providing your own Custom Column Group has the advantage of giving you full control over the presentation of the Column Group, however it is not as convenient as using the default Auto Column Group.
One significant difference is that the entire
dataPath array will be supplied as a value, rather
than just the current node value.
For details on how you can provide your own Custom Group Column see: Specifying Group Columns.
Example: Organisational Hierarchy
The following example combines all the steps above to show a simplified organisational hierarchy:
It is not necessary to include entries for each level in the path if data is not required at group levels as shown below:
The second variation above leaves out row data entries for 'Documents' and 'txt' nodes, in this case the grid
Filler Groups for these.
This following example includes the column 'Group Type' to highlight which nodes are 'provided' in the row data and which are generated by the grid as a 'filler' group:
Filler Groupsare generated by the grid they will not contain a
dataproperty on the
RowNode. This could be a limitation if you wanted to provide an 'id' for each group even when there is no data displayed at group levels.
Tree Data Aggregation
When using Tree Data, columns defined with an aggregation function will always perform aggregations on the group nodes. This means any supplied group data will be ignored in favour of the aggregated values.
However if there are no child nodes to aggregate it will default to the provided value in the row data.
The File Browser example below demonstrates aggregation on the 'size' column.
Also you can refer to the section on Aggregation more details.
Tree Data Filtering
As Tree Data has parent / child relationships, by default all child nodes will be included when a parent passes a filter, and as filtering is performed across all group levels, a group will be included if:
- a) it has any children that pass the filter, or
- b) its data passes the filter
To override this behaviour to use regular filtering instead, enable the following Grid Options property:
Example: File Browser
The following example presents a more complex example which includes Aggregation and Filtering:
- 'Add New Group' Button - will add a new group under Music.
- 'Move Selected to stuff' Button - will move any non parent groups into the 'stuff' folder.
- 'Remove Selected' Button - will remove selected group along with children.
- 'Files' Filter - you can filter group and leaf names across the entire file tree.
- 'Size' Aggregation - as you move selected items into 'stuff' you'll notice updated folder sizes.
Pivot and Row Grouping with Tree Data
It is not possible to do pivot or row grouping while using tree data. This means all the functions related to pivot (eg colDef.pivot, or pivot in the tool panel) and row grouping (eg colDef.rowGroup, or row group in the tool panel) will be disabled.
If you are showing child counts for the groups, then the child count is a count of all children and grand children. This is different to Row Grouping where only leaf levels are counted, in tree data, all group children are also counted.
To enable selection set
gridOptions.rowSelection to 'single' or 'multiple'
as normal. However there are some restrictions to be aware of.
Selecting Groups and Children
groupSelectsChildren does not work with tree data. This is because
groups in tree data are rows passed by the application that may or may not have children - a
group is simply a normal row that has another row as a child. Given groups and leaf nodes
are logically identical, it is not possible to treat them differently in selection.
If you want to achieve something similar to
groupSelectsChildren then you should
listen on the selection events and do the selection yourself in your application. You will come
across edge cases where only your application will understand what the best selection outcome is.
Checkbox vs Click Selection
Click selection is supported with tree data. However when you are displaying tree data, clicking rows for selection is confusing as mouse clicks are also used for expanding / contracting rows. For this reason we recommend not using click selecting and preferring checkbox selection instead.
Filler groups do not keep their selection state should the filler group be moved. For example if you have groups A->B->C, where C is the only row provided (so the grid creates groups A and B for you), and then you change the patch to D->B->C, group B will not keep it's selection.
If keeping selection of groups is a priority, then arrange your data so that the grid does not need to create any filler groups.