# Dept Stat Cards — Module Integration Guide

This document explains how any new loan module integrates the shared approval-stage stat cards into its index page.

---

## What the partial renders

Five Bootstrap cards in a responsive row — one per approval tier — each showing:

- The tier name and color-coded icon
- Total record count for that module
- Three badge counters: **Pending**, **Approved**, **Rejected**

```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 🛡 Cr.Supervisor│ │ 📈 Credit Head  │ │ 🛡 Risk Mgmt   │ │ 💰 EVP Finance  │ │ 👑 CEO/Mgmt     │
│ Total: 42       │ │ Total: 42       │ │ Total: 42       │ │ Total: 42       │ │ Total: 42       │
│ P:10 A:30 R:2   │ │ P:12 A:28 R:2   │ │ P:14 A:26 R:2   │ │ P:15 A:25 R:2   │ │ P:18 A:22 R:2   │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
```

---

## Partial location

```
app/Views/partials/_dept_stat_cards.php
```

---

## Step-by-step integration

### Step 1 — Build `$deptStats` in the controller `index()` method

The partial expects `$deptStats` — an array of cards, one per approval tier.
Each entry must have these keys:

| Key | Type | Description |
|---|---|---|
| `label` | string | Tier display name |
| `icon` | string | FontAwesome class (without `fas`) |
| `color` | string | Bootstrap color name (`primary`, `success`, etc.) |
| `total` | int | Total records in the module table |
| `pending` | int | Records where this tier status is not Approved or Denied |
| `approved` | int | Records where this tier status is `Approved` |
| `rejected` | int | Records where this tier status is `Denied` |

**Standard 5-tier definition (copy-paste this into every new module's `index()`):**

```php
$db       = \Config\Database::connect();
$statRows = $db->table('your_table_name')
    ->select('credit_supervisor_status, credit_head_status, risk_mgmt_status,
              evp_finance_status, ceo_president_status')
    ->get()->getResultArray();

$total    = count($statRows);

$deptDefs = [
    ['label' => 'Credit Supervisor', 'key' => 'credit_supervisor_status', 'icon' => 'fa-user-shield', 'color' => 'secondary'],
    ['label' => 'Credit Head',       'key' => 'credit_head_status',       'icon' => 'fa-user-tie',    'color' => 'info'],
    ['label' => 'Risk Management',   'key' => 'risk_mgmt_status',         'icon' => 'fa-shield-alt',  'color' => 'primary'],
    ['label' => 'EVP Finance',       'key' => 'evp_finance_status',       'icon' => 'fa-coins',       'color' => 'warning'],
    ['label' => 'CEO / Management',  'key' => 'ceo_president_status',     'icon' => 'fa-chess-king',  'color' => 'danger'],
];

$deptStats = [];
foreach ($deptDefs as $d) {
    $approved = $pending = $rejected = 0;
    foreach ($statRows as $r) {
        $v = $r[$d['key']] ?? 'Pending';
        if ($v === 'Approved')   $approved++;
        elseif ($v === 'Denied') $rejected++;
        else                     $pending++;
    }
    $deptStats[] = array_merge($d, [
        'total'    => $total,
        'approved' => $approved,
        'pending'  => $pending,
        'rejected' => $rejected,
    ]);
}
```

---

### Step 2 — Pass variables to the view

Pass `$deptStats` plus two module-specific display strings:

| Variable | Type | Description | Example |
|---|---|---|---|
| `deptStats` | array | Built in Step 1 | — |
| `deptStatLabel` | string | Entity noun shown under "Total …" | `'Loans'`, `'Applications'`, `'Facilities'` |
| `deptStatIcon` | string | FontAwesome class for the large background icon | `'fa-file-invoice-dollar'`, `'fa-building'`, `'fa-car'` |

```php
return view('App\Modules\YourModule\Views\index', $this->viewData([
    'title'         => 'Your Module Title',
    'deptStats'     => $deptStats,
    'deptStatLabel' => 'Loans',                  // ← change per module
    'deptStatIcon'  => 'fa-file-invoice-dollar', // ← change per module
]));
```

**If `deptStatLabel` or `deptStatIcon` are omitted**, the partial falls back to `'Records'` and `'fa-file-alt'` automatically — so the cards always render even before you customise the values.

---

### Step 3 — Include the partial in the index view

In `app/Modules/YourModule/Views/index.php`, replace any inline card loop with:

```php
<?= $this->include('App\Views\partials\_dept_stat_cards') ?>
```

Place it immediately after the page header and before the flash messages:

```php
<?= $this->extend('App\Views\layouts\main') ?>
<?= $this->section('content') ?>

<!-- Page header -->
<div class="d-flex align-items-center justify-content-between mb-4">
    <h5 class="fw-bold mb-0">
        <i class="fas fa-your-icon me-2 text-primary"></i>Your Module
    </h5>
    <?php if (can('applications.create')): ?>
    <a href="<?= base_url('your-module/create') ?>" class="btn btn-primary btn-sm">
        <i class="fas fa-plus me-1"></i> New Record
    </a>
    <?php endif ?>
</div>

<!-- Approval stage stat cards -->
<?= $this->include('App\Views\partials\_dept_stat_cards') ?>

<!-- Flash messages -->
<?php if (session()->getFlashdata('success')): ?>
<div class="alert alert-success alert-dismissible fade show">
    <?= esc(session()->getFlashdata('success')) ?>
    <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
</div>
<?php endif ?>

<!-- DataTable ... -->
```

---

## Live examples

| Module | Table | `deptStatLabel` | `deptStatIcon` | Controller |
|---|---|---|---|---|
| Mortgage Loans | `mortgage_applications` | `'Applications'` | `'fa-file-invoice-dollar'` | `MortgageLoanController::index()` |
| Apex Loans | `apex_facilities` | `'Facilities'` | `'fa-building'` | `ApexLoanController::index()` |

---

## Customising tier colors

The standard color palette used across all modules:

| Tier | `color` value | Rendered as |
|---|---|---|
| Credit Supervisor | `secondary` | Grey |
| Credit Head | `info` | Light blue |
| Risk Management | `primary` | Blue |
| EVP Finance | `warning` | Amber |
| CEO / Management | `danger` | Red |

You may override any color for a specific module by changing the `color` value in that module's `$deptDefs` array. All valid Bootstrap color names are accepted (`primary`, `secondary`, `success`, `danger`, `warning`, `info`, `dark`).

---

## Adding a non-standard tier

If a future module has a custom approval stage (e.g. a "Board" tier), add it to `$deptDefs` with a unique `key` matching the DB column name and the partial will render it automatically — no changes to the partial itself are needed.

```php
['label' => 'Board Approval', 'key' => 'board_status', 'icon' => 'fa-landmark', 'color' => 'dark'],
```

---

## Partial variable reference

```
app/Views/partials/_dept_stat_cards.php
```

| Variable | Source | Required | Default |
|---|---|---|---|
| `$deptStats` | Controller `viewData()` | Yes | — |
| `$deptStatLabel` | Controller `viewData()` | No | `'Records'` |
| `$deptStatIcon` | Controller `viewData()` | No | `'fa-file-alt'` |
