diff --git a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/_index.md b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/_index.md index 6920ddaee96..9a92e57262a 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/_index.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/_index.md @@ -11,17 +11,18 @@ description: "Describes the configuration and usage of the Data Widgets module, This module contains the following widgets: -* [Data Grid 2](/appstore/modules/data-grid-2/) -* [Data Grid 2 Properties](/appstore/modules/data-grid-2-properties/) -* [Drop-Down Sort](/appstore/modules/gallery/#dropdown) -* [Filters](/appstore/modules/data-grid-2/#filters) -* [Gallery](/appstore/modules/gallery/) -* [Tree node](/appstore/modules/tree-node/) +- [Data Grid 2](/appstore/modules/data-grid-2/) +- [Data Grid 2 Properties](/appstore/modules/data-grid-2-properties/) +- [Drop-Down Sort](/appstore/modules/gallery/#dropdown) +- [Filters](/appstore/modules/data-grid-2/#filters) +- [Gallery](/appstore/modules/gallery/) +- [Selection helper](/appstore/modules/selection-helper/) +- [Tree node](/appstore/modules/tree-node/) ## Migration If you were previously using the Data Grid 2 module, you must follow these steps before updating it to the new [Data Widgets](https://marketplace.mendix.com/link/component/116540) module: -1. Rename the current **DataGrid** module (under **Marketplace** modules) to *DataWidgets* in Studio Pro. +1. Rename the current **DataGrid** module (under **Marketplace** modules) to _DataWidgets_ in Studio Pro. 1. Open the Marketplace and search for **Data Widgets**. 1. Download and replace the current (renamed) DataWidgets module. diff --git a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2-properties.md b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2-properties.md index ea05d61b8bd..ee995308ae8 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2-properties.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2-properties.md @@ -27,8 +27,8 @@ The time (in seconds) the grid waits between refreshing the data. Auto-refreshin This property controls row selection capabilities. Selection is turned off by default, but can be enabled by choosing ether **Single** or **Multi**: -* The **Single** selection is selection type where only one row can be selected at the time -* The **Multi** type support selecting several rows at the time +- The **Single** selection is selection type where only one row can be selected at the time +- The **Multi** type support selecting several rows at the time {{% alert color="info" %}} Data grid currently supports only in-memory selection. This implies some limitation which allows selecting only visible rows. If you change a data grid page or reload the browser window, then selection will be cleared.{{% /alert %}} @@ -53,10 +53,24 @@ When set to **Yes**, the data grid displays a checkbox in the header that, when #### Loading Type -This property controls how loading states are displayed during data operations such as pagination, filtering, and refresh. +This property controls how loading states are displayed during data operations such as pagination, filtering, and refresh. Available options include spinner (rotating overlay) and skeleton (placeholder content). Loading indicators automatically appear during initial data load, pagination navigation, filter operations, sorting, and export operations. The system includes smart timing to prevent flickering on fast operations, and also provides appropriate timeout handling for slow operations. +### Behavior Tab + +#### Selection + +This section contains properties related to selection behavior when **Selection** is set to **Single** or **Multi**. + +#### Keep Selection + +{{% alert color="info" %}} +This property is available only when **Selection** is set to **Single** or **Multi**. +{{% /alert %}} + +When set to **Yes**, selected items persist across page navigation, data refreshes, filter operations, and sorting changes. By default, this property is set to **No**, which clears the selection whenever the datasource changes. When enabled, selections remain active until manually cleared by the user or through a nanoflow or microflow action. + ### Columns Tab {#columns} #### Columns @@ -87,7 +101,7 @@ This property controls the visibility of navigation buttons. If set to **Auto**, #### Show Number of Rows -This property displays the total number of rows in the pagination area, providing users with context about the dataset size. +This property displays the total number of rows in the pagination area, providing users with context about the dataset size. When enabled, it shows information such as **1 to 20 of 150**. It works with virtual scrolling, load more pagination, and standard pagination modes. On large datasets, the total count calculation may impact initial load time. @@ -115,9 +129,9 @@ This property sets the action to be performed when the row is clicked. This property sets the action to be performed when the row is selected or unselected. -#### Filters {#filters-placeholder} +#### Filters {#filters-placeholder} -This placeholder acts as a container for filter widgets that operate on the entire grid. This placeholder provides a designated area for placing filter widgets (text filter, date filter, number filter, drop-down filter) that filter across all grid data rather than being limited to individual columns. +This placeholder acts as a container for filter widgets that operate on the entire grid. This placeholder provides a designated area for placing filter widgets (text filter, date filter, number filter, drop-down filter) that filter across all grid data rather than being limited to individual columns. Filter widgets placed here automatically link to the grid's datasource, and changes immediately affect the grid data. Still, widgets should be configured to work properly. Multiple filters work together using **AND** logic by default. @@ -143,7 +157,7 @@ This flag controls column hiding for the entire data grid. If set to **No**, the #### Store Filters in Personalization -This property controls whether filter states are saved as part of user personalization settings or not. When enabled, the system preserves filter input values, selected filter types, applied filter combinations, filter visibility states, and custom filter configurations in the user's personalization profile. +This property controls whether filter states are saved as part of user personalization settings or not. When enabled, the system preserves filter input values, selected filter types, applied filter combinations, filter visibility states, and custom filter configurations in the user's personalization profile. Filter states can be stored in browser localStorage or database attributes depending on personalization configuration. When enabled, users' filter preferences persist across sessions and page refreshes. When disabled, filters reset to default values on every page load — useful for shared screens, dashboards, or public interfaces. @@ -181,7 +195,7 @@ Defines a string value that labels the checkbox of the row when the selection is #### Select All Rows -This property provides an ARIA label for the **Select All** checkbox in the grid header. This ARIA label is announced by screen readers when users navigate to the select all checkbox. +This property provides an ARIA label for the **Select All** checkbox in the grid header. This ARIA label is announced by screen readers when users navigate to the select all checkbox. The label integrates with three-state checkbox functionality (unchecked, checked, indeterminate) and supports localization through text templates. Screen readers announce appropriate state changes when the checkbox is toggled, improving accessibility compliance for bulk-selection operations. diff --git a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2.md b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2.md index 9e657fe91af..dafb44c117c 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/data-grid-2.md @@ -21,15 +21,15 @@ 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 +- 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 @@ -39,9 +39,9 @@ In the new data grid, you are able to choose how users can iterate within the gr **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 +- Arrow up: ascending sorting applied +- Arrow down: descending sorting applied +- Double-sided arrow: no sorting is applied {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/data-grid-2/sorting-asc.png" alt="Ascending sort" class="no-border" >}} {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/data-grid-2/sorting-desc.png" alt="Descending sort" class="no-border" >}} @@ -109,8 +109,8 @@ The **Paging Buttons** option will render the default buttons as the previous da 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. +- **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 @@ -158,9 +158,9 @@ You can define how each cell will be rendered in the data grid. We offer three c {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/data-grid-2/column-width.png" alt="Settings for column width for each column item" class="no-border" >}} -* **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](https://www.w3.org/TR/css-flexbox-1/). +- **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](https://www.w3.org/TR/css-flexbox-1/). ### Alignment @@ -208,10 +208,10 @@ Association filtering configuration has been moved from column properties to the The dropdown filter widget supports association filtering when configured in custom mode: -* **Entity (Association)** — 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 -* **Option caption** — expression used as caption for each option in the dropdown +- **Entity (Association)** — 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 +- **Option caption** — expression used as caption for each option in the dropdown ### Visible {#visible-filter} @@ -251,8 +251,8 @@ Triggers an action (such as a nanoflow, microflow, or Show page action) when the 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**: Grid-wide filters can be placed in the [filters placeholder](/appstore/modules/data-grid-2-properties/#filters-placeholder). This allows for filtering across multiple attributes and more complex filtering scenarios. +- **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**: Grid-wide filters can be placed in the [filters placeholder](/appstore/modules/data-grid-2-properties/#filters-placeholder). This allows for filtering across multiple attributes and more complex filtering scenarios. {{% alert color="warning" %}} The type of your selected attribute should match the filter type. For example, a **Text filter** should be used for a string attribute. @@ -264,8 +264,8 @@ Also the desired attribute must be filterable. For example, not a value which is All filter widgets support two configuration modes: -* **Auto Mode**: automatically detects filterable attributes from the parent grid (works when placed in grid columns) -* **Custom Mode**: allows manual specification of target data source and attributes for more flexible filtering scenarios +- **Auto Mode**: automatically detects filterable attributes from the parent grid (works when placed in grid columns) +- **Custom Mode**: allows manual specification of target data source and attributes for more flexible filtering scenarios {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/data-grid-2/settings-show-column-filters.png" alt="Settings for data grid 2" class="no-border" >}} @@ -279,13 +279,13 @@ Here is an example of dropzones for filters in **Structure mode**: **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 +- 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**: @@ -319,7 +319,7 @@ When **Default filter** is defined as **Between** these fields will appear to de 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 +- Date & Time #### Events @@ -335,11 +335,11 @@ In custom mode, you can manually configure the data source and attributes, while For association filtering, you can configure: -* **Filter by Association**: sets the filter to operate on entity associations -* **Entity**: selects the target association for filtering -* **Selectable objects**: configures the data source that provides available filter options -* **Use lazy load**: controls when options are loaded (immediate vs on-demand) -* **Option caption**: defines how each option is displayed to users +- **Filter by Association**: sets the filter to operate on entity associations +- **Entity**: selects the target association for filtering +- **Selectable objects**: configures the data source that provides available filter options +- **Use lazy load**: controls when options are loaded (immediate vs on-demand) +- **Option caption**: defines how each option is displayed to users The filter also supports enhanced features like multi-select, filterable options (combobox-style), and various selection methods (checkbox or row click). @@ -355,8 +355,8 @@ When a drop-down filter is used in conjunction with an [Association Filter](#ass 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). +- **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). {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/data-grid-2/dropdown-filter-item.png" alt="Example of settings for new option" class="no-border" >}} @@ -370,7 +370,7 @@ You can also define the empty option caption, which will be rendered as the firs 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: -* String +- String {{% alert color="warning" %}} If **Multiselect** is enabled you must select a String attribute containing `Unlimited` in its size. @@ -386,12 +386,12 @@ In this section you can select an action to be executed **On change** by the fil 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 +- 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: @@ -415,10 +415,10 @@ To have better control of when the filter will be applied, we offer a **Apply af 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 one of the following types: -* Autonumber -* Decimal -* Integer -* Long +- Autonumber +- Decimal +- Integer +- Long #### Events @@ -430,15 +430,15 @@ In this section you can select an action to be executed **On change** by the fil **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 +- 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: @@ -462,8 +462,8 @@ To have better control of when the filter will be applied, we offer a **Apply af 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 one of the following types: -* Hashed string -* String +- Hashed string +- String #### Events @@ -473,15 +473,15 @@ In this section you can select an action to be executed **On change** by the fil 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 +- 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 @@ -497,15 +497,15 @@ There cannot be more than one filter of the same type in the data grid header. F ## 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](/appstore/modules/data-widgets/) module. +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](/appstore/modules/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: +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. +- **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. {{% alert color="info" %}} 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. @@ -568,6 +568,10 @@ When selection is enabled, you can choose a method for selecting rows. The **Che 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. +### 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 datasource changes. When enabled, selected items remain selected until manually cleared by the user. + ### Selection and Row Click Action {{% alert color="info" %}} @@ -609,9 +613,9 @@ To achieve this behavior, set the **On click trigger** to **Double click**. When Legend: -| Symbol | Meaning | -| ------ | ---- | -| 1 | Available only when selection is enabled. | +| Symbol | Meaning | +| ------ | ------------------------------------------------------- | +| 1 | Available only when selection is enabled. | | 2 | Available only when selection mode should be **Multi**. | ## Resetting Filters @@ -625,30 +629,33 @@ The name of the filter or data grid can be found at **Properties** > **Common** ### Filter Widget 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. +- Widget placement is incorrect. **Solution**: Place widget inside Gallery header, Data Grid 2 header, or 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 is still set to **Auto**. +- 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 is still set to **Auto**. **Solution**: Switch widget attributes setting 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. +- 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. +- 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. diff --git a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/gallery.md b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/gallery.md index 000e23b7e4b..965d6e3d77e 100644 --- a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/gallery.md +++ b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/gallery.md @@ -17,12 +17,12 @@ Here is an example of a Gallery widget using filters: The gallery has an option to enable advanced options. When this option is toggled on, it enables numerous features to customize your gallery: -* Pagination type -* Pagination position -* Empty list option -* Dynamic item class -* Filtering -* Sorting +- Pagination type +- Pagination position +- Empty list option +- Dynamic item class +- Filtering +- Sorting ## Configuration @@ -84,15 +84,15 @@ Triggers an action (such as a nanoflow, microflow, or Show page action) when the In order to enable filtering within the gallery items you need to 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 +- 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. 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 just have one filter widget for each type, for example `Text Filter` and `Number Filter`. @@ -108,7 +108,7 @@ An example of text filter being used in the composable region combined with a dr {{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/gallery/filter-region.png" alt="Example of filtering composable region" width="300" class="no-border" >}} -For more information about filters, see the [Filters](/appstore/modules/data-grid-2/#filters) section of *Data Grid 2*. +For more information about filters, see the [Filters](/appstore/modules/data-grid-2/#filters) section of _Data Grid 2_. ## Sorting @@ -128,8 +128,88 @@ The Drop-Down Sort widget is a widget you can use in combination with the Galler The Drop-Down Sort widget has two options you can set: -* Empty option caption: value to be used when no value is selected -* Screen reader caption: value to be announced by screen readers when using assistive technology +- Empty option caption: value to be used when no value is selected +- Screen reader caption: value to be announced by screen readers when using assistive technology + +## Selection + +Enabling selection allows users to select gallery items by clicking on them. Selection is disabled by default and can be activated by changing the **Selection** setting from **None** to either **Single** or **Multi**. + +The Gallery widget keeps selected items in memory and supports selection persistence across page navigation when the **Keep selection** option is enabled. This allows users to maintain their selections while browsing through paginated data or navigating between different pages in your application. + +### Selection Property + +The **Selection** property determines what type of selection is available to users: + +- **None**: Selection is disabled. Users cannot select gallery items. +- **Single**: Users can select only one item at a time. Selecting a new item automatically deselects the previously selected item. +- **Multi**: Users can select multiple items simultaneously using various interaction methods. + +When selection is enabled, the Gallery automatically provides visual feedback to indicate selected items and supports keyboard navigation for accessibility. + +### Selection and Click Actions Constraint + +{{% alert color="info" %}} +It is not possible to use both selection and onClick actions simultaneously when the **On click trigger** is set to **Single click**. This constraint prevents ambiguous user interactions where a single click could both select an item and trigger an action. +{{% /alert %}} + +#### Supported Combinations + +| Selection Mode | On Click Trigger | Selection Method | Click Action | Supported | +| -------------- | ---------------- | ---------------- | --------------------------------------------- | --------- | +| None | Single click | N/A | ✓ Click triggers action | ✓ Yes | +| None | Double click | N/A | ✓ Double-click triggers action | ✓ Yes | +| Single/Multi | Single click | Item click | ✗ Ambiguous interaction | ✗ **No** | +| Single/Multi | Double click | Item click | ✓ Click selects, double-click triggers action | ✓ Yes | + +#### Error Prevention + +If you attempt to configure both selection (Single or Multi) and an onClick action with **Single click** trigger, the Gallery will display a design-time error: + +> "The item click action is ambiguous. Change 'On click trigger' to 'Double click' or set 'Selection' to 'None'." + +#### Recommended Approach + +For galleries that need both selection and click actions: + +1. Set **On click trigger** to **Double click** +2. Configure your desired selection mode (Single or Multi) +3. Users can then select items with single clicks and trigger actions with double clicks + +### Selection with Action Buttons in Header + +Gallery selection works seamlessly with action buttons and other widgets placed in the gallery header. This pattern enables powerful bulk operation workflows. + +#### Selection Helper Integration + +Place a **Selection Helper** widget in the gallery header to provide bulk selection controls: + +- **Select All**: Quickly select all visible items +- **Clear Selection**: Remove all current selections +- **Selection Status**: Visual indicator of current selection state (all, some, or none selected) + +#### Selection Count Display + +Enable the **Show selection count** property to display the number of selected items: + +- **Top**: Shows count above the gallery items +- **Bottom**: Shows count below the gallery items +- **Off**: Hides the selection count + +The selection count automatically updates as users select or deselect items and includes a "Clear selection" button for easy deselection. + +#### Event Handling + +Use the **On selection change** action to trigger custom logic when selection changes: + +- Update UI elements based on selection state +- Enable/disable action buttons +- Load additional data for selected items +- Validate selection before allowing operations + +### 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 datasource changes. When enabled, selected items remain selected until manually cleared by the user. ## Keyboard Navigation and Selection @@ -141,8 +221,8 @@ You can also see when an item is selected: an item with a light gray background For the keyboard navigation and keyboard selection to work, the user must open the **General** tab and then set the **Selection** property to one of the following: -* **Single**: enables keyboard navigation with just single selection -* **Multi**: to enable keyboard navigation with multi-selection +- **Single**: enables keyboard navigation with just single selection +- **Multi**: to enable keyboard navigation with multi-selection ### Keyboard Navigation @@ -166,5 +246,5 @@ Employing keyboard navigation is an effective way of ensuring users who cannot u The new Gallery widget uses [CSS Grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout) as its base for styling. If you need to combine rows or columns you can achieve this using the following helper classes in the `Dynamic item class`: -* `widget-gallery-column-span-1` until `widget-gallery-column-span-12`: these classes merge column spaces, pushing items to a new row when the selected amount is reached for each platform -* `widget-gallery-row-span-1` until `widget-gallery-row-span-12`: these classes merge row spaces, pushing items into new columns or rows when needed +- `widget-gallery-column-span-1` until `widget-gallery-column-span-12`: these classes merge column spaces, pushing items to a new row when the selected amount is reached for each platform +- `widget-gallery-row-span-1` until `widget-gallery-row-span-12`: these classes merge row spaces, pushing items into new columns or rows when needed diff --git a/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/selection-helper.md b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/selection-helper.md new file mode 100644 index 00000000000..e54f7579827 --- /dev/null +++ b/content/en/docs/marketplace/platform-supported-content/modules/data-widgets/selection-helper.md @@ -0,0 +1,114 @@ +--- +title: "Selection Helper" +url: /appstore/modules/selection-helper/ +description: "Describes the configuration and usage of the Selection Helper widget, which is available in the Mendix Marketplace." +#If moving or renaming this doc file, implement a temporary redirect and let the respective team know they should update the URL in the product. See Mapping to Products for more details. +--- + +## Introduction + +The [Selection Helper](https://marketplace.mendix.com/link/component/116540) widget provides bulk selection controls for data widgets, enabling users to quickly select all or clear all items when multi-selection is enabled. While primarily often used for Gallery widgets, it also supports Data Grid 2 applications. + +Here is an example of a Selection Helper widget in a Gallery: + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/example-selection-helper.png" alt="Example of Selection Helper in a Gallery widget" width="400" class="no-border" >}} + +Use the Selection Helper widget when you need to provide users with efficient bulk selection capabilities in your data widgets. This is particularly useful for: + +- **Gallery bulk operations**: Enable users to select multiple items in gallery layouts for batch processing like delete, update, or export operations +- **Data Grid 2 bulk operations**: Provide similar functionality for tabular data presentations +- **Data management workflows**: Streamline processes where users need to work with multiple records simultaneously +- **Administrative interfaces**: Provide power users with quick selection tools for managing large datasets + +## Prerequisites + +Before using the Selection Helper widget, ensure: + +- **For Gallery**: Gallery widget is configured with Selection set to Multi +- **For Data Grid 2**: Data Grid 2 is configured with Selection set to Multi + +The Selection Helper must be placed inside the data widget's header content area: + +### For Gallery + +1. Go to your Gallery widget +2. In the Header section, add the Selection Helper widget to the header content area +3. Configure the Selection Helper properties as needed + +### For Data Grid 2 + +1. Go to your Data Grid 2 widget +2. In the Header section, add the Selection Helper widget to the header content area +3. Configure the Selection Helper properties as needed + +## Properties + +### Style + +Controls how the selection control appears to users: + +- **Check box** (default): Displays a standard checkbox that reflects the current selection state +- **Custom**: Allows you to define custom widgets for different selection states + +#### Custom style + +Available when `Style` is set to `Custom`. Define custom widgets that display based on the current selection state: + +- **None Selected Widget**: Widget displayed when no items are currently selected. Usually contains "Select all" controls or empty state indicators. +- **Some Selected Widget**: Widget displayed when some (but not all) items are selected. Often used to show "Select all" controls or partial selection indicators. +- **All Selected Widget**: Widget displayed when all visible items in the grid are selected. Typically used to show "Clear selection" controls or indicators. + +Here is an example of a Selection Helper with custom style configured: + +{{< figure src="/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/style-custom-selection-helper.png" alt="Example of Selection Helper with custom style configured" width="400" class="no-border" >}} + +#### Selection States and Behavior + +The Selection Helper automatically manages three distinct selection states: + +| State | Checkbox Appearance | Click Behavior | Use Case | +| ----- | -------------------- | ------------------------- | ----------------------------------------- | +| None | Unchecked | Selects all visible items | Starting state, no selections made | +| Some | Indeterminate (dash) | Selects all visible items | Partial selection, complete the selection | +| All | Checked | Clears all selections | Full selection, allow deselection | + +### Check Box Caption + +Available when Style = Check box + +Optional text label displayed next to the checkbox. Use this to provide context about the selection action, such as "Select all items" or "Toggle selection". + +### State Synchronization + +The Selection Helper maintains real-time synchronization with the parent data widget: + +- Changes made through the Selection Helper immediately reflect in individual row/item selections +- Individual row/item selection changes update the Selection Helper state accordingly +- Selection state persists across pagination when Keep selection is enabled in the data widget + +## Integration with Data Widgets + +### Compatible Selection Methods + +The Selection Helper works with both Gallery and Data Grid 2 selection methods: + +- **Gallery**: Users can select via item clicks and the Selection Helper +- **Data Grid 2**: Users can select via both individual checkboxes/row clicks and the Selection Helper + +## Common Use Cases + +### Gallery Bulk Selection + +Place a Selection Helper with default checkbox style in the Gallery header for simple select-all functionality in grid or list layouts. + +### Data Grid 2 Bulk Selection + +Use the Selection Helper in Data Grid 2 headers for tabular data bulk operations. + +### Custom Bulk Operations Interface + +Use custom style to integrate with your app's design system across both Gallery and Data Grid 2. + +### Administrative Data Management + +Combine with action buttons that enable/disable based on selection state for both grid and list interfaces. diff --git a/static/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/example-selection-helper.png b/static/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/example-selection-helper.png new file mode 100644 index 00000000000..81f28c23ecd Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/example-selection-helper.png differ diff --git a/static/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/style-custom-selection-helper.png b/static/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/style-custom-selection-helper.png new file mode 100644 index 00000000000..266ff56eb98 Binary files /dev/null and b/static/attachments/appstore/platform-supported-content/modules/data-widgets/selection-helper/style-custom-selection-helper.png differ