# Theme Page Types & Architecture

## Overview
The system has three types of page content that work differently:

---

## 1. **Customizable Theme Pages** ✏️

These are pages you design in the theme builder that get copied to websites.

### Examples:
- **Home** - Landing page
- **About Us** - Company information
- **Contact Us** - Contact form and details
- **Services** - Services listing
- **Products** - Products listing page
- **Gallery** - Image gallery
- **FAQ** - Frequently asked questions
- **Terms & Conditions**
- **Privacy Policy**
- **Custom Pages** - Any custom content

### How They Work:
1. **Design in Theme Builder** → `/admin/theme-builder/builder/{themeId}`
2. **Create page** → Select page type (home, about, contact, etc.)
3. **Design in Builder V2** → Full drag & drop editor
4. **Mark as Published** → Only published pages are copied
5. **When user installs theme** → Pages are copied to their website's `pages` table
6. **User can customize** → Users can edit these pages later

### Database Flow:
```
theme_pages (theme templates)
    ↓ (when theme is installed)
pages (website's actual pages)
```

---

## 2. **Global Sections (Header & Footer)** 🌐

These appear on EVERY page and are managed separately.

### Types:
- **Header** - Top navigation, logo, menu
- **Footer** - Bottom section with links, copyright, etc.

### How They Work:
1. **Design in Theme Builder** → Create page with type "Header" or "Footer"
2. **Design the section** → Use Builder V2 to create the layout
3. **Mark as Published**
4. **When user installs theme** → Copied to `global_sections` table (NOT pages)
5. **User can customize via Customizer** → `/websites/{id}/customizer`

### Visual Indicators:
- **Blue "Global Section" badge** in theme builder
- **"Appears on all pages" text** instead of slug
- **Can't be set as home page** (that wouldn't make sense)

### Database Flow:
```
theme_pages (type: header/footer)
    ↓ (when theme is installed)
global_sections (website's header/footer)
```

---

## 3. **System-Managed Pages** 🔒

These are **NOT customizable** in the theme builder. They're auto-generated for functionality.

### Examples:
- **Product Detail** - Individual product page (e-commerce)
- **Shopping Cart** - Cart page (e-commerce)
- **Checkout** - Checkout flow (e-commerce)
- **Order Success** - Thank you page (e-commerce)
- **Blog Post Detail** - Individual blog post

### Why NOT Customizable?
These pages have **critical functionality** that must work correctly:
- Form fields (checkout form, payment info)
- Cart logic (add/remove items, calculate totals)
- Order processing
- Payment gateway integration

### How They Work:
1. **Auto-generated** when website has e-commerce/blog enabled
2. **System templates** with fixed structure
3. **Inherit theme styling** (colors, fonts from theme)
4. **Logic can't be changed** (to prevent breaking functionality)

---

## Complete Page Type Reference

### Available in Theme Builder:
```php
'home' => 'Home Page'           // Can be set as home page ⭐
'about' => 'About Us'
'contact' => 'Contact Us'
'services' => 'Services'
'products' => 'Products Listing'
'blog' => 'Blog'
'gallery' => 'Gallery'
'faq' => 'FAQ'
'terms' => 'Terms & Conditions'
'privacy' => 'Privacy Policy'
'custom' => 'Custom Page'

// Global Sections
'header' => 'Header'            // Copied to global_sections 🌐
'footer' => 'Footer'            // Copied to global_sections 🌐
```

### NOT in Theme Builder (System Pages):
```php
'product_detail' => 'Product Detail'   // E-commerce only 🔒
'cart' => 'Shopping Cart'              // E-commerce only 🔒
'checkout' => 'Checkout'               // E-commerce only 🔒
'order_success' => 'Order Success'     // E-commerce only 🔒
'blog_post' => 'Blog Post Detail'      // Blog only 🔒
```

---

## Theme Installation Flow

When a user creates a website and selects your theme:

1. **Check for theme pages** in database
2. **For each published page**:
   - If `page_type` is `header` or `footer`:
     - ✅ Copy to `global_sections` table
     - Sets `type = 'header'` or `'footer'`
   - If regular page:
     - ✅ Copy to `pages` table
     - Sets `is_builder_v2_page = true`
     - Sets `is_home = true` if `page_type = 'home'`
3. **System pages** (cart, checkout) created separately if e-commerce enabled

---

## User Experience

### As Theme Designer:
1. Create theme at `/admin/theme-builder/builder/{id}`
2. Add pages: home, about, contact, header, footer
3. Design each in Builder V2
4. Mark all as published
5. Set one page as home page (usually the "home" page type)

### As Website Owner:
1. Create website, select your theme
2. Gets all your designed pages automatically
3. Header/footer appear on all pages
4. Can customize pages via Builder V2
5. Can customize header/footer via Customizer
6. System pages (cart/checkout) appear automatically if e-commerce enabled

---

## Key Features Implemented

✅ Header/Footer as special page types
✅ Global sections copied to `global_sections` table
✅ Regular pages copied to `pages` table
✅ Visual indicators (badges) for different page types
✅ "Set as Home Page" button for regular pages
✅ Header/Footer marked as "Global Section" with info badge
✅ System pages excluded from theme builder
✅ Auto-detection: if theme has pages → use them, else → create defaults

---

## Testing Your Theme

1. **Create header/footer pages**:
   - Go to theme builder
   - Create page with type "Header"
   - Design your navigation/logo
   - Create page with type "Footer"
   - Design your footer content
   - Publish both

2. **Create regular pages**:
   - Create home, about, contact pages
   - Design them in Builder V2
   - Set one as home page (click house icon)
   - Publish all

3. **Test installation**:
   - Create new website
   - Select your theme
   - Check pages are created
   - Check header/footer appear via Customizer

4. **Verify**:
   - Pages exist in `/websites/{id}/pages`
   - Header/footer exist in `/websites/{id}/customizer`
   - Home page is marked correctly
   - All content matches your designs

---

## Database Schema

### theme_pages
```
id, theme_id, page_type, title, slug,
builder_data, is_published, order
```

### pages (website pages)
```
id, website_id, title, slug,
builder_v2_data, is_builder_v2_page,
is_home, is_published
```

### global_sections (header/footer)
```
id, website_id, name, type,
builder_data, is_custom
```

---

## Summary

**Header & Footer**: ✅ Design in theme builder → Copy to global_sections
**Regular Pages**: ✅ Design in theme builder → Copy to pages
**System Pages**: ❌ Not in theme builder → Auto-generated with fixed structure