MyClub/DOCS/ELEMENTOR_STYLE_EDITOR.md

# Elementor-Style Visual Editor

## 🎨 Overview

The Elementor-Style Visual Editor brings WordPress Elementor-like page building capabilities to your football club website. Edit your homepage visually with live element highlighting, drag-free controls, and professional styling options.

## ✨ Key Features

### Visual Editing Mode
- **Live Element Highlighting**: Hover over any element to see it highlighted with a blue dashed border
- **Element Badges**: Click on element badges to instantly open their settings
- **Selected Element**: Active element shows a solid blue border with semi-transparent overlay
- **No Page Reload**: Changes preview live (refresh to see final result)

### Professional Controls
- **Left Control Panel**: Quick access toolbar with edit mode toggle, undo/redo, device preview, and save
- **Right Settings Drawer**: Comprehensive element configuration panel
- **Search Elements**: Quickly find the element you want to edit
- **Template Import/Export**: Save and reuse your configurations

### Advanced Features
- **Undo/Redo History**: Full editing history with navigation
- **Device Preview**: Switch between Desktop, Tablet, and Mobile views
- **Template Management**: Export configurations as JSON and import them later
- **Batch Save**: All changes saved in one operation

## 🚀 How to Use

### Entering Edit Mode

1. **Login** as administrator
2. **Navigate** to the homepage
3. **Click** the purple edit button in the bottom-left control panel
4. **Watch** as all editable elements get highlighted with badges

### Editing Elements

**Method 1: Click Element Badge**
- Hover over any element (header, hero, news, etc.)
- Click the element name badge that appears
- Settings drawer opens automatically

**Method 2: Use Settings Panel**
- Click the settings (gear) icon in the left control panel
- Browse or search for elements in the "Elements" tab
- Click on an element to expand its settings

### Configuring Variants

1. **Select Element**: Click on the element or find it in the panel
2. **Choose Variant**: Select from available style variants in dropdown
3. **View Description**: Each variant shows a description below
4. **See Changes**: Element updates immediately in the preview

### Saving Changes

1. **Make Changes**: Edit multiple elements as needed
2. **Review**: Check the orange "unsaved changes" badge
3. **Click Save**: Green save button in left panel or settings tab
4. **Wait**: Page automatically refreshes to apply changes

## 📐 Control Panel Breakdown

### Left Floating Panel (Bottom-Left)

```
┌────────────┐
│  👁️ / ✏️   │ ← Edit Mode Toggle
├────────────┤
│    ⚙️      │ ← Settings Drawer
│    ↶      │ ← Undo
│    ↷      │ ← Redo
├────────────┤
│   🖥️ / 📱  │ ← Device Preview
├────────────┤
│    💾      │ ← Save Changes
└────────────┘
```

### Right Settings Drawer

**Elements Tab**:
- Search bar for quick element finding
- Accordion list of all editable elements
- Current variant shown below element name
- Expand to see variant selector and description

**Settings Tab**:
- Page information
- History controls (undo/redo with count)
- Save button with change indicator
- Template export/import buttons

## 🎯 Available Elements & Variants

### Header
Visual style of the top header/logo area

- **Unified**: Classic horizontal header with logo and text
- **Edge**: Modern centered header with gradient background
- **Minimal**: Clean minimal centered header
- **Modern**: Bold header with accent colors and shadow

### Hero
Main featured content section

- **Grid**: 3-column grid (1 large + 2 small cards)
- **Swiper**: Swipeable carousel slider
- **Swiper Full**: Full-width hero carousel
- **Edge**: Dramatic full-screen hero from Edge style

### News
Article/blog listing section

- **Grid**: Card grid layout
- **Scroller**: Horizontal scrolling cards
- **List**: Traditional vertical list
- **Magazine**: Magazine-style with categories

### Matches
Match display section

- **Compact**: Minimal match cards
- **Expanded**: Detailed match information with stats
- **Timeline**: Timeline view of fixtures

### Sponsors
Sponsor logos section

- **Grid**: Grid with title sponsor
- **Slider**: Infinite scrolling slider
- **Scroller**: Horizontal scroller
- **Pyramid**: Pyramid/tiered layout

## ⌨️ Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Ctrl/Cmd + Z` | Undo |
| `Ctrl/Cmd + Y` | Redo |
| `Ctrl/Cmd + S` | Save Changes |
| `Esc` | Close Settings Drawer |

## 💡 Pro Tips

### Fast Editing Workflow

1. **Enter edit mode** once
2. **Click element badges** directly (faster than using panel)
3. **Make all changes** before saving
4. **Export template** for backup before major changes
5. **Save once** to apply all changes

### Best Practices

- **Preview Before Save**: Check all changes in different device views
- **Use Undo/Redo**: Don't hesitate to experiment, you can always undo
- **Export Templates**: Save successful configurations as templates
- **Test Mobile**: Always check mobile device preview before saving
- **Batch Changes**: Edit multiple elements in one session for efficiency

