JobClassificationView.cshtml Documentation 📄


📑 Table of Contents

  1. Overview & Purpose
  2. Key Functional Areas
  3. Dependencies & Technologies
  4. Layout & ViewData
  5. ViewModel & Data Models
  6. Form Structure & Fields
  7. Syncfusion ComboBox Components
  8. JavaScript Logic & Utilities
    8.1. Dynamic Dropdowns (State → City → County)
    8.2. Modal Preview & Confirmation
    8.3. Syncfusion Change Handlers (valueChange)
    8.4. Validation & Formatting
  9. API Endpoints Overview
  10. Sequence Diagram (UML)
  11. Usage Examples
  12. Error Handling & Return Types
  13. Conclusion

1. Overview & Purpose

File: IrbyImaging/Views/FringeBenefits/JobClassificationView.cshtml
Module: Fringe Benefits / Time Entry
Objective:
This Razor View provides a Job Classification entry interface where administrators can add or edit classification records associated with mechanics’ fringe benefits. It collects data such as classification number, name, fringe amount, location (state/city/county), job, and cost codes. A preview modal confirms entries before submission.

🔍 Use Cases

  • Create a new job classification for fringe benefit calculations.
  • Dynamically filter cities/counties based on selected state.
  • Select jobs and related cost codes via Syncfusion ComboBoxes.
  • Preview form data in a Bootstrap modal before final submission.

2. Key Functional Areas

Functional Area Description
Form Inputs Classification Number, Name, Fringe Amount, State/City/County selects
Syncfusion ComboBoxes Job selection & Cost Code selection with dynamic filtering
Dynamic Dropdowns Chained selects for state → city → county
Preview Modal Bootstrap modal summarizing form entries for user confirmation
Client‐side Validation Required field checks, decimal formatting
AJAX Calls Fetch cost codes by job via /TimeEntry/GetCostCodesByJob endpoint
Styling & Layout Custom CSS + Bootstrap 4 + Syncfusion Fluent theme
Third‐party Libraries Syncfusion EJ2, DataTables, Dropzone, jQuery, Select2

3. Dependencies & Technologies

CSS Dependencies 📚

Library Purpose
~/libs/bootstrap-datepicker/css/bootstrap-datepicker.min.css Datepicker styling
~/libs/datatables.net-bs4/css/dataTables.bootstrap4.min.css DataTables theme
~/libs/datatables.net-responsive-bs4/css/responsive.bootstrap4.min.css Responsive tables
https://cdn.syncfusion.com/ej2/27.1.48/fluent.css Syncfusion Fluent theme
https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css Bootstrap 4 layout
https://cdn.jsdelivr.net/npm/bootstrap-icons/... Bootstrap Icons

JavaScript Dependencies 📜

Library Purpose
jQuery (3.6.0) DOM manipulation & event handling
Bootstrap Bundle (bootstrap.bundle.min.js) Modals, dropdowns, and UI components
Syncfusion EJ2 (ej2.min.js) ComboBox & advanced UI controls
DataTables & Buttons (dataTables.min.js, buttons.html5.js, ...) Tabular data export/printing
Dropzone (dropzone.js) File upload (commented out)
Select2 (select2.min.js) Enhanced <select> (optional)
Custom scripts (app.js) Project-specific behaviors

4. Layout & ViewData

@model IrbyImaging.DomainClasses.MechanicTimesheet
@using Syncfusion.EJ2; 
@using Syncfusion.EJ2.Grids;
@using Syncfusion.EJ2.Popups;
@using Syncfusion.JavaScript;
@using Newtonsoft.Json;
@using IrbyImaging.DomainClasses;

@{
    ViewData["Title"] = "Job Classification";
    Layout = "~/Views/Shared/_TimeLayout.cshtml";
}
  • Layout: Inherits _TimeLayout.cshtml for shared header/footer and CSS/JS bundles.
  • ViewData["Title"]: Sets page title to Job Classification.
  • Model: A MechanicTimesheet domain class (not directly used in form fields).

