πŸ“– TimesheetListViewModel Documentation


πŸ—‚ Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. View Models & Data Models
  5. UML Class Diagram
  6. Sample Code Blocks & Usage Examples
  7. Third-Party Integrations
  8. 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:
    • EmployeeTimeSheet
    • EquipmentTimesheet

3. Key Functional Areas

  1. List Representation
    • TimesheetListViewModel encapsulates a single timesheet entry.
  2. Paging & Sorting
    • TimesheetPagedViewModel wraps a collection of TimesheetListViewModel with metadata for paging & sorting.
  3. Search & Filter
    • TimesheetSearchParams captures 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.
  • AutoMapper (implied)
    • Mapping domain entities (Timesheet in DomainClasses) to view models.
  • ASP.NET Core Identity
    • User.Identity.Name for CreatedBy filter.

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]).
  • πŸ“Š Extensibility
    • The SearchParams pattern allows easy addition of new filters.
  • πŸš€ 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! πŸŽ‰