balancesCostModalYTD.cshtml Documentation 📑

File Path: IrbyImaging/Views/IView/balancesCostModalYTD.cshtml
Purpose: Razor view to render a Year-To-Date (YTD) Cost breakdown for jobs, complete with export functionality (CSV, Excel, Print) via DataTables.


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. ViewModel & Data Models
  4. Key Functional Areas
  5. Third‑Party Integrations
  6. UML Class Diagram
  7. Error Handling & Return Types
  8. Usage Examples
  9. Conclusion

1. Overview & Purpose 🎯

This Razor view displays a modal-like table of Year‑To‑Date (YTD) cost details for various jobs, cost codes, and descriptive fields. It leverages DataTables (jQuery plugin) to provide:

  • Searching & filtering
  • Sorting & paging
  • Export options: CSV, Excel, Print

Typically used in a modal dialog or a partial view when a user wants to inspect YTD costs for a selected job or cost center.


2. Dependencies & Technologies 🛠️

Category Library / Tech Purpose
Server‑Side ASP.NET MVC / Razor View engine & model binding
Model IrbyImaging.UI.Models.Balances Strongly‑typed ViewModel
CSS Bootstrap 4 (implicit) Basic styling
CSS DataTables Bootstrap integration Table styling
JavaScript jQuery (v3.5.1+) DOM manipulation
JavaScript Plugin DataTables v1.10.25 Enhanced table features
JS Extensions DataTables Buttons, JSZip, pdfmake, vfs_fonts Export: CSV, Excel, PDF, Print

3. ViewModel & Data Models 🔍

3.1. Balances ViewModel

namespace IrbyImaging.UI.Models
{
    public class Balances
    {
        // Collection of YTD cost details
        public List<BalanceDetail> Details { get; set; }
    }
}

3.2. BalanceDetail Data Model

Property Type Description
JobNumber string Unique job identifier
JobName string Descriptive job name
ReportingYear int Year of the report (e.g., 2023)
ReportingMonth int Month of the report (1–12)
CostCode string Cost code (e.g., labor, materials)
CostCodeDescription string Human‑readable description for the cost code
Cost decimal Year‑to‑Date cost amount

4. Key Functional Areas 🚀

4.1. Model Binding

At the top of the view, the strongly‑typed model is declared:

@model IrbyImaging.UI.Models.Balances

This binds the Balances ViewModel, enabling Razor helpers like @Html.DisplayFor(...).


4.2. HTML Structure & Markup

<div class="row">
  <div id="ControlRegion">
    <table id="jobDatatable" class="table table-striped table-bordered dt-responsive">
      <thead>
        <tr>
          <th>Job Number</th>
          <th>Job Name</th>
          <th>Year</th>
          <th>Month</th>
          <th>Cost Code</th>
          <th>Description</th>
          <th>YTD Cost</th>
        </tr>
      </thead>
      <tbody>
        @foreach (var item in Model.Details) {
          <tr>
            <td>@Html.DisplayFor(m => item.JobNumber)</td>
            <td>@Html.DisplayFor(m => item.JobName)</td>
            <td>@Html.DisplayFor(m => item.ReportingYear)</td>
            <td>@Html.DisplayFor(m => item.ReportingMonth)</td>
            <td>@Html.DisplayFor(m => item.CostCode)</td>
            <td>@Html.DisplayFor(m => item.CostCodeDescription)</td>
            <td>@Html.DisplayFor(m => item.Cost)</td>
          </tr>
        }
      </tbody>
    </table>
  </div>
</div>
  • <table id="jobDatatable">: Root table that DataTables will enhance.
  • <thead> & <tbody>: Standard table headers and rows generated via Razor loop.

4.3. CSS Styling

<style>
  /* Ensures table header is displayed when exporting/printing */
  #jobDatatable { display: table-header-group; }
</style>

