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

// 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

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:

{
  "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