treeDataGrid

treeDataGrid displays hierarchical data in a table with expandable rows.

XML Element	`treeDataGrid`
Java Class	`TreeDataGrid`

XML Element

treeDataGrid

Java Class

TreeDataGrid

Overview

Basics

LIVE DEMO

treeDataGrid primarily replicates the functionality of the dataGrid component.

An example of treeDataGrid declaration in the XML view descriptor is shown below:

<data>
    <collection id="tasksDc"
                class="io.jmix.uisamples.entity.Task">
        <fetchPlan extends="_local">
            <property name="parentTask" fetchPlan="_local"/>
            <property name="assignee" fetchPlan="_local"/>
        </fetchPlan>
        <loader id="tasksDl">
            <query>
                <![CDATA[select e from Task e]]>
            </query>
        </loader>
    </collection>
</data>
<facets>
    <dataLoadCoordinator auto="true"/>
</facets>
    <treeDataGrid id="taskDataGrid"
                  dataContainer="tasksDc"
                  hierarchyProperty="parentTask"
                  width="100%"
                  minHeight="20em">
        <columns>
            <column property="name"/>
            <column property="dueDate"/>
            <column property="assignee"/>
        </columns>
    </treeDataGrid>

The tasksDc collection container stores Task entities. The treeDataGrid is bound to this container using the dataContainer attribute, and its columns element defines which entity attributes are shown.

Actions

The treeDataGrid component implements the HasActions interface and can contain both standard list actions and custom actions. Actions are invoked by clicking designated buttons or from the context menu that appears on the right click.

To add action in Jmix Studio, select the component in the view descriptor XML or in the Jmix UI structure panel and click on the Add→Action button in the Jmix UI inspector panel.

<hbox id="buttonsPanel" classNames="buttons-panel"> (1)
    <button id="createBtn" action="departmentsTable.create"/>
    <button id="editBtn" action="departmentsTable.edit"/>
    <button id="removeBtn" action="departmentsTable.remove"/>
    <button id="infoBtn" action="departmentsTable.getInfo" icon="INFO_CIRCLE"/>
</hbox>
<treeDataGrid id="departmentsTable"
              hierarchyProperty="parentDepartment"
              width="100%"
              minHeight="20em"
              dataContainer="departmentsDc">
    <columns>
        <column property="name"/>
        <column property="hrManager"/>
    </columns>
    <actions>
        <action id="create" type="list_create"/> (2)
        <action id="edit" type="list_edit"/>
        <action id="remove" type="list_remove"/>
        <action id="getInfo" text="Get Info"/> (3)
    </actions>
</treeDataGrid>

1	Define `hbox` to contain action buttons.
2	Define the `list_create` standard action.
3	Define the `getInfo` custom action. Value of its text attribute represents the action in the context menu and is used as the button caption.

The context menu offers an alternative way to access actions through a right click. Each action is represented by its own menu item.

Use the contextMenu element to refine the list of items in the menu, organizing them with separators and a hierarchical structure.

<treeDataGrid id="treeDataGrid"
              hierarchyProperty="parentDepartment"
              width="100%"
              minHeight="20em"
              dataContainer="departmentsDc">
    <columns>
        <column property="name"/>
        <column property="hrManager"/>
    </columns>
    <actions showInContextMenuEnabled="false"> (1)
        <action id="create" type="list_create"/>
        <action id="edit" type="list_edit"/>
        <action id="remove" type="list_remove"/>
        <action id="getInfo" text="Get Info"/>
        <action id="viewCalendar" text="Calendar"/>
    </actions>
    <contextMenu>
        <item action="treeDataGrid.create"/> (2)
        <item action="treeDataGrid.edit"/>
        <item action="treeDataGrid.remove"/>
        <separator/>
        <item text="More"> (3)
            <item action="treeDataGrid.getInfo" icon="INFO_CIRCLE"/>
            <item action="treeDataGrid.viewCalendar" icon="CALENDAR"/>
        </item>
    </contextMenu>
