# Phase 2.2 Quick Start Guide

**Goal:** Add consistent navigation tabs to module pages in 5 minutes or less per file.

---

## Step-by-Step Implementation

### Step 1: Create the Reusable Component (One Time Only)

Create `views/components/module_nav_tabs.php`:

```php
<?php
/**
 * Reusable Module Navigation Tabs Component
 *
 * @param array $tabs - Array of tab definitions with optional 'permission' key
 * @param string $currentPage - Current active page identifier
 */
function renderModuleNavTabs($tabs, $currentPage) {
    if (empty($tabs)) return;

    // Filter tabs based on user permissions
    $visibleTabs = array_filter($tabs, function($tab) {
        // If no permission required, show the tab
        if (empty($tab['permission'])) {
            return true;
        }
        // Check if user has the required permission
        return hasPermission($tab['permission']);
    });

    // Don't render anything if no tabs are visible
    if (empty($visibleTabs)) return;
    ?>
    <ul class="nav nav-tabs mb-4" role="tablist">
        <?php foreach ($visibleTabs as $tab): ?>
            <li class="nav-item" role="presentation">
                <a class="nav-link <?= $currentPage === $tab['id'] ? 'active' : '' ?>"
                   href="<?= base_url($tab['url']) ?>"
                   <?= $currentPage === $tab['id'] ? 'aria-current="page"' : '' ?>>
                    <?php if (!empty($tab['icon'])): ?>
                        <i class="bi bi-<?= e($tab['icon']) ?> me-1"></i>
                    <?php endif; ?>
                    <?= e($tab['label']) ?>
                    <?php if (!empty($tab['badge'])): ?>
                        <span class="badge bg-<?= $tab['badge_color'] ?? 'primary' ?> ms-1">
                            <?= e($tab['badge']) ?>
                        </span>
                    <?php endif; ?>
                </a>
            </li>
        <?php endforeach; ?>
    </ul>
    <?php
}
?>
```

---

### Step 2: Update Controller (Pass $currentPage)

In your controller method, add `currentPage` to the data array:

```php
public function dashboard() {
    $this->requireAuth();
    
    // ... your existing code ...
    
    $this->layout('hr/recruitment/dashboard', [
        'pageTitle' => 'Recruitment Dashboard',
        'currentPage' => 'dashboard',  // ← ADD THIS
        // ... other data ...
    ]);
}
```

**Repeat for each page in the module:**
- `dashboard` → `'currentPage' => 'dashboard'`
- `positions/index` → `'currentPage' => 'positions'`
- `applications/index` → `'currentPage' => 'applications'`
- etc.

---

### Step 3: Update View Files (Add Nav Tabs)

Open each view file and add the navigation tabs **after the page header** and **before the main content**.

**Example: `views/hr/recruitment/dashboard.php`**

```php
<!-- Page Header -->
<div class="d-flex align-items-center mb-3">
    <div class="flex-grow-1">
        <h1 class="page-header mb-0">Recruitment Dashboard</h1>
    </div>
    <div>
        <!-- Action buttons -->
    </div>
</div>

<!-- ✅ ADD MODULE NAVIGATION TABS HERE -->
<?php
require_once BASE_PATH . '/views/components/module_nav_tabs.php';

$recruitmentTabs = [
    ['id' => 'dashboard', 'label' => 'Dashboard', 'icon' => 'speedometer2', 'url' => 'hr/recruitment/dashboard'],
    ['id' => 'positions', 'label' => 'Positions', 'icon' => 'briefcase', 'url' => 'hr/recruitment/positions'],
    ['id' => 'applications', 'label' => 'Applications', 'icon' => 'file-earmark-person', 'url' => 'hr/recruitment/applications'],
    ['id' => 'interviews', 'label' => 'Interviews', 'icon' => 'calendar-event', 'url' => 'hr/recruitment/interviews'],
    ['id' => 'assessments', 'label' => 'Assessments', 'icon' => 'clipboard-check', 'url' => 'hr/recruitment/assessments'],
    ['id' => 'offers', 'label' => 'Offers', 'icon' => 'envelope-check', 'url' => 'hr/recruitment/offers'],
];

renderModuleNavTabs($recruitmentTabs, $currentPage ?? 'dashboard');
?>

<!-- Main Content -->
<div class="row">
    <!-- ... existing content ... -->
</div>
```

**Copy the same `$recruitmentTabs` array to ALL files in the module:**
- `views/hr/recruitment/dashboard.php`
- `views/hr/recruitment/positions/index.php`
- `views/hr/recruitment/applications/index.php`
- `views/hr/recruitment/interviews/index.php`
- `views/hr/recruitment/assessments/index.php`
- `views/hr/recruitment/offers/index.php`

---

## Tab Definitions by Module

### HR → Recruitment

