120 lines
7.4 KiB
Markdown
120 lines
7.4 KiB
Markdown
# MgGrid — Parameters & Events
|
|
|
|
> Part of the MgGrid system. See `README.md` for overview and component hierarchy.
|
|
|
|
## Required Parameters
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `SignalRClient` | `AcSignalRClientBase` | SignalR client for server communication |
|
|
| `Logger` | `TLoggerClient` | Logger instance |
|
|
| `GetAllMessageTag` | `int` | SignalR tag for loading all items |
|
|
|
|
## CRUD Message Tags
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `GetAllMessageTag` | `int` | Tag for "get all items" request |
|
|
| `GetItemMessageTag` | `int` | Tag for "get single item" request |
|
|
| `AddMessageTag` | `int` | Tag for "add item" request |
|
|
| `UpdateMessageTag` | `int` | Tag for "update item" request |
|
|
| `RemoveMessageTag` | `int` | Tag for "remove item" request |
|
|
|
|
These are bundled into a `SignalRCrudTags` during `OnInitializedAsync`. See `AyCode.Services/docs/SIGNALR_DATASOURCE/README.md` (in AyCode.Core repo) for details.
|
|
|
|
## Data & Context Parameters
|
|
|
|
| Parameter | Type | Description |
|
|
|---|---|---|
|
|
| `DataSource` | `IList<TDataItem>` | Bind with `AcObservableCollection<TDataItem>` for external data. If not set, grid creates its own. |
|
|
| `ParentDataItem` | `IId<TId>?` | Parent entity for detail grids. `null` = master grid. |
|
|
| `KeyFieldNameToParentId` | `string?` | Property name on `TDataItem` that references the parent's ID |
|
|
| `ContextIds` | `object[]?` | Additional context passed to `AcSignalRDataSource` constructor |
|
|
| `CustomFilterCriteria` | `string?` | Consumer-supplied **base** filter criteria (a DevExpress criteria string) — propagated to the data source, triggers reload; server parses + whitelists it. AND-merged with the grid's automatic `FilterCriteria` (ADR-0004 unified model). Renamed `FilterText` → `CustomFilterText` → `CustomFilterCriteria` (2026-07-16). |
|
|
|
|
## Display & Behavior Parameters
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|---|---|---|---|
|
|
| `Caption` | `string` | `typeof(TDataItem).Name` | Grid title (shown in fullscreen header) |
|
|
| `GridName` | `string` | `"{TDataItem.Name}Grid"` | Name used in log messages |
|
|
| `AutoSaveLayoutName` | `string?` | `"Grid{TDataItem.Name}"` | Base name for layout storage keys |
|
|
| `EnableServerLayouts` | `bool` | `true` | Roams the UserSave layout tier via the SignalR server endpoint (see `MGGRID_LAYOUT.md` → Server Roaming). Server calls happen only on the Save/Load layout buttons. |
|
|
|
|
## Quick-Filter Panel
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|---|---|---|---|
|
|
| `FilterPanel` | `RenderFragment?` | `null` | Quick-filter controls rendered below the toolbar (composed into the grid's `ToolbarTemplate`); the slot wraps them in a styled `.mg-grid-filter-panel` container. When set, the toolbar shows a Show/Hide Filters toggle (`MGGRID_TOOLBAR.md`). |
|
|
| `ShowFilterPanel` | `bool` | `true` | Initial visibility of the filter panel; the toolbar toggle flips it at runtime (`IsFilterPanelVisible` / `ToggleFilterPanel`). |
|
|
|
|
Place `MgTagBox` controls (from `Components/`) in the slot. Each control applies a per-field `IN(FieldName, selected...)` criteria via `IMgGridBase.SetFieldQuickFilter` → DevExpress `SetFieldFilterCriteria`; DevExpress AND-combines the per-field criteria with each other and with the user's filter row automatically (no clobber). Empty selection clears that field's filter. Several controls in one panel therefore narrow the grid cumulatively (field A **and** field B).
|
|
|
|
```razor
|
|
<FilterPanel>
|
|
<MgTagBox TData="string" TValue="string" FieldName="Status"
|
|
Data="@_statusOptions" NullText="All statuses" />
|
|
</FilterPanel>
|
|
```
|
|
|
|
**Lookup (foreign-key) columns.** When the target column holds an ID (e.g. `PartnerId`) but users pick by name, bind the tag box to the lookup objects and let `ValueFieldName` supply the IDs. `FieldName` still names the *grid* column, so the emitted `IN(PartnerId, 3, 7)` matches the underlying data field — not the cell's display template:
|
|
|
|
```razor
|
|
<FilterPanel>
|
|
<MgTagBox TData="Partner" TValue="int" FieldName="PartnerId"
|
|
Data="@Partners" ValueFieldName="Id" TextFieldName="Name"
|
|
NullText="All partners" />
|
|
</FilterPanel>
|
|
```
|
|
|
|
A nullable FK column (`int?`) behaves the same — rows whose value is `null` match no selection.
|
|
|
|
**Sizing.** `MgTagBox` defaults its `SizeMode` to the grid's (`IMgGridBase.GridSizeMode`) when the consumer leaves it unset, so the panel matches the grid's density with no per-control declaration. An explicit `SizeMode` on the control always wins.
|
|
|
|
**Layout.** The panel is a flex row: controls sit side by side sharing the width and wrap to the next line only when they no longer fit (`.mg-grid-filter-panel > *` — `flex` / `min-width` / `max-width` in `mg-grid-info-panel.css`; tune there for a different density). It is styled to read as its **own band** between the toolbar and the group panel, aligned with the native group panel via the grid's own SizeMode-adaptive tokens (`--dxbl-grid-group-panel-container-padding-*`). Since it is composed into the `ToolbarTemplate` it physically lives inside `.dxbl-grid-toolbar-container`; that container's padding is zeroed (`:has(.mg-grid-toolbar-with-filter)`) and each row supplies its own: the toolbar row (`.mg-grid-toolbar-row`) reuses the container's native padding tokens, the band reuses the group panel's. Separator above = the band's `border-top`; below = the container's native `border-bottom`. A consumer `.hide-toolbar` class (detail grids) therefore hides the panel together with the toolbar.
|
|
|
|
Implementation note: imperative parameter writes inside DevExpress editors (`Values`, `SizeMode`) must be wrapped in `BeginUpdate()`/`EndUpdate()` (the parameter tracker throws otherwise) — `MgTagBox` handles this internally.
|
|
|
|
Design + the server-side forward path (`FilterMode.Server`): AyCode.Core repo `docs/adr/0004-signalr-datasource-server-side-filtering.md`.
|
|
|
|
## Event Callbacks
|
|
|
|
All grid events are re-exposed with `OnGrid` prefix to avoid collisions with `DxGrid` base events:
|
|
|
|
| Event | DxGrid Equivalent | When Fired |
|
|
|---|---|---|
|
|
| `OnGridItemDeleting` | `DataItemDeleting` | Before item removal (can cancel via `e.Cancel`) |
|
|
| `OnGridEditModelSaving` | `EditModelSaving` | Before item save (can cancel via `e.Cancel`) |
|
|
| `OnGridEditStart` | `EditStart` | When edit mode begins |
|
|
| `OnGridCustomizeEditModel` | `CustomizeEditModel` | When edit model is being prepared |
|
|
| `OnGridFocusedRowChanged` | `FocusedRowChanged` | When focused row changes |
|
|
| `OnDataSourceChanged` | — | After data source is loaded/reloaded |
|
|
| `OnGridItemChanged` | — | After server confirms a CRUD operation |
|
|
| `OnGridItemChanging` | — | Before a CRUD operation is sent to server |
|
|
|
|
Internal event wiring (in `SetParametersAsyncCore`, first call):
|
|
|
|
| DxGrid Event | → Internal Handler |
|
|
|---|---|
|
|
| `DataItemDeleting` | `OnItemDeleting` |
|
|
| `EditModelSaving` | `OnItemSaving` |
|
|
| `CustomizeEditModel` | `OnCustomizeEditModel` |
|
|
| `FocusedRowChanged` | `OnFocusedRowChanged` |
|
|
| `EditStart` | `OnEditStart` |
|
|
| `EditCanceling` | `OnEditCanceling` |
|
|
|
|
## Default Grid Settings
|
|
|
|
Set in `SetParametersAsyncCore` (first call only):
|
|
|
|
| Setting | Value |
|
|
|---|---|
|
|
| `KeyFieldName` | `"Id"` |
|
|
| `TextWrapEnabled` | `false` |
|
|
| `AllowSelectRowByClick` | `true` |
|
|
| `HighlightRowOnHover` | `true` |
|
|
| `AutoCollapseDetailRow` | `true` |
|
|
| `AutoExpandAllGroupRows` | `false` |
|
|
|
|
Project adapters typically add more defaults in `OnParametersSet` (e.g., `EditMode`, `FocusedRowEnabled`, `PageSize`, `ShowFilterRow`, `SizeMode` based on `IsMasterGrid`).
|