π TimesheetListViewModel Documentation
π Table of Contents
- Overview & Purpose
- Dependencies & Technologies
- Key Functional Areas
- View Models & Data Models
- UML Class Diagram
- Sample Code Blocks & Usage Examples
- Third-Party Integrations
- Conclusion & Best Practices
1. Overview & Purpose
TimesheetListViewModel.cs defines a set of View Models used in the UI layer of the IrbyImaging application to:
- π Represent timesheet records in list and paged formats
- π Support filtering, sorting, and pagination
- π Decouple domain entities from UI-specific logic
These models enable ASP.NET MVC / Razor Pages views (or Web APIs) to exchange strongly-typed data for displaying, searching, and paging through timesheets, associated employees, and equipment usage.
2. Dependencies & Technologies
- .NET (C#) β Primary language
- ASP.NET MVC / Razor β UI framework consuming these models
- DocumentFormat.OpenXml β (Referenced, though not directly used here)
- IrbyImaging.DomainClasses β Provides domain entities:
EmployeeTimeSheetEquipmentTimesheet
3. Key Functional Areas
- List Representation
TimesheetListViewModelencapsulates a single timesheet entry.
- Paging & Sorting
TimesheetPagedViewModelwraps a collection ofTimesheetListViewModelwith metadata for paging & sorting.
- Search & Filter
TimesheetSearchParamscaptures common filter criteria.
Each model is a Plain-Old-CLR-Object (POCO) without behavior (methods), focusing purely on data transport between layers.
4. View Models & Data Models
4.1 TimesheetListViewModel
| Property | Type | Description |
|---|---|---|
| TimesheetId | Guid |
Unique identifier for the timesheet |
| TimesheetNumber | string |
Human-friendly timesheet number |
| CrewName | string |
Name of the crew/team working |
| WorkDate | DateTime |
Date the work was performed |
| TotalHours | double |
Sum of all hours recorded (employees + equipment) |
| CreatedBy | string |
User who created the timesheet |
| Job | string |
Job description or number |
| CostCode | string |
Cost code associated with the job |
| EmployeeTimeSheets | List<EmployeeTimeSheet> |
Collection of individual employee timesheet lines |
| EquipmentTimeSheets | List<EquipmentTimesheet> |
Collection of equipment usage entries |
public class TimesheetListViewModel
{
public Guid TimesheetId { get; set; }
public string TimesheetNumber { get; set; }
public string CrewName { get; set; }
public DateTime WorkDate { get; set; }
public double TotalHours { get; set; }
public string CreatedBy { get; set; }
public string Job { get; set; }
public string CostCode { get; set; }
public List<EmployeeTimeSheet> EmployeeTimeSheets { get; set; }
public List<EquipmentTimesheet> EquipmentTimeSheets { get; set; }
}
4.2 TimesheetPagedViewModel
| Property | Type | Description |
|---|---|---|
| Timesheets | IEnumerable<TimesheetListViewModel> |
Collection of timesheet records to display on the current page |
| CurrentPage | int |
1-based index of the current page |
| PageSize | int |
Number of items per page |
| TotalItems | int |
Total number of timesheets matching the search criteria |
| TotalPages | int |
Computed: ceil(TotalItems / (double)PageSize) |
| SortField | string |
Field name by which data is sorted (e.g., "WorkDate", "CrewName") |
| SortOrder | string |
Sort direction: "asc" or "desc" |
| SearchParams | TimesheetSearchParams |
Encapsulates the current filter criteria |
public class TimesheetPagedViewModel
{
public IEnumerable<TimesheetListViewModel> Timesheets { get; set; }
public int CurrentPage { get; set; }
public int PageSize { get; set; }
public int TotalItems { get; set; }
public int TotalPages { get; set; }
public string SortField { get; set; }
public string SortOrder { get; set; } // "asc" or "desc"
public TimesheetSearchParams SearchParams { get; set; }
}
4.3 TimesheetSearchParams
| Property | Type | Description |
|---|---|---|
| StartDate | DateTime? |
Optional filter: earliest work date |
| EndDate | DateTime? |
Optional filter: latest work date |
| CreatedBy | string |
Optional filter: user who created the timesheet |
| JobNumber | string |
Optional filter: associated job or project number |
public class TimesheetSearchParams
{
public DateTime? StartDate { get; set; }
public DateTime? EndDate { get; set; }
public string CreatedBy { get; set; }
public string JobNumber { get; set; }
}
5. UML Class Diagram
classDiagram
TimesheetListViewModel --> EmployeeTimeSheet
TimesheetListViewModel --> EquipmentTimesheet
TimesheetPagedViewModel "1" o-- "*" TimesheetListViewModel
TimesheetPagedViewModel --> TimesheetSearchParams
class TimesheetListViewModel {
+Guid TimesheetId
+string TimesheetNumber
+string CrewName
+DateTime WorkDate
+double TotalHours
+string CreatedBy
+string Job
+string CostCode
+List<EmployeeTimeSheet> EmployeeTimeSheets
+List<EquipmentTimesheet> EquipmentTimeSheets
}
class TimesheetPagedViewModel {
+IEnumerable<TimesheetListViewModel> Timesheets
+int CurrentPage
+int PageSize
+int TotalItems
+int TotalPages
+string SortField
+string SortOrder
+TimesheetSearchParams SearchParams
}
class TimesheetSearchParams {
+DateTime? StartDate
+DateTime? EndDate
+string CreatedBy
+string JobNumber
}
6. Sample Code Blocks & Usage Examples
6.1 Initializing a Single Timesheet
var ts = new TimesheetListViewModel
{
TimesheetId = Guid.NewGuid(),
TimesheetNumber = "TS-2024-001",
CrewName = "Excavation Crew A",
WorkDate = DateTime.Today,
TotalHours = 32.5,
CreatedBy = "jdoe",
Job = "Project X",
CostCode = "CC1001",
EmployeeTimeSheets = new List<EmployeeTimeSheet> {
new EmployeeTimeSheet { /* ... */ },
new EmployeeTimeSheet { /* ... */ }
},
EquipmentTimeSheets = new List<EquipmentTimesheet> {
new EquipmentTimesheet { /* ... */ }
}
};
6.2 Preparing a Paged View for a Razor View
public IActionResult Index(int page = 1, string sort = "WorkDate", string order = "desc",
DateTime? start = null, DateTime? end = null)
{
// 1. Build search params
var search = new TimesheetSearchParams {
StartDate = start,
EndDate = end,
CreatedBy = User.Identity.Name,
JobNumber = null
};
// 2. Query domain/services for paged data
var pagedList = _timesheetService.GetPagedTimesheets(page, 20, sort, order, search);
// 3. Map domain to ViewModel
var viewModel = new TimesheetPagedViewModel {
Timesheets = pagedList.Items.Select(x => _mapper.Map<TimesheetListViewModel>(x)),
CurrentPage = pagedList.PageNumber,
PageSize = pagedList.PageSize,
TotalItems = pagedList.TotalCount,
TotalPages = pagedList.TotalPages,
SortField = sort,
SortOrder = order,
SearchParams= search
};
return View(viewModel);
}
6.3 Razor Snippet for Display
@model TimesheetPagedViewModel
<table class="table">
<thead>
<tr>
<th>@Html.ActionLink("Work Date", "Index", new { sort = "WorkDate", order = Model.SortOrder == "asc" ? "desc" : "asc" })</th>
<th>Crew</th>
<th>Total Hours</th>
<th>Created By</th>
<th>Actions</th>
</tr>
</thead>
<tbody>
@foreach(var ts in Model.Timesheets) {
<tr>
<td>@ts.WorkDate.ToShortDateString()</td>
<td>@ts.CrewName</td>
<td>@ts.TotalHours</td>
<td>@ts.CreatedBy</td>
<td>
<a asp-action="Details" asp-route-id="@ts.TimesheetId">π View</a>
</td>
</tr>
}
</tbody>
</table>
<!-- Pagination Controls -->
<div>
Page @Model.CurrentPage of @Model.TotalPages
</div>
7. Third-Party Integrations
- DocumentFormat.OpenXml
- The file references
DocumentFormat.OpenXml.Office2010.ExcelAc, indicating potential future use for Excel export/import.
- The file references
- AutoMapper (implied)
- Mapping domain entities (
Timesheetin DomainClasses) to view models.
- Mapping domain entities (
- ASP.NET Core Identity
User.Identity.NameforCreatedByfilter.
8. Conclusion & Best Practices
- π Separation of Concerns
- UI models hold only dataβno business logic.
- π Mapping
- Use mapping libraries (e.g., AutoMapper) for conversion between domain and UI models.
- βοΈ Validation & Defaults
- Consider adding data annotations for client- & server-side validation (e.g.,
[Required],[Range]).
- Consider adding data annotations for client- & server-side validation (e.g.,
- π Extensibility
- The
SearchParamspattern allows easy addition of new filters.
- The
- π Pagination Performance
- Ensure back-end queries apply paging/sorting before materializing results to minimize memory and bandwidth.
This detailed documentation should provide comprehensive insight into TimesheetListViewModel.csβfrom its core purpose to practical usage in your ASP.NET application. Happy coding! π