</treeDataGrid>

1	Hide all actions from the menu. Or hide a specific action using its visible attribute.
2	Add menu items explicitly for necessary actions.
3	Nest items within each other to create a hierarchy.

Theme Variants

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

Variant	Description	Supported By
`no-border`	Removes the outer border around the grid.	Aura, Lumo
`no-row-borders`	Removes the horizontal borders between rows.	Aura, Lumo
`column-borders`	Adds vertical borders between columns.	Aura, Lumo
`row-stripes`	Alternates row background colors to improve readability.	Aura, Lumo
`compact`	Reduces row height and spacing.	Aura, Lumo
`wrap-cell-content`	Allows cell content to wrap onto multiple lines instead of truncating.	Aura, Lumo

no-border

Removes the outer border around the grid.

Aura, Lumo

no-row-borders

Removes the horizontal borders between rows.

Aura, Lumo

column-borders

Adds vertical borders between columns.

Aura, Lumo

row-stripes

Alternates row background colors to improve readability.

Aura, Lumo

compact

Reduces row height and spacing.

Aura, Lumo

wrap-cell-content

Allows cell content to wrap onto multiple lines instead of truncating.

Aura, Lumo

Attributes

The following attributes are specific to treeDataGrid:

Name Description Default

Name	Description	Default
`allRowsVisible`	If `true`, all rows are displayed at once with no scroll bars, effectively disabling virtual scrolling. This means that instead of only rendering the visible rows and loading more as the user scrolls, the grid will render all the rows in the DOM simultaneously. Using this feature is discouraged for a large number of items as it may cause performance issues.	`false`
`columnReorderingAllowed`	If `true`, enables users to change the order of columns.	`false`
`detailsVisibleOnClick`	If `true`, enables item details to be revealed on mouse click.	`true`
`dropMode`	Determines rows where a drop can happen. Possible values: `BETWEEN`, `ON_TOP`, `ON_TOP_OR_BETWEEN`, `ON_GRID`. This feature might be used, for example, to reorder rows and to drag rows between grids.	—
`editorBuffered`	If `true`, activates buffered mode for inline editing meaning that the user must confirm making changes by clicking a confirm button. This mode also allows users to cancel their changes. In unbuffered mode changes are applied without the need for confirmation.	`false`
`emptyStateText`	Sets the empty state text.	—
`hierarchyProperty`	Defines the name of the entity attribute, which refers to the same entity.	—
`metaClass`	Sets the meta class.	—
`multiSort`	If `true`, enables sorting by multiple columns.	`false`
`multiSortOnShiftClickOnly`	If `true`, multi-sorting is activated only when clicking on the column header while holding down the Shift key.	`false`
`multiSortPriority`	Determines whether the clicked column is added to the end or beginning of the sorted columns list. Possible values: `PREPEND`, `APPEND`.	`PREPEND`
`nestedNullBehavior`	Sets the behavior when parsing nested properties which may contain null values in the property chain. Possible values: `THROW`, `ALLOW_NULLS`.	`THROW`
`pageSize`	Determines the page size or the number of items that will be fetched from the data provider at a time.	`50`
`rowDraggable`	If `true`, enables users to drag rows in the grid.	`false`
`selectionMode`	Sets the selection mode. Possible values: `SINGLE`, `MULTI`.	`SINGLE`
`showOrphans`	If `false` orphan records are not shown. If `true`, orphan records will appear at the top level as roots. An orphan record is a child record that refers to a non-existent parent, often occurring when data is loaded partially due to filtering or paging. While not showing orphans seems logical with filters, it can lead to empty or partially filled pages. It is discouraged to use the `treeDataGrid` component together with `simplePagination`.	`false`

allRowsVisible

If true, all rows are displayed at once with no scroll bars, effectively disabling virtual scrolling. This means that instead of only rendering the visible rows and loading more as the user scrolls, the grid will render all the rows in the DOM simultaneously. Using this feature is discouraged for a large number of items as it may cause performance issues.

false

columnReorderingAllowed

