|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142 |
- ---
- 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[]
-
- [[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]#TreeDataProvider# 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]
- ----
- // Initialize a TreeGrid and set in-memory data
- TreeGrid<Project> treeGrid = new TreeGrid<>();
- treeGrid.setItems(getRootProjects(), Project::getSubProjects);
-
- // 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::getLastModified).setCaption("Last Modified");
- ----
-
- The [classname]#TreeData# class can be used to build the hierarchical data structure,
- and it can then be passed on to [classname]#TreeDataProvider#. 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]#TreeDataProvider# with [classname]#TreeData# 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]
- ----
- TreeDataProvider<Project> dataProvider = (TreeDataProvider<Project>) treeGrid.getDataProvider();
-
- TreeData<Project> data = dataProvider.getTreeData();
- // 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.
-
- [[components.treegrid.expandcollapse]]
- == Expanding and Collapsing Nodes
-
- [classname]#TreeGrid# nodes that have children can be expanded and collapsed by either user interaction or through the server-side API:
-
- [source, java]
- ----
- // Expands a child project. If the child project is not yet
- // in the visible hierarchy, nothing will be shown.
- treeGrid.expand(childProject);
- // Expands the root project. If child project now becomes
- // visible it is also expanded into view.
- treeGrid.expand(rootProject);
- // Collapses the child project.
- treeGrid.collapse(childProject);
- ----
-
- To use the server-side API with a backend data provider the [methodname]#hashCode# and [methodname]#equals# methods for the node's type must be implemented so that when the desired node is retrieved from the backend it can be correctly matched with the object passed to either [methodname]#expand# or [methodname]#collapse#.
-
- [[components.treegrid.hierarchycolumn]]
- == 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");
- ----
-
- [[components.treegrid.node.collapsing]]
- == 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));
- ----
-
- [[components.treegrid.events]]
- == 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.
-
- [[components.treegrid.keyboard]]
- == Keyboard Navigation and Focus Handling in TreeGrid
-
- As opposed to [classname]#Grid#, individual cells are not focusable in [classname]#TreeGrid#, and only whole rows
- receive focus. The user can navigate through rows with kbd:[Up] and kbd:[Down], collapse rows with kbd:[Left],
- and expand them with kbd:[Right].
|