# 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