If true, enables users to change the order of columns.

false

detailsVisibleOnClick

If true, enables item details to be revealed on mouse click.

true

dropMode

Determines rows where a drop can happen. Possible values: BETWEEN, ON_TOP, ON_TOP_OR_BETWEEN, ON_GRID. This feature might be used, for example, to reorder rows and to drag rows between grids.

—

editorBuffered

If true, activates buffered mode for inline editing meaning that the user must confirm making changes by clicking a confirm button. This mode also allows users to cancel their changes. In unbuffered mode changes are applied without the need for confirmation.

false

emptyStateText

Sets the empty state text.

—

hierarchyProperty

Defines the name of the entity attribute, which refers to the same entity.

—

metaClass

Sets the meta class.

—

multiSort

If true, enables sorting by multiple columns.

false

multiSortOnShiftClickOnly

If true, multi-sorting is activated only when clicking on the column header while holding down the Shift key.

false

multiSortPriority

Determines whether the clicked column is added to the end or beginning of the sorted columns list. Possible values: PREPEND, APPEND.

PREPEND

nestedNullBehavior

Sets the behavior when parsing nested properties which may contain null values in the property chain. Possible values: THROW, ALLOW_NULLS.

THROW

pageSize

Determines the page size or the number of items that will be fetched from the data provider at a time.

50

rowDraggable

If true, enables users to drag rows in the grid.

false

selectionMode

Sets the selection mode. Possible values: SINGLE, MULTI.

SINGLE

showOrphans

If false orphan records are not shown. If true, orphan records will appear at the top level as roots. An orphan record is a child record that refers to a non-existent parent, often occurring when data is loaded partially due to filtering or paging. While not showing orphans seems logical with filters, it can lead to empty or partially filled pages. It is discouraged to use the treeDataGrid component together with simplePagination.

false

The following shared attributes are supported by treeDataGrid:

id - alignSelf - classNames - colspan - css - dataContainer - enabled - height - maxHeight - maxWidth - minHeight - minWidth - tabIndex - themeNames - visible - width

Handlers

The following handlers are specific to treeDataGrid:

Name Description

Name	Description
`CellFocusEvent`	`com.vaadin.flow.component.grid.CellFocusEvent` fired when a cell in the data grid is focused. Corresponds to the `grid-cell-focus` DOM event.
`CollapseEvent`	com.vaadin.flow.component.treegrid.CollapseEvent is fired when an item is collapsed.
`ColumnReorderEvent`	`com.vaadin.flow.component.grid.ColumnReorderEvent` fired when the columns in the data grid are reordered. Corresponds to the `column-reorder-all-columns` DOM event.
`ColumnResizeEvent`	`com.vaadin.flow.component.grid.ColumnResizeEvent` fired when a data grid column is resized by the user. Corresponds to the `column-drag-resize` DOM event.
`ExpandEvent`	`com.vaadin.flow.component.treegrid.ExpandEvent` is fired when an item is expanded.
`GridDragEndEvent`	`com.vaadin.flow.component.grid.dnd.GridDragEndEvent` - drag end event of dataGrid rows. Corresponds to the `grid-dragend` DOM event.
`GridDragStartEvent`	`com.vaadin.flow.component.grid.dnd.GridDragStartEvent` - drag start event of dataGrid rows. Corresponds to the `grid-dragstart` DOM event.
`GridDropEvent`	`com.vaadin.flow.component.grid.dnd.GridDropEvent` - drop event that occurs on the data grid or its rows. Corresponds to the `grid-drop` DOM event.
`ItemClickEvent`	`com.vaadin.flow.component.grid.ItemClickEvent` fired when a data grid item is clicked. Corresponds to the `item-click` DOM event.
`ItemDoubleClickEvent`	`com.vaadin.flow.component.grid.ItemDoubleClickEvent` fired when a data grid item is double-clicked. Corresponds to the `item-double-click` DOM event.
`SortEvent`	`com.vaadin.flow.data.event.SortEvent` - event describing a change in sorting of a DataProvider. Fired by `SortNotifiers`.
`dataGenerator`	Adds a data generator for the data grid. If the generator was already added, does nothing. See the `com.vaadin.flow.data.provider.HasDataGenerators` interface.
`dragFilter`	Allows to control which specific rows can be dragged, rather than making all rows draggable with rowDraggable.
`dropFilter`	Allows to control which specific rows are valid drop targets.
`enterPressHandler`	Handles the event when the user presses the Enter key.
`partNameGenerator`	Generates parts of CSS class names for cells based on given conditions. This allows for customizing cell appearance based on the data displayed.
`tooltipGenerator`	Generates tooltip for the column cell based on given conditions. See live demo.