5. ViewModel & Data Models

Although the view is strongly-typed to MechanicTimesheet, it relies primarily on ViewBag properties populated by the controller:

ViewBag Property Type Description
States List<SelectListItem> All US states for State dropdown
CitiesByState Dictionary<string, List<string>> Maps state → list of cities
CountiesByCity Dictionary<string, List<string>> Maps `state
Jobs List<{ Text, Value }> Job options for Syncfusion Current Job combo
CostCodes List<{ Text, Value }> Initial (empty) or default cost codes

⚠️ Note: CostCodes is initially empty/disabled until a job is selected.


6. Form Structure & Fields

<form asp-action="JobClassificationUpload" method="post" id="jobClassificationForm">
  <div class="card">
    <div class="card-body">
      <div class="row">
        <!-- Left Column -->
        <div class="col-lg-2">
          <div class="form-group">
            <label for="classificationNumber">Classification Number</label>
            <input type="number" class="form-control" id="classificationNumber" name="classificationNumber" required>
          </div>
          <div class="form-group mt-2">
            <label for="classificationName">Classification Name</label>
            <input type="text" class="form-control" id="classificationName" name="classificationName" required>
          </div>
          <div class="form-group mt-2">
            <label for="fringeAmount">Fringe Amount</label>
            <input type="number" step="0.01" class="form-control" id="fringeAmount" name="fringeAmount" required>
          </div>
        </div>
        <!-- Right Column -->
        <div class="col-lg-2">
          <div class="form-group">
            <label for="state">State</label>
            <select class="form-control" id="state" name="state" required>
              <option value="">Select State</option>
              @* Populated via ViewBag.States *@
            </select>
          </div>
          <!-- City & County -->
          <div class="form-group mt-2">
            <label for="city">City</label>
            <select class="form-control" id="city" name="city" required disabled>
              <option value="">Select City</option>
            </select>
          </div>
          <div class="form-group mt-2">
            <label for="county">County</label>
            <select class="form-control" id="county" name="county" required disabled>
              <option value="">Select County</option>
            </select>
          </div>
        </div>
      </div>

      <!-- Syncfusion ComboBoxes -->
      <!-- Current Job -->
      <div class="row mt-2">
        <div class="col-lg-4">
          <label for="jobCombo">Current Job</label>
          <ejs-combobox id="jobCombo" dataSource="@(ViewBag.Jobs)" placeholder="Select a job"
                        popupHeight="230px" allowFiltering="true" filterType="Contains"
                        change="valueChange">
            <e-combobox-fields text="Text" value="Value"></e-combobox-fields>
          </ejs-combobox>
          <input type="hidden" id="jobId" name="jobId" />
        </div>
      </div>
      <!-- Cost Code -->
      <div class="row mt-2">
        <div class="col-lg-4">
          <label for="costCodeCombo">Select a Cost Code</label>
          <ejs-combobox id="costCodeCombo" dataSource="@(ViewBag.CostCodes)"
                        placeholder="Select a cost code" popupHeight="230px"
                        allowFiltering="true" filterType="Contains"
                        change="valueChange">
            <e-combobox-fields text="Text" value="Value"></e-combobox-fields>
          </ejs-combobox>
          <input type="hidden" id="costCodeNumber" name="costCodeNumber" />
          <input type="hidden" id="costCodeName" name="costCodeName" />
        </div>
      </div>

      <!-- Submit Button -->
      <div class="row mt-3">
        <div class="col">
          <button type="button" class="btn btn-primary" id="previewButton">Submit</button>
        </div>
      </div>
    </div>
  </div>
</form>
  • IDs & Names: Ensure consistency between input IDs (for JS) and name attributes (for model binding).
  • Hidden Inputs: Store chosen Job ID and Cost Code details for server submission.
  • Required Fields: HTML5 required attribute ensures basic browser validation.

7. Syncfusion ComboBox Components 🔄

The view leverages Syncfusion EJ2 ComboBox controls for enhanced filtering and dropdown performance.

<ejs-combobox id="jobCombo"
              dataSource="@(ViewBag.Jobs)"
              placeholder="Select a job"
              popupHeight="230px"
              allowFiltering="true"
              filterType="Contains"
              change="valueChange">
  <e-combobox-fields text="Text" value="Value"></e-combobox-fields>
</ejs-combobox>

Key attributes:

  • dataSource: Binds to the Jobs / CostCodes list of { Text, Value } objects.
  • allowFiltering: Enables text filtering inside the dropdown.
  • popupHeight: Limits dropdown height.
  • change="valueChange": Binds to the global valueChange(args) JS handler.

8. JavaScript Logic & Utilities 💻

All client-side behavior is implemented via jQuery, Bootstrap’s JS, and Syncfusion instance methods.

8.1 Dynamic Dropdowns (State → City → County)

$(document).ready(function () {
  var citiesByState   = @Html.Raw(Json.Serialize(ViewBag.CitiesByState));
  var countiesByCity  = @Html.Raw(Json.Serialize(ViewBag.CountiesByCity));

  $('#state').change(function () {
    var selectedState = $(this).val();
    var cityDropdown   = $('#city').empty().append('<option>Select City</option>');
    var countyDropdown = $('#county').empty().append('<option>Select County</option>').prop('disabled', true);

    if (selectedState && citiesByState[selectedState]) {
      cityDropdown.prop('disabled', false);
      citiesByState[selectedState].forEach(city => {
        cityDropdown.append($('<option>').val(city).text(city));
      });
    } else {
      cityDropdown.prop('disabled', true);
    }
  });

  $('#city').change(function () {
    var key = $('#state').val() + '|' + $(this).val();
    var countyDropdown = $('#county').empty().append('<option>Select County</option>');

    if (countiesByCity[key]) {
      countyDropdown.prop('disabled', false);
      countiesByCity[key].forEach(county => {
        countyDropdown.append($('<option>').val(county).text(county));
      });
    } else {
      countyDropdown.prop('disabled', true);
    }
  });
});
  • Data Sources are serialized via Json.Serialize.
  • Chaining ensures user can’t select a city until a state is chosen—and similarly for county.

8.2 Modal Preview & Confirmation

$('#previewButton').click(function() {
  if (!validateForm()) {
    alert('Please fill in all required fields …');
    return;
  }
  // Populate modal fields
  $('#modalClassNumber').text($('#classificationNumber').val());
  // … fill all other modal spans

  // Show Bootstrap modal
  var confirmationModal = new bootstrap.Modal($('#confirmationModal')[0]);
  confirmationModal.show();
});

$('#confirmSubmit').click(function() {
  $('#jobClassificationForm').submit();
});
  • Preview Button: Validates then opens a summary modal.
  • Confirm: On modal “Ok”, submits the form.

8.3 Syncfusion Change Handlers (valueChange)

function valueChange(args) {
  if (this.element.id === 'jobCombo') {
    // Store Job ID
    document.getElementById('jobId').value = args.value;
    // Clear CostCode combo
    var costCodeCombo = document.querySelector("#costCodeCombo").ej2_instances[0];
    costCodeCombo.dataSource = [];
    costCodeCombo.enabled = true;

    // Fetch cost codes via AJAX
    fetch(`/TimeEntry/GetCostCodesByJob?jobId=${args.value}`)
      .then(r => r.json())
      .then(data => { costCodeCombo.dataSource = data; costCodeCombo.dataBind(); })
      .catch(e => console.error(e));
  }
  else if (this.element.id === 'costCodeCombo') {
    var [codeNum, codeName] = args.value.split('|');
    $('#costCodeNumber').val(codeNum);
    $('#costCodeName').val(codeName);
  }
}
  • JobCombo: Triggers AJAX to retrieve cost codes for the selected job.
  • CostCodeCombo: Parses Value into number & name, stores in hidden fields.

8.4 Validation & Formatting

// Decimal formatting for fringeAmount
$('#fringeAmount').on('blur', function() {
  let val = parseFloat($(this).val());
  if (!isNaN(val)) $(this).val(val.toFixed(2));
});

// Simple form validation
function validateForm() {
  return $('#classificationNumber').val() &&
         $('#classificationName').val() &&
         $('#fringeAmount').val() &&
         $('#state').val() &&
         $('#city').val() &&
         $('#county').val() &&
         $('#jobId').val() &&
         $('#costCodeNumber').val();
}
  • Blur Event: Ensures 2‑decimal formatting.
  • validateForm(): Checks all required inputs before modal preview.

9. API Endpoints Overview 🌐

Endpoint Method Purpose
/TimeEntry/GetCostCodesByJob GET Returns JSON list of cost codes for a given job.

Response Shape:

[
  { "Text": "1001|Maintenance Repairs", "Value": "1001|Maintenance Repairs" },
  { "Text": "1002|Parts Replacement",    "Value": "1002|Parts Replacement" }
]

10. Sequence Diagram (UML)

sequenceDiagram
  participant User
  participant Page as JobClassificationView
  participant JS as Client-Side JS
  participant API as /TimeEntry/GetCostCodesByJob
  participant Server

  User->>Page: Load view (States, Jobs, empty CostCodes)
  User->>JS: Select State
  JS->>Page: Populate City dropdown
  User->>JS: Select City
  JS->>Page: Populate County dropdown
  User->>JS: Select Job
  JS->>API: GET CostCodesByJob?jobId=123
  API-->>JS: JSON cost codes
  JS->>Page: Bind cost codes to ComboBox
  User->>JS: Click Submit
  JS->>JS: validateForm()
  JS->>Page: Fill modal spans
  JS->>User: Show confirmationModal
  User->>JS: Click Ok
  JS->>Server: form submit (JobClassificationUpload)
  Server-->>Page: Redirect/Result

11. Usage Examples

Initializing View from Controller (C#)

public IActionResult JobClassificationView() {
    ViewBag.States = GetStateList(); // returns List<SelectListItem>
    ViewBag.CitiesByState = GetCitiesByState(); // Dictionary<string, List<string>>
    ViewBag.CountiesByCity = GetCountiesByCity(); // Dictionary<string, List<string>>
    ViewBag.Jobs = GetJobList(); // List<{Text,Value}>
    ViewBag.CostCodes = new List<object>(); // empty initially
    return View();
}

Handling Submission (C#)

[HttpPost]
public IActionResult JobClassificationUpload(int classificationNumber,
                                             string classificationName,
                                             decimal fringeAmount,
                                             string state,
                                             string city,
                                             string county,
                                             int jobId,
                                             string costCodeNumber,
                                             string costCodeName) {
    // Map to domain model, save to DB
    _service.SaveJobClassification(...);
    return RedirectToAction("Success");
}

12. Error Handling & Return Types

  • AJAX Fetch Error: Logged to console; dropdown enabled to allow manual entry.
  • Form Validation Errors: Handled via alert and HTML5 required.
  • Server‐side Errors: Should be caught in controller and returned via ModelState or TempData (not shown here).

13. Conclusion 🎯

The JobClassificationView is a comprehensive Razor page that streamlines the creation of job classification records for fringe benefits.
Key takeaways:

  • User Experience is enhanced via chained dropdowns, Syncfusion ComboBoxes, and confirmation modals.
  • Maintainability is achieved by centralizing view data in ViewBag and modular JS handlers (valueChange, validateForm).
  • Extensibility: Additional fields or validations can be integrated easily by following the existing patterns.

🚀 This view can be reused or extended for any similar data-entry scenario requiring dynamic selects, preview modals, and rich UI components.