updateweb

docs/MEDIA_LIBRARY_GUIDE.md

@@ -0,0 +1,186 @@
+# 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
+
+```javascript
+Initializing media library...
+Loaded folders: 2
+Loaded files: 5
+Media library initialized
+```
+
+### Upload Flow
+
+```javascript
+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
+
+```javascript
+Creating folder: MyFolder in parent: null
+Create folder response: {success: true, folder: {...}}
+```
+
+### Error Examples
+
+```javascript
+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