Data Grid 2

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 uses a flexible, modular approach for filtering. You can place dedicated filter widgets (text filter, date filter, number filter, drop-down filter) in the filters placeholder above the grid, or within individual column headers. These specialized filter widgets provide tailored behavior for different data types and use cases. This system is superior to a built-in filtering system in that it allows for a more maintainable and customizable architecture.

Here is an example of a data grid using filters:

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

• Pagination type and positioning
• Row count display
• Loading state indicators
• Empty list option
• Dynamic row and cell class
• Column capabilities
• Filter personalization settings
• Custom configuration
• Modular filtering with dedicated filter widgets

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:

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:

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

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

Pagination

The data grid offers three types of pagination: Paging buttons, Virtual scrolling, and Load more.

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 pagination options (Below grid, Above grid, or Both) set where the pagination appears. For Virtual scrolling and Load more, this option is available only when Show number of rows is set to Yes.
• 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. This option is available only when Pagination is set to Paging buttons and Custom pagination is set to No.

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.

Row Count Display

When Show number of rows is set to Yes, the pagination area displays the number of loaded rows and the total number of rows. This provides users with context about the data set size. The counter shows information such as "20 of 150", and automatically updates when users load more rows, apply filters, or refresh data. This option is available only for Virtual scrolling and Load more.

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 drop-zones 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 Properties Common in the Page Editor.

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 the header and each visible 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.

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.

Tooltip

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.

Association Filter

The drop-down filter widget supports association filtering when Filter by is set to Association:

• Entity – Defines the association that will be used for filtering.
• Selectable objects – Defines data source for filter options, returning list of all possible entities that could be associated.
• Use lazy load – Controls when filter options are loaded. When set to No (recommended), data is fetched immediately providing better personalization support. When set to Yes, data is fetched only when the filter is opened, improving initial load times but limiting personalization capabilities.
• Caption source and Caption – Set whether option captions come from an attribute or an expression, and which attribute or expression is displayed for each option in the drop-down.
• Search attribute – Sets the string attribute used for searching when Caption source is Expression and Filterable is Yes.

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 drop-zone. 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.

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.

On Selection Change Action

The On selection change property triggers an action (such as a nanoflow, microflow, or client action) when the end-user changes selection in the data grid. This includes selecting or deselecting individual rows, using the "Select all" checkbox, or clearing the selection. The action provides a way to respond to selection state changes and implement custom logic based on the current selection.

Filters

Data Grid 2 uses a modular filtering system with dedicated filter widgets that can be placed in two locations:

• Column Headers: Individual filters can be placed in column headers by enabling Show column filters. When this option is selected, a drop zone appears in each column header where you can place the appropriate filter widget.
• Filters Placeholder: Filter widgets can be placed in the filters placeholder above the grid. This allows for filtering across multiple attributes and more complex filtering scenarios.

Filter Widget Configuration

The text, number, and date filters have a Filter attributes property. The drop-down filter has an Attribute config property, which is available only when Filter by is set to Attribute. Both properties have two values:

• Auto – Uses the attribute of the column that the filter is placed in. This option works only when the filter is placed in a column.
• Custom – You select the attributes in Attributes (or the attribute in Attribute for the drop-down filter). The filter is linked to the data source of the data widget it is placed in. Use this option when the filter is placed outside a column.

When the drop-down filter's Filter by is set to Association, there is no Auto or Custom choice.

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
• Empty
• Not empty

Here is an example of Date filter as Between:

You can select the initial filter criterion in the Default filter property of the date filter:

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:

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, the Default start date and Default end date fields replace Default value so you can define the start and end dates:

Configurations

In this section you can select a Saved attribute in order to save the current value of the filter. When Default filter is set to Between, Saved attribute is replaced by Saved start date attribute and Saved end date attribute. However, the value is not automatically applied to the widget. To restore the previously saved value of the filter, you must use the same attribute in the Default value expression (or Default start date and Default end date for a range). 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 of the filter value or filter type. This means it is executed every time the user types or selects a value, or changes the filter type.

Drop-Down Filter

Drop-down filter allows users to match enumeration values, Boolean attributes, or an association. Use Filter by to choose between Attribute and Association. When filtering by attribute, Attribute config can be set to Auto (uses the attribute of the column that the filter is placed in) or Custom (you select the attribute).

