TDvorak/MyClub
1
0
Fork 0
mirror of https://github.com/Dvorinka/MyClubServer.git synced 2026-06-04 02:32:57 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

upload

Browse Source
This commit is contained in:
Tomáš Dvořák
2025-10-16 13:32:05 +02:00
commit 12cba639b9
663 changed files with 168914 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCS/BANNER_SYSTEM_DOCUMENTATION.md
+385
View File
@@ -0,0 +1,385 @@
# 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