119 lines
5.8 KiB
Markdown
119 lines
5.8 KiB
Markdown
# MgGrid System
|
|
|
|
> Comprehensive documentation for the **MgGrid** component family — the primary UI data grid pattern in the AyCode.Blazor framework.
|
|
> Source: `Components/Grids/`
|
|
> For SignalR transport: `AyCode.Services/docs/SIGNALR/README.md` (in AyCode.Core repo)
|
|
> For `AcSignalRDataSource`: `AyCode.Services.Server/docs/SIGNALR_DATASOURCE/README.md` (in AyCode.Core repo)
|
|
|
|
## Overview
|
|
|
|
**MgGridBase** is an abstract generic Blazor component that extends DevExpress `DxGrid` with:
|
|
- **Automatic SignalR CRUD** via `AcSignalRDataSource` (see AyCode.Core docs)
|
|
- **Layout persistence** — column order, widths, sorting, grouping auto-saved to `localStorage`
|
|
- **Master-detail hierarchy** — nested grids share context via `CascadingParameter`
|
|
- **InfoPanel integration** — side panel shows focused row details, supports edit mode
|
|
- **Fullscreen mode** — standalone overlay or via `MgGridWithInfoPanel` wrapper
|
|
- **Change tracking** — client-side tracking with server sync via `SaveChangesAsync`
|
|
|
|
## Detailed Documentation
|
|
|
|
| File | Topics |
|
|
|---|---|
|
|
| `MGGRID_PARAMETERS.md` | Component parameters (required, CRUD tags, data & context, display), event callbacks, default grid settings |
|
|
| `MGGRID_CRUD.md` | Lifecycle, CRUD operations, ID generation, edit flow, disposal |
|
|
| `MGGRID_LAYOUT.md` | Layout persistence (storage keys, three tiers, operations, persisted state) |
|
|
| `MGGRID_DETAIL.md` | Master-detail hierarchy |
|
|
| `MGGRID_RENDERING.md` | Fullscreen mode, rendering |
|
|
| `MGGRID_INFOPANEL.md` | MgGridInfoPanel, MgGridWithInfoPanel wrapper, responsive layout, templates, editors |
|
|
| `MGGRID_TOOLBAR.md` | MgGridToolbarTemplate (buttons, parameters, state) |
|
|
| `MGGRID_COLUMNS.md` | MgGridDataColumn (InfoPanel params, UrlLink) |
|
|
| `MGGRID_DATASOURCE.md` | MgGridSignalRDataSource (server-side data, local cache, background refresh) |
|
|
| `MGGRID_ISSUES.md` | Known issues (`ACBLAZOR-GRID-I-*`, `ACBLAZOR-GRID-B-*`) — currently none formally tracked |
|
|
| `MGGRID_TODO.md` | Planned work (`ACBLAZOR-GRID-T-*`) — refactors, missing features, optimizations |
|
|
|
|
## Component Hierarchy
|
|
|
|
```
|
|
DxGrid (DevExpress)
|
|
└── MgGridBase<TSignalRDataSource, TDataItem, TId, TLoggerClient> (AyCode.Blazor — abstract)
|
|
└── [Project-specific adapter] ← consumer fixes TSignalRDataSource, TId, TLoggerClient
|
|
└── [Concrete entity grid] ← consumer sets CRUD tags in constructor
|
|
```
|
|
|
|
### Companion Components
|
|
|
|
| Component | Purpose | Docs |
|
|
|---|---|---|
|
|
| **MgGridWithInfoPanel** | `DxSplitter` wrapper: grid + InfoPanel, fullscreen, splitter persistence | `MGGRID_INFOPANEL.md` |
|
|
| **MgGridToolbarBase** | `DxToolbar` base with `Grid` reference, `RefreshClick` callback | `MGGRID_TOOLBAR.md` |
|
|
| **MgGridToolbarTemplate** | Full toolbar: CRUD, navigation, layout menu, fullscreen, export | `MGGRID_TOOLBAR.md` |
|
|
| **MgGridDataColumn** | Extended `DxGridDataColumn` with InfoPanel params and `UrlLink` | `MGGRID_COLUMNS.md` |
|
|
| **MgGridInfoPanel** | Default InfoPanel: column-value pairs, edit mode, typed editors | `MGGRID_INFOPANEL.md` |
|
|
| **MgGridSignalRDataSource** | `GridCustomDataSource` wrapper: server-side filter/sort/page, local cache | `MGGRID_DATASOURCE.md` |
|
|
|
|
## Generic Type Parameters
|
|
|
|
```csharp
|
|
MgGridBase<TSignalRDataSource, TDataItem, TId, TLoggerClient>
|
|
```
|
|
|
|
| Parameter | Constraint | Purpose |
|
|
|---|---|---|
|
|
| `TSignalRDataSource` | `: AcSignalRDataSource<…>` | SignalR-backed data source (see `AyCode.Services.Server/docs/SIGNALR_DATASOURCE/README.md` in AyCode.Core repo) |
|
|
| `TDataItem` | `: class, IId<TId>` | Entity type displayed in the grid |
|
|
| `TId` | `: struct` | Primary key type (`int`, `Guid`) |
|
|
| `TLoggerClient` | `: AcLoggerBase` | Logger for diagnostics |
|
|
|
|
### Usage Example (Project-Specific Adapter)
|
|
|
|
```csharp
|
|
// Project adapter — fixes TSignalRDataSource, TId, TLoggerClient for the entire project
|
|
public class MyProjectGridBase<TDataItem>
|
|
: MgGridBase<MySignalRDataSource<TDataItem>, TDataItem, int, MyLoggerClient>
|
|
where TDataItem : class, IId<int>
|
|
{
|
|
[Inject] public required MyLoggedInModel LoggedInModel { get; set; }
|
|
protected override int GetLayoutUserId() => LoggedInModel.UserId;
|
|
}
|
|
|
|
// Concrete grid — only TDataItem remains open
|
|
public class GridOrderBase : MyProjectGridBase<Order>
|
|
{
|
|
public GridOrderBase()
|
|
{
|
|
GetAllMessageTag = MySignalRTags.GetOrders;
|
|
AddMessageTag = MySignalRTags.AddOrder;
|
|
UpdateMessageTag = MySignalRTags.UpdateOrder;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Interface: IMgGridBase
|
|
|
|
The public contract exposed to companion components (toolbar, InfoPanel, wrapper):
|
|
|
|
| Member | Type | Description |
|
|
|---|---|---|
|
|
| `IsSyncing` | `bool` | Whether SignalR sync is in progress |
|
|
| `Caption` | `string` | Grid title |
|
|
| `GridEditState` | `MgGridEditState` | `None` / `New` / `Edit` |
|
|
| `ParentGrid` | `IMgGridBase?` | Parent in master-detail hierarchy |
|
|
| `GetRootGrid()` | `IMgGridBase` | Walks to topmost grid |
|
|
| `StepPrevRow()` | `void` | Navigate to previous visible row |
|
|
| `StepNextRow()` | `void` | Navigate to next visible row |
|
|
| `InfoPanelInstance` | `IInfoPanelBase?` | Resolved InfoPanel reference |
|
|
| `IsFullscreen` | `bool` | Current fullscreen state |
|
|
| `AutomaticLayoutStorageKey` | `string` | Current auto-save storage key |
|
|
| `ToggleFullscreen()` | `void` | Toggle fullscreen mode |
|
|
| `SaveUserLayoutAsync()` | `Task` | Save layout manually |
|
|
| `LoadUserLayoutAsync()` | `Task` | Load manually saved layout |
|
|
| `ResetLayoutAsync()` | `Task` | Reset to default layout |
|
|
| `HasUserLayoutAsync()` | `Task<bool>` | Check if manual save exists |
|
|
|
|
## Event Args Classes
|
|
|
|
| Class | Base | Extra Properties |
|
|
|---|---|---|
|
|
| `GridDataItemChangedEventArgs<T>` | — | `Grid`, `DataItem`, `TrackingState`, `CancelStateChangeInvoke` |
|
|
| `GridDataItemChangingEventArgs<T>` | `GridDataItemChangedEventArgs<T>` | `IsCanceled` |
|