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.
|