MyClub/DOCS/BANNER_SYSTEM_DOCUMENTATION.md

# Banner and Advertising System - Complete Documentation

## Overview
The banner and advertising system provides a comprehensive solution for managing advertising spaces across the website. The system features automatic placement recommendations based on image resolution, preset dimensions for optimal display, and automatic sponsor integration.

## Key Features

### 1. **Preset-Based Banner Placements**
The system includes 5 predefined banner placements with optimal dimensions:

| Placement | Dimensions | Aspect Ratio | Position | Description |
|-----------|------------|--------------|----------|-------------|
| `homepage_top` | 1200 × 200 | 6:1 | Top | Main banner at the top of homepage, shown to all visitors |
| `homepage_middle` | 970 × 250 | 3.88:1 | Middle | Banner in the middle of the page between content |
| `homepage_sidebar` | 300 × 250 | 1.2:1 | Sidebar | Smaller banner in the right sidebar panel |
| `homepage_footer` | 1200 × 200 | 6:1 | Footer | Banner at the bottom of the page before footer |
| `article_inline` | 728 × 90 | 8.09:1 | Article | Banner displayed within article text |

### 2. **Automatic Image Resolution Detection**
When uploading a banner image:
- The system automatically detects the image resolution (width × height)
- Calculates the aspect ratio
- Provides up to 3 recommended placements based on image dimensions
- Recommends the best matching placement (highlighted as "Nejlepší")
- Displays resolution info: "Rozlišení: 1200×200 px, Poměr stran: 6.00:1"

### 3. **Smart Placement Recommendations**
The recommendation algorithm:
1. Compares image aspect ratio with preset aspect ratios
2. Evaluates width and height differences
3. Scores each placement (lower score = better match)
4. Returns top 3 recommendations ranked by quality
5. Auto-selects the best match if no placement is already chosen

### 4. **Live Preview System**
- Shows banner preview in the admin modal
- Preview respects the selected placement dimensions
- Displays where the banner will appear: "Zobrazení v pozici: [Placement Label]"
- Scaled proportionally to fit admin interface (max 600px width)

### 5. **Placement Information Display**
For each placement, the system shows:
- **Label**: User-friendly Czech name
- **Description**: Detailed explanation of where and how it displays
- **Dimensions**: Exact pixel dimensions (read-only, automatically set)
- **Aspect Ratio**: Calculated ratio for reference
- **Position**: Logical position identifier (top, middle, sidebar, footer, article)

### 6. **Manual Dimension Removal**
- Width and height fields are **removed** from manual input
- Dimensions are **automatically set** based on selected placement preset
- This ensures consistency and prevents display issues
- Users can only select from predefined placements

### 7. **Automatic Sponsor Integration**
When a banner is created/updated:
- The banner data is stored in the `sponsors` table with placement metadata
- Active banners (`is_active = true`) automatically appear in:
  - **Footer**: Displayed in "Naši partneři" section with inverted logo styling
  - **Sponsors Page**: Listed alongside regular sponsors
  - **Homepage Sponsors Section**: Included in the sponsors grid/slider
- Provides dual functionality: advertising + partnership visibility

### 8. **Enhanced Admin Interface**
The Banners Admin Page (`/admin/bannery`) includes:
- **Table View** with columns:
  - Náhled (Preview thumbnail)
  - Název (Name) + URL preview
  - Umístění (Placement label + position badge)
  - Rozměry (Dimensions display)
  - Aktivní (Active status badge)
  - Akce (Edit/Delete actions)
- **Modal Editor** with:
  - Name input
  - Click-through URL (optional)
  - Image upload with progress indicator
  - Resolution detection alert
  - Placement recommendations panel
  - Placement selector with descriptions
  - Dimension display (read-only)
  - Live preview area
  - Active toggle switch

## Technical Implementation

### Database Schema
Banners use the existing `sponsors` table with additional fields:
```sql
CREATE TABLE sponsors (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  logo_url TEXT,
  website_url TEXT,
  is_active BOOLEAN DEFAULT true,
  tier TEXT DEFAULT 'standard',
  display_order INTEGER DEFAULT 0,
  placement TEXT,  -- e.g., 'homepage_top'
  width INTEGER,   -- e.g., 1200
  height INTEGER,  -- e.g., 200
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);
```

