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-btnimplementations - 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¶
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-mvc/src/main/resources/resources/settBuilder/themes/admin/js/enhancedMediaBrowser.jsweb-mvc/src/main/resources/resources/settBuilder/themes/admin/js/mustacheTemplates/enhancedMediaBrowser.mustache
Integration Points¶
web-admin/src/main/resources/templates/admin/footerScripts.html- Script loadingweb-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¶
- ✅ Individual Tag Removal - Remove single keywords by clicking × on filter tags
- ✅ Compact Layout - Eliminated excessive whitespace, cleaner interface
- ✅ Better UX Flow - Logical progression from search → filters → results
- ✅ Progressive Disclosure - Tag cloud hidden by default, shows when needed
- ✅ 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.jsis loading correctly - Ensure buttons have
image-selector-btnclass
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/123is accessible
Debug Mode¶
Enable debug logging: