๐Ÿ“‹ CreateCrew.cshtml Documentation


Table of Contents

  1. ๐Ÿง Overview & Purpose
  2. ๐Ÿš€ Key Functional Areas
  3. ๐Ÿ›  Dependencies & Technologies
  4. ๐Ÿ“Š View Model & Data Models
  5. ๐Ÿ”Ž UI Structure & Razor Markup
  6. ๐Ÿงฉ Helper Methods & Utilities
  7. ๐Ÿ”’ Error Handling & Return Types
  8. ๐ŸŒ API Endpoints Overview
  9. โš™๏ธ Thirdโ€‘party Integrations
  10. ๐Ÿ” Sample Code Blocks
  11. ๐Ÿ‘จโ€๐Ÿ’ป Usage Examples
  12. ๐Ÿ“ˆ UML Diagrams
  13. ๐Ÿ“ Conclusion

๐Ÿง Overview & Purpose

CreateCrew.cshtml is a Razor View in the IrbyImaging/Views/FieldLog folder. It renders a dynamic form for creating a Crew entity in the Time Entry system:

  • ๐ŸŽฏ Purpose: Allow a user to enter a Crew name, select a Job, and dynamically add multiple Employees and Equipment entriesโ€”complete with cost codes, classes, perโ€‘diem rates, worked hours, etc.
  • ๐Ÿ—๏ธ Intended Use: Embedded in a TimeEntry workflow; posted via AJAX to /TimeEntry/CreateCrew for serverโ€‘side processing.

๐Ÿš€ Key Functional Areas

Section Description
Header & Layout Sets page title & layout (_TimeLayout.cshtml).
External Libraries Loads jQuery, Tailwind, FontAwesome, SignaturePad, Syncfusion EJ2 scripts/CSS.
Form Markup Inputs for Crew name, Job dropdown, Employees section, Equipment section.
Dynamic Rows JavaScript adds/removes Employee/Equipment rows with Syncfusion dropdowns & inputs.
Filtering Logic Filters CostCodes & Classes by selected Job & cost code.
Form Submission Gathers data, builds crew JSON, and AJAX POST.

๐Ÿ›  Dependencies & Technologies

  • ASP.NET Core MVC (Razor Views)
  • jQuery 3.7.1
  • Tailwind CSS 2.2.19
  • FontAwesome 6.4.0
  • SignaturePad 4.1.7
  • Syncfusion EJ2
    • ej2-inputs
    • ej2-calendars
  • AJAX via jQuery

๐Ÿ“Š View Model & Data Models

The View expects a Model with these collections, serialized to JavaScript:

Property Type Description
Jobs IEnumerable<DropdownItem> List of available Jobs
Employees IEnumerable<DropdownItem> List of available Employees
CostCodes IEnumerable<CostCodeItem> Cost codes with properties (JobId, Type, Number)
Classes IEnumerable<ClassItem> Class codes (JobId, optional CostCodeNumber)
PerDiemTypes IEnumerable<DropdownItem> e.g., Taxable (600), Nonโ€‘Taxable (610)
Equipment IEnumerable<DropdownItem> Equipment catalog

DropdownItem

public class DropdownItem {
  public int Value { get; set; }
  public string Text { get; set; }
}

CostCodeItem

public class CostCodeItem {
  public int Value { get; set; }
  public string Text { get; set; }
  public int JobId { get; set; }
  public int CostCodeType { get; set; }    // 1 = Employee, 2 = Equipment
  public int CostCodeNumber { get; set; }
}

Crew Submission Model

public class CrewDto {
  public string CrewName { get; set; }
  public int JobId { get; set; }
  public List<CrewEmployeeDto> CrewEmployees { get; set; }
  public List<CrewEquipmentDto> CrewEquipment { get; set; }
}
public class CrewEmployeeDto {
  public int EmployeeId { get; set; }
  public int CostCodeId   { get; set; }
  public int Class        { get; set; }
  public string PerDiemType { get; set; }
  public decimal PerDiemRate { get; set; }
  public string StartTime    { get; set; }
}
public class CrewEquipmentDto {
  public int EquipmentId { get; set; }
  public int CostCodeId  { get; set; }
  public decimal WorkedHours { get; set; }
}

๐Ÿ”Ž UI Structure & Razor Markup

@using Syncfusion.EJ2
@addTagHelper *, Syncfusion.EJ2
@{ 
  ViewData["Title"] = "Create Crew";
  Layout = "~/Views/Shared/_TimeLayout.cshtml"; 
}

<div class="container mx-auto p-6">
  <h1 class="text-2xl font-bold mb-4">Create Crew</h1>
  <form id="createCrewForm">
    <!-- Crew Name -->
    <div class="mb-4">
      <label for="crewName">Crew Name</label>
      <input id="crewName" name="crewName" required />
    </div>
    <!-- Job Dropdown -->
    <div class="mb-4">
      <label for="jobSelect">Select Job</label>
      <ejs-dropdownlist id="jobSelect" 
                        dataSource="@Model.Jobs"
                        change="filterCodes"
                        allowFiltering="true"
                        placeholder="Select Job">
        <e-dropdownlist-fields text="Text" value="Value"></e-dropdownlist-fields>
      </ejs-dropdownlist>
    </div>
    <!-- Employee Section -->
    <div class="mb-4">
      <h2>Crew Employees</h2>
      <div id="employeesSection"></div>
      <button type="button" id="addEmployeeRow">Add Employee</button>
    </div>
    <!-- Equipment Section (injected via JS) -->
    <!-- Submit Button -->
    <button type="submit">Create Crew</button>
  </form>
</div>
  • Dynamic Sections:
    • Employee rows injected inside #employeesSection
    • Equipment rows inside #equipmentSection

๐Ÿงฉ Helper Methods & Utilities

Function Purpose
updateEmployeeCostCodesForRow(row, jobId) Filters Cost Code dropdown by Job & Type=Employee.
updateEquipmentCostCodesForRow(row, jobId) Filters Cost Code dropdown by Job & Type=Equipment.
sortClassesPriority(classes) Prioritizes classes containing โ€œJDECโ€ or โ€œBESโ€.
filterEmployeeClass(dropdown, jobId, costCodeNumber) Filters & rebuilds Class dropdown by Job & optional CostCode.
filterCodes(args) Topโ€‘level Job change handler; updates all rows.
addEmployeeRow() Dynamically appends a new employee row and initializes Syncfusion widgets.
addEquipmentRow() Dynamically appends a new equipment row and initializes widgets.

๐Ÿ”’ Error Handling & Return Types

  • Console Logging & Warnings

    • Each helper method wraps logic in try...catch and logs errors to console.error.
    • Graceful fallback: If a widget is missing, logs a warning rather than throwing.
  • AJAX Submission

    $.ajax({
      url: '/TimeEntry/CreateCrew',
      type: 'POST',
      data: JSON.stringify(crew),
      contentType: 'application/json',
      success: response => alert(response.message),
      error: err => { console.error(err); alert("Error creating crew"); }
    });
    
    • Return Type: Expects JSON { message: string }.

๐ŸŒ API Endpoints Overview

Method URL Body Response Description
POST /TimeEntry/CreateCrew CrewDto (JSON) { message: string } Creates a new Crew entry on server.

โš™๏ธ Thirdโ€‘party Integrations

  • Syncfusion EJ2
    • DropDownList for Jobs, Employees, CostCodes, Classes, PerDiemTypes, Equipment
    • TimePicker for Employee Start Time
  • SignaturePad (loaded but not yet used in this view)
  • Tailwind CSS & FontAwesome for styling

๐Ÿ” Sample Code Blocks

1. Initializing window.CrewModel

<script>
  window.CrewModel = {
    Jobs: @Html.Raw(Json.Serialize(Model.Jobs)),
    Employees: @Html.Raw(Json.Serialize(Model.Employees)),
    CostCodes: @Html.Raw(Json.Serialize(Model.CostCodes)),
    Classes: @Html.Raw(Json.Serialize(Model.Classes)),
    PerDiemTypes: @Html.Raw(Json.Serialize(Model.PerDiemTypes)),
    Equipment: @Html.Raw(Json.Serialize(Model.Equipment)),
  };
  console.log("CrewModel:", window.CrewModel);
</script>

2. Adding an Employee Row

function addEmployeeRow() {
  var uniqueId = "row_" + Math.random().toString(36).substr(2, 9);
  var rowHtml = '<div id="' + uniqueId + '"> ... </div>';
  $("#employeesSection").append(rowHtml);

  // Initialize Syncfusion DropDownLists & TimePicker...
}

๐Ÿ‘จโ€๐Ÿ’ป Usage Examples

  1. Load Page
    • Model data (Jobs, Employees, etc.) are serialized into window.CrewModel.
  2. Add Employee
    • Click Add Employee โ†’ a new row appears.
    • Select an Employee, Cost Code โ†’ Class dropdown autoโ€‘filters.
    • Choose Per Diem Type, enter Rate, pick Start Time.
  3. Add Equipment
    • Click Add Equipment โ†’ choose Equipment, Cost Code, Worked Hours.
  4. Submit
    • Create Crew โ†’ AJAX sends payload to server โ†’ server replies with confirmation.

๐Ÿ“ˆ UML Diagrams

Class Diagram

@startuml
class CrewDto {
  +string CrewName
  +int JobId
  +List<CrewEmployeeDto> CrewEmployees
  +List<CrewEquipmentDto> CrewEquipment
}

class CrewEmployeeDto {
  +int EmployeeId
  +int CostCodeId
  +int Class
  +string PerDiemType
  +decimal PerDiemRate
  +string StartTime
}

class CrewEquipmentDto {
  +int EquipmentId
  +int CostCodeId
  +decimal WorkedHours
}

CrewDto --> CrewEmployeeDto
CrewDto --> CrewEquipmentDto
@enduml

Sequence Diagram (Highโ€‘Level)

@startuml
actor User
participant Browser
participant CreateCrewView
participant Server

User -> Browser : Navigate to /FieldLog/CreateCrew
Browser -> CreateCrewView : Render razor + scripts
CreateCrewView -> Browser : HTML + JS loaded
User -> Browser : fill form & add rows
Browser -> Browser : addEmployeeRow() / addEquipmentRow()
User -> Browser : click "Create Crew"
Browser -> Server : AJAX POST /TimeEntry/CreateCrew
Server -> Browser : {"message":"Crew created!"}
Browser -> User   : alert("Crew created!")
@enduml

๐Ÿ“ Conclusion

The CreateCrew.cshtml view provides a rich, interactive interface for building a Crew payload. Leveraging Syncfusion EJ2, jQuery, and Tailwind CSS, it dynamically manages complex dropdown dependencies (Jobs โ†’ Cost Codes โ†’ Classes) and bundles employee/equipment data for seamless serverโ€‘side ingestion. The modular helper functions and robust error logging make maintenance and extension straightforward. ๐Ÿš€