HRM-10/HRM.DA/Service/VirtualGrid/README.md

89 lines
5.1 KiB
Markdown
Raw Normal View History

2026-11-09 14:41:04 +06:00
# Virtual grid — common virtual-scrolling grid for large lists
One common controller, service and Angular component serve every virtual-scrolling list. The data
still comes **the usual way**: a service method returns a `List<BO>` (query in the module's DA). A grid
only says *which* service method to call and *which* columns to show.
| Layer | File | Role |
|---|---|---|
| BO | `HRM.BO/VirtualGrid/VirtualGrid.cs` | Request/page/layout DTOs, `EnumVirtualGridColumnType`, `IVirtualGridService` |
| Service | `HRM.DA/Service/VirtualGrid/VirtualGridService.cs` | Access check, keeps the loaded list in memory, search/sort/page, Excel |
| Grids | `HRM.DA/Service/VirtualGrid/Definitions/*.cs` | **One small class per grid**: columns + which service to call |
| Registry | `HRM.DA/Service/VirtualGrid/VirtualGridRegistry.cs` | Key → grid. Unlisted keys cannot be queried |
| Controller | `HRM.UI/Controllers/CommonInterface/VirtualGridController.cs` | `GET api/virtualGrid/layout/{key}`, `POST page`, `POST export-excel` |
| Angular | `custom-components/virtual-grid/` (`VirtualGridModule`, `<app-virtual-grid>`) | Virtual scrolling, search box, sort, total, Excel button |
## How it works
1. Screen opens → the component asks for the grid's columns (`layout`).
2. **Preview** → `grid.load(filters)` → `page` with `refresh: true` → the grid's `LoadData` calls the
service (e.g. `EmployeeService.GetDiscontinuedEmployeeDetails`) → the whole `List<BO>` is kept in
server memory (per user + filters, 10 min sliding / 30 min max) → the first 100 rows go back.
3. **Scroll / sort / search** → `page` with `refresh: false` → answered from the kept list: search,
sort, `Skip/Take` 100. The service is not called again.
4. **Export to Excel** → every matching row of the kept list, same order, as `.xlsx`.
The browser only ever holds ~100 rows, however long the list is.
## Adding a grid (existing screen with a service that already returns a list)
1. **Grid class** — `Definitions/<Name>VirtualGrid.cs`:
```csharp
internal sealed class LeaveHistoryVirtualGrid : VirtualGridListDefinition<LeaveEntry>
{
public const string GridKey = "leave-history";
public override string Key => GridKey;
public override string Title => "Leave History";
public override List<VirtualGridColumn> GetColumns(VirtualGridContext context) => new List<VirtualGridColumn>
{
// Field = a property of LeaveEntry (camelCase)
new VirtualGridColumn { Field = "employeeNo", Title = "Employee No", Width = 110 },
new VirtualGridColumn { Field = "fromDate", Title = "From", Width = 120, Type = EnumVirtualGridColumnType.Date },
new VirtualGridColumn { Field = "amount", Title = "Amount", Width = 120, Type = EnumVirtualGridColumnType.Money },
};
protected override List<LeaveEntry> LoadData(VirtualGridFilters filters, VirtualGridContext context)
{
DateTime from = filters.GetDate("fromDate", "From Date", true).Value; // user-facing errors
DateTime to = filters.GetDate("toDate", "To Date", true).Value;
return new LeaveEntryService().Get(from, to, context.PayrollTypeID.Value); // the existing service
}
}
```
2. **Registry** — `{ LeaveHistoryVirtualGrid.GridKey, () => new LeaveHistoryVirtualGrid() }`.
3. **Screen** — import `VirtualGridModule`, then:
```html
<app-virtual-grid #grid gridKey="leave-history" [height]="600"></app-virtual-grid>
```
```ts
this.grid.load({ fromDate: '2025-01-01', toDate: '2025-12-31' }); // filters as strings
```
No new controller, Angular service or model. For a brand-new screen, write its query in the module's
DA and a service method returning `List<BO>` (as always), then steps 1–3.
Worked example: `Definitions/DiscontinueEmployeeVirtualGrid.cs` →
`EmployeeService.GetDiscontinuedEmployeeDetails` → `EmployeeDA.GetDiscontinuedEmployeeDetails`.
## Column types
`Text` (default), `Number`, `Money` (`1,234.56`), `Date` (`dd MMM yyyy`), `DateTime` (`dd MMM yyyy HH:mm`).
The screen shows values in that format and the search box searches that same text, so users find what
they see. Set `Sortable = false` / `Searchable = false` on a column to turn either off.
## Very large lists: `VirtualGridSqlDefinition` (advanced)
A list grid loads the whole list once per Preview — fine up to tens of thousands of rows. When even
that is too slow, derive from `VirtualGridSqlDefinition` instead: give each column a `Sql` expression
and a `BuildSource` returning `FROM … WHERE …` with parameters, and SQL Server pages each request
(`OFFSET/FETCH`, `HRM.DA/DA/VirtualGrid/VirtualGridDA.cs`). User values reach SQL only as parameters;
spliced text is code-produced only.
## Rules
- A service a grid calls must not run one query per row; load lookups once (see `GetDiscontinuedEmployeeDetails`).
- Self-service (ESS) logins are refused unless the grid sets `AllowSelfServiceUsers`. Authorization in
this app is menu-driven, so add any further check a grid needs in `LoadData`.
- The kept list is per user, payroll type, grid and filter values; Preview always reloads it.