🎟️ TicketViewModel.cs Documentation

A comprehensive guide to the TicketViewModel class in IrbyImaging.UI, illuminating its purpose, structure, and usage within the application.


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. UML Class Diagram
  4. Key Functional Areas
  5. DataAnnotations & Serialization
  6. Usage Examples
  7. Integration with MVC
  8. Helper Methods & Utilities
  9. Error Handling & Edge Cases
  10. Conclusion & Best Practices

🌐 Overview & Purpose

TicketViewModel is a ViewModel class designed to bridge the application's domain layer (IrbyImaging.DomainClasses.Ticket) and the UI presentation. It:

  • Maps domain properties to UI-friendly representations.
  • Applies DataAnnotations for display and formatting.
  • Encapsulates light-weight business logic for description parsing.
  • Prepares raw data (JSON, binary images) for rendering.

🔧 Dependencies & Technologies

Technology / Library Purpose
.NET / C# Language and platform
ASP.NET MVC DataAnnotations UI metadata (labels, formatting)
Newtonsoft.Json (Optional) JSON serialization/deserialization
IrbyImaging.DomainClasses Core domain types (e.g., Ticket, TicketType)
IrbyImaging.Utility Extension methods (e.g., GetDisplayName() for enums)

📊 UML Class Diagram

classDiagram
    class Ticket {
        +Guid Id
        +int TicketNumber
        +string CustomerName
        +DateTime CreatedOn
        +string Description
        +TicketType Type
        +StatusEnum Status
        +string RequestedJson
        +string EmployeeAndJobDetails
        +string ShippingAddress
        +byte[] ImageContents
        +DateTime UpdatedOn
    }

    class TicketViewModel {
        +Guid Id
        +int TicketNumber
        +string CustomerName
        +DateTime CreatedOn
        +string Description
        +string Status
        +string Type
        +string RequestedJson
        +string EmployeeAndJobDetails
        +string ShippingAddress
        +string LastUpdate
        +string LastUpdatedBy
        +DateTime UpdatedOn
        +byte[] ImageContents

        +TicketViewModel()
        +TicketViewModel(Ticket ticket)
    }

    Ticket --> TicketViewModel : maps to

🔑 Key Functional Areas

Properties

Property Type Description
Id Guid Unique identifier of the ticket.
TicketNumber int Numeric ticket code.
CustomerName string Display name of the customer.
CreatedOn DateTime Date when the ticket was created.
Description string Human-readable description (with custom parsing).
Status string Current status (enum → display name).
Type string Ticket category (enum → string).
RequestedJson string Raw JSON for request details.
EmployeeAndJobDetails string Employee/job assignment details.
ShippingAddress string Address for shipping, if applicable.
LastUpdate string Textual last update (e.g., “2 days ago”).
LastUpdatedBy string User who last updated the ticket.
UpdatedOn DateTime Last update timestamp.
ImageContents byte[] Binary image data (e.g., attachments).

ℹ️ Note: Some “Last…” fields are settable for UI display but not yet wired in constructor.

Constructors

  1. Default

    public TicketViewModel() { }
    
    • Initializes an empty view model (useful for model binding on forms).
  2. Domain-to-ViewModel Mapper

    public TicketViewModel(Ticket ticket) { ... }
    
    • Maps domain properties → view model fields.
    • Applies business logic for Incident type descriptions.
    • Uses GetDisplayName() to translate enum statuses to friendly text.

Business Logic in Constructor

if (ticket.Type == TicketType.Incident) {
    var parts = ticket.Description.Split(':', 2);
    // Remove default prefix if:
    if (parts[0] == "Having an issue with something else") {
        Description = parts[1];
    } else {
        Description = ticket.Description;
    }
} else {
    Description = ticket.Description;
}
  • Purpose: Strip boilerplate prefix for certain incident tickets to improve readability.

📋 DataAnnotations & Serialization

Field Attribute Effect
CustomerName [Display(Name = "Customer")] Label “Customer” in views.
CreatedOn [Display(Name = "Created On")] Custom label.
[DataType(DataType.Date)] Render date-only picker/format.
LastUpdate / LastUpdatedBy [Display(Name = "Last Update")] Same label (typo? might need “By”).
UpdatedOn [DataType(DataType.Date)] Date formatting.

🔄 JSON: Although RequestedJson is a raw string, you can parse it client-side or via JsonConvert.DeserializeObject(...) if structured.


🚀 Usage Examples

1. Mapping a Domain Ticket

using IrbyImaging.DomainClasses;
using IrbyImaging.ViewModels;

// Suppose you fetched a ticket from the database:
Ticket domainTicket = ticketRepository.GetById(id);

// Create the ViewModel:
TicketViewModel vm = new TicketViewModel(domainTicket);

// Pass to MVC view:
return View(vm);

2. Rendering in Razor

@model IrbyImaging.ViewModels.TicketViewModel

<h2>Ticket #@Model.TicketNumber</h2>
<dl>
  <dt>@Html.DisplayNameFor(m => m.CustomerName)</dt>
  <dd>@Model.CustomerName</dd>

  <dt>@Html.DisplayNameFor(m => m.CreatedOn)</dt>
  <dd>@Model.CreatedOn.ToShortDateString()</dd>

  <dt>Description</dt>
  <dd>@Model.Description</dd>
</dl>

⚙️ Integration with MVC

  1. Controller

    • Instantiate TicketViewModel from domain.
    • Return it to the View.
  2. View (Razor)

    • Leverage @Html.DisplayNameFor(...) and @Html.EditorFor(...) thanks to DataAnnotations.
    • Display binary images:
      @if (Model.ImageContents?.Length > 0) {
        string base64 = Convert.ToBase64String(Model.ImageContents);
        <img src="data:image/png;base64,@base64" alt="Attachment" />
      }
      
  3. Forms / Posting Back

    • Use the parameterless constructor and bind fields if editing.

🛠️ Helper Methods & Utilities

  • GetDisplayName()

    // Extension (in IrbyImaging.Utility):
    public static string GetDisplayName(this Enum enumValue) { /*...*/ }
    
    • Converts status enums into friendly names (e.g., Open → “Open Ticket”).
  • Newtonsoft.Json

    • (Commented in code) you could parse RequestedJson:
      var details = JsonConvert.DeserializeObject<YourDto>(ticket.RequestedJson);
      

🚨 Error Handling & Edge Cases

  • Null ticket: the constructor does not guard against a null Ticket. Always ensure non-nullity.
  • Malformed Description: Split(':',2) expects at least one colon; safe since it returns an array of length 1 if none exist.
  • Missing Date Fields: UpdatedOn, LastUpdate, LastUpdatedBy remain defaults unless set externally.

✅ Conclusion & Best Practices

  • Separation of Concerns: Business logic for description cleaning is minimal—consider moving to a dedicated service if it grows.
  • DataAnnotations: Keep labels & formatting DRY by centralizing attribute definitions.
  • Error Safety: Add null checks or throw meaningful exceptions for invalid domain objects.
  • Extension: You may enrich the ViewModel with validation attributes ([Required], [StringLength]) for form-binding scenarios.

✨ TicketViewModel streamlines the presentation of Ticket data in MVC views, balancing simple mapping with light business logic to ensure a clean, user-friendly UI.