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:

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:

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)

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