Skip to content

Enhanced Media Browser

Overview

The Enhanced Media Browser is a modern, feature-rich media selection component for the Badger Commerce admin interface. It provides an intuitive interface for browsing, searching, filtering, and uploading media files with improved UX and performance.

Features

🎯 Core Functionality

  • Modern Grid Layout: Clean, responsive grid with larger thumbnails
  • Real-time Search: Debounced search with instant results
  • Tag-based Filtering: Filter media by keywords with individual tag removal
  • Image Preview: Live preview panel with detailed information
  • Multiple Selection: Support for single or multiple image selection
  • Upload Integration: Enhanced drag & drop upload with visual feedback
  • Keyboard Navigation: Arrow keys navigation, Enter to select, Escape to close

🎨 User Experience Improvements

  • Progressive Disclosure: Tag cloud hidden by default, shown on demand
  • Compact Layout: Efficient use of space with minimal whitespace
  • Individual Tag Removal: Remove specific filter tags without clearing all
  • Visual Feedback: Clear indication of active filters and selections
  • Responsive Design: Works across desktop, tablet, and mobile devices

🔧 Technical Features

  • Backward Compatibility: Works with existing image-selector-btn implementations
  • Graceful Fallback: Falls back to original browser if enhanced template unavailable
  • Performance Optimized: Lazy loading, pagination, and debounced search
  • API Integration: Enhanced endpoints with legacy support

Usage

Basic Integration

<button type="button" class="btn btn-primary image-selector-btn"
        data-cardinality="1"
        data-callback-function-name="myCallbackFunction">
    <i class="fa fa-images"></i> Choose Image
</button>

Multiple Selection

<button type="button" class="btn btn-primary image-selector-btn"
        data-cardinality="5"
        data-callback-function-name="myMultipleCallback">
    <i class="fa fa-images"></i> Choose Images (up to 5)
</button>

Callback Function

function myCallbackFunction(selectedMedia) {
    // selectedMedia is an array of objects with:
    // - mediaId: string
    // - url: string
    // - title: string
    // - altText: string
    // - description: string

    selectedMedia.forEach(function(media) {
        console.log('Selected:', media.title, media.url);
    });
}

User Interface Layout

┌─ Search Bar ────────────────────────────── [🔍] [✖] [🔧 Filter by Tags] ─┐
├─ Active Filters (only when active) ────────────────────────────────────────┤
│  Active filters: [tag1 ×] [tag2 ×] [tag3 ×]                    Clear all │
├─ Tag Cloud (hidden by default) ────────────────────────── [× Hide] ────────┤
│  Click tags to filter: [tag1] [tag2] [tag3] [tag4] [tag5]                 │
├─ Image Grid ───────────────────────────────────────────────────────────────┤
│  [img] [img] [img] [img]                                                   │
│  [img] [img] [img] [img]                                                   │
│  │                                                                         │
│  └─ Preview Panel ──────────────────────────────────────────────────────────┤
│    Image Preview                                                           │
│    Title: Selected Image                                                   │
│    Description: Image details                                              │
│    Tags: [tag1] [tag2] [tag3]                                              │
└─────────────────────────────────────────────────────────────────────────────┘

API Endpoints

Enhanced Search Endpoint

GET /admin/rest/media/browser

Parameters: - search (optional): Search term for title/description - type (optional): Media type filter - keywords (optional): Array of keywords to filter by - p (default: 1): Page number - size (default: 12): Page size (max 24)

Response: 

{
    "media": [...],
    "totalPages": 5,
    "totalElements": 58,
    "currentPage": 1,
    "hasNext": true,
    "hasPrevious": false
}

Legacy Support

  • GET /admin/rest/media/searchByImages - Still supported for backward compatibility

Testing

Test Page

Navigate to /admin/mediaBrowserTest to access the test page demonstrating: - Single image selection - Multiple image selection (up to 3 images) - Callback function integration - Error handling

Manual Testing Checklist

Basic Functionality

  • [ ] Media browser opens when clicking image selector buttons
  • [ ] Images load in grid layout with proper thumbnails
  • [ ] Search functionality works with debouncing
  • [ ] Tag filtering works with individual removal
  • [ ] Image selection works (single and multiple)
  • [ ] Preview panel shows selected image details
  • [ ] Upload tab allows drag & drop file upload
  • [ ] Modal closes properly after selection

Keyboard Navigation

  • [ ] Arrow keys navigate between images
  • [ ] Enter key selects highlighted image
  • [ ] Escape key closes the modal
  • [ ] Tab navigation works through interface elements

Responsive Design

  • [ ] Interface works on desktop (1200px+)
  • [ ] Interface works on tablet (768px-1199px)
  • [ ] Interface works on mobile (< 768px)
  • [ ] Grid layout adjusts appropriately

Files

Core Implementation

  • web/src/main/resources/resources/settBuilder/themes/admin/js/enhancedMediaBrowser.js
  • web/src/main/resources/resources/settBuilder/themes/admin/js/mustacheTemplates/enhancedMediaBrowser.mustache

Integration Points

  • web-admin/src/main/resources/templates/admin/footerScripts.html - Script loading
  • web-admin/src/main/java/uk/co/kedos/badger/settbuilder/render/admin/MediaAdminController.java - Backend endpoints

Test Files

  • web-admin/src/main/resources/templates/admin/mediaBrowserTest.html - Test page

Browser Support

  • Modern Browsers: Chrome 80+, Firefox 75+, Safari 13+, Edge 80+
  • Mobile: iOS Safari 13+, Chrome Mobile 80+
  • Fallback: Older browsers use original implementation

Performance Targets

  • Initial Load: < 2 seconds for 12 images
  • Search Response: < 500ms
  • Image Rendering: < 100ms per image
  • Memory Usage: < 50MB for 100+ images in browser

Current Status

✅ ACTIVE: The Enhanced Media Browser is currently active and replaces the original media chooser.

Key Improvements Completed

  1. ✅ Individual Tag Removal - Remove single keywords by clicking × on filter tags
  2. ✅ Compact Layout - Eliminated excessive whitespace, cleaner interface
  3. ✅ Better UX Flow - Logical progression from search → filters → results
  4. ✅ Progressive Disclosure - Tag cloud hidden by default, shows when needed
  5. ✅ Upload Functionality - Full upload support with dropzone integration

Integration Status

  • ✅ Enhanced script loaded in admin interface
  • ✅ Template and mustache files active
  • ✅ Test page available at /admin/mediaBrowserTest
  • ✅ Backward compatibility maintained
  • ✅ Upload functionality restored and working

Configuration

JavaScript Configuration

MediaBrowser.config = {
    pageSize: 12,        // Images per page
    modalId: 'enhancedMediaModal',
    // ... other options
};

CSS Customization

The enhanced media browser includes embedded CSS in the Mustache template. Styles can be customized by modifying the template or extracting to external CSS files.

Troubleshooting

Common Issues

Media Browser Doesn't Open

  • Check browser console for JavaScript errors
  • Verify enhancedMediaBrowser.js is loading correctly
  • Ensure buttons have image-selector-btn class

Images Don't Load

  • Check network tab for failed API requests
  • Verify media repository has images
  • Check image URL paths in admin config

Upload Issues

  • Verify AWS credentials are configured correctly
  • Check server logs for S3 connection errors
  • Ensure upload endpoint /admin/imageUpload/123 is accessible

Debug Mode

Enable debug logging: 

MediaBrowser.config.debug = true;