# Media Tagging System - Quick Installation Guide

## Adding Tagging to Any Page

Follow these steps to add the media tagging system to any HTML page in the application.

## Step 1: Include CSS

Add the media-tags.css stylesheet in the `<head>` section:

```html
<link rel="stylesheet" href="src/styles/media-tags.css">
```

## Step 2: Include JavaScript Files

Add these script tags before the closing `</body>` tag, in this order:

```html
<!-- Media Tagging System -->
<script src="src/features/media/mediaTagManager.js"></script>
<script src="src/features/media/mediaTagUI.js"></script>
<script src="src/features/media/globalTaggingInit.js"></script>

<!-- Optional: Campaign Integration -->
<script src="src/features/academy/campaignTagging.js"></script>
```

## Step 3: Initialize (Automatic)

The tagging system will automatically initialize when the page loads. It will be available via global variables:

- `window.globalMediaTagManager` - Tag manager instance
- `window.globalMediaTagUI` - UI component instance

## Step 4: Use the System

### Basic Tagging

```javascript
// Tag a photo
tagMedia('photo_123.jpg', ['selfie', 'bedroom']);

// Get tags for a photo
const tags = getMediaTags('photo_123.jpg');

// Find photos with specific tags
const photos = findMediaByTags(['selfie', 'outfit'], matchAll=false);

// Open tag management UI
openTagManager();
```

### Add Tagging to Gallery Items

```javascript
// For each media item in your gallery
const mediaId = photo.path || photo.id;
addTaggingToElement(galleryItemElement, mediaId, 'photo');
```

### Campaign Level Integration

```javascript
// In your campaign level setup
const campaignTagging = createCampaignTagging();

campaignTagging.initializeTaggingTask({
    requiredTags: ['outfit', 'pose'],
    requiredTagCount: 2,
    targetMediaIds: photoIds,
    onComplete: (progress) => {
        console.log('Task complete!', progress);
    }
});

campaignTagging.displayTaggingInterface(container, mediaItems);
```

## Complete Example Page

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>My Page with Tagging</title>
    
    <!-- Required Styles -->
    <link rel="stylesheet" href="src/styles/color-variables.css">
    <link rel="stylesheet" href="src/styles/styles.css">
    <link rel="stylesheet" href="src/styles/media-tags.css">
</head>
<body>
    <div id="app">
        <button onclick="openTagManager()">🏷️ Manage Tags</button>
        <div id="photo-gallery"></div>
    </div>

    <!-- Core Game Scripts -->
    <script src="src/core/game.js"></script>
    
    <!-- Media Tagging System -->
    <script src="src/features/media/mediaTagManager.js"></script>
    <script src="src/features/media/mediaTagUI.js"></script>
    <script src="src/features/media/globalTaggingInit.js"></script>

    <script>
        // Wait for tagging system to be ready
        window.addEventListener('taggingSystemReady', () => {
            console.log('Tagging system ready!');
            initializePhotoGallery();
        });

        function initializePhotoGallery() {
            const gallery = document.getElementById('photo-gallery');
            
            // Load your photos
            const photos = [/* your photos */];
            
            photos.forEach(photo => {
                const item = document.createElement('div');
                item.className = 'photo-item';
                item.innerHTML = `
                    <img src="${photo.url}" alt="${photo.name}" />
                    <div class="photo-info">
                        <h4>${photo.name}</h4>
                    </div>
                `;
                
                // Add tagging to this item
                addTaggingToElement(item, photo.id, 'photo');
                
                gallery.appendChild(item);
            });
        }
    </script>
</body>
</html>
```

## Integration with Existing Code

### If You Already Have a Photo Gallery

```javascript
// Find your existing gallery items
const galleryItems = document.querySelectorAll('.photo-item');

// Add tagging to each one
galleryItems.forEach(item => {
    const photoId = item.dataset.photoId; // or however you identify photos
    addTaggingToElement(item, photoId, 'photo');
});
```

### If You're Using a Framework/Template

The tagging system works with dynamically created elements:

```javascript
// React-style example (pseudo-code)
function PhotoItem({ photo }) {
    useEffect(() => {
        const element = document.getElementById(`photo-${photo.id}`);
        if (element) {
            addTaggingToElement(element, photo.id, 'photo');
        }
    }, [photo.id]);

    return <div id={`photo-${photo.id}`} className="photo-item">...</div>;
}
```

## Adding to Training Academy

To add tagging to training-academy.html:

1. Include the CSS and JS files (see Step 1 & 2)
2. In your level setup:

```javascript
// In level configuration
{
    id: 'my-level-with-tagging',
    setup: function() {
        const container = document.getElementById('level-container');
        const photos = [/* captured during level */];
        
        const campaignTagging = createCampaignTagging();
        campaignTagging.initializeTaggingTask({
            requiredTagCount: 1,
            targetMediaIds: photos.map(p => p.id),
            onComplete: () => {
                this.completeLevel();
            }
        });
        
        campaignTagging.displayTaggingInterface(container, photos);
    }
}
```

## Troubleshooting

### "Tagging system not initialized"
Make sure:
1. Scripts are loaded in correct order
2. `window.game.dataManager` exists
3. Check browser console for errors

### Tags not saving
- Verify localStorage is not full
- Check that `window.game.dataManager` is working
- Look for errors in console

### UI not showing
- Ensure `media-tags.css` is loaded
- Check CSS variables are defined
- Verify modal container exists in DOM

## Events You Can Listen To

```javascript
// When tags change
window.addEventListener('tagsChanged', (e) => {
    console.log('Tags updated', e.detail);
});

// When filters change
window.addEventListener('tagFiltersChanged', (e) => {
    console.log('Filters updated', e.detail);
});

// When system is ready
window.addEventListener('taggingSystemReady', (e) => {
    console.log('Ready to tag!', e.detail);
});
```

## Advanced: Custom Integration

If you need more control:

```javascript
// Create your own instances instead of using global
const myTagManager = new MediaTagManager(window.game.dataManager);
const myTagUI = new MediaTagUI(myTagManager);

// Customize callbacks
myTagUI.onTagsChanged = function() {
    console.log('Custom handler');
    // Your custom logic
};

// Use your instances
myTagUI.renderTagInput(container, mediaId);
```

## Files Reference

Core files you need:
- `src/features/media/mediaTagManager.js` - Core logic
- `src/features/media/mediaTagUI.js` - UI components
- `src/features/media/globalTaggingInit.js` - Auto-initialization
- `src/styles/media-tags.css` - Styling

Optional files:
- `src/features/academy/campaignTagging.js` - Campaign integration
- `src/features/media/libraryTaggingIntegration.js` - Library-specific code

## Need Help?

See full documentation:
- `docs/MEDIA_TAGGING_SYSTEM.md` - Complete API reference
- `docs/TAGGING_IMPLEMENTATION_SUMMARY.md` - Implementation details
- `src/data/modes/example-tagging-level.js` - Working example

---

That's it! The tagging system is now ready to use on your page.
