imce_field_widget
Project Summary
A clean media field widget with IMCE integration for single-value media fields, providing intuitive file selection with modal dialog and validation.
Features
The IMCE Field Widget provides a streamlined solution for media field selection by integrating the popular IMCE file browser directly into Drupal's media fields. This module is specifically designed for single-value media entity reference fields and offers several key features:
Core Functionality:
- IMCE Integration: Seamlessly integrates the IMCE file browser as a modal dialog for file selection
- Media Field Support: Works exclusively with single-value media entity reference fields
- Modal Interface: Clean, user-friendly modal dialog for file browsing and selection
- File Scheme Support: Configurable support for both public and private file schemes
Advanced Features:
- Required Field Validation: Proper validation for required fields with visual error indicators
- User Selection Preservation: Maintains user selections during form validation errors on other fields
- Accessibility: Full keyboard navigation and screen reader support
- Translation Ready: Complete translation support with included POT template
- Comprehensive Testing: Unit, kernel, and functional tests for reliability
Coming Features:
- Custom Formatters: Create new media formatters with IMCE integration
- Schema Extensions: Extend Drupal's schema for custom media field configurations
- Folder Specifications: Implement custom folder structures and organization within IMCE
- Enhanced Modal Styling: Customize IMCE CSS styles inside the modal for better UX
Use Cases:
- Content editors who prefer IMCE's familiar file browser interface
- Sites requiring consistent file selection across multiple content types
- Organizations that want to leverage IMCE's file management capabilities within media fields
- Projects needing single-value media fields with enhanced user experience
Post-Installation
After installing the module, configuration is straightforward:
- Enable the Module: The module will be available after installation
- Configure Media Fields: Go to Structure > Content types > [Your Content Type] > Fields
- Select Widget: Edit your media field and change the widget to "IMCE Field Widget"
- Configure Settings: Choose the file scheme (public/private) in the widget settings
- IMCE Setup: Ensure IMCE is properly configured for your chosen file scheme
The widget will automatically appear in your content forms once configured. Users will see a "Select Media" button that opens the IMCE file browser in a modal dialog. Selected files are immediately displayed with preview and removal options.
Special Considerations:
- Only works with single-value media fields (cardinality = 1)
- Requires proper IMCE configuration for file schemes
- Includes automatic error handling for invalid media references
Additional Requirements
This module requires the following Drupal modules and dependencies:
Required Modules:
- Drupal Core (9, 10, or 11)
- Media module (
drupal/media) - IMCE module (
drupal/imce) - File module (
drupal/file) - Image module (
drupal/image)
Technical Requirements:
- jQuery UI (for modal dialogs - included with Drupal core)
- PHP 7.4 or higher
- Proper file system permissions for IMCE
Recommended modules/libraries
While not required, these modules can enhance the functionality:
- IMCE Mkdir: Provides directory creation capabilities within IMCE
- IMCE File Manager: Enhanced file management features
- Media Library: Can be used alongside for different use cases
- File Entity: Provides additional file management capabilities
Similar projects
Several modules provide similar functionality, but IMCE Field Widget offers unique advantages:
- Media Library Widget: Drupal core's solution, but lacks IMCE's file browser interface
- Entity Browser: More complex, designed for multiple entity types
- Inline Entity Form: Focuses on inline editing rather than file selection
- Media Entity Browser: Similar to Entity Browser but media-specific
What sets IMCE Field Widget apart:
- Simplicity: Clean, focused solution for single-value media fields
- IMCE Integration: Leverages the familiar and powerful IMCE file browser
- User Experience: Modal interface with immediate preview and removal
- Validation: Robust required field validation with user selection preservation
- Performance: Lightweight implementation with minimal overhead
Supporting this Module
This module is developed as open-source software. If you find it useful, consider:
- Contributing code improvements or bug fixes
- Reporting issues and feature requests
- Writing documentation or tutorials
- Testing on different Drupal versions and configurations
Community Documentation
For additional resources and support:
- Demo Site: [Coming soon - will be available on DrupalPod]
- Video Tutorial: [YouTube walkthrough in development]
- Documentation: Comprehensive README included with the module
- Issue Queue: Available on the project page for bug reports and feature requests
The module includes extensive inline documentation and follows Drupal coding standards for easy maintenance and contribution.