CellFocusEvent

com.vaadin.flow.component.grid.CellFocusEvent fired when a cell in the data grid is focused. Corresponds to the grid-cell-focus DOM event.

CollapseEvent

com.vaadin.flow.component.treegrid.CollapseEvent is fired when an item is collapsed.

ColumnReorderEvent

com.vaadin.flow.component.grid.ColumnReorderEvent fired when the columns in the data grid are reordered. Corresponds to the column-reorder-all-columns DOM event.

ColumnResizeEvent

com.vaadin.flow.component.grid.ColumnResizeEvent fired when a data grid column is resized by the user. Corresponds to the column-drag-resize DOM event.

ExpandEvent

com.vaadin.flow.component.treegrid.ExpandEvent is fired when an item is expanded.

GridDragEndEvent

com.vaadin.flow.component.grid.dnd.GridDragEndEvent - drag end event of dataGrid rows. Corresponds to the grid-dragend DOM event.

GridDragStartEvent

com.vaadin.flow.component.grid.dnd.GridDragStartEvent - drag start event of dataGrid rows. Corresponds to the grid-dragstart DOM event.

GridDropEvent

com.vaadin.flow.component.grid.dnd.GridDropEvent - drop event that occurs on the data grid or its rows. Corresponds to the grid-drop DOM event.

ItemClickEvent

com.vaadin.flow.component.grid.ItemClickEvent fired when a data grid item is clicked. Corresponds to the item-click DOM event.

ItemDoubleClickEvent

com.vaadin.flow.component.grid.ItemDoubleClickEvent fired when a data grid item is double-clicked. Corresponds to the item-double-click DOM event.

SortEvent

com.vaadin.flow.data.event.SortEvent - event describing a change in sorting of a DataProvider. Fired by SortNotifiers.

dataGenerator

Adds a data generator for the data grid. If the generator was already added, does nothing. See the com.vaadin.flow.data.provider.HasDataGenerators interface.

dragFilter

Allows to control which specific rows can be dragged, rather than making all rows draggable with rowDraggable.

dropFilter

Allows to control which specific rows are valid drop targets.

enterPressHandler

Handles the event when the user presses the Enter key.

partNameGenerator

Generates parts of CSS class names for cells based on given conditions. This allows for customizing cell appearance based on the data displayed.

tooltipGenerator

Generates tooltip for the column cell based on given conditions. See live demo.

The following shared handlers are supported by treeDataGrid:

AttachEvent - BlurEvent - DetachEvent - FocusEvent

Elements

Elements of dataGrid provide a wide range of options to control the appearance, behavior, and functionality of columns both collectively and individually.

To add an element to a selected component click the Add button in the Jmix UI inspector panel.

columns

The columns element can specify a set of attributes to display and behaviors for all columns.

XML Element	`columns`
Attributes	exclude - includeAll - resizable - sortable
Elements	column

XML Element

columns

Attributes

exclude - includeAll - resizable - sortable

Elements

column

Table 1. Attributes
Name	Description	Default
exclude	Excludes specific attributes from being shown. Several attributes must be separated with a comma. For example: `exclude = "id, version, sortValue"`.	—
includeAll	If `true` includes all the attributes specified in the corresponding data container’s fetch plan.	—
resizable	If `true`, all columns are user-resizable.	`false`
sortable	If `true`, all columns are sortable.	`true`

