# Visual Builder Development SOP
## Standard Operating Procedure for Component Development & Testing

### 🎯 Purpose
This SOP ensures that all visual builder components work correctly in both the builder interface and public website views. It prevents issues with HTML caching, component rendering, and data persistence.

---

## 📋 Pre-Development Checklist

### 1. Environment Setup
- [ ] Local development server is running
- [ ] Database connection is working
- [ ] Subdomain routing is configured (e.g., `test.neosolvix.test`)
- [ ] Browser developer tools are ready

### 2. Baseline Testing
- [ ] Test existing components work in builder
- [ ] Test existing components display on public view
- [ ] Note any existing issues

---

## 🔧 Component Development Process

### 1. Create/Modify Component Template
**Location**: `resources/views/pages/custom-builder.blade.php`

- [ ] Add/update HTML template in `<template id="component-name-template">`
- [ ] Include default data attributes if component stores settings
- [ ] Add proper CSS classes and Bootstrap structure
- [ ] Include component controls (Edit/Delete buttons)

**Example for data-driven components:**
```html
<template id="video-template">
    <div class="component-wrapper" data-type="video" data-video-url="" data-video-type="youtube">
        <!-- Component content -->
    </div>
</template>
```

### 2. Add Component to Palette
- [ ] Add component item in the component palette section
- [ ] Use appropriate Bootstrap icon
- [ ] Set correct `data-type` attribute

### 3. Implement Properties Panel
- [ ] Add case for component in `updatePropertiesPanel()` method
- [ ] Create form controls for component configuration
- [ ] Add event listeners for real-time updates
- [ ] Store settings in data attributes for extraction

### 4. Add Component Extraction Logic
- [ ] Add case in `extractComponentData()` method
- [ ] Extract data from DOM elements AND data attributes (fallback)
- [ ] Handle both configured and unconfigured states
- [ ] Filter out builder-specific classes/styles

### 5. Add Server-Side Rendering
**Location**: `app/Models/Page.php` in `renderBuilderComponent()` method

- [ ] Add case for component type
- [ ] Handle all content properties (URL, settings, etc.)
- [ ] Add proper error handling with try-catch
- [ ] Include fallback/placeholder content
- [ ] Escape HTML properly for security

---

## 🧪 Testing Protocol

### Phase 1: Builder Interface Testing
- [ ] **Drag & Drop**: Component can be dragged from palette
- [ ] **Initial State**: Component shows proper placeholder/default content
- [ ] **Properties Panel**: Right panel shows component-specific controls
- [ ] **Configuration**: All settings can be modified and apply immediately
- [ ] **Visual Updates**: Component updates in real-time when properties change
- [ ] **Save Functionality**: Component data is extracted correctly during save

### Phase 2: Data Persistence Testing
- [ ] **Save Page**: Use "Save" button in builder
- [ ] **Refresh Builder**: Hard refresh browser and verify component settings persist
- [ ] **Database Check**: Verify component data is saved in `builder_data` field
- [ ] **Multiple Components**: Test with multiple instances of the component

### Phase 3: Public View Testing ⚠️ **CRITICAL**

#### 3.1 Clear HTML Cache First
```bash
# Run this command to clear pre-generated HTML cache
php artisan tinker --execute="
\App\Models\Page::where('is_builder_page', true)
    ->whereNotNull('html')
    ->update(['html' => null]);
echo 'HTML cache cleared for all builder pages';
"
```

#### 3.2 Test Public Rendering
- [ ] **Access Public URL**: Visit `http://subdomain.neosolvix.test`
- [ ] **Inspect Element**: Verify component HTML appears in DOM
- [ ] **Visual Check**: Component displays correctly visually
- [ ] **Functionality**: Interactive elements work (videos play, links work, etc.)
- [ ] **Responsive Design**: Test on different screen sizes
- [ ] **Cross-Browser**: Test in different browsers if needed

### Phase 4: Edge Case Testing
- [ ] **Empty/Default State**: Component with no configuration
- [ ] **Invalid Data**: Component with broken URLs or bad data
- [ ] **Nested Components**: Component inside containers/sections
- [ ] **Multiple Instances**: Several components of same type on one page

---

## 🚨 Common Issues & Solutions

### Issue 1: Component Not Appearing on Public View
**Symptoms**: Component shows in builder but missing from public page
**Cause**: HTML caching using old pre-generated content
**Solution**: 
```bash
# Clear HTML cache for specific page
php artisan tinker --execute="
\$page = \App\Models\Page::find(PAGE_ID);
\$page->html = null;
\$page->save();
echo 'HTML cache cleared';
"
```

### Issue 2: Component Data Not Saving
**Symptoms**: Settings reset after page refresh
**Cause**: Missing data extraction logic or incorrect selector
**Solution**: 
- Check `extractComponentData()` method has case for component
- Verify data attributes are set correctly
- Test selector paths in browser console

### Issue 3: Properties Panel Not Showing
**Symptoms**: Right panel doesn't show component settings
**Cause**: Missing case in `updatePropertiesPanel()` method
**Solution**: Add component case with proper form controls

### Issue 4: Component Rendering Errors
**Symptoms**: Component shows placeholder or error on public view
**Cause**: Missing server-side rendering logic or PHP errors
**Solution**: 
- Check `Page.php` has case for component in `renderBuilderComponent()`
- Check error logs for PHP errors
- Add proper error handling

---

## 📊 Final Verification Checklist

Before marking development complete, verify:

### Builder Functionality
- [ ] Component appears in palette
- [ ] Can be dragged and dropped
- [ ] Properties panel works correctly
- [ ] Settings persist after save/refresh
- [ ] Visual updates work in real-time

### Public View Functionality  
- [ ] Component appears in public page HTML (inspect element)
- [ ] Component displays correctly visually
- [ ] All interactive features work
- [ ] Responsive design works on mobile
- [ ] No JavaScript console errors

### Code Quality
- [ ] Server-side rendering handles all edge cases
- [ ] Proper HTML escaping for security
- [ ] Error handling with fallbacks
- [ ] Code follows existing patterns
- [ ] Comments added for complex logic

### Documentation
- [ ] Component usage documented
- [ ] Any special requirements noted
- [ ] Breaking changes communicated

---

## 🔄 Maintenance Tasks

### Weekly
- [ ] Test all components on public views
- [ ] Clear HTML cache if issues found
- [ ] Review error logs for component issues

### After Major Updates
- [ ] Re-test all existing components
- [ ] Verify backward compatibility
- [ ] Update documentation if needed

### Before Production Deployment
- [ ] Full component test suite
- [ ] Clear all HTML caches
- [ ] Verify public pages render correctly

---

## 🛠️ Quick Commands Reference

```bash
# Clear HTML cache for all builder pages
php artisan tinker --execute="App\Models\Page::where('is_builder_page', true)->update(['html' => null]);"

# Check specific page data
php artisan tinker --execute="dd(App\Models\Page::find(PAGE_ID)->builder_data);"

# Test page rendering
php artisan tinker --execute="echo App\Models\Page::find(PAGE_ID)->getRenderedContent();"

# Find pages with HTML cache
php artisan tinker --execute="App\Models\Page::whereNotNull('html')->where('html', '!=', '')->pluck('id', 'title');"
```

---

## 📞 Troubleshooting Contacts

When issues arise:
1. Check this SOP first
2. Clear HTML cache
3. Test in browser dev tools
4. Check server error logs
5. Verify database data

**Remember**: Always test both builder AND public view! 🎯