### Element Selection Tips

- **Header**: First impression matters - choose based on brand identity
- **Hero**: Drive engagement - swiper for content variety, grid for stability
- **News**: Match visitor behavior - grid for scanning, scroller for browsing
- **Matches**: Consider info density - compact for many matches, expanded for detail
- **Sponsors**: Balance visibility - grid for fewer sponsors, slider for many

## 🔧 Advanced Usage

### Template Management

**Export Template**:
1. Configure all elements as desired
2. Click "Export" button in drawer header
3. JSON file downloads with all configurations
4. Save for backup or sharing

**Import Template**:
1. Click "Import" button in drawer header
2. Select previously exported JSON file
3. All configurations apply immediately
4. Review and save to persist

### History Management

- **View Count**: Settings tab shows "X / Y changes"
- **Navigate**: Use undo/redo buttons or keyboard
- **Limit**: Last 50 changes stored
- **Reset**: Save to clear history

### Device Preview

**Desktop View** (default):
- Full-width preview
- All elements visible
- No overlay

**Tablet View**:
- 768px viewport simulation
- Dark overlay on sides
- Restricted width preview

**Mobile View**:
- 375px viewport simulation
- Dark overlay on sides
- Mobile-optimized preview

## 🐛 Troubleshooting

### Element Not Highlighting

**Problem**: Element doesn't show border/badge on hover

**Solutions**:
- Ensure edit mode is ON (purple button pressed)
- Check element has `data-element` attribute
- Refresh page if overlays disappeared

### Changes Not Saving

**Problem**: Save button doesn't work or changes lost

**Solutions**:
- Check browser console for errors
- Verify you're logged in as admin
- Try saving one element at a time
- Export template as backup, then try again

### Preview Not Updating

**Problem**: Changes don't show in preview

**Solutions**:
- Some changes need page refresh to see
- Try toggling device preview
- Click save to apply changes permanently

### Can't Find Element

**Problem**: Element not in the list

**Solutions**:
- Use search bar to filter
- Check if element is wrapped with `EditableElement`
- Verify element name in `ELEMENT_VARIANTS`

## 🎓 For Developers

### Adding Editable Elements

Wrap any section with `EditableElement`:

```tsx
import EditableElement from '../components/editor/EditableElement';

<EditableElement elementName="myElement">
  <div>Your content here</div>
</EditableElement>
```

### Defining Variants

Add to `services/pageElements.ts`:

```typescript
export const ELEMENT_VARIANTS: Record<string, ElementVariant[]> = {
  myElement: [
    { 
      value: 'variant1', 
      label: 'Variant 1', 
      description: 'Clean and simple layout' 
    },
    { 
      value: 'variant2', 
      label: 'Variant 2', 
      description: 'Bold and colorful design' 
    },
  ],
};
```

### Using Variant in Component

```tsx
const { getVariant } = useAllPageElementConfigs('homepage');
const myVariant = getVariant('myElement', 'variant1');

// Render based on variant
{myVariant === 'variant1' && <Variant1Component />}
{myVariant === 'variant2' && <Variant2Component />}
```

## 🎉 Comparison with WordPress Elementor

| Feature | Elementor | Our Editor | Notes |
|---------|-----------|------------|-------|
| Visual Editing | ✅ | ✅ | Live element highlighting |
| Drag & Drop | ✅ | ❌ | Not needed for variant switching |
| Live Preview | ✅ | ⚠️ | Needs refresh for full preview |
| Undo/Redo | ✅ | ✅ | Full history support |
| Device Preview | ✅ | ✅ | Desktop/Tablet/Mobile |
| Template Library | ✅ | ✅ | Export/Import JSON |
| Advanced Styling | ✅ | 🔄 | Coming soon with AdvancedStyleControls |
| Widget Library | ✅ | ⚠️ | Predefined variants instead |
| Responsive Editing | ✅ | 🔄 | Per-device settings planned |
| Custom CSS | ✅ | 🔄 | Planned feature |

✅ = Fully implemented  
⚠️ = Partially implemented  
❌ = Not implemented  
🔄 = Planned

## 📚 Related Documentation

- `VISUAL_ELEMENT_EDITOR.md` - Technical implementation details
- `QUICK_START_VISUAL_EDITOR.md` - Quick start guide
- `NAVIGATION_SYSTEM.md` - Navigation configuration
- `README.md` - General documentation

## 🆘 Support

For issues or questions:
1. Check this documentation
2. Review browser console for errors
3. Test in different browser
4. Check `page_element_configs` database table
5. Review component source code

---

**Version**: 2.0  
**Last Updated**: 2025-01-13  
**Compatibility**: React 18+, Chakra UI 2+