5.1 KiB
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
- Screen opens → the component asks for the grid's columns (
layout). - Preview →
grid.load(filters)→pagewithrefresh: true→ the grid'sLoadDatacalls the service (e.g.EmployeeService.GetDiscontinuedEmployeeDetails) → the wholeList<BO>is kept in server memory (per user + filters, 10 min sliding / 30 min max) → the first 100 rows go back. - Scroll / sort / search →
pagewithrefresh: false→ answered from the kept list: search, sort,Skip/Take100. The service is not called again. - 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)
- Grid class —
Definitions/<Name>VirtualGrid.cs: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 } } - Registry —
{ LeaveHistoryVirtualGrid.GridKey, () => new LeaveHistoryVirtualGrid() }. - Screen — import
VirtualGridModule, then:<app-virtual-grid #grid gridKey="leave-history" [height]="600"></app-virtual-grid>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 inLoadData. - The kept list is per user, payroll type, grid and filter values; Preview always reloads it.