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
Files
80f833b926493477b766f025be9b25e28ed4eb67
MyClub/DOCS/ZONERAMA_GALLERY_IMPLEMENTATION.md
T
Tomáš Dvořák 12cba639b9 upload
2025-10-16 13:32:05 +02:00

364 lines
12 KiB
Markdown
Raw Blame History

# 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**
Reference in New Issue View Git Blame Copy Permalink