MyClub/DOCS/ZONERAMA_GALLERY_IMPLEMENTATION.md

# Zonerama Gallery System Implementation

## Overview
Implemented a comprehensive gallery system using two data sources for complete album coverage with blog integration.

## Data Sources

### 1. zonerama_profile.json (Main/Newest)
- **Path**: `/cache/prefetch/zonerama_profile.json`
- **Purpose**: Main Zonerama profile albums (newest/most recent)
- **Updated**: Automatically by backend prefetch system
- **Priority**: First source checked

### 2. zonerama_albums.json (Blog Integration)
- **Path**: `/cache/prefetch/zonerama_albums.json`
- **Purpose**: Additional albums fetched when creating blog posts
- **Updated**: When admin adds album to blog post
- **Priority**: Second source, checked for additional albums

### Data Flow
1. **Gallery pages** combine both sources
2. **Sort by date** (newest first)
3. **Remove duplicates** (profile takes priority)
4. Display unified album list

## Components Created/Updated

### 1. PhotoModal Component ✅
**Location**: `frontend/src/components/gallery/PhotoModal.tsx`

**Features**:
- Full-screen photo preview with blur backdrop
- **Copy button**: Copies image to clipboard
- **Download button**: Downloads image to device
- **View Original button**: Opens photo on Zonerama
- Zonerama copyright attribution
- Album title display

### 2. GallerySection Component (Homepage) ✅
**Location**: `frontend/src/components/home/GallerySection.tsx`

**Features**:
- Displays 5 most recent albums on homepage
- Album cover images from first photo
- Date, photo count, and view statistics
- Links to full gallery page and individual albums
- Zonerama attribution notice
- Responsive grid layout (1-5 columns)
- Hover effects and animations

### 3. GalleryPage (Full Gallery) ✅
**Location**: `frontend/src/pages/GalleryPage.tsx`

**Updates**:
- Changed from API endpoint to prefetch cache
- Loads all albums from `zonerama_profile.json`
- Album grid with cover images
- Statistics display (date, photo count, views)
- Click-through to album detail pages

### 4. AlbumDetailPage ✅
**Location**: `frontend/src/pages/AlbumDetailPage.tsx`

**Updates**:
- Loads album data from `zonerama_profile.json`
- Finds specific album by ID
- Photo grid display (2-5 columns responsive)
- Breadcrumb navigation
- Zonerama attribution and external link
- Opens PhotoModal on photo click

### 5. GalleryAdminPage ✅
**Location**: `frontend/src/pages/admin/GalleryAdminPage.tsx`

**Features**:
- View all albums from Zonerama profile
- Statistics overview (total albums, photos, views)
- Album table with:
  - Cover image thumbnail
  - Album name, date
  - Photo count and view statistics
  - Preview and Zonerama links
- **Refresh button**: Triggers backend sync from Zonerama
- Empty state with refresh prompt

## Routes

### Public Routes
- `/galerie` - Gallery page with all albums
- `/galerie/album/:id` - Individual album detail page

### Admin Routes
- `/admin/galerie` - Gallery management (replaced ZoneramaAdminPage)

## Integration Points

### HomePage Updates
**File**: `frontend/src/pages/HomePage.tsx`

Replaced all `ImageGallery` instances with `GallerySection` in:
- **Unified style** (lines ~1890)
- **Magazine style** (lines ~938)
- **Pro style** (lines ~1452)
- **Edge style** (lines ~1170)

### App.tsx Updates
- Import `GalleryAdminPage` instead of `ZoneramaAdminPage`
- Route `/admin/galerie` updated to use new component

## User Experience Flow

### Homepage
1. User sees "Fotogalerie" section with 5 most recent albums
2. Each album shows cover photo, title, date, photo count
3. Click on album → navigates to album detail page
4. "Zobrazit vše" button → navigates to full gallery page

### Gallery Page
1. Shows all available albums in grid layout
2. Zonerama attribution at top
3. Click on album → navigates to album detail page
4. Empty state if no albums available

### Album Detail Page
1. Breadcrumb navigation (Home → Galerie → Album)
2. Album header with stats and Zonerama link
3. Photo grid (responsive 2-5 columns)
4. Click on photo → opens PhotoModal