<link href="~/lib/datatables/css/dataTables.bootstrap4.min.css" rel="stylesheet" />
<link href="https://cdn.datatables.net/1.10.25/css/jquery.dataTables.min.css" rel="stylesheet" />
<link href="https://cdn.datatables.net/buttons/1.7.1/css/buttons.dataTables.min.css" rel="stylesheet" />
  • Uses Bootstrap 4 and DataTables styles for a consistent, responsive look.

4.4. Data Rendering

  • Razor foreach loop iterates Model.Details.
  • @Html.DisplayFor helpers ensure proper formatting and HTML encoding.

4.5. JavaScript / DataTables Integration

CDN Scripts

<script src="https://cdn.datatables.net/1.10.25/js/jquery.dataTables.min.js"></script>
<script src="https://cdn.datatables.net/buttons/1.7.1/js/dataTables.buttons.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.1.3/jszip.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdfmake/0.1.53/pdfmake.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdfmake/0.1.53/vfs_fonts.js"></script>
<script src="https://cdn.datatables.net/buttons/1.7.1/js/buttons.html5.min.js"></script>
<script src="https://cdn.datatables.net/buttons/1.7.1/js/buttons.print.min.js"></script>

Initialization Script

<script type="text/javascript">
  $(document).ready(function () {
    $('#jobDatatable').DataTable({
      dom: 'Bfrtip',
      buttons: [
        'csv', 'excel', 'print'
      ]
    });
  });
</script>
  • dom: 'Bfrtip': Places buttons at the top (B), filter (f), table (t), information (i), and pagination (p).
  • Built‑in buttons: CSV, Excel, Print.

5. Third‑Party Integrations 🔗

  • DataTables: Powerful table plugin for jQuery (sorting, paging, export).
  • JSZip & pdfmake: Underpin Excel and PDF exports.
  • (Commented Out) Syncfusion JavaScript: Initially integrated but replaced by DataTables.

6. UML Class Diagram 🏗️

classDiagram
    class Balances {
        +List~BalanceDetail~ Details
    }
    class BalanceDetail {
        +string JobNumber
        +string JobName
        +int ReportingYear
        +int ReportingMonth
        +string CostCode
        +string CostCodeDescription
        +decimal Cost
    }
    Balances --> "0..*" BalanceDetail

7. Error Handling & Return Types 🚨

  • View Side: No explicit error handling; errors bubble up to the MVC pipeline.
  • Controller Side: Should ensure Model.Details is non‑null (e.g., an empty list if no data).
  • DataTables: Displays console errors if initialization fails.

8. Usage Examples 🔧

8.1. Controller Action

public IActionResult ShowBalancesYTD(int jobId)
{
    // Fetch balances from service/repository
    var balances = _balanceService.GetBalancesForJob(jobId);
    return PartialView("balancesCostModalYTD", balances);
}

8.2. Triggering the Modal (e.g., with Bootstrap)

<!-- Button to open modal -->
<button id="btnOpenBalances" class="btn btn-primary">View YTD Costs</button>

<!-- Placeholder for loaded partial view -->
<div id="balancesModalContainer"></div>

<script>
  $('#btnOpenBalances').on('click', function() {
    $.get('/IView/ShowBalancesYTD?jobId=123', function(html) {
      $('#balancesModalContainer').html(html);
      // If using Bootstrap modal:
      $('#balancesModalContainer .modal').modal('show');
    });
  });
</script>

9. Conclusion 🏁

  • balancesCostModalYTD.cshtml is a focused Razor partial view for presenting Year‑to‑Date cost details in a dynamic, export‑ready table.
  • Leveraging jQuery DataTables provides a rich, user‑friendly experience—sorting, filtering, exporting—with minimal custom code.
  • By binding a strongly‑typed Balances ViewModel, the view remains clean, maintainable, and secure.

Feel free to customize styling, adjust DataTable options, or integrate additional export formats as your requirements evolve! 🚀