### Frontend Components

#### 1. **BannersAdminPage.tsx**
Location: `frontend/src/pages/admin/BannersAdminPage.tsx`

Key Functions:
- `getPreset(placement)` - Retrieves preset configuration by placement value
- `recommendPlacement(width, height)` - Returns top 3 recommended placements
- `onUpload(file)` - Handles image upload with resolution detection
- `openCreate()` - Opens modal with default placement preset
- `openEdit(sponsor)` - Opens modal for editing existing banner

State Management:
- `editing` - Current banner being edited
- `imageResolution` - Detected image dimensions
- `recommendedPlacements` - Array of recommended placements
- `uploadingImage` - Upload progress indicator

#### 2. **BannerDisplay.tsx**
Location: `frontend/src/components/banners/BannerDisplay.tsx`

Props:
```typescript
interface BannerDisplayProps {
  banners: Banner[];
  placement: 'homepage_top' | 'homepage_middle' | 'homepage_sidebar' | 'homepage_footer' | 'article_inline';
  containerStyle?: React.CSSProperties;
}
```

Features:
- Filters active banners for specific placement
- Applies placement-specific styling
- Handles responsive layout
- Provides hover effects
- Lazy loads images

#### 3. **Footer.tsx**
Location: `frontend/src/components/layout/Footer.tsx`

Sponsor Display:
- Fetches sponsors from `/api/v1/public/sponsors`
- Filters active sponsors (`is_active !== false`)
- Displays in responsive grid (2-6 columns)
- Inverted logos for dark background
- Links to sponsor websites with tracking

### Backend Integration

#### API Endpoints
```
GET    /api/v1/public/sponsors        - List all active sponsors/banners
POST   /api/v1/sponsors                - Create new banner (admin)
PUT    /api/v1/sponsors/:id            - Update banner (admin)
DELETE /api/v1/sponsors/:id            - Delete banner (admin)
```

#### Sponsor Model (Go)
```go
type Sponsor struct {
    gorm.Model
    Name         string `gorm:"not null" json:"name"`
    LogoURL      string `json:"logo_url"`
    WebsiteURL   string `json:"website_url"`
    Description  string `json:"description"`
    IsActive     bool   `gorm:"default:true" json:"is_active"`
    Tier         string `gorm:"default:'standard'" json:"tier"`
    DisplayOrder int    `gorm:"default:0" json:"display_order"`
    Placement    string `json:"placement"`
    Width        int    `json:"width"`
    Height       int    `json:"height"`
}
```

### Display Locations

#### Homepage
Banners are displayed in the following locations on the homepage:

1. **Top Banner** (`homepage_top`)
   - Full-width section after header
   - Light gray background with borders
   - Centered content

2. **Middle Banner** (`homepage_middle`)
   - Between content sections
   - Centered display
   - Standard margin spacing

3. **Sidebar Banner** (`homepage_sidebar`)
   - Right sidebar (desktop)
   - Sticky positioning (top: 96px)
   - Stacked on mobile
   - Rounded corners with shadow

4. **Footer Banner** (`homepage_footer`)
   - Above footer navigation
   - Full-width with background
   - Centered content

#### Article Pages
5. **Inline Banner** (`article_inline`)
   - Embedded within article content
   - Standard ad format (728×90)
   - Responsive on mobile

#### Footer
All active banners (regardless of placement) also appear as sponsors in:
- Footer "Naši partneři" section
- 6-column responsive grid
- White inverted logos on dark background

#### Sponsors Page
Banners are included in the sponsors page listing at `/sponzori`.

## Usage Guide

### Adding a New Banner

1. **Navigate to Admin Panel**
   - Go to `/admin/bannery`
   - Click "Nový banner" button

2. **Upload Image**
   - Click "Nahrát obrázek" button
   - Select your banner image file
   - System automatically detects resolution

3. **Review Recommendations**
   - Check the detected resolution alert
   - Review recommended placements (up to 3)
   - Best match is highlighted in green

