# 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` (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`, ``) | 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` 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/VirtualGrid.cs`: ```csharp internal sealed class LeaveHistoryVirtualGrid : VirtualGridListDefinition { public const string GridKey = "leave-history"; public override string Key => GridKey; public override string Title => "Leave History"; public override List GetColumns(VirtualGridContext context) => new List { // 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 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 ``` ```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` (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.