column

The column element defines an individual column. Attributes set for an individual column override those set for all columns.

XML Element	`column`
Attributes	autowidth - editable - filterable - flexGrow - footer - frozen - header - key - property - resizable - sortable - textAlign - visible - width
Handlers	AttachEvent - DataGridColumnVisibilityChangedEvent - DetachEvent - partNameGenerator - renderer - tooltipGenerator
Elements	Aggregation - FragmentRenderer - dataGrid Renderers

XML Element

column

Attributes

autowidth - editable - filterable - flexGrow - footer - frozen - header - key - property - resizable - sortable - textAlign - visible - width

Handlers

AttachEvent - DataGridColumnVisibilityChangedEvent - DetachEvent - partNameGenerator - renderer - tooltipGenerator

Elements

Aggregation - FragmentRenderer - dataGrid Renderers

Table 2. Attributes
Name	Description	Default
autoWidth	If `true`, the column width will adjust to its contents.	`false`
editable	If `true`, the column can be edited. See Inline Editing.	`false`
filterable	If `true` enables filtering for this column. See Filtering.	`false`
flexGrow	Sets the flex grow ratio for this column. When set to `0`, the column width is fixed.	`0`
footer	Sets a footer text to the column. The attribute value can either be the text itself or a key in the message bundle. In case of a key, the value should begin with the `msg://` prefix.	–
frozen	If `true`, freezes (locks in place) the column, so that it remains visible as the user scrolls the table horizontally. It’s generally recommended to freeze columns from left to right.	`false`
header	Sets the column header text. The attribute value can either be the text itself or a key in the message bundle. In case of a key, the value should begin with the `msg://` prefix.	–
key	Sets the user-defined identifier to map this column. The key can be used to fetch the column later with the `getColumnByKey(String)` method. The key has to be unique within the data grid, and it can’t be changed after set once.	—
property	Specifies the name of an entity attribute to be displayed in the column. This can be an attribute of the root entity `property = "user"` or an attribute of its child entity property = `user.department.name (use dot notation to traverse the object graph).	—
resizable	If `true`, the column is user-resizable.	`false`
sortable	If `true`, the column is sortable.	`false`
textAlign	Specifies the alignment of the text with the following possible values: `START`, `CENTER`, `END`. See Text Alignment.	`START`
visible	If `true`, the column is visible.	`true`
width	Sets the width of the column as a CSS string.	—

Table 3. Handlers
Name	Description
DataGridColumnVisibilityChangedEvent	Fired when the column visibility is changed through the gridColumnVisibility component.
partNameGenerator	Generates parts of CSS class names for this column based on given conditions. This allows for customizing cell appearance based on the data displayed. See live demo.
renderer	Renders column content using text or components. See text renderer and component renderer.
tooltipGenerator	Generates tooltip for the column cell based on given conditions. See live demo.

The contextMenu element organizes items the right-click menu in a way that differs from their default arrangement. See the example.

XML Element	`contextMenu`
Attributes	id - classNames - css - enabled - visible
Handlers	AttachEvent - DetachEvent - GridContextMenuOpenedEvent - openedChangeEvent - dynamicContentHandler
Elements	item - separator

XML Element

contextMenu

Attributes

id - classNames - css - enabled - visible

Handlers

AttachEvent - DetachEvent - GridContextMenuOpenedEvent - openedChangeEvent - dynamicContentHandler

Elements

item - separator

Table 4. Handlers
Name	Description
GridContextMenuOpenedEvent	Fired when the context menu opened state changes. May return the target item or the id of the target column allowing the menu to display items based on the clicked item.
openedChangeEvent	Fired when the context menu opened state changes.
dynamicContentHandler	Handles dynamic updates to the menu when it opens, such as adding menu items or their content. See the relevant `datagrid` example.

treeDataGrid

Overview

Basics

Actions

Context Menu

Theme Variants

Attributes

Handlers

Elements

columns

column

contextMenu

See Also