mirror of
https://github.com/Dvorinka/MyClubServer.git
synced 2026-06-03 18:22:57 +00:00
dev day #63
This commit is contained in:
Tomas Dvorak
@@ -0,0 +1,290 @@
|
||||
# File Preview Component
|
||||
|
||||
## Overview
|
||||
A comprehensive file preview component that provides inline viewing and downloading capabilities for various file types including images, PDFs, videos, audio files, and Office documents (PPTX, DOCX, XLSX).
|
||||
|
||||
## Component Location
|
||||
`frontend/src/components/common/FilePreview.tsx`
|
||||
|
||||
## Features
|
||||
|
||||
### 1. **Supported File Types**
|
||||
|
||||
#### Full Preview Support (in modal)
|
||||
- **Images**: JPG, JPEG, PNG, GIF, SVG, WebP, BMP
|
||||
- Direct inline display
|
||||
- Click to zoom in modal
|
||||
- Error handling for failed loads
|
||||
|
||||
- **PDFs**:
|
||||
- Embedded iframe viewer
|
||||
- Native browser PDF viewer
|
||||
- Maintains aspect ratio
|
||||
|
||||
- **Videos**: MP4, AVI, MOV, WebM
|
||||
- HTML5 video player with controls
|
||||
- 16:9 aspect ratio
|
||||
- Support for multiple formats
|
||||
|
||||
- **Audio**: MP3, WAV, OGG
|
||||
- HTML5 audio player with controls
|
||||
- Icon display with player below
|
||||
|
||||
#### Online Preview Support
|
||||
- **PowerPoint**: PPTX, PPT
|
||||
- "Zobrazit online" button using Microsoft Office Online Viewer
|
||||
- Download option
|
||||
- File info display
|
||||
|
||||
- **Word**: DOCX, DOC
|
||||
- Same online viewer support
|
||||
- Icon and file metadata
|
||||
|
||||
- **Excel**: XLSX, XLS
|
||||
- Online spreadsheet viewer
|
||||
- Download and preview options
|
||||
|
||||
### 2. **Display Modes**
|
||||
|
||||
#### Compact Mode (default)
|
||||
```tsx
|
||||
<FilePreview
|
||||
url="/uploads/document.pdf"
|
||||
name="Document.pdf"
|
||||
mimeType="application/pdf"
|
||||
size={1024000}
|
||||
/>
|
||||
```
|
||||
- Shows file icon, name, and size
|
||||
- Preview and Download buttons
|
||||
- Responsive layout
|
||||
|
||||
#### Inline Mode (for images)
|
||||
```tsx
|
||||
<FilePreview
|
||||
url="/uploads/photo.jpg"
|
||||
name="Photo.jpg"
|
||||
mimeType="image/jpeg"
|
||||
size={512000}
|
||||
showInline={true}
|
||||
/>
|
||||
```
|
||||
- Displays image directly in the page
|
||||
- Click to open full-size modal
|
||||
- Max height: 400px
|
||||
|
||||
### 3. **User Interface Elements**
|
||||
|
||||
#### File Information
|
||||
- Icon based on file type (color-coded)
|
||||
- File name (truncated if too long)
|
||||
- File size (displayed in KB or MB)
|
||||
- MIME type indicator
|
||||
|
||||
#### Action Buttons
|
||||
- **Náhled** (Preview): Opens modal with file preview
|
||||
- **Stáhnout** (Download): Direct download link
|
||||
- **Zobrazit online** (View Online): For Office documents
|
||||
|
||||
#### Modal Preview
|
||||
- Full-screen modal (90vw × 90vh)
|
||||
- Dark overlay background
|
||||
- Close button
|
||||
- Download button in footer
|
||||
- Responsive content area
|
||||
|
||||
## Props
|
||||
|
||||
```typescript
|
||||
interface FilePreviewProps {
|
||||
url: string; // File URL (relative or absolute)
|
||||
name?: string; // Display name (defaults to filename from URL)
|
||||
mimeType?: string; // MIME type (e.g., 'image/jpeg', 'application/pdf')
|
||||
size?: number; // File size in bytes
|
||||
showInline?: boolean; // Show inline preview for images (default: false)
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage (Event Attachments)
|
||||
```tsx
|
||||
import FilePreview from '../components/common/FilePreview';
|
||||
|
||||
// In your component
|
||||
{attachments.map((att, idx) => (
|
||||
<FilePreview
|
||||
key={idx}
|
||||
url={att.url}
|
||||
name={att.name}
|
||||
mimeType={att.mime_type}
|
||||
size={att.size}
|
||||
/>
|
||||
))}
|
||||
```
|
||||
|
||||
### Inline Image Gallery
|
||||
```tsx
|
||||
{images.map((img, idx) => (
|
||||
<FilePreview
|
||||
key={idx}
|
||||
url={img.url}
|
||||
name={img.name}
|
||||
mimeType="image/jpeg"
|
||||
size={img.size}
|
||||
showInline={true}
|
||||
/>
|
||||
))}
|
||||
```
|
||||
|
||||
### PDF Document
|
||||
```tsx
|
||||
<FilePreview
|
||||
url="/uploads/report.pdf"
|
||||
name="Monthly Report.pdf"
|
||||
mimeType="application/pdf"
|
||||
size={2048000}
|
||||
/>
|
||||
```
|
||||
|
||||
### PowerPoint Presentation
|
||||
```tsx
|
||||
<FilePreview
|
||||
url="/uploads/presentation.pptx"
|
||||
name="Company Presentation.pptx"
|
||||
mimeType="application/vnd.openxmlformats-officedocument.presentationml.presentation"
|
||||
size={3145728}
|
||||
/>
|
||||
```
|
||||
|
||||
## File Type Detection
|
||||
|
||||
The component automatically detects file types based on MIME type:
|
||||
|
||||
| MIME Type Pattern | Icon | Color | Preview Available |
|
||||
|------------------|------|-------|-------------------|
|
||||
| `image/*` | FiImage | Purple | ✅ Yes (inline) |
|
||||
| `application/pdf` | FiFileText | Red | ✅ Yes (iframe) |
|
||||
| `video/*` | FiVideo | Pink | ✅ Yes (player) |
|
||||
| `audio/*` | FiMusic | Green | ✅ Yes (player) |
|
||||
| `*word*`, `*document*` | FiFileText | Blue | ⚠️ Online only |
|
||||
| `*sheet*`, `*excel*` | FiFile | Green | ⚠️ Online only |
|
||||
| `*presentation*`, `*powerpoint*` | FiFile | Orange | ⚠️ Online only |
|
||||
| Other | FiFile | Gray | ❌ Download only |
|
||||
|
||||
## Microsoft Office Online Viewer
|
||||
|
||||
For Office documents (PPTX, DOCX, XLSX), the component offers a "Zobrazit online" button that opens the file in Microsoft Office Online Viewer:
|
||||
|
||||
```
|
||||
https://view.officeapps.live.com/op/view.aspx?src=[ENCODED_FILE_URL]
|
||||
```
|
||||
|
||||
**Requirements:**
|
||||
- File must be publicly accessible
|
||||
- Supported formats: DOCX, XLSX, PPTX
|
||||
- Internet connection required
|
||||
|
||||
## Integration with ActivityDetailPage
|
||||
|
||||
The FilePreview component has been integrated into `ActivityDetailPage.tsx`:
|
||||
|
||||
**Before:**
|
||||
- Simple download button
|
||||
- No preview functionality
|
||||
- Minimal file information
|
||||
|
||||
**After:**
|
||||
- Full preview support for all file types
|
||||
- Inline image display
|
||||
- Modal viewer for PDFs, videos, audio
|
||||
- Office document online viewer
|
||||
- Better file metadata display
|
||||
|
||||
## Styling & Theming
|
||||
|
||||
The component uses Chakra UI's color mode values:
|
||||
|
||||
```tsx
|
||||
const borderColor = useColorModeValue('gray.200', 'gray.700');
|
||||
const cardBg = useColorModeValue('white', 'gray.800');
|
||||
const mutedText = useColorModeValue('gray.600', 'gray.300');
|
||||
const linkColor = useColorModeValue('blue.600', 'blue.300');
|
||||
```
|
||||
|
||||
This ensures proper display in both light and dark modes.
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Image Loading Errors
|
||||
- Catches `onError` event
|
||||
- Displays fallback message
|
||||
- Provides download option
|
||||
|
||||
### Video/Audio Playback Errors
|
||||
- Shows browser's native error message
|
||||
- Falls back to download option
|
||||
|
||||
### PDF Loading Issues
|
||||
- Browser's native PDF viewer handles errors
|
||||
- Users can download if preview fails
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Proper ARIA labels
|
||||
- Keyboard navigation support (modal)
|
||||
- Screen reader friendly
|
||||
- High contrast icons
|
||||
- Responsive design
|
||||
|
||||
## Browser Compatibility
|
||||
|
||||
| Browser | Images | PDFs | Video | Audio | Office Docs |
|
||||
|---------|--------|------|-------|-------|-------------|
|
||||
| Chrome 90+ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Firefox 88+ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Safari 14+ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
| Edge 90+ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
||||
|
||||
**Note:** Office document online viewing requires an internet connection and works on all modern browsers.
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
1. **Lazy Loading**: Images are loaded only when visible
|
||||
2. **Modal Loading**: Preview content loads only when modal opens
|
||||
3. **External Links**: Downloads don't trigger component re-renders
|
||||
4. **Error Boundaries**: Failed loads don't crash the component
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
|
||||
1. **Caching**: Cache preview content
|
||||
2. **Thumbnails**: Generate thumbnails for large files
|
||||
3. **Full-screen mode**: Add full-screen toggle for videos
|
||||
4. **Download progress**: Show progress bar for large files
|
||||
5. **Zoom controls**: Add zoom in/out for images and PDFs
|
||||
6. **Print option**: Add print button for documents
|
||||
7. **Share functionality**: Social sharing buttons
|
||||
8. **Multi-page PDF navigation**: Add page controls for PDFs
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `@chakra-ui/react`: UI components
|
||||
- `react-icons/fi`: Feather icons
|
||||
- `assetUrl` utility: URL resolution helper
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] Image preview opens in modal
|
||||
- [ ] PDF displays in iframe
|
||||
- [ ] Video plays with controls
|
||||
- [ ] Audio plays correctly
|
||||
- [ ] Office docs show "View Online" button
|
||||
- [ ] Download button works
|
||||
- [ ] Error states display properly
|
||||
- [ ] Responsive on mobile
|
||||
- [ ] Dark mode looks correct
|
||||
- [ ] File sizes format correctly (KB/MB)
|
||||
- [ ] Modal closes properly
|
||||
- [ ] External links open in new tab
|
||||
Reference in New Issue
Block a user