HRM-10/HRM.DA/DA/VirtualPaging/README.md
2026-11-09 16:39:51 +06:00

124 lines
5.8 KiB
Markdown

# Virtual paging: large lists with virtual scrolling
SQL Server does the paging. Each request reads only the rows the grid needs (100 at a time) with
`OFFSET … FETCH`, and the search, sort and total count run in the same SQL. Nothing is kept in server
memory, so it works the same for 1,000 or 1,000,000 rows and always shows the latest data.
| Piece | File | What it does |
|---|---|---|
| Request / result | `HRM.BO/VirtualPaging/VirtualPaging.cs` | `VirtualPageRequest` (filters, columns, skip/take, search, sort) and `VirtualPageResult`, shared by every page |
| Paging SQL | `HRM.DA/DA/VirtualPaging/VirtualPagingDA.cs` | Wraps a page's query with search, sort, `OFFSET/FETCH` and the totals |
| Excel | `HRM.DA/DA/VirtualPaging/VirtualPagingExcel.cs` | Streams the rows from SQL Server straight into an `.xlsx` (Open XML SAX writer) |
| Grid | `ClientApp/src/app/custom-components/virtual-grid/` (`VirtualGridModule`) | `<app-virtual-grid>`: virtual scrolling, search box, total, Export to Excel |
## A new page: 4 small steps (worked example: Discontinue Employee Details)
**1. DA: the query.** An ordinary `SELECT` built with `MakeSQL`. Each column alias is a grid field name.
No `ORDER BY` and no `WITH` (the query is used as a derived table).
```csharp
internal static string GetDiscontinuedEmployeeQuery(DateTime fromDate, DateTime toDate, int payrollTypeID)
{
return SQLParser.MakeSQL(@"
SELECT v.EMPLOYEENO AS employeeNo,
v.NAME AS name,
v.JOININGDATE AS joiningDate,
ISNULL(v.BASICSALARY, 0) AS basicSalary
FROM VW_EMPLOYEEBASIC v
INNER JOIN EMPLOYEE e ON e.EMPLOYEEID = v.EmployeeId
WHERE e.STATUS = %n AND e.PAYROLLTYPEID = %n
AND e.ENDOFCONTRACTDATE >= %d AND e.ENDOFCONTRACTDATE < %d",
(int)EnumEmployeeStatus.Discontinued, payrollTypeID, fromDate.Date, toDate.Date.AddDays(1));
}
```
**2. Service: one method** (canonical try/catch) + its line in the module's `I…Service` interface:
```csharp
public VirtualPageResult GetDiscontinuedEmployeePage(VirtualPageRequest request, DateTime fromDate, DateTime toDate, int payrollTypeID)
{
VirtualPageResult result = null;
TransactionContext tc = null;
try
{
tc = TransactionContext.Begin();
string query = EmployeeDA.GetDiscontinuedEmployeeQuery(fromDate, toDate, payrollTypeID);
result = VirtualPagingDA.GetPage(tc, query, request, "employeeNo"); // "employeeNo" = a unique field
tc.End();
}
catch (Exception e)
{
if (tc != null) tc.HandleError();
ExceptionLog.Write(e);
throw new ServiceException(e.Message, e);
}
return result;
}
```
**3. Controller: one endpoint** in the module's own controller. Read the page's filters from the request:
```csharp
[HttpPost("getDiscontinueEmployeePage")]
public ActionResult GetDiscontinueEmployeePage(VirtualPageRequest request)
{
try
{
CurrentUser currentUser = CurrentUser.GetCurrentUser(HttpContext.User);
if (currentUser.UserType == EnumUserType.Employee)
return StatusCode(StatusCodes.Status403Forbidden, "You are not allowed to see this report.");
DateTime fromDate = request.GetDate("fromDate", "From Date"); // also GetInt / GetString
DateTime toDate = request.GetDate("toDate", "To Date");
VirtualPageResult result = _EmployeeService.GetDiscontinuedEmployeePage(request, fromDate, toDate, currentUser.PayrollTypeID ?? 0);
if (result.ExcelFile != null) // Export to Excel
return File(result.ExcelFile, VirtualPageResult.ExcelContentType, "DiscontinueEmployeeDetails.xlsx");
return Ok(result);
}
catch (ArgumentException ex) { return BadRequest(ex.Message); }
catch (Exception ex) { return StatusCode(StatusCodes.Status500InternalServerError, ex.Message); }
}
```
**4. 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: 'basicSalary', title: 'Basic Salary', type: 'money' },
];
preview() {
this.grid.load({ fromDate: this.fromDate, toDate: this.toDate }); // any filters; Dates go as yyyy-MM-dd
}
```
`field` = the column alias in the query. Column `type`: `text` (default), `number`, `money` (1,234.56),
`date` (dd MMM yyyy), `datetime`. `sortable: false` turns sorting off for a column.
## How one request runs
| User action | Request | SQL |
|---|---|---|
| Preview | `skip 0, take 100, countTotal true` | `COUNT` + first 100 rows, one round trip |
| Scroll | `skip 100, 200, …` | next 100 rows only (no `COUNT`) |
| Sort | `sortField`, `sortDir` | `ORDER BY` that column, then the unique field |
| Search (after 400 ms) | `search`, `countTotal true` | `WHERE` every column `LIKE @vpSearch`, new `COUNT` |
| Export to Excel | `exportExcel true` | every matching row, same search and sort, written row by row into an `.xlsx` on the server; the browser only downloads the file |
## Rules
- **Speed**: the page query's `WHERE` must use an index (see `DiscontinueEmployeeReport_DB_Changes.sql`).
Values computed in C# cannot be searched or sorted, so compute them in the query (see the department
tiers and blood group in `GetDiscontinuedEmployeeQuery`).
- **Safety**: the query is built by code with `MakeSQL` from typed values (dates, ints). The search text,
skip and take are SQL parameters; field names must be plain identifiers and are bracketed.
- **Access**: authorization in this app is menu-driven, so every page endpoint checks who may call it
(self-service logins are refused above).
- The key field passed to `GetPage` must be unique, so pages never overlap or skip rows.