```php
$recruitmentTabs = [
    ['id' => 'dashboard', 'label' => 'Dashboard', 'icon' => 'speedometer2', 'url' => 'hr/recruitment/dashboard', 'permission' => 'hr.view'],
    ['id' => 'positions', 'label' => 'Positions', 'icon' => 'briefcase', 'url' => 'hr/recruitment/positions', 'permission' => 'hr.view'],
    ['id' => 'applications', 'label' => 'Applications', 'icon' => 'file-earmark-person', 'url' => 'hr/recruitment/applications', 'permission' => 'hr.view'],
    ['id' => 'interviews', 'label' => 'Interviews', 'icon' => 'calendar-event', 'url' => 'hr/recruitment/interviews', 'permission' => 'hr.view'],
    ['id' => 'assessments', 'label' => 'Assessments', 'icon' => 'clipboard-check', 'url' => 'hr/recruitment/assessments', 'permission' => 'hr.view'],
    ['id' => 'offers', 'label' => 'Offers', 'icon' => 'envelope-check', 'url' => 'hr/recruitment/offers', 'permission' => 'hr.view'],
];
```

### Manufacturing → Quality

```php
$qualityTabs = [
    ['id' => 'dashboard', 'label' => 'Dashboard', 'icon' => 'speedometer2', 'url' => 'manufacturing/quality', 'permission' => 'manufacturing.view'],
    ['id' => 'inspections', 'label' => 'Inspections', 'icon' => 'clipboard-check', 'url' => 'manufacturing/quality/inspections', 'permission' => 'manufacturing.view'],
    ['id' => 'ncr', 'label' => 'NCR', 'icon' => 'exclamation-triangle', 'url' => 'manufacturing/quality/ncr', 'permission' => 'manufacturing.view'],
    ['id' => 'metrics', 'label' => 'Metrics', 'icon' => 'graph-up', 'url' => 'manufacturing/quality/metrics', 'permission' => 'manufacturing.view'],
    ['id' => 'templates', 'label' => 'Templates', 'icon' => 'file-earmark-text', 'url' => 'manufacturing/quality/templates', 'permission' => 'manufacturing.view'],
];
```

### Projects

```php
$projectTabs = [
    ['id' => 'dashboard', 'label' => 'Dashboard', 'icon' => 'speedometer2', 'url' => 'projects/dashboard', 'permission' => 'projects.view'],
    ['id' => 'my_tasks', 'label' => 'My Tasks', 'icon' => 'check2-square', 'url' => 'projects/my_tasks', 'permission' => 'projects.view'],
    ['id' => 'list', 'label' => 'All Projects', 'icon' => 'list-ul', 'url' => 'projects/list', 'permission' => 'projects.view'],
    ['id' => 'board', 'label' => 'Board', 'icon' => 'kanban', 'url' => 'projects/board', 'permission' => 'projects.view'],
    ['id' => 'gantt', 'label' => 'Gantt', 'icon' => 'bar-chart-steps', 'url' => 'projects/gantt', 'permission' => 'projects.view'],
];
```

### Manufacturing → Maintenance

```php
$maintenanceTabs = [
    ['id' => 'work_orders', 'label' => 'Work Orders', 'icon' => 'wrench', 'url' => 'manufacturing/maintenance/work_orders', 'permission' => 'manufacturing.view'],
    ['id' => 'schedules', 'label' => 'Schedules', 'icon' => 'calendar-check', 'url' => 'manufacturing/maintenance/schedules', 'permission' => 'manufacturing.view'],
    ['id' => 'downtime', 'label' => 'Downtime', 'icon' => 'exclamation-circle', 'url' => 'manufacturing/maintenance/downtime', 'permission' => 'manufacturing.view'],
];
```

### Manufacturing → MRP

```php
$mrpTabs = [
    ['id' => 'dashboard', 'label' => 'Dashboard', 'icon' => 'speedometer2', 'url' => 'manufacturing/mrp', 'permission' => 'manufacturing.view'],
    ['id' => 'requisitions', 'label' => 'Requisitions', 'icon' => 'cart-plus', 'url' => 'manufacturing/mrp/requisitions', 'permission' => 'manufacturing.view'],
    ['id' => 'safety_stock', 'label' => 'Safety Stock', 'icon' => 'shield-check', 'url' => 'manufacturing/mrp/safety_stock', 'permission' => 'manufacturing.view'],
];
```

### Manufacturing → Capacity

