89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
# 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.
|