Your IP : 216.73.216.79
# CMS Builder — Panduan Lengkap untuk Developer
> Dokumentasi teknikal untuk sistem FrontendSite CMS Builder.
> Rujukan cepat faham arsitektur, component rendering, content modules, menu, routing, dan seeding.
>
> **Auth Pages:** Sistem autentikasi frontend user (login, register, forgot/reset password, email verification) dibina sebagai CMS Pages. Rujuk [CMS-AUTH-SYSTEM.md](./CMS-AUTH-SYSTEM.md).
---
## 1. Konsep Asas
CMS Builder membolehkan pembinaan website **dynamic tanpa coding** melalui 3 entiti utama:
| Entiti | Table | Fungsi |
|--------|-------|--------|
| **Component** | `frontend_components` | Blok content boleh guna semula (Blade template) |
| **Site** | `frontend_sites` | Website dengan header, footer, layout tersendiri |
| **Page** | `frontend_pages` | Halaman dalam site, mengandungi komponen |
### 3 Langkah Setup
```
Step 1: Buat Component → Step 2: Buat Site → Step 3: Buat Page
↓
Attach component ke page
```
#### Step 1: Buat Component
Admin panel: `/admin/frontend-site/components/create`
| Field | Contoh | Penerangan |
|-------|--------|------------|
| `code` | `hero_banner` | Unik, jadi variable `$hero_banner` dalam Blade |
| `name` | Hero Banner | Nama paparan |
| `type` | `PHP` / `HTML` / `JS` / `CSS` | `PHP` jika guna query DB |
| `category` | `Header` / `Section` / `Content` / `Footer` / `Panel` / `Modal` | Kumpulan komponen |
| `content` | Blade template | Content sebenar komponen |
#### Step 2: Buat Site
Admin panel: `/admin/frontend-site/sites/create`
| Field | Penerangan |
|-------|------------|
| `name` | Nama website |
| `slug` | URL segment (unique) |
| `header_fk` | Pilih component untuk header (contoh: `navbar`) |
| `footer_fk` | Pilih component untuk footer (contoh: `footer`) |
| `layout` | Blade layout yang wrap header + page + footer |
| `is_default` | Site utama bila access `/` |
#### Step 3: Buat Page & Attach Component
Admin panel: `/admin/frontend-site/pages/create`
1. Pilih `site`
2. Isi `name`, `slug`
3. Attach component — tick component dalam list, set `sort_order`
4. Isi `page_content` (optional) — content utama page, guna `$hero_banner`, `$features` dll
5. Save → `BladeSyncService::syncAll()` akan sync ke storage
---
## 2. Styling — CSS
Ada 3 tempat boleh letak CSS:
### 2.1 Dalam Component (Inline)
Letak `<style>` terus dalam `content` component:
```blade
<style>
.cms-hero { background: linear-gradient(135deg, #0f172a, #1e293b); padding: 6rem 2rem; text-align: center; color: white; }
.cms-hero h1 { font-size: 3rem; margin: 0; }
</style>
<section class="cms-hero">
<h1>Welcome to {{ $siteName }}</h1>
</section>
```
### 2.2 Dalam Site Layout
Letak `<style>` dalam field `layout` site, CSS dikongsi semua page:
```blade
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: system-ui, sans-serif; color: #1e293b; }
</style>
{!! $__header__ !!}
<main>{!! $__page__ !!}</main>
{!! $__footer__ !!}
```
### 2.3 Dalam Page Layout (Custom)
Tandakan `use_custom_layout = true` pada page, layout guna `LAYOUTS/PAGE/{siteSlug}/{slug}.blade.php`:
```
STORAGE PATH:
LAYOUTS/SITE/{site-slug}.blade.php ← Site layout (default)
LAYOUTS/PAGE/{site-slug}/{slug}.blade.php ← Page layout (custom)
```
### CSS Classes Standard (Guna dalam Component)
```css
.cms-section { padding: 4rem 2rem; font-family: sans-serif; }
.cms-section--alt { background: #f8fafc; }
.cms-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1.5rem; max-width: 1200px; margin: 0 auto; }
.cms-grid--sm { grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 1rem; }
.cms-card { background: white; border-radius: 1rem; overflow: hidden; border: 1px solid #e2e8f0; transition: 0.3s; text-decoration: none; color: inherit; display: block; }
.cms-card:hover { box-shadow: 0 10px 40px rgba(0,0,0,0.08); transform: translateY(-2px); }
.cms-card-img { width: 100%; height: 200px; object-fit: cover; display: block; }
.cms-thumb { width: 100%; height: 120px; object-fit: cover; border-radius: 0.75rem; border: 1px solid #e2e8f0; cursor: pointer; transition: 0.3s; }
.cms-thumb:hover { transform: scale(1.05); }
.cms-download-item { display: flex; align-items: center; justify-content: space-between; padding: 1rem 1.5rem; background: white; border-radius: 0.75rem; border: 1px solid #e2e8f0; text-decoration: none; color: inherit; transition: 0.2s; }
.cms-download-item:hover { border-color: #3b82f6; }
.cms-slide { border-radius: 1rem; overflow: hidden; position: relative; height: 250px; background-size: cover; background-position: center; display: flex; align-items: flex-end; padding: 2rem; color: white; }
```
---
## 3. Navbar & Menu — $menuTree
### 3.1 $menuTree — Bagaimana Ia Dihasilkan
`PortalHandler::handle()` akan:
```
1. Query RoleMapping:
→ role_code = 'public'
→ category = 'navbar'
→ site_id = current site
2. Bina recursive tree berdasarkan parent_id → menu_id:
$buildTree = function($parentId) use (&$buildTree, $mappings) {
$branch = [];
foreach ($mappings as $mapping) {
if ($mapping->parent_id == $parentId) {
$item = $mapping->menu->toArray();
$children = $buildTree($mapping->menu_id);
if ($children) $item['children'] = $children;
$branch[] = $item;
}
}
return $branch;
};
$menuTree = $buildTree(0);
3. Pass ke semua component/page/layout sebagai:
$vars['menuTree'] = $menuTree
```
Struktur `$menuTree`:
```php
[
[
'menu_name' => 'About',
'menu_link' => '/about',
'menu_icon' => null,
'menu_id' => 1,
'children' => [
[
'menu_name' => 'Team',
'menu_link' => '/team',
'children' => [],
],
],
],
[
'menu_name' => 'Contact',
'menu_link' => '/contact',
'children' => [],
],
]
```
### 3.2 Manual Menu vs Auto Fallback
```
ADA role_mapping untuk public/navbar?
├── YA → $menuTree = nested tree dari frontend_menu + frontend_role_mapping
└── TIDAK → $menuTree = flat list semua pages dalam site (auto fallback)
```
**Manual Menu:** Admin create di `Frontend Menu` → `Assign Menu` → pilih role `public`, category `main-navbar`.
**Auto Fallback:** Jika tiada langsung `RoleMapping` untuk `public`/`navbar`, system auto guna semua `FrontendPage` dalam site sebagai flat menu.
### 3.3 Link Auto-Prefix
Link `/about` auto jadi `/{siteSlug}/about` dalam component:
```blade
@php
$link = $item['menu_link'] ?? '#';
if (str_starts_with($link, '/') && !str_starts_with($link, '//') && !filter_var($link, FILTER_VALIDATE_URL)) {
$link = '/' . $siteSlug . $link;
}
@endphp
<a href="{{ $link }}">{{ $item['menu_name'] }}</a>
```
### 3.4 Component Navbar — Contoh Lengkap
```blade
@php
$buildLink = function($link) use ($siteSlug) {
if (str_starts_with($link, '/') && !str_starts_with($link, '//') && !filter_var($link, FILTER_VALIDATE_URL))
return '/' . $siteSlug . $link;
return $link;
};
@endphp
<nav style="background:#0f172a;padding:0 2rem;display:flex;align-items:center;justify-content:space-between;height:70px;">
<a href="/{{ $siteSlug }}" style="color:white;font-size:1.25rem;font-weight:700;text-decoration:none;">{{ $siteName }}</a>
<div style="display:flex;gap:0.5rem;">
@foreach($menuTree as $item)
<div style="position:relative;"
onmouseover="var d=this.querySelector('.dropdown');if(d)d.style.display='block';"
onmouseout="var d=this.querySelector('.dropdown');if(d)d.style.display='none';">
<a href="{{ $buildLink($item['menu_link']) }}" style="color:#cbd5e1;text-decoration:none;padding:0.5rem 1rem;">
{{ $item['menu_name'] }}
</a>
@if(!empty($item['children']))
<div class="dropdown" style="display:none;position:absolute;top:100%;left:0;background:#1e293b;min-width:180px;">
@foreach($item['children'] as $child)
<a href="{{ $buildLink($child['menu_link']) }}" style="display:block;color:#94a3b8;padding:0.4rem 0.75rem;">
{{ $child['menu_name'] }}
</a>
@endforeach
</div>
@endif
</div>
@endforeach
</div>
</nav>
```
### 3.5 Variable Tersedia dalam Komponen
| Variable | Type | Sumber |
|----------|------|--------|
| `$siteSlug` | string | `$site->slug` |
| `$siteName` | string | `$site->name` |
| `$sitePages` | collection | Semua page dalam site |
| `$menus` | collection | Flat list `Menu` models |
| `$menuTree` | array | Nested menu (parent-child) |
| `$__entry__` | string | Output entry script (rendered) |
| `$__header__` | string | Rendered header HTML |
| `$__page__` | string | Rendered page content HTML |
| `$__footer__` | string | Rendered footer HTML |
| `$_shared` | stdClass | Object untuk sharing data antara komponen |
---
## 4. Content Modules — Cara Query 7 Jenis Content
Untuk papar data content dalam component, guna `@php` dalam component content (type: PHP).
### Pattern Asas
```blade
@php
$items = \App\Models\Backend\ContentArticle::with('translations')
->where('article_status', 'ACTIVE')
->latest()
->take(3)
->get();
@endphp
@if($items->count())
<section class="cms-section">
<h2>Latest News</h2>
@foreach($items as $item)
@php
$t = $item->translations->firstWhere('article_translation_main', 1)
?? $item->translations->first();
@endphp
<div class="cms-card">
<h3>{{ $t?->article_translation_title ?? 'Untitled' }}</h3>
</div>
@endforeach
</section>
@endif
```
### 4.1 ContentArticle
**Table:** `content_article`, PK: `article_id`
**Translation:** `content_article_translation`
```blade
@php
$items = \App\Models\Backend\ContentArticle::with('translations')
->where('article_status', 'ACTIVE')
->latest()
->take(3)
->get();
@endphp
@if($items->count())
<section class="cms-section">
<h2>Articles</h2>
<div class="cms-grid">
@foreach($items as $item)
@php
$t = $item->translations->firstWhere('article_translation_main',1) ?? $item->translations->first();
$img = $item->article_image ? (str_starts_with($item->article_image, 'http') ? $item->article_image : Storage::url($item->article_image)) : null;
@endphp
<div class="cms-card">
@if($img)<img src="{{ $img }}" class="cms-card-img">@endif
<div style="padding:1.25rem;">
<small>{{ $item->article_category }}</small>
<h3>{{ $t?->article_translation_title ?? 'Untitled' }}</h3>
<p>{{ Str::limit(strip_tags($t?->article_translation_content ?? ''), 120) }}</p>
</div>
</div>
@endforeach
</div>
</section>
@endif
```
### 4.2 ContentSlider
**Table:** `content_slider`, PK: `slider_id`
**Translation:** `content_slider_translation` (gambar dalam translation)
```blade
@php
$items = \App\Models\Backend\ContentSlider::with('translations')
->where('slider_status', 'ACTIVE')
->latest()
->take(3)
->get();
@endphp
@if($items->count())
<section class="cms-section">
<h2>Sliders</h2>
@foreach($items as $item)
@php
$t = $item->translations->firstWhere('slider_translation_main',1) ?? $item->translations->first();
$img = $t?->slider_translation_img ? (str_starts_with($t->slider_translation_img, 'http') ? $t->slider_translation_img : Storage::url($t->slider_translation_img)) : null;
@endphp
<div class="cms-slide" @if($img) style="background-image:url('{{ $img }}')" @endif>
<h3>{{ $t?->slider_translation_title ?? 'Banner' }}</h3>
</div>
@endforeach
</section>
@endif
```
### 4.3 ContentApplication
**Table:** `content_applications`, PK: `application_id`
**Translation:** `content_application_translations`
```blade
@php
$items = \App\Models\Backend\ContentApplication::with('translations')
->where('application_status', 'ACTIVE')
->latest()
->take(3)
->get();
@endphp
@if($items->count())
<section class="cms-section cms-section--alt">
<h2>Applications</h2>
<div class="cms-grid">
@foreach($items as $item)
@php
$t = $item->translations->firstWhere('application_translation_main',1) ?? $item->translations->first();
@endphp
<div class="cms-card" style="padding:1.5rem;">
<h3>{{ $t?->application_translation_title ?? 'Service' }}</h3>
<small>{{ $item->application_cat }}</small>
@if($item->application_url)
<br><a href="{{ $item->application_url }}" target="_blank">Apply Now</a>
@endif
</div>
@endforeach
</div>
</section>
@endif
```
### 4.4 ContentDownload
**Table:** `content_downloads`, PK: `download_id`
**Note:** Translation guna self-referencing `download_parent_id` (bukan table berasingan)
```blade
@php
$items = \App\Models\Backend\ContentDownload::where('download_status', 'ACTIVE')
->latest()
->take(4)
->get();
@endphp
@if($items->count())
<section class="cms-section cms-section--alt">
<h2>Downloads</h2>
@foreach($items as $item)
<a href="{{ $item->download_file ? Storage::url($item->download_file) : '#' }}" class="cms-download-item" style="display:block;margin-bottom:0.5rem;">
<span>{{ $item->download_title ?? 'Document' }}</span>
<small>{{ $item->download_category ?? '' }}</small>
</a>
@endforeach
</section>
@endif
```
### 4.5 ContentImage
**Table:** `content_images`, PK: `image_id`
**Note:** Translation guna self-referencing `image_parent_id`
```blade
@php
$items = \App\Models\Backend\ContentImage::where('image_status', 'ACTIVE')
->latest()
->take(6)
->get();
@endphp
@if($items->count())
<section class="cms-section">
<h2>Images</h2>
<div class="cms-grid cms-grid--sm">
@foreach($items as $item)
@php
$url = $item->image_file ? (str_starts_with($item->image_file, 'http') ? $item->image_file : Storage::url($item->image_file)) : null;
@endphp
@if($url)
<img src="{{ $url }}" class="cms-thumb" alt="{{ $item->image_title ?? '' }}">
@endif
@endforeach
</div>
</section>
@endif
```
### 4.6 ContentPhotoGallery
**Table:** `content_photo_gallery`, PK: `gallery_id`
**Translation:** `content_photo_gallery_translations`
**Child Photos:** `content_photo_list` (FK: `photo_gallery_id`)
```blade
@php
$items = \App\Models\Backend\ContentPhotoGallery::with('translations', 'photoLists')
->where('gallery_status', 'ACTIVE')
->latest()
->take(4)
->get();
@endphp
@if($items->count())
<section class="cms-section cms-section--alt">
<h2>Photo Galleries</h2>
<div class="cms-grid">
@foreach($items as $item)
@php
$t = $item->translations->firstWhere('gallery_translation_main',1) ?? $item->translations->first();
$thumb = $item->gallery_thumbnail
? (str_starts_with($item->gallery_thumbnail, 'http') ? $item->gallery_thumbnail : Storage::url($item->gallery_thumbnail))
: null;
@endphp
<a href="/{{ $siteSlug }}/{{ $item->gallery_code }}" class="cms-card">
@if($thumb)<img src="{{ $thumb }}" class="cms-card-img">@endif
<div style="padding:1.25rem;">
<h3>{{ $t?->gallery_translation_title ?? 'Gallery' }}</h3>
<span>{{ $item->photoLists->count() }} photos</span>
</div>
</a>
@endforeach
</div>
</section>
@endif
```
### 4.7 ContentVideo
**Table:** `content_video`, PK: `video_id`
**Translation:** `content_video_translation`
```blade
@php
$items = \App\Models\Backend\ContentVideo::with('translations')
->where('video_status', 'ACTIVE')
->latest()
->take(3)
->get();
@endphp
@if($items->count())
<section class="cms-section">
<h2>Videos</h2>
<div class="cms-grid">
@foreach($items as $item)
@php
$t = $item->translations->firstWhere('video_translation_main',1) ?? $item->translations->first();
$img = $item->video_img ? (str_starts_with($item->video_img, 'http') ? $item->video_img : Storage::url($item->video_img)) : null;
@endphp
<div class="cms-card">
@if($img)<img src="{{ $img }}" class="cms-card-img">@endif
<div style="padding:1.25rem;">
<h3>{{ $t?->video_translation_title ?? 'Untitled' }}</h3>
@if($item->video_source == 'YOUTUBE' && $item->video_url)
<a href="{{ $item->video_url }}" target="_blank">Watch on YouTube</a>
@endif
</div>
</div>
@endforeach
</div>
</section>
@endif
```
### Image URL Pattern (WAJIB Guna)
Semua field gambar guna pattern ini:
```blade
@php
$img = $item->article_image
? (str_starts_with($item->article_image, 'http')
? $item->article_image
: Storage::url($item->article_image))
: null;
@endphp
```
Sebab: gambar boleh dari **external URL** (picsum.photos) atau **local storage** (upload admin).
---
## 5. Flow Component Render — DB → HTML
```
DATABASE
┌──────────────────────────────┐
│ frontend_components.content │
│ frontend_sites.layout │
│ frontend_pages.layout │
│ frontend_pages.entry_script │
│ frontend_pages.page_content │
└──────────┬───────────────────┘
│ BladeSyncService::syncAll()
▼
STORAGE (storage/app/)
┌──────────────────────────────────────────────────┐
│ PHP/{code}.blade.php ← components │
│ LAYOUTS/SITE/{slug}.blade.php ← site layout │
│ LAYOUTS/PAGE/{site}/{page}.blade.php ← page lay │
│ ENTRY/PAGE/{site}/{page}.blade.php ← entry scr │
│ PAGE_CONTENT/{site}/{page}.blade.php ← page cont │
└──────────────────────────────────────────────────┘
│ PortalHandler::handle()
▼
RENDER PIPELINE (PortalHandler)
┌──────────────────────────────────────────────────┐
│ 1. Load site meta (cache → DB) │
│ 2. Load page (default atau by slug) │
│ 3. Query RoleMapping → build $menuTree │
│ 4. Fallback: pages as flat menu │
│ 5. Render ENTRY script → $__entry__ │
│ 6. Loop components: │
│ Storage::get("PHP/{code}.blade.php") │
│ Blade::render() → ${$comp->code} │
│ 7. Render PAGE_CONTENT → $pageHtml │
│ (guna ${code} variables dalam Blade) │
│ 8. Render HEADER component → $__header__ │
│ 9. Render FOOTER component → $__footer__ │
│ 10. Render LAYOUT (site/page): │
│ Blade::render($layout, [ │
│ '__header__', '__page__', '__footer__' │
│ ]) │
└──────────────────────────────────────────────────┘
│
▼
view('frontend.cms', compact('html'))
│
▼
{!! $html !!}
```
### 5.1 BladeSyncService — DB ke Storage
Dipanggil setiap kali CRUD komponen/site/page:
```php
// Sync semua component content ke storage/app/PHP/{code}.blade.php
BladeSyncService::syncComponents();
// Sync site layout ke storage/app/LAYOUTS/SITE/{slug}.blade.php
BladeSyncService::syncSiteLayouts();
// Sync page custom layout ke storage/app/LAYOUTS/PAGE/{site}/{slug}.blade.php
BladeSyncService::syncPageLayouts();
// Sync entry script ke storage/app/ENTRY/PAGE/{site}/{slug}.blade.php
BladeSyncService::syncEntries();
// Sync page content ke storage/app/PAGE_CONTENT/{site}/{slug}.blade.php
BladeSyncService::syncPageContent();
```
### 5.2 PortalHandler — Render Engine
```php
// Satu-satunya method — render page dalam site
PortalHandler::handle($siteSlug, $pageSlug = null);
// ContentArticle / Gallery / Video detail guna query param dalam component page
// portalHandler->handle($siteSlug, 'articles') dengan ?id={code} dalam component
```
### 5.3 Component Code Jadi Variable
Component dengan `code = hero_banner` akan render dan tersedia sebagai `$hero_banner` dalam page content:
```blade
{{-- Page Content --}}
{!! $hero_banner !!}
{!! $features !!}
```
### 5.4 Entry Script Pattern
Guna entry script untuk preprocessing atau set shared data.
**Cara 1 — Auto-capture (v2):** `@php $var = value` terus auto-carried forward ke component/page content/layout. Tak perlu guna `$_shared` untuk variable ringkas:
```blade
{{-- Entry Script — jalan SEBELUM components di-render --}}
@php
$pageTitle = 'Welcome to Our Site';
$showBanner = true;
$items = App\Models\Backend\ContentArticle::take(3)->get();
@endphp
{{-- Page Content: variables auto-available --}}
<h1>{{ $pageTitle }}</h1>
@if($showBanner) <div class="banner">...</div> @endif
```
**Cara 2 — `$_shared` (pass-by-reference):** Disarankan untuk data yang perlu diubah suai oleh pelbagai komponen:
```blade
@php
$_shared->pageTitle = 'Welcome to Our Site';
$_shared->showBanner = true;
@endphp
{{-- Guna dalam mana-mana component --}}
@if($_shared->showBanner ?? false)
<div class="banner">{{ $_shared->pageTitle }}</div>
@endif
```
### 5.5 Layout Pattern
**Site Layout** (default untuk semua page dalam site):
```blade
<!DOCTYPE html>
<html>
<head><title>{{ $siteName }}</title></head>
<body>
{!! $__header__ !!}
<main class="container">{!! $__page__ !!}</main>
{!! $__footer__ !!}
</body>
</html>
```
**Page Custom Layout** (override site layout bila `use_custom_layout = true`):
```blade
<!DOCTYPE html>
<html>
<head><title>Custom Page</title></head>
<body>
{!! $__header__ !!}
<div class="full-width">{!! $__page__ !!}</div>
{!! $__footer__ !!}
</body>
</html>
```
---
## 6. Auto-Render vs Manual Render
### 6.1 Auto-Render (Tanpa Page/Component)
Tiada modul yang auto-render sebagai dedicated detail page melalui URL path. Semua module content dipapar sebagai **component list** dalam page biasa.
**ContentArticle / Gallery detail** dimuat melalui page component guna query param `?id=`:
| Module | URL Pattern | Kaedah |
|--------|-------------|--------|
| **ContentArticle** | `/{siteSlug}/{pageSlug}?id={article_code}` | Page component query `request()->query('id')` |
| **ContentPhotoGallery** | `/{siteSlug}/{pageSlug}?id={gallery_code}` | Page component query `request()->query('id')` |
| Module lain (Slider, Video, etc.) | — | Component list sahaja |
**Contoh URL:**
```
http://127.0.0.1:8000/new-site/article?id=pelancaran-2026
```
- `article` = page slug
- `?id=pelancaran-2026` = filter ContentArticle by `article_code`
### 6.2 Manual Render (Guna Component)
Semua modul lain **hanya display sebagai component list** dalam page:
| Module | Component | Kaedah |
|--------|-----------|--------|
| ContentSlider | `mod_sliders` | Component type PHP query terus |
| ContentVideo | `mod_videos` | Component type PHP query terus |
| ContentDownload | `mod_downloads` | Component type PHP query terus |
| ContentApplication | `mod_applications` | Component type PHP query terus |
| ContentImage | `mod_images` | Component type PHP query terus |
| ContentPhotoList | `mod_photolist` | Component type PHP query terus |
> Tiada dedicated page/URL untuk slider, video, download, application, image, photo list.
> Ia hanya dipapar dalam page melalui component `mod_*`.
---
## 7. Routing — Macam Mana URL Di-resolve
### 7.1 Route Definitions (routes/web.php:610-618)
```php
Route::prefix('/')->middleware('visitor.log')->group(function () {
Route::get('/', [FrontendSiteRenderController::class, 'default'])->name('home');
Route::get('{site}/{slug}', [FrontendSiteRenderController::class, 'resolve'])
->where('slug', '.*') // slug boleh guna slash
->name('frontend-site.page');
Route::get('{slug}', [FrontendSiteRenderController::class, 'resolve'])
->name('frontend-site.home');
});
```
### 7.2 Resolution Pipeline
**Default site pages (single slug — no site prefix):**
```
URL: /about (default site page — tanpa site slug)
↓
FrontendSiteRenderController::resolve('about')
↓
1. Default site check: FrontendSiteCacheService::getDefaultSite()
→ Cari site dengan is_default = true
↓
2. Adakah 'about' dalam pages default site?
├── YA → PortalHandler::handle('default-site', 'about')
└── TIDAK → proceed ke step 3 (site check)
```
**Non-default site / multi-segment URL:**
```
URL: /module-site/video-tutorial
↓
FrontendSiteRenderController::resolve('module-site', 'video-tutorial')
↓
3. Cache check: FrontendSiteCacheService::get('module-site')
→ Baca storage/app/site-meta.json
→ Cari site dengan slug 'module-site'
↓
4. Site ditemui dalam cache?
├── YA → proceed ke step 5
└── TIDAK → fallback ke HomeController::contentArticle($slug)
↓
5. Page check: Adakah 'video-tutorial' dalam site pages?
├── YA → PortalHandler::handle('module-site', 'video-tutorial')
└── TIDAK → abort(404) (tiada auto-render untuk article/gallery)
```
> **Detail ContentArticle/Gallery** tidak di-render melalui URL path. Guna query param dalam page component: `/{siteSlug}/{pageSlug}?id={code}`
> **Ringkasan URL Pattern:**
> - Default site: `base-url/page-slug` (no site slug needed)
> - Other sites: `base-url/site-slug/page-slug`
> - Backward compatible: `base-url/default-site-slug/page-slug` still works
### 7.3 Cache Layer (FrontendSiteCacheService)
Cache disimpan sebagai JSON di `storage/app/site-meta.json`:
```json
{
"my-site": {
"id": 1,
"name": "My Modern Site",
"slug": "my-site",
"is_default": true,
"header_code": "navbar",
"footer_code": "footer",
"pages": {
"home": { "id": 1, "name": "Home", "is_default": true, "components": ["hero","features"] },
"about": { "id": 2, "name": "About", "is_default": false, "components": ["about_content"] }
}
}
}
```
Cache di-rebuild setiap kali `BladeSyncService::syncAll()` dipanggil (iaitu setiap kali CRUD site/page/component).
---
## 8. Seeder Pattern — Order yang Betul
### 8.1 Order dalam DatabaseSeeder
```php
$this->call([
BackendUserSeeder::class, // 1. Admin user
FrontendUserSeeder::class, // 2. Frontend user
AdminRolePermissionSeeder::class, // 3. Roles & permissions
BackendMenuSeeder::class, // 4. Backend menu
ThemeRuleSeeder::class, // 5. Theme rules
RefDataSeeder::class, // 6. Reference data (categories, statuses)
SettingSeeder::class, // 7. System settings
DataDashboardSeeder::class, // 8. Dashboard widgets
WebSiteBackupSeeder::class, // 9. Components + Sites + Pages + Menus
FrontendAuthPagesSeeder::class, // 10. Auth pages
ContentApplicationSeeder::class, // 11-23. Content data seeders
ContentArticleAboutUsSeeder::class,
ContentArticleFaqSeeder::class,
ContentCalendarSeeder::class,
ContentDirectorySeeder::class,
ContentDownloadSeeder::class,
ContentGallerySeeder::class,
ContentImageSeeder::class,
ContentNewsSeeder::class,
ContentPublicHolidaySeeder::class,
ContentSliderSeeder::class,
ContentTranslationSeeder::class,
ContentVideoSeeder::class,
]);
app(BladeSyncService::class)->syncAll();
```
### 8.2 Dependency Graph
```
BackendUserSeeder (1)
└── independent
FrontendUserSeeder (2)
└── independent
AdminRolePermissionSeeder (3)
└── perlu BackendUserSeeder — assign role super-admin ke user
BackendMenuSeeder (4)
└── perlu AdminRolePermissionSeeder — guna Role model
ThemeRuleSeeder (5)
└── independent
RefDataSeeder (6)
└── independent — create reference codes
SettingSeeder (7)
└── independent
DataDashboardSeeder (8)
└── independent
WebSiteBackupSeeder (9)
└── perlu RefDataSeeder — guna status 'ACTIVE'
└── create: components + sites + pages + menu items + downloads
FrontendAuthPagesSeeder (10)
└── perlu WebSiteBackupSeeder — lookup site
Content*Seeder (11-23)
└── perlu WebSiteBackupSeeder — lookup site/page
└── perlu RefDataSeeder — guna status/category codes
```
### 8.3 Important Notes
1. **WebSiteBackupSeeder** guna `create()` (bukan `updateOrCreate`). Jika run 2 kali tanpa truncate → duplicate entry error.
2. **BladeSyncService::syncAll()** dipanggil di akhir `DatabaseSeeder` — penting untuk ensure component content di-sync ke storage.
3. **Portal Display** column untuk ContentArticle dan ContentPhotoGallery sekarang guna `frontend_sites` (bukan `Ref(PORTAL)`).
4. **Component Categories** dalam `WebSiteBackupSeeder`:
- `navbar_web` → category `Header` (bukan `Navbar`)
- `footer_web` → category `Footer` (bukan `Footer Web`)
- **Sebab:** Category mesti match dengan pilihan dalam form: Header, Footer, Section, Content, Panel, Modal
### 8.4 Seed Command
```bash
# Seed semua
php artisan db:seed
# Refresh total
php artisan migrate:fresh --seed
```
---
## 9. Common Issues & Troubleshooting
### 9.1 Component Tak Muncul di Page
```
Sebab 1: Component belum di-attach ke page
Fix: Edit page → tick component dalam list → Save
Sebab 2: BladeSync belum jalan
Fix: Save semula mana-mana site/component/page → trigger syncAll()
Sebab 3: Component code takde dalam page_content
Fix: Pastikan page_content ada {!! $component_code !!}
```
### 9.2 "Undefined variable $xxx" Error
```
Sebab: Component code tak wujud atau belum di-render
Fix: Pastikan component dengan code 'xxx' telah di-attach ke page
dan component status = active
Variable available:
$siteSlug, $siteName, $sitePages
$menus, $menuTree
$_shared, $__entry__, $__header__, $__page__, $__footer__
${component_code} — untuk setiap component yang di-attach
```
### 9.3 Blank Page / Layout Tak Muncul
```
Sebab: Site layout kosong atau tiada
Fix: 1. Edit site → pastikan field layout tidak kosong
2. Layout mesti ada {!! $__header__ !!}, {!! $__page__ !!}, {!! $__footer__ !!}
```
### 9.4 Menu Tak Muncul di Navbar
```
Sebab 1: Tiada RoleMapping untuk public/navbar
Fix: Admin → Frontend Menu → Assign Menu
→ Role: public → Category: navbar → Add menu items
Sebab 2: Fallback ke pages (jika langsung tiada RoleMapping)
Check: Ada tak frontend_pages untuk site ni?
PortalHandler akan auto fallback ke flat page list
Sebab 3: Site ID tak matching
Fix: Pastikan site_id dalam RoleMapping = site_id semasa
```
### 9.5 Article / Gallery 404 (Auto-Render)
```
Sebab 1: article_portal_category / gallery_portal tak sama dengan site slug
Fix: Edit ContentArticle → Portal Display pilih site yang betul
Sebab 2: Status bukan ACTIVE
Fix: Pastikan article_status / gallery_status = 'ACTIVE'
Sebab 3: Site slug tiada dalam cache
Fix: Save mana-mana site → trigger BladeSyncService → rebuild cache
```
### 9.6 Vite / Asset Tak Loading
```
Sebab: npm run build belum jalan
Fix: npm run build (root) + cd public/tailadmin && npm run build
Check: public/build/manifest.json wujud?
public/tailadmin/dist/ ada?
```
### 9.7 Component Content Tak Update
```
Sebab: BladeSync tak trigger lepas edit component content
Fix: BladeSyncService::syncAll() dipanggil dalam controller setiap CRUD.
Jika manual edit DB, kena trigger sync manual:
php artisan tinker
app(BladeSyncService::class)->syncAll();
```
### 9.8 Duplicate Slug / Code
```
Sebab: frontend_pages slug unique per site
frontend_components code unique global
frontend_sites slug unique global
Fix: Guna validation dalam controller:
'slug' => 'required|unique:frontend_pages,slug,NULL,id,site_fk,'.$site_fk
```
### 9.9 Seeder Error — Duplicate Entry
```
Sebab: ContentModuleSeeder guna create()
Jika run 2 kali → duplicate key error
Fix: php artisan migrate:fresh --seed (reset total)
atau truncate manual table content dulu
```
### 9.10 Cache Site Tak Update
```
Sebab: FrontendSiteCacheService cache (site-meta.json) outdated
Fix: Save mana-mana site → trigger syncAll() → rebuild cache
Atau delete storage/app/site-meta.json (auto-rebuild on next request)
```
---
## 10. Monaco Editor — Popup Modal & Component Integration
Semua editor (Component, Site, Page) guna **popup modal pattern** — bukan inline editor.
### 10.1 Editor Modal Flow
```
Click editor trigger box → Modal opens → Edit code → Save/Close
↓
Editor trigger shows preview (first 800 chars)
```
**Features:**
- **Ctrl+S** — AJAX save (tiada page reload)
- **Escape** — close modal, sync ke textarea
- **Click outside modal** — close modal
- **Format button** — auto-format code (Shift+Alt+F)
- **Language selector** — PHP/HTML/CSS/JavaScript
### 10.2 AJAX Save Pattern (SEBiji macam Component)
**Controller pattern** — ajax() check LEPAS update (bukan sebelum validation):
```php
public function update(Request $request, $id)
{
$page = FrontendPage::findOrFail($id);
$data = $request->validate([...]);
// AJAX modal save hanya update kod, tak sentuh name/slug
$page->update($request->ajax() ? Arr::except($data, ['name', 'slug']) : $data);
app(BladeSyncService::class)->syncAll();
// AJAX check LEPAS update — bukan sebelum validation
if ($request->ajax()) {
return response()->json(['message' => 'Code updated successfully!']);
}
flash()->success('Page updated successfully!');
return redirect()->route('frontend-site.pages.index', [...]);
}
```
**JavaScript pattern** — FormData + `X-Requested-With` header:
```javascript
var form = document.getElementById('page-form');
var formData = new FormData(form);
// Hanya hantar field yang sedang diedit
formData.delete('layout');
formData.delete('entry_script');
formData.delete('page_content');
if (currentEditorType === 'entry') {
formData.set('entry_script', entryInput.value);
} else if (currentEditorType === 'pageContent') {
formData.set('page_content', pageContentInput.value);
} else if (currentEditorType === 'layout') {
formData.set('layout', layoutInput.value);
}
formData.set('_method', 'PUT'); // untuk update
fetch(form.action, {
method: 'POST',
body: formData,
headers: {
'X-Requested-With': 'XMLHttpRequest',
'Accept': 'application/json',
},
})
.then(function (res) { return res.json(); })
.then(function (data) { showToast(data.message || 'Code updated successfully!'); })
.catch(function () { showToast('Failed to save.', true); });
```
**Penting:**
- `ajax()` check mesti LEPAS update — kalau SEBELUM, validation error (422) akan block
- `X-Requested-With: XMLHttpRequest` header wajib — tanpa ni `$request->ajax()` return false
- `_method: PUT` untuk update route — Laravel method spoofing
- AJAX modal save **tidak update** `name` & `slug` — main Save baru update metadata
### 10.2a Create Mode — page_id Coordination
Create form ada hidden field `page_id`.
```
First modal Save → create page → return page_id → set hidden field
Main Save → update page yang sama (tiada duplicate slug error)
```
**Sebab:** Modal Save perlu create page supaya code boleh disimpan. Main Save kemudiannya update page yang sama, bukan create baru.
### 10.2b Pre-editing Validation (Name & Slug)
Sebelum modal boleh dibuka atau disave:
- Editor trigger boxes disable (greyed out) kalau Name/Slug kosong.
- Butang Save dalam modal disable sehingga Name/Slug diisi.
- Kalau user cuba klik/drop tanpa isi:
- Name & Slug border merah + shake animation.
- Toast: *"Please fill in Name and Slug before editing code."*
- Error hilang automatik bila user taip.
### 10.3 Component Panel dalam Modal
Buka modal editor → klik "Components" button dalam toolbar → panel drop down.
**Features:**
- **Search/filter** — taip nama component, terus filter
- **Recently Used** — auto-save guna localStorage (max 6)
- **Drag & drop** — drag chip terus ke editor
- **Drag ghost preview** — nampak nama component semasa drag (hijau)
**Workflow:**
```
Open Modal → Click "Components" → Drag chip → Drop in Editor → Done
↓
Recently Used auto-saved
```
### 10.4 Component Count Badge
Butang "Open Component Panel" ada badge nombor hijau — berapa component dah dipilih.
Update automatik bila tick/untick checkbox.
### 10.5 Editor Trigger → Modal Drop
Drag component dari side drawer → drop pada editor trigger box:
1. Trigger show blue highlight (`.drag-over` class)
2. On drop → auto-open modal → insert component
**CSS:**
```css
#editor-trigger.drag-over {
border-color: #3b82f6 !important;
background: #eff6ff !important;
box-shadow: 0 0 0 3px rgba(59,130,246,0.2);
}
```
---
## Appendix A: Storage Structure
```
storage/app/
├── PHP/{code}.blade.php ← Component templates
├── LAYOUTS/SITE/{slug}.blade.php ← Site layouts
├── LAYOUTS/PAGE/{site}/{page}.blade.php ← Page layouts
├── ENTRY/PAGE/{site}/{page}.blade.php ← Entry scripts
├── PAGE_CONTENT/{site}/{page}.blade.php ← Page content
└── site-meta.json ← Site cache
```
## Appendix B: Service Classes Reference
| Service | File | Fungsi |
|---------|------|--------|
| `BladeSyncService` | `app/Services/BladeSyncService.php` | Sync DB → storage files |
| `PortalHandler` | `app/Services/PortalHandler.php` | Render engine untuk CMS site |
| `FrontendSiteCacheService` | `app/Services/FrontendSiteCacheService.php` | JSON cache site metadata |
| `MenuFilterService` | `app/Services/MenuFilterService.php` | Filter/redirect untuk menu assign |
## Appendix C: Model Reference
| Model | Table | PK |
|-------|-------|----|
| `Backend\FrontendSite` | `frontend_sites` | `id` |
| `Backend\FrontendComponent` | `frontend_components` | `id` |
| `Backend\FrontendPage` | `frontend_pages` | `id` |
| `Backend\FrontendPageComponent` | `frontend_page_components` | `id` (pivot) |
| `Backend\menu\frontend\Menu` | `frontend_menu` | `menu_id` |
| `Backend\menu\frontend\RoleMapping` | `frontend_role_mapping` | `id` |
| `Backend\ContentArticle` | `content_article` | `article_id` |
| `Backend\ContentSlider` | `content_slider` | `slider_id` |
| `Backend\ContentApplication` | `content_applications` | `application_id` |
| `Backend\ContentDownload` | `content_downloads` | `download_id` |
| `Backend\ContentImage` | `content_images` | `image_id` |
| `Backend\ContentPhotoGallery` | `content_photo_gallery` | `gallery_id` |
| `Backend\ContentPhotoList` | `content_photo_list` | `photo_id` |
| `Backend\ContentVideo` | `content_video` | `video_id` |