Initial Documentation for TreeGrid and Hierarchical Data (#8880)

* Initial Documentation for TreeGrid and Hierarchical Data

Fixes #8615, part of #8616

11 files changed, 105 insertions, 8 deletions

diff --git a/documentation/components/chapter-components.asciidoc b/documentation/components/chapter-components.asciidoc
index f92a132e98..e1093ba03e 100644
--- a/documentation/components/chapter-components.asciidoc
+++ b/documentation/components/chapter-components.asciidoc
@@ -46,6 +46,8 @@ include::components-twincolselect.asciidoc[leveloffset=+2]
 
 include::components-grid.asciidoc[leveloffset=+2]
 
+include::components-treegrid.asciidoc[leveloffset=+2]
+
 include::components-menubar.asciidoc[leveloffset=+2]
 
 include::components-upload.asciidoc[leveloffset=+2]
diff --git a/documentation/components/components-customcomponent.asciidoc b/documentation/components/components-customcomponent.asciidoc
index dd5a86b823..5529bf21be 100644
--- a/documentation/components/components-customcomponent.asciidoc
+++ b/documentation/components/components-customcomponent.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: Composition with CustomComponent
-order: 31
+order: 32
 layout: page
 ---
 
diff --git a/documentation/components/components-customfield.asciidoc b/documentation/components/components-customfield.asciidoc
index 38ac780e8f..a369f390a2 100644
--- a/documentation/components/components-customfield.asciidoc
+++ b/documentation/components/components-customfield.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: Composite Fields with CustomField
-order: 32
+order: 33
 layout: page
 ---
 
diff --git a/documentation/components/components-embedded.asciidoc b/documentation/components/components-embedded.asciidoc
index bf4f9eb47b..84a7971500 100644
--- a/documentation/components/components-embedded.asciidoc
+++ b/documentation/components/components-embedded.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: Embedded Resources
-order: 33
+order: 34
 layout: page
 ---
 
diff --git a/documentation/components/components-menubar.asciidoc b/documentation/components/components-menubar.asciidoc
index be3548012f..0c54196b87 100644
--- a/documentation/components/components-menubar.asciidoc
+++ b/documentation/components/components-menubar.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: MenuBar
-order: 25
+order: 26
 layout: page
 ---
 
diff --git a/documentation/components/components-popupview.asciidoc b/documentation/components/components-popupview.asciidoc
index a1296ad14d..bc58fe6b19 100644
--- a/documentation/components/components-popupview.asciidoc
+++ b/documentation/components/components-popupview.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: PopupView
-order: 29
+order: 30
 layout: page
 ---
 
diff --git a/documentation/components/components-progressbar.asciidoc b/documentation/components/components-progressbar.asciidoc
index db7e8990de..b6337ff3ad 100644
--- a/documentation/components/components-progressbar.asciidoc
+++ b/documentation/components/components-progressbar.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: ProgressBar
-order: 27
+order: 28
 layout: page
 ---
 
diff --git a/documentation/components/components-slider.asciidoc b/documentation/components/components-slider.asciidoc
index 9b447f27fe..7ae972ae77 100644
--- a/documentation/components/components-slider.asciidoc
+++ b/documentation/components/components-slider.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: Slider
-order: 28
+order: 29
 layout: page
 ---
 
diff --git a/documentation/components/components-treegrid.asciidoc b/documentation/components/components-treegrid.asciidoc
new file mode 100644
index 0000000000..b0e28fee5f
--- /dev/null
+++ b/documentation/components/components-treegrid.asciidoc
@@ -0,0 +1,95 @@
+---
+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");
+----
+
diff --git a/documentation/components/components-upload.asciidoc b/documentation/components/components-upload.asciidoc
index 8288bd2bc1..cde631d148 100644
--- a/documentation/components/components-upload.asciidoc
+++ b/documentation/components/components-upload.asciidoc
@@ -1,6 +1,6 @@
 ---
 title: Upload
-order: 26
+order: 27
 layout: page
 ---
 
diff --git a/documentation/components/img/tree-grid-basic.png b/documentation/components/img/tree-grid-basic.png
new file mode 100644
index 0000000000..fa826a2525
--- /dev/null
+++ b/documentation/components/img/tree-grid-basic.png