To filter by association, set Filter by to Association and configure the following properties:

• Entity: selects the association (reference or reference set) to filter on
• Selectable objects: configures the data source that provides available filter options
• Caption source: sets whether option captions come from an Attribute or an Expression
• Caption: the string attribute or expression that is displayed for each option
• Search attribute: the string attribute used for searching when Caption source is Expression and Filterable is Yes
• Use lazy load: controls when options are loaded (immediately or when the filter is opened)

The filter also supports Multiselect, Filterable (search input), Clearable, Show selected items as (Text or Labels), and Selection method (Checkbox or Row click). Show selected items as is available only when Filterable and Multiselect are both set to Yes, and Selection method only when Show selected items as is set to Labels. Clearable is hidden when Filterable is set to Yes, because a filterable drop-down is always clearable.

To define the options yourself, set Automatic options to No and add items to Options. 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 setting Multiselect to Yes. Multiple selections can look like this:

You can also define the Empty option caption, which is rendered as the first item when Multiselect and Filterable are set to No. It allows users to clear the filter.

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 use the same attribute in the Default value expression. The attribute available in this section must be this type:

• 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.

Number Filter

The Number filter allows users to match autonumber, 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
• Empty
• Not empty

You can select the initial filter criterion in the Default filter property of the number filter:

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, an expression that returns a Decimal value. It is used as the initial value when your data grid page opens.

To control when the filter is applied, use the Apply after (ms) option in the On change behavior group. This option applies the filter after a predefined period of time while typing. The default value is 500 ms.

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 use the same attribute in the Default value expression. The attribute available in this section must be one of the following types:

• 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
• Empty
• Not empty

You can select the initial filter criterion in the Default filter property of the text filter:

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:

You can also define the Default value of the widget, an expression that returns a String value. It is used as the initial value when your data grid page opens.

To control when the filter is applied, use the Apply after (ms) option in the On change behavior group. This option applies the filter after a predefined period of time while typing. The default value is 500 ms.

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 use the same attribute in the Default value expression. The attribute available in this section must be one of the following types:

• 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

To filter across multiple attributes from the data grid header (outside the columns), place filter widgets in the filters placeholder. The data grid does not have its own filtering configuration. Instead, configure the filter widgets themselves. Filter widgets placed in the filters placeholder are linked to the data grid automatically. To choose which attributes a filter applies to, set Filter attributes (text, number, and date filters) or Attribute config (drop-down filter) to Custom and select the attributes. For more information, see the documentation for each filter widget:

• Text Filter
• Number Filter
• Date Filter
• Drop-Down Filter

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.

Configuration

You can store the current configuration of the data grid. In this way, if you re-open your page then the current sorted columns, column order, column widths, and hidden columns will remain the same as in the previous state. When Store filters is set to Yes, filter values are stored as well. Use Store configuration in on the data grid Personalization tab in Studio Pro to choose where the configuration is stored: Attribute or Browser local storage. Browser local storage is scoped to the browser profile, not to the Mendix user, and hides the Attribute and On change properties. When you choose Attribute, you need to select a String attribute with Unlimited as its size in Attribute.

Here is an example of an unlimited string attribute:

When Store configuration in is set to Attribute, you need to surround the data grid with a data view in order 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:

In-Memory Selection

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 (on the Behavior tab, in the Selection group) from None to either Single or Multi.

By default, the data grid widget keeps selected items in short-living memory that is cleared when the data source changes, for example when you change the data grid page. To keep the selection across pages, set Keep selection to Yes. To let the end-user select all rows across all pages, set "Select all" across pages to Yes.

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 click method does not add any additional controls to the row, and the end-user must click the row itself to select that row.

"Select All" Checkbox

If the "Select all" checkbox setting is enabled, then the data grid widget shows a checkbox at the header. This setting is available only when Selection is set to Multi and Selection method is set to Checkbox. This checkbox controls the selection for all rows on the current page. Clicking on this checkbox will select all rows on the current page. If all items are already selected, clicking the checkbox clears the selection.

Keep Selection

If this setting is enabled, then selected items persist across page navigation, data refreshes, filtering, and sorting operations.

By default, Keep selection is disabled and the selection is cleared when the data source changes. When enabled, selected items remain selected until manually cleared by the user.

