Data Grid 2

Last modified: November 19, 2024

Introduction

Data Grid 2 is the successor to the standard data grid widget for displaying content in a tabular form. It comes with many powerful new features and settings like support for widgets, row and cell coloring, responsive layout, accessibility, and paging options like virtual scrolling. The Data Grid 2 widget offers personalization support so that end-users can show, hide, and re-order columns. Personalizations can be persisted in the database for flexibility and control.

This document focusing on explaining module features. For precise details on data grid 2 widget properties, see Data Grid 2 Properties.

The data source determines which objects will be shown in a Data Grid 2 widget. In v2.3.0 and above, selecting the entity of the data source will automatically fill the contents, create columns with filters, and create buttons. You can also select which columns to use for the content generation.

The widget also uses a flexible approach for filtering. You can drag data-grid-specific widgets into the header of the grid and tailor the behavior of the filters. There are filters for text, numbers, and dates, and there is an option to add drop-down filters for single or multiple selections.

Here is an example of a data grid using filters:

You can enable these advanced options to customize your data grid:

Pagination type
Pagination position
Empty list option
Dynamic row and cell class
Column capabilities
Custom configuration
Header Filters

Capabilities

In the new data grid, you are able to choose how users can iterate within the grid. Iteration capabilities are listed below.

Sorting

Sorting enables the header to be clickable. When clicked it will switch between ascending, descending, and no sorting. This functionality can be discerned according to the arrows on the right side:

Arrow up: ascending sorting applied
Arrow down: descending sorting applied
Double-sided arrow: no sorting is applied

Resizing

Resizing enables the header to be resizable by dragging the handle on the right side of a header. Here is an example of the handle indicating the column is resizable:

Handle indicating the column is resizable

Reordering

Reordering enables the header to be reordered by dragging and dropping in another column. When dragging, a black handle indicates where the column can be dropped:

Here is an example of reordering in progress:

Hiding

Hiding enables a column to be hidden. When this option is enabled for any column, a button with an eye icon () will appear on the right side of the data grid like the example below. It contains all the columns hidden by default or enabled to be hidden. When de-selected, the column will not be visible in the grid anymore.

Here is an example of hiding button containing columns to be hidden:

When a column is marked as “Yes, hidden by default” it will render differently in Structure mode and Design mode and to indicate that the column is hidden. When running the application, the column will in fact be hidden by default.

Here is an example containing a column with Yes, hidden by default in Structure mode:

Here is an example containing a column with Yes, hidden by default in Design mode:

Allow Row Events

Allow Row Events is only available when a column is set to Custom Content.

When set to Yes, default events such as On click action or selection will be triggered when the user interacts with the content.

If a column contains interactive elements such as buttons, this might lead to unexpected behavior when both a click on the button and the action configured on the row are triggered. To prevent default events from triggering when interacting with content, set this setting to No.

Pagination

This widget does not support system texts, meaning is not possible to translate its content to another language.

In the new data grid we offer two types of pagination: Paging Buttons and Virtual Scrolling.

Paging Buttons

The Paging Buttons option will render the default buttons as the previous data grid. When the data source is uncountable (for example, external entities), neither the last page button nor the counting will be available.

You can configure pagination based on the following properties:

Position — The Position of paging button options allow you to position paging buttons above or below the data grid.
Visibility — The Show paging buttons options allow you to always show paging, or to automatically show and hide paging based on the amount of available data compared to the display limit per page.

Virtual Scrolling

The Virtual Scrolling option forces the data grid to show a fixed amount of items (defined in the page size option) within a scrollable container. When the end-user reaches the bottom of the scrollable container it fetches more items automatically.

Load More

This option functions similarly to the Virtual Scrolling feature, but instead of automatically loading data as the end-user scrolls, a button is displayed at the end of the list of items. Clicking this button enables the end-user to fetch more items.

Columns

In Data Grid you can choose what you want to render into columns. This can be an attribute, dynamic text, or even a combination of widgets (custom content). To choose what you want to render, open a column in the column list and select the appropriate option according to your needs.

Here is an example of column properties:

Attribute

Attribute renders the value of a selected attribute.

Dynamic Text

Dynamic Text renders a text-templated string which can contain text combined with attributes:

Custom Content

Custom Content allows users to drop widgets into the data grid and use the column attribute value to show custom content. After selecting this option you will be given dropzones in which to drop your widgets.

Here is an example of custom content using new Badge widget in Structure mode:

For more information on configuring various widget properties, see Common Widget Properties.

Column Width

You can define how each cell will be rendered in the data grid. We offer three choices:

Auto-fill — With this option it will auto define the width of your column, if all columns are using auto-fill, it will divide evenly the same width, if another column is configured with auto-fit or manual, it will fill the available space.
Auto-fit — Content With this option it will calculate the width of your column based on the content of each row.
Manual — With this option you will manually define the size of your column based of flexbox grow values, for more information, please check here.

