vaadin-framework/documentation/components/components-treegrid.asciidoc

---
title: TreeGrid
order: 25
layout: page
---

[[components.treegrid]]
= TreeGrid

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/grids-and-trees/treegrid"]
endif::web[]

IMPORTANT: The [classname]#TreeGrid# component is currently being developed and only available in the Framework 8.1 prerelease versions, starting from 8.1.0.alpha1.

[[components.treegrid.overview]]
== Overview

[classname]#TreeGrid# is for displaying hierarchical tabular data laid out in rows and columns.
It is otherwise identical to the [classname]#Grid# component, but it adds the possibility to show
hierarchical data, allowing the user to expand and collapse nodes to show or hide data.

See the documentation for <<dummy/../../../framework/components/components-grid.asciidoc#components.grid,"Grid">> for all the shared features between [classname]#Grid# and [classname]#TreeGrid#.

[[figure.components.treegrid.basic]]
.A [classname]#TreeGrid#
image::img/tree-grid-basic.png[width=70%, scaledwidth=100%]

[[components.treegrid.data]]
== Binding to Data

[classname]#TreeGrid# is used by binding it to a hierarchical data provider. The data provider can be based on in-memory or back end data. For in-memory data, the [classname]#InMemoryHierarchicalDataProvider# can be used, and for loading data from a back end, you need to implement three methods from the [interfacename]#HierarchicalDataProvider# interface. Usage of both data providers is described in
<<dummy/../../../framework/datamodel/datamodel-hierarchical.asciidoc#datamodel.hierarchical,"Hierarchical Data">>.

Populating a [classname]#TreeGrid# with in-memory data can be done as follows

[source, java]
----
Project rootProject = getRootRroject();

HierarchyData<Project> data = new HierarchyData<>();
// add a root level item with null parent
data.addItem(null, rootProject);

// Add all children for root item
rootProject.flattened().forEach(
       project -> data.addItems(project, project.getSubProjects()));

TreeGrid<Project> treeGrid = new TreeGrid<>();
treeGrid.setDataProvider(new InMemoryHierarchicalDataProvider<>(data));

// the first column gets the hierarchy indicator by default
treeGrid.addColumn(Project::getName).setCaption("Project Name");
treeGrid.addColumn(Project::getHoursDone).setCaption("Hours Done");
treeGrid.addColumn(Project::getdLastModified).setCaption("Last Modified");
----

The [classname]#HierarchyData# class can be used to build the hierarchical data structure,
and it can then be passed on to [classname]#InMemoryHierarchicalDataProvider#. It is simply a hierarchical
collection, that the data provider uses to populate the [classname]#TreeGrid#.

The [methodname]#setItems# method in [classname]#TreeGrid# can be used to set the root level items. Internally
an [classname]#InMemoryHierarchicalDataProvider# with [classname]#HierarchyData# is used. If at any time you want to modify the in-memory data in the grid, you may do it as follows

[source, java]
----
InMemoryHierarchicalDataProvider<Project> dataProvider = (InMemoryHierarchicalDataProvider<Project>) treeGrid.getDataProvider();

HierarchyData<Project> data = dataProvider.getData();
// add new items
data.addItem(null, newProject);
data.addItems(newProject, newProject.getChildren());

// after adding / removing data, data provider needs to be refreshed
dataProvider.refreshAll();
----

Note that for adding or removing nodes, you always need to call the [methodname]#refreshAll# method in the data provider you are using. The [methodname]#refreshItem# method can only be used when just the data for that item is updated, but not for updates that add or remove items.

== Changing the Hierarchy Column

By default, the [classname]#TreeGrid# shows the hierarchy indicator by default in the first column of the grid.
You can change it with with the [methodname]#setHierarchyColumn#, method, that takes as a parameter the column's ID specified with the [methodname]#setId# method in [classname]#Column#.

[source, java]
----
// the first column gets the hierarchy indicator by default
treeGrid.addColumn(Project::getLastModified).setCaption("Last Modified");
treeGrid.addColumn(Project::getName).setCaption("Project Name").setId("name");
treeGrid.addColumn(Project::getHoursDone).setCaption("Hours Done");

treeGrid.setHierarchyColumn("name");
----

== Prevent Node Collapsing

[classname]#TreeGrid# supports setting a callback method that can allow or prevent the user from collapsing an expanded node.
It can be set with [methodname]#setItemCollapseAllowedProvider# method, that takes a [interfacename]#SerializablePredicate#.
For nodes that cannot be collapsed, the [literal]#++collapse-disabled++# class name is applied to the expansion element

Avoid doing any heavy operations in the method, since it is called for each item when it is being sent to the client.

Example using a predefined set of persons that can not be collapsed:
[source, java]
----
Set<Person> alwaysExpanded;
personTreeGrid.setItemCollapseAllowedProvider(person -> 
       !alwaysExpanded.contains(person));
----

== Listening to Events

In addition to supporting all the listeners of the standard [classname]#Grid#, [classname]#TreeGrid# supports listening to the expansion and collapsing of items in its hierarchy.
The expand and collapse listeners can be added as follows:

[source, java]
----
treeGrid.addExpandListener(event -> log("Item expanded: " + event.getExpandedItem()));
treeGrid.addCollapseListener(event -> log("Item collapsed: " + event.getCollapsedItem()));
----

The return types of the methods `getExpandedItem` and `getCollapsedItem` are the same as the type of the [classname]#TreeGrid# the events originated from.
Note that collapse listeners will not be triggered for any expanded subtrees of the collapsed item.