Selection and Row Click Action

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 click	Single click on the row		No
Row click	Double-click on the row	Click on the row; Ctrl + click (or Command + click on Mac) toggles the row	Yes

To use the Row click selection method together with an on-click action, set the On click trigger to Double click. When a data grid is configured this way, the end-user selects a row with a single click and triggers the action by double-clicking the row.

Selection and Actions in the Filters Placeholder

When the button is placed in the filters placeholder, the assigned action can receive the currently selected rows as a parameter.

How Selection is Passed to Actions

When a button placed in the filters placeholder triggers a microflow or nanoflow, the selected rows are passed as input:

• If Selection is set to Single:
  • The action receives a single object.
• If Selection is set to Multi:
  • The action receives a list of objects.

This allows developers to build logic that operates on one or several items.

Example Use Cases

• Mark as Done: A button triggers a microflow that updates the status of selected tasks.
• Delete Selected: A button deletes all selected records.
• Export Selected: A button triggers a microflow or nanoflow that exports the selected list to a file.

Configuration

To configure selection, do the following:

1. Enable Selection in the data grid 2 widget.
2. Insert an Action Button into the Filters placeholder.
3. Configure the button to trigger a microflow or nanoflow.
4. Set the input parameter of the flow to match the selection type (single object or list).

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

The Data Widgets module includes two JavaScript actions that reset filters from a nanoflow:

• Reset Filter (Reset_Filter) – This resets a single filter widget.
• Reset All Filters (Reset_All_Filters) – This resets all filter widgets of a Data Grid 2 or Gallery widget.

Both actions are available for web apps only. In the nanoflow toolbox, you can find them in the Data widgets category.

Parameters

Both actions have the following parameters:

• targetName – The name of the widget to reset, as a String. For Reset Filter, this is the name of a text, number, date, or drop-down filter. For Reset All Filters, this is the name of a Data Grid 2 or Gallery widget. You can find the name of a widget in its properties, at Common > Name.
• setToDefault – A Boolean that sets how the filters are reset:
  • true – The filter returns to its default state. For text, number, and date filters, this is the filter type set in Default filter and the value set in Default value (or Default start date and Default end date when the default filter is Between). For the drop-down filter, this is the selection set in Default value.
  • false – The filter is emptied. Text, number, and date filters keep the filter type that is currently selected, and their value is cleared. The drop-down filter clears its selection.

Reset All Filters resets both the filters in the column headers and the filters in the filters placeholder of the data grid.

Adding a Reset Button

To add a button that resets all filters of a data grid, do the following:

1. Create a nanoflow.
2. Drag the Reset All Filters action from the Data widgets category of the toolbox into the nanoflow.
3. Set targetName to the name of the data grid, as a String expression, for example 'productsGrid'.
4. Set setToDefault to true to return the filters to their default values, or to false to clear them.
5. Place a button on the page, for example in the filters placeholder of the data grid, and set its On click action to call the nanoflow.

To reset a single filter, follow the same steps with the Reset Filter action, and set targetName to the name of the filter widget.

Troubleshooting Runtime Errors

Filter Widget Errors

Error:

"The filter widget must be placed inside the column or header of the Data grid 2.0 or inside header of the Gallery widget."

• Widget placement is incorrect.

Solution: Place the widget in the filters placeholder of Gallery or Data Grid 2, or in a Data Grid 2 column.

Error:

"Unable to get filter store. Check parent widget configuration."

• This error indicates that there is issue with widget settings. Most of the time this error happens when widget is placed in the header of Data Grid 2 or Gallery, but the Filter attributes setting (or Attribute config for the drop-down filter) is still set to Auto.

Solution: Switch Filter attributes (or Attribute config for the drop-down filter) to Custom and configure the attribute for filtering.

Error:

"The [filter] is not compatible with [datatype] data type."

• This error indicates that attribute configured in the Data Grid 2 for column is not compatible with current filter type.

Solution: Change filter to appropriate filter type. For example for string attributes use text filter.

"The attribute is not filterable. Please choose a different attribute."

• This error indicates that it is not possible to use current attribute for filtering due to technical limitations.

Solution: Read and understand why some attributes are filterable and other are not. Change the model or choose another attribute.