Alignment

You can choose how the content inside your columns will be aligned. We offer three choices: left, center, and right.

This will also change the alignment of your header.

Settings for alignment of each column item

Dynamic Cell Class

In the new data grid we offer an option to dynamically apply a CSS class in a specific cell. You can achieve this by adding an expression based on the column value (attribute) like the example below.

In this example we check the value of StringAttribute and then apply the class .my-name-class if the attribute is equal to my name to the cell:

Wrap Text

You can choose if you want to wrap the text content of a column and apply ellipsis in the end of it.

If you are using Custom content in the Show option of the General tab, please make sure you are using a Text Widget without containers around it. Containers sometimes interfere with wrapping texts.

If you need to display advisory information for cell content, you can specify the tooltip text. This text will be shown when a user is hovering over the cell content.

This property is not available if you enable Custom content for the column

Association Filter

Reference — this property defines the association that will be used for filtering. When set, it enables filtering over association with the Drop-down filter. Drop-down filter will prioritize this property over Attribute property.
Data source — defines data source for filter options. The data source should return list of all possible entities that could be associated with a parent.
Use lazy load — When set to Yes, data for the filter will be fetched only when the drop-down filter is opened. This improves the loading times of the data grid, but limits the functionality of saving filter values. For more details, see Drop-down Filter.
Option caption — the expression that will be used as caption for the option.

This column configuration is intended to be used in conjunction with Drop-down Filter. Other filter types do not support association filtering.

Visible

When using a data grid, sometimes columns do not need to be shown. Using this Visible expression configuration, you can specify when you want to display columns

Rows

This section defines options for the rows of the grid.

Empty List Message

The Empty List Message option defines what users can see when the data grid does not have a value to be presented or when a filter is applied without results. When this option is defined as custom you can place widgets right above the rows in a dropzone. Here is an example:

Dynamic Row Class

The Dynamic Row Class option allows users to dynamically apply a CSS class in a specific row. This option will apply for the entire row the same class. You can achieve this by adding an expression based on the column value (attribute), like the example below.

If you have a dynamic cell class being applied it will have precedence over the row class.

In this example we check the value of StringAttribute and then apply the class .my-name-class if the attribute is equal to my name to the row:

Events

The new data grid can trigger some events while iterating with it.

On Click Action

Triggers an action (such as a nanoflow, microflow, or Show page action) when the end-user clicks in one of the rows. It also adds a pointer cursor to signal that it is clickable. This function also complies with accessibility features and can be reached using only the keyboard.

Filters

Sets of filters can be used in combination with data grids. To be able to use filters you need to select the option Show column filters. When this option is selected a drop-zone where you can place your desired filter widget will appear in each column header.

The type of your selected attribute should match the filter type. For example, a Text filter should be used for a String attribute.

Also the desired attribute must be filterable. For example, not a value which is calculated.

Here is an example of dropzones for filters in Structure mode:

Date Filter

Date filter allows users to match date attributes based on these predefined criteria:

Between
Greater than
Greater than or equal
Equal
Not equal
Smaller than
Smaller than or equal

Here is an example of Date filter as Between:

When Date filter is defined with Between it is not possible to type the date manually. It also has a clear button to clear the date range.

You can select your filter criteria in the Date Filter settings:

When Adjustable by user is defined as No it will not render the option to choose the filter type in the widget.

Here is an example of available filter types for Date Filter:

Here is an example of Date Filter with Adjustable by user defined as No:

Example of Date filter with “Adjustable by user” set as No

You can also define the default value of the widget which will be predefined as initial value when opening your data grid page.

When Default filter is defined as Between these fields will appear to define the start and end dates:

Example of Date filter with “Default value” set as Between

Configurations

In this section you can select a Saved attribute in order to save the current value of the filter. However, the value is not automatically applied to the widget. To restore the previously saved value of the filter, you must configure the same attribute as the Default value of the widget. The attribute available in this section must be this type:

Date & Time

Events

In this section you can select an action to be executed On change by the filter value. This means every time the user types or selects a value it will be executed.

Drop-Down Filter

Drop-down filter allows users to match enumeration values, Boolean attributes, or an association attribute. To configure the available options when you press the drop-down filter, you can manually add them to the options list or select Automatic options to automatically load the values:

Example of settings for drop-down filter

When a drop-down filter is used in conjunction with an Association Filter data grid configuration, only Automatic options are supported. Any custom options will be ignored. To enable association filtering, see the Association Filter section.

Due to current limitations, Default value property will be ignored when a drop-down filter is used in conjunction with an Association Filter data grid configuration.

Due to current limitations, Saved attribute property will be ignored when a drop-down filter is used in conjunction with an Association Filter data grid configuration where Use lazy load is set to Yes. This limitation also applies when using page state, meaning that the filter value used in the drop-down filter will not persist when navigating between pages.

