MyClub/DOCS/VISUAL_ELEMENT_EDITOR.md

Visual Element Editor System

Overview

The Visual Element Editor system allows admins to configure different visual variants for page elements without writing code. Each element (header, hero, news section, etc.) can have multiple style variants that can be switched through a visual interface.

Architecture

Backend

Database:

• Table: page_element_configs
• Stores: page_type, element_name, variant, settings (JSONB)

Models:

• internal/models/page_element_config.go - Data model with JSONB support

Controllers:

• internal/controllers/page_element_config_controller.go
  • GetPageElementConfigs - Public endpoint for fetching configs
  • CreateOrUpdatePageElementConfig - Admin endpoint for saving
  • BatchUpdatePageElementConfigs - Batch update for multiple elements

API Endpoints:

GET    /api/v1/page-elements?page_type=homepage           - Public
GET    /api/v1/admin/page-elements                        - Admin: Get all
POST   /api/v1/admin/page-elements                        - Admin: Create/Update
PUT    /api/v1/admin/page-elements/:id                    - Admin: Update
DELETE /api/v1/admin/page-elements/:id                    - Admin: Delete
POST   /api/v1/admin/page-elements/batch                  - Admin: Batch update

Frontend

Services:

• frontend/src/services/pageElements.ts
  • API client functions
  • Element variant definitions (ELEMENT_VARIANTS constant)

Hooks:

• frontend/src/hooks/usePageElementConfig.ts
  • usePageElementConfig(pageType, elementName, defaultVariant) - Single element
  • useAllPageElementConfigs(pageType) - All elements for a page

Components:

• frontend/src/components/editor/VisualPageEditor.tsx
  • Floating button overlay for admins
  • Drawer interface for selecting variants
  • Save & reload functionality

Element Variants:

• frontend/src/components/home/HeaderVariants.tsx
  • Unified: Classic header with logo and navigation
  • Edge: Modern edge-to-edge with gradient
  • Minimal: Clean minimal header
  • Modern: Bold modern with accent colors

Usage

For Admins

1. Open Visual Editor:

   • Navigate to the homepage
   • As admin, you'll see a purple floating button (bottom right)
   • Click to open the Visual Editor drawer

2. Configure Elements:

   • Toggle "Editing" mode ON
   • Select variants for each element (header, hero, news, matches, sponsors)
   • Preview shows current selection

3. Save Changes:

   • Click "Save & Reload"
   • Page will reload with new configurations
   • Changes are persisted in database

For Developers

Adding New Element Variants

1. Define Variants:

// In services/pageElements.ts
export const ELEMENT_VARIANTS: Record<string, ElementVariant[]> = {
  myElement: [
    { value: 'variant1', label: 'Variant 1', description: 'Description' },
    { value: 'variant2', label: 'Variant 2', description: 'Description' },
  ],
};

2. Create Variant Component:

// MyElementVariants.tsx
interface MyElementVariantsProps {
  variant: 'variant1' | 'variant2';
  // ...other props
}

const MyElementVariants: React.FC<MyElementVariantsProps> = ({ variant, ...props }) => {
  if (variant === 'variant1') {
    return <div>Variant 1 Implementation</div>;
  }
  
  if (variant === 'variant2') {
    return <div>Variant 2 Implementation</div>;
  }
  
  return null;
};

3. Use in Page:

import { useAllPageElementConfigs } from '../hooks/usePageElementConfig';
import MyElementVariants from '../components/MyElementVariants';

const MyPage = () => {
  const { getVariant } = useAllPageElementConfigs('mypage');
  const elementVariant = getVariant('myElement', 'variant1');
  
  return (
    <div>
      <MyElementVariants variant={elementVariant} {...props} />
    </div>
  );
};

Database Migration

Run migration to create the table:

# The migration files are already created:
# database/migrations/000020_create_page_element_configs.up.sql
# database/migrations/000020_create_page_element_configs.down.sql

# Run migrations
make migrate-up

Available Element Variants

Header

• unified: Classic header with logo and navigation
• edge: Modern edge-to-edge header with gradient background
• minimal: Clean minimal header, centered
• modern: Bold modern header with accent colors

Hero

• grid: News grid layout
• swiper: Swipeable carousel
• swiper_full: Full-width swipeable hero
• edge: Edge-style hero from ?style=edge

News

• grid: Card grid layout
• scroller: Horizontal scroller
• list: Vertical list layout
• magazine: Magazine-style layout

Matches

• compact: Compact match cards
• expanded: Detailed match information
• timeline: Timeline view

Sponsors

• grid: Grid layout with title sponsor
• slider: Animated slider
• scroller: Horizontal scroller
• pyramid: Pyramid layout

Benefits

1. No Code Changes: Admins can switch styles without developer intervention
2. Unified System: Single base style with element variants instead of multiple complete themes
3. Persistent: Configurations saved in database
4. Live Preview: Changes apply immediately after save
5. Per-Element Control: Mix and match different variants

Migration from Old System

The old system used complete page styles (unified, magazine, pro, edge). The new system:

1. Keeps unified as base: All pages use unified CSS as foundation
2. Adds element variants: Individual elements can have different styles
3. Removes custom styles: No more separate magazine.css, pro.css, edge.css
4. Database-driven: Preferences stored in database instead of settings

Migration Steps

1. Run database migration
2. Admin configures preferred variants through Visual Editor
3. Old style query parameters (?style=edge) still work for backwards compatibility
4. Gradually remove old style CSS files as variants are implemented

Future Enhancements

• Add preview mode without reload
• Export/import configurations
• Per-page configurations (different homepage vs about page)
• Color scheme variants
• Layout density options (compact, normal, spacious)
• Responsive variants (mobile-specific)
• A/B testing support
• Analytics integration to track variant performance