4. **Select Placement**
   - Choose from dropdown or click "Použít" on recommendation
   - View placement description below selector
   - See dimensions display (auto-set, read-only)

5. **Preview Banner**
   - Check live preview in modal
   - Verify it matches expected dimensions
   - See placement label below preview

6. **Configure Details**
   - Enter banner name (required)
   - Add website URL for click-through (optional)
   - Toggle active status (default: active)

7. **Save**
   - Click "Uložit" button
   - Banner appears immediately on site
   - Also added to sponsors in footer

### Editing an Existing Banner

1. Click edit icon (pencil) in banner table
2. Modify any fields except dimensions
3. Upload new image to change resolution/placement
4. Save changes

### Best Practices

#### Image Preparation
- **Use correct dimensions** for target placement
- **High quality images** (at least 2x for retina displays)
- **Optimize file size** (recommended: <500KB)
- **Use PNG or JPG** formats
- **Test on mobile** - ensure text is readable

#### Recommended Image Sizes
For best quality on retina displays:
- `homepage_top`: 2400×400 @ 72dpi
- `homepage_middle`: 1940×500 @ 72dpi
- `homepage_sidebar`: 600×500 @ 72dpi
- `homepage_footer`: 2400×400 @ 72dpi
- `article_inline`: 1456×180 @ 72dpi

#### Naming Convention
Use descriptive names:
- ❌ Bad: "Banner 1", "IMG_1234"
- ✅ Good: "Hlavní partner 2025", "Turnaj léto 2025"

#### URL Configuration
- Always use `https://` protocol
- Test link before saving
- Use tracking parameters if needed: `?utm_source=banner&utm_medium=homepage`

#### Active Status
- Set to active only when campaign is live
- Deactivate expired campaigns instead of deleting
- Keeps historical data and analytics

## Troubleshooting

### Issue: Banner not displaying
**Solutions:**
1. Check `is_active` status is `true`
2. Verify placement matches homepage style
3. Clear browser cache
4. Check image URL is accessible

### Issue: Wrong placement recommendations
**Cause:** Image aspect ratio doesn't match any preset closely

**Solutions:**
1. Resize image to match recommended dimensions
2. Choose closest preset manually
3. Accept that banner may not perfectly fit

### Issue: Image resolution not detected
**Cause:** Browser security/CORS issues

**Solutions:**
1. Upload image again
2. Try different image format
3. Check image file integrity
4. Use supported format (JPG/PNG/WebP)

### Issue: Banner overlaps content
**Cause:** Custom styling conflicts

**Solutions:**
1. Use preset placements only
2. Don't modify width/height manually
3. Check responsive behavior on mobile

### Issue: Sponsor not showing in footer
**Cause:** Banner not marked as active or API error

**Solutions:**
1. Verify `is_active = true`
2. Check API endpoint `/api/v1/public/sponsors`
3. Refresh page to reload sponsors
4. Check browser console for errors

## Future Enhancements

Potential improvements:
- [ ] A/B testing for banner effectiveness
- [ ] Click-through tracking and analytics
- [ ] Impression counting
- [ ] Scheduled banner campaigns (start/end dates)
- [ ] Banner rotation for same placement
- [ ] Custom placement creation
- [ ] Banner templates library
- [ ] Bulk upload functionality
- [ ] Performance metrics dashboard

## Technical Notes

### Performance Considerations
- Images use `loading="lazy"` for off-screen banners
- Responsive images with `object-fit: contain`
- Minimal re-renders with React state management
- Cached sponsor data in footer

### Accessibility
- All banners have descriptive `alt` text
- Clickable areas use semantic `<a>` tags
- Keyboard navigation support
- ARIA labels where appropriate

### Security
- Image uploads validate file types
- URLs sanitized before storage
- External links use `rel="noopener noreferrer"`
- XSS protection on user inputs

## Support

For issues or questions about the banner system:
1. Check this documentation first
2. Review browser console for errors
3. Test with different image formats
4. Contact system administrator

---

**Last Updated:** 2025-01-12
**Version:** 1.0
**Maintained by:** MyClub Development Team