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

89 lines
5.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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