```php
$capacityTabs = [
    ['id' => 'dashboard', 'label' => 'Dashboard', 'icon' => 'speedometer2', 'url' => 'manufacturing/capacity', 'permission' => 'manufacturing.view'],
    ['id' => 'availability', 'label' => 'Availability', 'icon' => 'calendar-check', 'url' => 'manufacturing/capacity/availability', 'permission' => 'manufacturing.view'],
    ['id' => 'feasibility', 'label' => 'Feasibility', 'icon' => 'clipboard-data', 'url' => 'manufacturing/capacity/feasibility', 'permission' => 'manufacturing.view'],
    ['id' => 'machine_status', 'label' => 'Machine Status', 'icon' => 'gear', 'url' => 'manufacturing/capacity/machine_status', 'permission' => 'manufacturing.view'],
];
```

---

## Common Bootstrap Icons

| Purpose | Icon Class | Example |
|---------|-----------|---------|
| Dashboard | `speedometer2` | <i class="bi bi-speedometer2"></i> |
| List/All | `list-ul` | <i class="bi bi-list-ul"></i> |
| Tasks | `check2-square` | <i class="bi bi-check2-square"></i> |
| Calendar | `calendar-event` | <i class="bi bi-calendar-event"></i> |
| People | `people` | <i class="bi bi-people"></i> |
| Documents | `file-earmark-text` | <i class="bi bi-file-earmark-text"></i> |
| Settings | `gear` | <i class="bi bi-gear"></i> |
| Charts | `graph-up` | <i class="bi bi-graph-up"></i> |
| Quality | `clipboard-check` | <i class="bi bi-clipboard-check"></i> |
| Warning | `exclamation-triangle` | <i class="bi bi-exclamation-triangle"></i> |
| Tools | `wrench` | <i class="bi bi-wrench"></i> |
| Board | `kanban` | <i class="bi bi-kanban"></i> |

Full icon list: https://icons.getbootstrap.com/

---

## Testing Checklist

After implementing nav tabs on a module:

- [ ] All tabs link to correct pages
- [ ] Active tab is highlighted
- [ ] Icons display correctly
- [ ] Tabs are responsive on mobile
- [ ] Keyboard navigation works (Tab key)
- [ ] No console errors

---

## Troubleshooting

### Issue: Active tab not highlighting

**Problem:** `$currentPage` variable not set in controller

**Solution:** Add to controller:
```php
$this->layout('module/page', [
    'currentPage' => 'page_id',  // ← Make sure this matches tab['id']
    // ...
]);
```

### Issue: Icons not showing

**Problem:** Wrong icon class or Bootstrap Icons not loaded

**Solution:**
1. Check icon class: `bi bi-icon-name` (not `bi-icon-name`)
2. Verify Bootstrap Icons CSS is loaded in layout

### Issue: Tabs wrapping on mobile

**Problem:** Too many tabs or long labels

**Solution:**
1. Reduce number of tabs (max 6 recommended)
2. Shorten labels on mobile using CSS
3. Consider dropdown menu for overflow tabs

### Issue: Tab not showing for certain users

**Problem:** User doesn't have required permission

**Solution:**
1. Check the `permission` key in tab definition
2. Verify user has that permission: `SELECT * FROM user_permissions WHERE user_id = X`
3. Check user's role permissions: `SELECT * FROM role_permissions WHERE role_id = Y`
4. Test with admin user (should see all tabs)

**Debug helper:**
```php
<?php if (isset($_GET['debug'])): ?>
<div class="alert alert-info">
    <strong>Debug Info:</strong><br>
    User ID: <?= $_SESSION['user_id'] ?? 'Not set' ?><br>
    User Role: <?= $_SESSION['user_role'] ?? 'Not set' ?><br>
    Has hr.view: <?= hasPermission('hr.view') ? 'YES' : 'NO' ?><br>
    Has manufacturing.view: <?= hasPermission('manufacturing.view') ? 'YES' : 'NO' ?><br>
    All Permissions: <?= implode(', ', $_SESSION['user_permissions'] ?? []) ?>
</div>
<?php endif; ?>
```

Add `?debug=1` to URL to see permission info.

### Issue: All tabs disappeared

**Problem:** All tabs require permissions user doesn't have

**Solution:**
1. At least one tab should be visible to all users with module access
2. Consider making the "Dashboard" tab have no permission requirement
3. Or use the same base permission for all tabs (e.g., `hr.view`)

---

## Time Estimates

| Task | Time |
|------|------|
| Create reusable component (one time) | 15 min |
| Update 1 controller method | 1 min |
| Update 1 view file | 3-5 min |
| Test 1 module (6 pages) | 10 min |
| **Total per module (6 pages)** | **~45 min** |

---

## Next Module to Implement

**Recommended order:**
1. ✅ HR → Recruitment (highest user traffic)
2. ✅ Manufacturing → Quality (critical operations)
3. ✅ Projects (frequently used)
4. Manufacturing → Maintenance
5. Manufacturing → MRP
6. Manufacturing → Capacity

---

**Quick Reference:** See `docs/UI_UX_PHASE2_2_MODULE_NAVIGATION.md` for full details.