# Ref Module

## 1. Pengenalan

Module **Reference** — lookup table untuk menyimpan data master seperti categories, statuses, types yang digunakan oleh modul-modul lain. Guna pattern key-value (cat → code → descr).

## 2. Database

**Table:** `ref`

| Column | Type | Description |
|--------|------|-------------|
| id | bigint (PK) | Primary key |
| cat | string | Kumpulan (contoh: `ARTICLE_CAT`, `LANGUAGE`, `PORTAL`) |
| code | string | Value code (contoh: `ACTIVE`, `BM`, `EN`) |
| descr | string | Description Bahasa Malaysia |
| descr_en | string (nullable) | Description English |
| sort | integer (nullable) | Urutan display |
| parent | string (nullable) | Parent code (hierarki) |
| icon_name | string (nullable) | Nama icon |
| created_by | string (nullable) | Creator username/ID |
| updated_by | string (nullable) | Updater username/ID |
| deleted_at | integer (nullable) | Soft delete |
| timestamps | - | created_at, updated_at |

**Indexes:** cat, code, parent, sort, deleted_at, [cat,sort], [parent,sort]

## 3. Routes

| Method | URI | Permission | Name |
|--------|-----|------------|------|
| GET | `/admin/ref` | `ref.view` | `ref.index` |
| GET | `/admin/ref/create` | `ref.create` | `ref.create` |
| POST | `/admin/ref` | `ref.create` | `ref.store` |
| GET | `/admin/ref/{id}/edit` | `ref.update` | `ref.edit` |
| PUT | `/admin/ref/{id}` | `ref.update` | `ref.update` |
| DELETE | `/admin/ref/{id}` | `ref.delete` | `ref.destroy` |
| POST | `/admin/ref/reorder` | `ref.update` | `ref.reorder` |

## 4. Controller — `RefController`

**Functions:**
- `index()` — List refs, search by cat/code/descr, pagination.
- `create()` — Return create form.
- `store(RefRequest)` — Create ref record.
- `edit($id)` — Return edit form.
- `update(RefRequest, $id)` — Update ref record.
- `destroy($id)` — Delete ref record.

## 5. Model — `Ref`

- Table: `ref`
- Fillable: cat, code, descr, descr_en, sort, parent, icon_name, created_by, updated_by, deleted_at

## 6. Views

- `index.blade.php` — Table: No, Cat, Code, Description (BM), Description (EN), Sort, Actions (edit/delete)
- `create.blade.php` — Form: Cat*, Code*, Description (BM), Description (EN), Sort, Parent, Icon Name
- `edit.blade.php` — Same with pre-filled values
- `show.blade.php` — Detail view

## 7. Cara Guna dalam Module Lain

```php
// Dalam controller — dapatkan options untuk dropdown
$cats = Ref::where('cat', 'ARTICLE_CAT')->orderBy('sort')->pluck('descr', 'code');

// Dalam view
<select name="article_category">
    @foreach ($cats as $code => $descr)
        <option value="{{ $code }}">{{ $descr }}</option>
    @endforeach
</select>
```

Ada `HOW_TO_USE_REF.md` dalam folder view untuk 5 pendekatan berbeza.

## 7.1 Category Email Template

Module Email Template menggunakan ref untuk category:

```text
cat      = EMAIL_TEMPLATE_CATEGORY
code     = disimpan dalam email_templates.category
descr    = label BM
descr_en = label English (dipaparkan dalam UI Email Template)
```

Tambah row baru di `/admin/ref` untuk tambah category tanpa ubah kod. Jangan
rename `code` yang sudah digunakan oleh template sedia ada; tukar `descr` atau
`descr_en` sahaja untuk ubah label.


## 8. Seeder — `RefDataSeeder`

Seed data reference untuk semua categories, termasuk:
- LANGUAGE, PORTAL
- ARTICLE_CAT, ARTICLE_SUBCAT, ARTICLE_STATUS
- APPLICATION_CAT, APPLICATION_STATUS
- DOWNLOAD_CAT, DOWNLOAD_STATUS
- IMAGE_CAT, IMAGE_STATUS
- VIDEO_CAT, VIDEO_STATUS
- SLIDER_STATUS, SLIDER_TYPE, SLIDER_DIMENSION, SLIDER_URL_TYPE
- PHOTO_STATUS, GALLERY_CAT, GALLERY_STATUS
- FEEDBACK_TYPE, FEEDBACK_CATEGORY
- `EMAIL_TEMPLATE_CATEGORY`: `General` (Umum), `Authentication` (Pengesahan),
  `Account` (Akaun), `Feedback` (Maklum Balas), `Announcement` (Pengumuman)
- HOLIDAY_STATUS, CALENDAR_STATUS, CALENDAR_CATEGORY, CALENDAR_DISPLAY,
  CALENDAR_TYPE, DIRECTORY_STAFF_STATUS

Seeder menggunakan `updateOrCreate` berdasarkan `cat` + `code`, jadi selamat
dijalankan berulang. Perubahan pada `descr`/`descr_en` akan dikemas kini.

## 9. Permissions

| Permission | Description |
|------------|-------------|
| `ref.view` | View ref list & detail |
| `ref.create` | Create ref |
| `ref.update` | Edit ref |
| `ref.delete` | Delete ref |