# Page Builders Reference Guide

**Last Updated:** 2025-10-28
**Status:** All systems working ✅

---

## Quick Reference: Which File to Edit?

### Adding New Builder V2 Component
1. **React Component:** `resources/js/builder-v2/components/user/YourComponent.jsx`
2. **Renderer:** `resources/views/pages/render-v2.blade.php` (add renderYourComponent function)
3. **Register:** Import in `resources/js/builder-v2/main.jsx`

### Fixing Rendering Issues
- **File:** `resources/views/pages/render-v2.blade.php`
- **Used by:** Public website + Customizer preview + Builder V2

### Customizer Changes
- **Controller:** `app/Http/Controllers/CustomizerController.php`
- **Main UI:** `resources/views/websites/customizer/index.blade.php`
- **Panels:** `resources/views/websites/customizer/panels/*.blade.php`

---

## Page Builder Systems Overview

### 1. Page Builder V2 (React + Craft.js) ⭐ NEWEST
**Status:** Production Ready
**Recommended for:** All new pages

**Key Files:**
- Controller: `app/Http/Controllers/PageBuilderV2Controller.php`
- Builder UI: `resources/views/pages/builder-v2.blade.php`
- Renderer: `resources/views/pages/render-v2.blade.php` ⭐ CRITICAL
- React: `resources/js/builder-v2/`

**Database:**
- `pages.builder_v2_data` (JSON) - Craft.js format
- `pages.is_builder_v2_page` (BOOLEAN)

**Access:**
- New: `/websites/{id}/builder-v2`
- Edit: `/websites/{id}/pages/{page_id}/builder-v2`

---

### 2. Custom Visual Builder (Legacy)
**Status:** Stable, not recommended for new pages
**Used by:** Existing older pages

**Key Files:**
- Controller: `app/Http/Controllers/PageController.php`
- View: `resources/views/pages/custom-builder.blade.php`

**Database:**
- `pages.builder_data` (JSON)
- `pages.is_builder_page` (BOOLEAN)

**Access:**
- Edit: `/websites/{id}/pages/{page_id}/custom-builder`

---

### 3. Editor.js (Text Editor)
**Status:** Active
**Used by:** Blog posts, content pages

**Key Files:**
- View: `resources/views/pages/edit.blade.php`

**Database:**
- `pages.content` (JSON) - Editor.js format

**Access:**
- Edit: `/websites/{id}/pages/{page_id}/edit`

---

### 4. Theme Customizer (WordPress-style)
**Status:** Fully Working ✅
**Used by:** Site-wide styling (colors, fonts, global settings)

**Key Files:**
- Controller: `app/Http/Controllers/CustomizerController.php`
- Main UI: `resources/views/websites/customizer/index.blade.php`
- Panels: `resources/views/websites/customizer/panels/*.blade.php`

**Database:**
- `website_themes.color_overrides` (JSON)
- `website_themes.font_overrides` (JSON)
- `website_themes.settings_overrides` (JSON)

**Access:**
- `/websites/{id}/customizer`

---

## The Critical File: render-v2.blade.php

**Location:** `resources/views/pages/render-v2.blade.php`

**Used By:**
1. Page Builder V2 pages (frontend rendering)
2. Public website (what visitors see)
3. Customizer preview (live preview iframe)

**Contains:**
- ~40+ render functions (renderContainer, renderHeading, renderParagraph, etc.)
- HTML generation for all Builder V2 components
- Component styling and structure

**Important:**
- This file is shared across multiple systems
- Changes here affect: Builder V2, Public Website, and Customizer Preview
- Always test changes in all three contexts

---

## Recent Fixes (2025-10-28)

### Issue: Customizer Preview Different from Public Website
**Problem:** Preview used different view files than public website

**Solution:**
1. Updated `CustomizerController@preview` to use same views as `PublicController@renderPage`
2. Builder V2 pages now use: `public.builder-page` view (same as public)
3. Theme pages use: `themes.dynamic.layout` view (same as public)

**Result:** ✅ Preview now identical to public website

### Issue: Parse Errors in render-v2.blade.php
**Problem:** 12 brace mismatch errors in render functions

**Solution:**
- Fixed extra closing braces after `if (empty(...))` checks
- Fixed premature function closures
- Removed 12 extra braces across multiple functions

**Result:** ✅ All render functions work correctly

---

## Testing URLs

**Public Website:**
```
https://ava5.neosolvix.test/
```

**Theme Customizer:**
```
https://neosolvix.test/websites/24/customizer
```

**Page Builder V2:**
```
https://neosolvix.test/websites/24/pages/{page_id}/builder-v2
```

---

## Recommendations

### For New Pages
✅ Use **Page Builder V2** (builder-v2)
- Modern React-based interface
- Drag-and-drop functionality
- Best user experience

### For Existing Pages
✅ Keep using their current builder
- No need to migrate unless needed
- All builders are functional

### For Site Styling
✅ Use **Theme Customizer**
- WordPress-like interface
- Live preview
- Global styling changes

### For Blog/Content
✅ Use **Editor.js**
- Rich text editing
- Clean content management
- Good for text-heavy pages

---

## Development Notes

### Adding New Component to Builder V2

1. **Create React Component:**
   ```jsx
   // resources/js/builder-v2/components/user/MyComponent.jsx
   export const MyComponent = ({ text }) => {
     return <div>{text}</div>;
   };

   MyComponent.craft = {
     displayName: 'My Component',
     props: { text: 'Default text' }
   };
   ```

2. **Add Renderer:**
   ```php
   // In render-v2.blade.php
   if (!function_exists('renderMyComponent')) {
   function renderMyComponent($props) {
       $text = $props['text'] ?? 'Default text';
       $html = '<div>' . htmlspecialchars($text) . '</div>';
       return $html;
   }
   }
   ```

3. **Register Component:**
   ```javascript
   // In resources/js/builder-v2/main.jsx
   import { MyComponent } from './components/user/MyComponent';
   // Add to editor.resolver
   ```

4. **Build Assets:**
   ```bash
   npm run build
   ```

### Debugging Tips

**If preview doesn't update:**
1. Clear Laravel views: `php artisan view:clear`
2. Check browser console for JS errors
3. Verify customizer state is updating (check Network tab)

**If components don't render:**
1. Check `render-v2.blade.php` for syntax errors
2. Verify render function exists for component
3. Check browser console for PHP errors

**If Builder V2 doesn't load:**
1. Run `npm run build`
2. Check `public/build/` directory exists
3. Verify Vite manifest file is present

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     User Edits Page                         │
└───────────────────┬─────────────────────────────────────────┘
                    │
         ┌──────────┼──────────┬──────────────┐
         │          │          │              │
    Builder V2  Custom     Editor.js    Customizer
         │      Builder       │              │
         │          │          │              │
         └──────────┴──────────┴──────────────┘
                    │
         ┌──────────▼──────────┐
         │   Save to Database   │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │  Public Rendering    │
         │  (PublicController)  │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │  render-v2.blade.php │ ⭐ CRITICAL FILE
         │  (Component HTML)    │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │   User Sees Page     │
         └─────────────────────┘
```

---

## Support

For issues or questions:
1. Check this reference guide first
2. Review `CLAUDE.md` in project root
3. Test in all three contexts (Builder, Public, Customizer)

---

**Last Major Update:** Fixed customizer preview and render-v2.blade.php brace issues (2025-10-28)