treeDataGrid

A table of data that features collapsible sections in one of its columns. It resembles dataGrid and supports most of its functionality, but is better suited for datasets that require intuitive navigation through hierarchical data.

XML Element

treeDataGrid

Java Class

TreeDataGrid

Attributes

id - alignSelf - allRowsVisible - classNames - colspan - columnReorderingAllowed - css - dataContainer - detailsVisibleOnClick - dropMode - editorBuffered - enabled - height - hierarchyProperty - maxHeight - maxWidth - metaClass - minHeight - minWidth - multiSort - multiSortOnShiftClickOnly - multiSortPriority - nestedNullBehavior - pageSize - rowDraggable - selectionMode - showOrphans - tabIndex - themeNames - visible - width

Handlers

AttachEvent - BlurEvent - CellFocusEvent - CollapseEvent - ColumnReorderEvent - ColumnResizeEvent - DetachEvent - ExpandEvent - FocusEvent - GridDragEndEvent - GridDragStartEvent - GridDropEvent - ItemClickEvent - ItemDoubleClickEvent - SortEvent - dataGenerator - dragFilter - dropFilter - enterPressHandler - partNameGenerator - tooltipGenerator

Elements

actions - columns - column - contextMenu

Basics

treeDataGrid primarily replicates the functionality of the dataGrid component.

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

<data readOnly="true">
    <collection id="departmentsDc"
                class="com.company.onboarding.entity.Department"> (1)
        <fetchPlan extends="_base">
            <property name="hrManager" fetchPlan="_base"/>
            <property name="parentDepartment" fetchPlan="_base"/>
        </fetchPlan>
        <loader id="departmentsDl">
            <query>
                <![CDATA[select e from Department e]]>
            </query>
        </loader>
    </collection>
</data>
<layout>
            <treeDataGrid
                          hierarchyProperty="parentDepartment"
                          width="100%"
                          minHeight="20em"
                          dataContainer="departmentsDc"> (2)
                <columns> (3)
                    <column property="name"/>
                    <column property="hrManager"/>
                </columns>
            </treeDataGrid>
</layout>
1 Collection container for the Department entity.
2 treeDataGrid is bound to the departmentsDc container using the dataContainer attribute.
3 The columns element defines which entity attributes are shown in the tree data grid columns.
tree data grid basics

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.

tree data grid actions

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.

Show code
<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"> (2)
    <columns>
        <column property="name"/>
        <column property="hrManager"/>
    </columns>
    <actions>
        <action id="create" type="list_create"/>
        <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.

Context Menu

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.

tree data grid context menu
Show code
<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.

Attributes

In Jmix there are many common attributes that serve the same purpose for all components. The following are attributes specific to treeDataGrid:

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

hierarchyProperty

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

-

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

Handlers

In Jmix there are many common handlers that are configured in the same way for all components. The following are handlers specific to treeDataGrid:

To generate a handler stub in Jmix Studio, use the Handlers tab of the Jmix UI inspector panel or the Generate Handler action available in the top panel of the view class and through the CodeGenerate menu (Alt+Insert / Cmd+N).

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.

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

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 - LocalDateRenderer - LocalDateTimeRenderer - NumberRenderer

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.

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.

contextMenu

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

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.

See Also

See the Vaadin Docs for more information.