### Photo Modal
1. Full-screen photo view
2. Copy image to clipboard
3. Download image
4. View original on Zonerama
5. Copyright notice
6. Close with X, close button, or click outside

### Admin Page
1. Overview statistics (albums, photos, views)
2. Table of all albums with management options
3. **Refresh from Zonerama** button for sync
4. Preview and external link buttons per album

## Technical Details

### Data Loading
```typescript
// Load from prefetch cache
const response = await fetch(
  resolveBackendUrl('/cache/prefetch/zonerama_profile.json'), 
  { cache: 'no-cache' }
);
const data = await response.json();
const albums = data.albums || [];
```

### Photo URLs
- Photos use direct Zonerama URLs from `image_1500` field
- No backend proxy needed for display
- Original URLs preserved for "View Original" functionality

### Responsive Design
- **Mobile**: 1-2 columns
- **Tablet**: 2-3 columns  
- **Desktop**: 3-5 columns
- All images use lazy loading

### Copyright Attribution
All pages display:
> 📸 Všechny fotografie jsou z platformy [Zonerama](https://zonerama.com)

## Backend Integration Required

The admin page attempts to call:
```
POST /admin/gallery/refresh
```

This endpoint should:
1. Fetch latest data from Zonerama
2. Update `zonerama_profile.json` cache
3. Return success/error status

## Features Summary

✅ Homepage gallery section (5 recent albums)
✅ Full gallery page (all albums)
✅ Album detail pages with photo grids
✅ Photo modal with copy/download/view original
✅ Admin management page
✅ Zonerama copyright attribution everywhere
✅ Responsive design
✅ Lazy loading
✅ Error handling
✅ Loading states
✅ Empty states

## Blog Integration Workflow

### For Admin (Blog Creation)
1. **Create/Edit Blog Post** in ArticlesAdminPage
2. **Click "Add Gallery"** button
3. **AlbumPhotoPicker Modal** opens:
   - Paste Zonerama album URL (must contain `/Album/`)
   - Click "Načíst" (Fetch) button
   - System calls `/zonerama-album?link=...&photo_limit=100`
   - Album photos load in grid
4. **Select Photos** (click to select, checkbox appears)
   - Can select individual photos
   - Can "Select All"
5. **Click "Vybrat"** (Select) to confirm
6. **System Actions**:
   - Saves album to `zonerama_albums.json` cache
   - Stores album ID and photo IDs with blog post
   - Photos appear in blog post

### Backend Integration Required

#### 1. Album Fetch Endpoint
```
GET /zonerama-album?link={url}&photo_limit={number}
```
Returns:
```json
{
  "album": {
    "id": "13878599",
    "title": "Album Title",
    "url": "https://eu.zonerama.com/..."
  },
  "photos": [
    {
      "id": "564520717",
      "page_url": "https://...",
      "image_1500": "https://..."
    }
  ]
}
```

#### 2. Save Album to Cache Endpoint
```
POST /admin/zonerama/save-album
Body: {
  "link": "album_url",
  "photo_limit": 50
}
```
- Fetches album from Zonerama
- Adds to `zonerama_albums.json`
- Returns album data with photos

#### 3. Article Gallery Fields
Added to Article model:
- `gallery_album_id` - Album ID from Zonerama
- `gallery_album_url` - Album URL
- `gallery_photo_ids` - Array of selected photo IDs

## Files Modified
1. `frontend/src/components/home/GallerySection.tsx` (updated - combines both sources)
2. `frontend/src/pages/GalleryPage.tsx` (updated - combines both sources)
3. `frontend/src/pages/AlbumDetailPage.tsx` (updated - checks both sources)
4. `frontend/src/pages/ArticleDetailPage.tsx` (updated - reordered layout + gallery at end)
5. `frontend/src/pages/admin/ArticlesAdminPage.tsx` (updated - album photo insertion)
6. `frontend/src/pages/admin/GalleryAdminPage.tsx` (new)
7. `frontend/src/pages/HomePage.tsx` (updated)
8. `frontend/src/App.tsx` (updated)
9. `frontend/src/components/gallery/PhotoModal.tsx` (verified)
10. `frontend/src/components/admin/AlbumPhotoPicker.tsx` (new - blog photo picker)
11. `frontend/src/services/zonerama.ts` (updated - added saveAlbumToCache)
12. `frontend/src/services/articles.ts` (updated - added gallery fields)

## Files Removed (Non-Working Components)
1. `frontend/src/components/gallery/ImageGallery.tsx` (removed - used non-functional gallery.json)
2. `frontend/src/pages/admin/ZoneramaAdminPage.tsx` (removed - used non-functional zonerama_flat.json)

## Blog Layout (Updated) ✅

The blog post now displays sections in this order:

```
┌─────────────────────────────────────────────┐
│ [ARTICLE TITLE]                              │
│─────────────────────────────────────────────│
│ [FEATURED IMAGE] (full width)                │
│─────────────────────────────────────────────│
│ 🏟️ Zápas k článku (if connected)            │
│ [Competition] [Date]                         │
│ Team A 2:1 Team B                            │
│ → Protokol zápasu (fotbal.cz)               │
│─────────────────────────────────────────────│
│ [ARTICLE CONTENT]                            │
│ (Blog text with inserted photos)             │
│─────────────────────────────────────────────│
│ 📸 Fotogalerie k článku (if attached)       │
│ [Album Title] [Date] [12 foto]               │
│ [img] [img] [img] [img] [img] [img]         │
│ [img] [img] [img] [img] [img] [img]         │
│ → Zobrazit celé album                       │
│ 📸 Fotografie z Zonerama ↗                  │
└─────────────────────────────────────────────┘
```

## Admin: Album Photo Insertion ✅

In blog editor (`ArticlesAdminPage.tsx`), admins can insert album photos directly into content:

### How to Use:
1. **In Content Tab**: Click **"Vložit fotografie z alba"** button
2. **AlbumPhotoPicker Modal** opens:
   - Paste Zonerama album URL
   - Click "Načíst" (Fetch)
   - Album photos load in grid
3. **Select Photos**: Click photos to select (with checkboxes)
4. **Click "Vybrat"** (Select)
5. **System Actions**:
   - ✅ Saves album to `zonerama_albums.json`
   - ✅ Stores `gallery_album_id`, `gallery_album_url`, `gallery_photo_ids` with article
   - ✅ Inserts selected photos into editor at cursor position
   - ✅ Photos appear in blog content where admin placed them

### Features:
- **Cursor Position**: Photos inserted where editor cursor is
- **Multiple Photos**: Each photo inserted on new line
- **Album Metadata**: Saved with article for gallery section at end
- **Dual Purpose**: 
  - Photos in content (where admin places them)
  - Gallery section at bottom (all selected photos)

## Blog Gallery Display (End Section) ✅

Added to `ArticleDetailPage.tsx` - displays at the END after content:

### Features:
- **Album Info**: Title, date, photo count badges
- **Photo Grid**: Shows up to 12 photos (2-6 columns responsive)
- **Click Photos**: Links to full album page
- **"Zobrazit celé album"** button → Album detail page
- **Zonerama Link**: Attribution with external link
- **Auto-filtering**: Shows only selected photos if `gallery_photo_ids` set

### Data Flow:
1. Article has `gallery_album_id` + `gallery_photo_ids`
2. Fetches from both `zonerama_profile.json` and `zonerama_albums.json`
3. Filters photos by selected IDs (if specified)
4. Displays grid with first 12 photos
5. Links to full album page

## Testing Checklist
- [ ] Homepage displays 5 recent albums
- [ ] Gallery page shows all albums (combined sources)
- [ ] Clicking album opens detail page
- [ ] Clicking photo opens modal
- [ ] Copy button works
- [ ] Download button works
- [ ] View original link works
- [ ] Admin page loads albums
- [ ] Admin refresh button works (requires backend)
- [ ] Responsive design on mobile/tablet/desktop
- [ ] Zonerama attribution visible everywhere
- [ ] **Blog match section displays** when article linked to match
- [ ] **Blog gallery section displays** when article has gallery album
- [ ] **Gallery photos link to full album page**