When adding a new option, the following properties are required:

Caption — The text being rendered for each option in the drop-down.
Value — The corresponding value that will be compared, if a value is being compared with an enumeration, it should match exactly the enumeration value. This property allows the usage of expression (you can use conditionals to apply dynamic values).

This widget also allows multiple selections by selecting Multiselect in the settings. Multiple selections can look like this:

Example of multi select drop-down filter

You can also define the empty option caption, which will be rendered as the first item if Multiselect if set as No. It allows users to clean the filter if pressed.

Configurations

String

If Multiselect is enabled you must select a String attribute containing Unlimited in its size.

Events

In this section you can select an action to be executed On change by the filter value. This means every time the user types or selects a value it will be executed.

Number Filter

The Number filter allows users to match decimal, integer, and long attributes based on these predefined criteria:

Greater than
Greater than or equal
Equal
Not equal
Smaller than
Smaller than or equal

You can select your filter criteria in the Number Filter settings:

When Adjustable by user is defined as No it will not render the option to choose the filter type in the widget.

Here is an example of available filter types for Number Filter:

Here is an example of Number Filter with Adjustable by user set as No:

You can also define the default value of the widget, which will be predefined as initial value when opening your data grid page.

To have better control of when the filter will be applied, we offer a Apply after (ms) option under the On change behavior group. This option will only trigger the filter after a predefined period of time while typing. By default, Mendix suggests 500ms.

Configurations

Autonumber
Decimal
Integer
Long

Events

In this section you can select an action to be executed On change by the filter value. This means every time the user types or selects a value it will be executed.

Text Filter

Text filter allows users to match string attributes based on these predefined criteria:

Contains
Starts with
Ends with
Greater than
Greater than or equal
Equal
Not equal
Smaller than
Smaller than or equal

You can select your filter criteria in the Text filter settings:

When Adjustable by user is defined as No it will not render the option to choose the filter type in the widget.

Here is an example of available filter types for Text Filter:

Here is an example of Text Filter with Adjustable by user set to No:

Example of text filter with “Adjustable by user” set as No

You can also define the default value of the widget, which will be predefined as initial value when opening your data grid page.

Configurations

Hashed string
String

Events

In this section you can select an action to be executed On change by the filter value. This means every time the user types or selects a value it will be executed.

Grid Wide Filtering

In order to enable filtering within the data grid header (outside the columns) you need to enable Grid wide filters and select the desired attributes to be filtered in the Filtering tab. You can select attributes of the following types:

Autonumber
Boolean
Date & time
Decimal
Enumeration
Hashed string
Integer
Long
String

The attributes selected here will be used for the matching filter placed inside the composable region. Only the first keyword in the filter will be considered when filtering multiple attributes in grid wide filtering

When using multiple attributes, the filters will automatically select the matching attributes and then compose the desired filter value in an OR expression. Make sure you only have one filter widget for each type, for example Text Filter and Number Filter.

If a filter is being used and its type does not match with any selected attribute, then it will throw an error requesting you to select the correct filter widget.

There cannot be more than one filter of the same type in the data grid header. For example, if a data grid header already has a Number Filter, adding another Number Filter will cause incorrect data filtering.

Export to Excel

The Data Grid 2 widget ships with built-in functionality to export data from the data source you configured in the settings. The export is done via the Export_To_Excel JavaScript action that is distributed as part of the Data Widgets module.

To export data from the data grid, create a new nanoflow that calls Export_To_Excel. The Export_To_Excel action has a set of inputs:

Datagrid name - the name of the data grid from which data should be exported (the name can be found and copied from the data grid’s settings (Properties > Common > Name))
File name - the file name to use for the exported document (does not require an appended file extension)
Sheet name - the name to use for the Excel sheet of the exported document
Include column names - a Boolean expression that, if true, tells the action to include column captions as the first row in the exported document
Chunk size - the number of rows fetched from the backend to the browser at a time.

The recommended value for Chunk Size is 200. However, because each data grid has a unique set of columns and varying amounts of data per row, a different chunk size might result in better performance.

Configuration

You can define an attribute to store the current configuration of the data grid. In this way, if you re-open your page then the current sorted columns, order, and hidden columns will remain the same as in the previous state. To set this option, you need to select a String attribute with Unlimited as its size as the attribute in the data grid Personalization tab in Studio Pro.

If the desired String attribute does not contain Unlimited in its size, the Data grid will not be able to save all the configurations as expected.

Here is an example of an unlimited string attribute:

In order to select an attribute, you need to surround the new Data grid with a Data view. This will allow you to select an attribute. You can also define an action when the attribute will be updated with the new configurations.

Here is an example of a configuration containing an On change action:

Example of a configuration containing on change action

Performance

The performance of the new data grid can be affected if sorting or filtering are enabled. This is because Data widgets v1.1 - 1.2 retrieve all available values for sorting or filtering while the widget runs. This problem does not occur in versions above 1.3 because those versions use Filtering APIs to retrieve only the necessary data.

Troubleshooting

If you are using Atlas v2.x and you cannot upgrade to Atlas 3 at the moment, please replace the line 3 cssFiles with the following code in the file theme/settings.json:

"cssFiles": [ 
    "styles/web/css/main.css", 
    "theme.compiled.css" 
],

In-Memory Selection

In-memory selection was introduced in Data Widgets v2.7.0.

Enabling selection allows users to select a row by clicking the row or a checkbox. Selection is disabled by default, and can be activated by changing the Selection setting from None to either Single or Multi.

Since the data grid widget keeps selected items in short-living memory that is cleared every time you change the data grid page, selecting items across multiple pages is not supported. This means that the end-user can only select items that are currently visible.

Selection Mode

In Single selection mode, users are limited to selecting one row at a time.

In Multi mode, the user can select multiple rows.

Selection Method

When selection is enabled, you can choose a method for selecting rows. The Checkbox method adds a checkbox to the beginning of each row, and the end-user must click the checkbox to select the row. By contrast, the Row method does not add any additional controls to the row, and the end-user must click the row itself to select that row.

Show (Un)check All Toggle

If this setting is enabled, then the data grid widget shows a checkbox at the header. This checkbox controls the selection for all visible items. Clicking on this checkbox will select all visible items. If all items are already selected, clicking the checkbox clears the selection.

Selection and Row Click Action

The On click trigger setting was introduced in Data Widgets v2.13.0. Previous versions did not allow both selection and click actions at the same time.

The data grid settings support the case where it is possible to have both a selection and an on-click action at the same time.

The setting for action triggers is related to the selection method and can sometimes be ambiguous. See the table below to see which combinations of selection method and trigger are supported.

Selection method	Action trigger	Selection trigger	Supported
Checkbox	Single click on the row	Click on the checkbox, `Ctrl` + click on the row (or `Command` + click on the row on Mac)	Yes
Checkbox	Double-click on the row	Click on the checkbox, `Ctrl` + click on the row (or `Command` + click on the row on Mac)	Yes
Row	Single click on the row		No
Row	Double-click on the row	`Ctrl` + click on the row (or `Command` + click on the row on Mac)	Yes

To achieve this behavior, set the On click trigger to Double click. When a data grid is configured this way, the user may select a row by double-clicking it.

Keyboard Support

Key	Function
`→`	Moves focus one cell to the right.
`←`	Moves focus one cell to the left.
`↓`	Moves focus one cell down.
`↑`	Moves focus one cell up.
`Page up`	Moves focus one page up.
`Page down`	Moves focus once page down.
`Home`	Moves focus to the first cell in the row.
`End`	Moves focus to the last cell in the row.
`Ctrl` + `Home`	Moves focus to the first cell in grid.
`Ctrl` + `End`	Moves focus to the last cell in grid.
`Shift` + `Space`	Selects current row. (1)
`Ctrl` + `A`	Select all visible rows. (1)(2)
`Shift` + `↑`/`↓`	Moves focus and selects current and row above/below. (1)(2)
`Shift` + `Page up`/`Page down`	Moves focus one page up/down and selects all rows between current and final row. (1)(2)
`Shift` + `Home`/`End`	Moves focus to the start/end of the grid and selects all rows between current and final row. (1)(2)

Legend:

Symbol	Meaning
1	Available only when selection is enabled.
2	Available only when selection mode should be “Multi”.

Resetting Filters

Resetting filters is possible using Reset_Filter and Reset_All_Filters actions available as part of the Data Widgets module. Setting up these actions is a manual process that requires creating a nanoflow and setting the name of the filter or data grid to be reset.

The name of the filter or data grid can be found at Properties > Common > Name.

Data Grid 2

Introduction

Capabilities

Sorting

Resizing

Reordering

Hiding

Allow Row Events

Pagination

Paging Buttons

Virtual Scrolling

Load More

Columns

Attribute

Dynamic Text

Custom Content

Column Width

Alignment

Dynamic Cell Class

Wrap Text

Tooltip

Association Filter

Visible

Rows

Empty List Message

Dynamic Row Class

Events

On Click Action

Filters

Date Filter

Configurations

Events

Drop-Down Filter

Configurations

Events

Number Filter

Configurations

Events

Text Filter

Configurations

Events

Grid Wide Filtering

Export to Excel

Configuration

Performance

Troubleshooting

In-Memory Selection

Selection Mode

Selection Method

Show (Un)check All Toggle

Selection and Row Click Action

Keyboard Support

Resetting Filters

Feedback