# Grid

**Category:** Control

**Version:** 1.0

**Last Updated:** November 19, 2025

**Author:** Any2Info

***

### Overview

The **Grid Control** provides a way to visualize datasets structured like a table.

It supports several table-related features such as **paging**, **filtering**, and **sorting**, while offering extended **styling options** for layout, look, and line formatting.

This control is typically used to:

* Display datasets in tabular format
* Enable users to make selections for non-singular data entries

  (e.g., order lines, downtime records)

> Tip:
>
> The Grid Control is gradually being replaced by the **Gridlist Control**, which introduces new functionality like footers and multi-value row layouts. However, Grid Control remains supported for existing implementations.

***

### Events

| Event                 | Description                                                                                                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **On Update**         | Triggered whenever the grid receives or updates its data (initial load or filter change).                                                    |
| **On Grid Row Click** | Triggered whenever a user selects an individual row. This event allows specific actions, such as downloading files or opening/copying forms. |

***

### Data Mapping

Mappings define which data elements are shown and how they are connected to backend sources.

| Mapping               | Description                                                                                                                                                                                                                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Columns**           | Defines which columns are displayed in the grid. For more details on data formatting or styling, see **Advanced Configuration**. When switching to *table view*, each column supports **cell-based color mapping**, allowing background color to be dynamically set based on data values. |
| **Rows**              | Defines the data rows displayed in the grid. All datasets (*dataclips*) have a variable row count, so this property is automatically mapped.                                                                                                                                              |
| **Definition Header** | Used by the “New Form for Grid Line Action” to specify which form definition is used.                                                                                                                                                                                                     |
| **Document Header**   | Used by the “Download Grid Line Document” action to define the document identification value.                                                                                                                                                                                             |
| **Message Header**    | Used by the “Open Grid Line Form” or “Copy Grid Line Form” actions to determine which message to use.                                                                                                                                                                                     |

***

### Advanced Configuration

Advanced column configuration is available under

**Properties → Grid Data → Overview Fields**.

Each configuration option corresponds directly to the order of the column mappings.

| Aspect      | Description                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Caption** | Defines the text displayed for the column header. Defaults to the mapped column name.                                                                                                                         |
| **Weight**  | Determines the relative horizontal width of each column. A weight of `0` hides the column but retains its value for logic or actions.                                                                         |
| **Sorting** | Configures the default sorting order using sort index and direction.                                                                                                                                          |
| **Format**  | Defines how cell values are displayed based on type:• **Numerical values** – control decimal count using `{#}` (e.g. `€{2}` → *€4.50* for value `4.5`).• **Date/Time values** – use ISO8601 date format tags. |

***

### Styling

The Grid Control provides flexible styling for both readability and visual consistency:

* **Column-based and row-based styles** for alternating lines or highlighted records
* **Conditional coloring** via data mapping (e.g. color rows based on thresholds or statuses)
* **Header customization** through captions and weights
* **Hidden technical columns** (using weight `0`) for logic without display clutter

***

### Support & Future Continuation

> Status:
>
> The Grid Control currently receives **minimal new feature support** and will gradually be replaced by the **Gridlist Control**.

#### Key Differences in Successor (Gridlist)

| Feature          | Grid Control                    | Gridlist Control                        |
| ---------------- | ------------------------------- | --------------------------------------- |
| **Footers**      | Not supported                   | ✅ Supported                             |
| **Row Layout**   | Single value per column         | ✅ Multiple values under one column      |
| **Paging**       | ✅ Supported                     | ❌ Replaced with row-on-demand rendering |
| **Mapping**      | Requires Columns & Rows mapping | ✅ Uses direct dataset configuration     |
| **Cell Styling** | Basic                           | ✅ Advanced per-cell overrides           |

***

### Summary

The **Grid Control** is a versatile table component designed for structured data visualization and user interaction.

While it remains functional and configurable, it is being phased out in favor of the **Gridlist**, which offers modernized rendering, styling, and performance.

> Recommended Usage:
>
> Use **Grid Control** in existing implementations that rely on paging and column/row mappings.
>
> For new projects, consider transitioning to **Gridlist Control** for improved flexibility and maintainability.

### Changelog

| Version | Date              | Changes                              |
| ------- | ----------------- | ------------------------------------ |
| 1.0     | November 19, 2025 | Initial documentation version added. |