HRM-10/HRM.DA/Service/VirtualPaging/README.md
2026-11-09 14:54:13 +06:00

78 lines
3.3 KiB
Markdown

# Virtual paging: large lists with virtual scrolling
Data loads **the usual way**: DA query → service returns `List<BO>` → controller endpoint.
Only two common pieces are added:
| Piece | File | What it does |
|---|---|---|
| `VirtualPaging.Page(...)` | `HRM.DA/Service/VirtualPaging/VirtualPaging.cs` | Keeps the list in memory for a few minutes, then search, sort, 100 rows at a time and the total count |
| `<app-virtual-grid>` | `ClientApp/src/app/custom-components/virtual-grid/` (`VirtualGridModule`) | Virtual scrolling, search box, total, Export to Excel |
`VirtualPageRequest` / `VirtualPageResult` (`HRM.BO/VirtualPaging/VirtualPaging.cs`) are shared by every
page, so a page never needs its own request class.
## A new page: 2 steps
**1. Endpoint** in the module's own controller, calling the existing service:
```csharp
[HttpPost("getDiscontinueEmployeePage")]
public ActionResult GetDiscontinueEmployeePage(VirtualPageRequest request)
{
try
{
CurrentUser currentUser = CurrentUser.GetCurrentUser(HttpContext.User);
DateTime fromDate = request.GetDate("fromDate", "From Date"); // the page's own filters
DateTime toDate = request.GetDate("toDate", "To Date");
return Ok(VirtualPaging.Page(request, currentUser,
() => _EmployeeService.GetDiscontinuedEmployeeDetails(fromDate, toDate, currentUser.PayrollTypeID ?? 0)));
}
catch (Exception ex)
{
return StatusCode(StatusCodes.Status500InternalServerError, ex.Message);
}
}
```
Read filters with `request.GetDate(name)`, `request.GetInt(name)` or `request.GetString(name)` (null when not sent).
**2. Screen**: import `VirtualGridModule`, then:
```html
<app-virtual-grid #grid url="/Employee/getDiscontinueEmployeePage" [columns]="columns"
exportFileName="DiscontinueEmployeeDetails.xlsx"></app-virtual-grid>
```
```ts
columns: VirtualGridColumn[] = [
{ field: 'employeeNo', title: 'Employee No', width: 110 },
{ field: 'joiningDate', title: 'Joining Date', type: 'date' },
{ field: 'grossSalary', title: 'Gross Salary', type: 'money' },
];
preview() {
this.grid.load({ fromDate: this.fromDate, toDate: this.toDate }); // any filters; Dates are sent as yyyy-MM-dd
}
```
`field` is the property name of the BO (camelCase). Column `type`: `text` (default), `number`,
`money` (1,234.56), `date` (dd MMM yyyy), `datetime`. `sortable: false` turns sorting off for a column.
That is all. No registry, no extra service, no extra Angular service.
## How it runs
1. **Preview** → `grid.load(filters)` → the endpoint with `refresh: true` → the service is called once,
the list is kept in server memory (per user + endpoint + filters, 10 min since last use, 30 min at
most) → the first 100 rows and the total go back.
2. **Scroll / sort / search** → same endpoint, `refresh: false` → answered from the kept list.
3. **Export to Excel** → same endpoint with `take: 0` → every matching row → Kendo builds the `.xlsx`.
The browser shows ~100 rows at a time, however long the list is.
## Rules
- The service must not run one query per row; load lookups once (see `GetDiscontinuedEmployeeDetails`).
- Search looks in the text the grid shows (dates `dd MMM yyyy`, money `1,234.56`).
- Authorization is menu-driven in this app: put any extra check the page needs in its endpoint.