📄 SafetyDocumentCategories Model Documentation

Welcome to the in-depth documentation for the SafetyDocumentCategories model in IrbyImaging.UI. This guide covers every aspect of the file SafetyDocumentCategories.cs, explaining its purpose, structure, properties, relationships, usage examples, and even a UML diagram.


📑 Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Key Functional Areas
  4. Data Models
  5. UML Class Diagram
  6. Properties Reference
  7. Usage Examples & Code Snippets
  8. Common Scenarios & Best Practices
  9. Error Handling & Validation
  10. Conclusion

🔍 Overview & Purpose

The SafetyDocumentCategories file defines two Plain Old CLR Objects (POCOs) that represent categorization metadata for safety-related documents in the IrbyImaging.UI layer:

  • SafetyDocumentCategories
    Aggregates a list of individual document details grouped by category/type.
  • SafetyDocumentCategoryDetail
    Represents a single categorization entry for a safety document.

These models are typically used to:

  • Drive UI components (e.g., dropdowns, grids) that group and filter documents by category or index.
  • Carry metadata from backend APIs to the front-end for display or selection.
  • Facilitate multi-value indexing when a document can belong to multiple sub-categories.

🛠 Dependencies & Technologies

  • .NET 6+ / .NET Core
  • C# 10+
  • System.Collections.Generic (for List<T>)
  • System.Linq / System.Threading.Tasks (imported but not directly used here)

No third‑party NuGet packages are required for these POCOs.


⚙️ Key Functional Areas

  1. Category Definition
    Groups documents into high‑level categories for user selection.
  2. Indexing
    Defines how documents are indexed (by name, type, value, multi‑value flag).
  3. Aggregation
    Collates multiple SafetyDocumentCategoryDetail entries under a single SafetyDocumentCategories instance.

📦 Data Models

SafetyDocumentCategories

  • Role: Container for multiple SafetyDocumentCategoryDetail objects, representing a grouped category of documents.
  • Namespace: IrbyImaging.UI.Models
  • File: SafetyDocumentCategories.cs

SafetyDocumentCategoryDetail

  • Role: Represents the metadata for a single document category entry.
  • Namespace: IrbyImaging.UI.Models
  • File: SafetyDocumentCategories.cs

🏷 UML Class Diagram

classDiagram
    class SafetyDocumentCategories {
        +string DocumentCategory
        +string DocumentType
        +string IndexName
        +string IndexType
        +string IndexValue
        +bool   MultiValueIndex
        +List~SafetyDocumentCategoryDetail~ DocumentList
    }

    class SafetyDocumentCategoryDetail {
        +string DocumentCategory
        +string DocumentType
        +string IndexName
        +string IndexType
        +string IndexValue
        +bool   MultiValueIndex
    }

    SafetyDocumentCategories "1" --> "0..*" SafetyDocumentCategoryDetail : contains >

📋 Properties Reference

Property Table: SafetyDocumentCategories

Property Type Description
DocumentCategory string High‑level category (e.g., "Training", "Inspection").
DocumentType string Sub‑type or classification (e.g., "PDF", "Image").
IndexName string The name of the index key used for grouping (e.g., "Year", "Department").
IndexType string The type/format of the index (e.g., "Date", "String", "Numeric").
IndexValue string The specific value of the index (e.g., "2023", "SafetyTeam").
MultiValueIndex bool true if multiple index values are allowed, false otherwise.
DocumentList List<SafetyDocumentCategoryDetail> Child entries that further detail individual documents under this category.

Property Table: SafetyDocumentCategoryDetail

Property Type Description
DocumentCategory string Same as parent category for ease of filtering or display.
DocumentType string Same as parent type for detailed listing.
IndexName string Inherited from parent — helps with UI grouping.
IndexType string Defines data type of the index.
IndexValue string Actual value for this document entry.
MultiValueIndex bool Indicates if this entry can hold multiple index values.

🚀 Usage Examples & Code Snippets

1. Instantiating & Populating

using IrbyImaging.UI.Models;
using System.Collections.Generic;

var categoryGroup = new SafetyDocumentCategories
{
    DocumentCategory = "Inspection Reports",
    DocumentType     = "PDF",
    IndexName        = "Year",
    IndexType        = "Numeric",
    IndexValue       = "2023",
    MultiValueIndex  = false,
    DocumentList     = new List<SafetyDocumentCategoryDetail>
    {
        new SafetyDocumentCategoryDetail {
            DocumentCategory = "Inspection Reports",
            DocumentType     = "PDF",
            IndexName        = "Month",
            IndexType        = "String",
            IndexValue       = "March",
            MultiValueIndex  = false
        },
        new SafetyDocumentCategoryDetail {
            DocumentCategory = "Inspection Reports",
            DocumentType     = "PDF",
            IndexName        = "Month",
            IndexType        = "String",
            IndexValue       = "April",
            MultiValueIndex  = false
        }
    }
};

2. Binding to a Razor View

@model SafetyDocumentCategories

<h2>@Model.DocumentCategory - @Model.IndexValue</h2>
<ul>
  @foreach (var detail in Model.DocumentList)
  {
      <li>
          <strong>@detail.IndexName:</strong> @detail.IndexValue
      </li>
  }
</ul>

3. LINQ Filtering

// Get only entries with a specific index value
var marchReports = categoryGroup
    .DocumentList
    .Where(d => d.IndexValue == "March")
    .ToList();

🔧 Common Scenarios & Best Practices

  • Multi‑Value Indexing
    If MultiValueIndex is true, your UI should allow selecting or displaying multiple values (e.g., checkboxes, multi‑select lists).
  • Consistent Category Fields
    Keep DocumentCategory and DocumentType in sync between the parent and child objects to simplify filtering.
  • Client‑Side Grouping
    You can send a flat list of SafetyDocumentCategoryDetail objects to the client and group them in JavaScript by IndexName or IndexValue.

⚠️ Error Handling & Validation

  • Null Checks
    Ensure DocumentList is not null before iterating.
  • Empty Collections
    A missing or empty list indicates no documents in that category—handle gracefully in the UI.
  • Invalid Index Types
    If IndexType does not match expected formats (e.g., non‑numeric when numeric is required), perform validation before display or sorting.

🔚 Conclusion

The SafetyDocumentCategories and SafetyDocumentCategoryDetail classes provide a lightweight, flexible way to represent and group safety document metadata in the IrbyImaging.UI layer. By leveraging these models, you can:

  • Aggregate documents by category/type.
  • Index them dynamically for filtering and display.
  • Enable multi‑value indexing scenarios.

Use the provided code snippets and best practices as a starting point to integrate these models into your controllers, services, or Razor views. With clear separation of parent/child metadata, your UI can easily render complex document hierarchies in a user‑friendly manner.


Thank you for using IrbyImaging.UI! If you have any questions or need further assistance, feel free to raise an issue or consult the code owner. 🚧✅