HRM-10/HRM.DA/Service/VirtualGrid/README.md
2026-11-09 14:41:04 +06:00

5.1 KiB
Raw Blame History

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:
    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:
    <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 in LoadData.
  • The kept list is per user, payroll type, grid and filter values; Preview always reloads it.