SkyArtShop/docs/MEDIA_LIBRARY_GUIDE.md

Media Library Quick Reference

Opening the Media Library

Navigate to: http://localhost:5000/admin/media-library.html

Interface Overview

┌─────────────────────────────────────────────────────────────┐
│  Media Library                                         [X]   │
├─────────────────────────────────────────────────────────────┤
│  🏠 Root                                    0 selected       │
│  [🗂️ New Folder] [☁️ Upload Files] [🗑️ Delete Selected]   │
├─────────────────────────────────────────────────────────────┤
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐           │
│  │ 📁     │  │ 🖼️     │  │ 🖼️     │  │ 🖼️     │           │
│  │MyFolder│  │image1  │  │image2  │  │image3  │           │
│  │ 5 files│  │        │  │        │  │        │           │
│  └────────┘  └────────┘  └────────┘  └────────┘           │
│                                                             │
│  [Upload Zone - Hidden by default]                         │
│  ☁️ Drop files here or click to browse                     │
│  Supported: JPG, PNG, GIF, WebP (Max 5MB each)            │
│                                                             │
│  [Progress Bar - Shows during upload]                      │
│  ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░ 65%                                 │
└─────────────────────────────────────────────────────────────┘

Actions

Upload Files (Method 1: Click)

1. Click "Upload Files" button
2. Upload zone appears
3. Click anywhere in the drop zone
4. File picker opens
5. Select one or more images
6. Progress bar shows upload status
7. Success alert: "Successfully uploaded X file(s)!"
8. Files appear in the grid

Upload Files (Method 2: Drag & Drop)

1. Click "Upload Files" button
2. Upload zone appears
3. Drag files from your file manager
4. Drop onto the blue upload zone
5. Progress bar shows upload status
6. Success alert appears
7. Files appear in the grid

Create New Folder

1. Click "New Folder" button
2. Modal appears: "Create New Folder"
3. Enter folder name (e.g., "Products", "Logos", "Banners")
4. Click "Create Folder"
5. Success alert: "Folder 'Products' created successfully!"
6. Folder appears in the grid with 📁 icon

Navigate Folders

• Double-click a folder to open it
• Breadcrumb at top shows current path: 🏠 Root > Products > Summer
• Click breadcrumb links to go back to parent folders

Select Items

• Click checkbox on any file or folder to select
• Selected count shows: "3 selected"
• Delete Selected button appears when items are selected

Delete Items

1. Select one or more files/folders using checkboxes
2. Click "Delete Selected" button
3. Confirm deletion
4. Items are removed

Browser Console

Open Developer Tools (F12) and check Console tab for detailed logs:

Normal Flow

Initializing media library...
Loaded folders: 2
Loaded files: 5
Media library initialized

Upload Flow

Upload zone opened
Files selected: 2
Starting upload of 2 files
Adding file: photo.jpg image/jpeg 1234567
Adding file: banner.png image/png 987654
Sending upload request...
Upload progress: 50%
Upload progress: 100%
Upload complete, status: 200
Upload response: {success: true, files: Array(2)}

Folder Creation

Creating folder: MyFolder in parent: null
Create folder response: {success: true, folder: {...}}

Error Examples

Failed to load folders: Authentication required
// → Will redirect to login page

Upload failed: File type not allowed
// → Shows error alert

Failed to create folder: A folder with this name already exists
// → Shows error alert

Error Messages

Upload Errors

• "No files to upload" - No files selected
• "File type not allowed" - Invalid file type (only JPG, PNG, GIF, WebP)
• "File too large" - File exceeds 5MB limit
• "Upload failed with status 413" - Request too large
• "Upload failed due to network error" - Network connection issue
• "Authentication required" - Session expired, will redirect to login

Folder Errors

• "Please enter a folder name" - Empty folder name
• "A folder with this name already exists" - Duplicate name in same location
• "Parent folder not found" - Parent folder was deleted
• "Authentication required" - Session expired

File Support

Supported Formats

• ✅ JPEG/JPG
• ✅ PNG
• ✅ GIF
• ✅ WebP

File Limits

• Max file size: 5 MB per file
• Max files per upload: 10 files at once
• Total upload size: 50 MB per batch

File Naming

• Original names preserved in database
• Filenames sanitized and made unique
• Format: name-timestamp-random.ext
• Example: photo-1734657890-123456789.jpg

Tips

1. Use folders to organize your media by category (products, logos, banners, etc.)
2. Check console logs (F12) if something doesn't work as expected
3. File uploads show progress - don't navigate away during upload
4. Double-click folders to navigate, single-click to select
5. Breadcrumbs at the top help you navigate back to parent folders
6. Select multiple items using checkboxes for batch deletion

Integration with Homepage Editor

When you click "Choose Image" in the homepage editor:

• Media library opens in a modal
• Select an image
• Click "Select" or double-click the image
• Image URL is automatically inserted into the homepage field