Media Alias Display
Allows direct viewing of files via media URL aliases instead of rendering the full media entity page.
media_alias_display
Install
composer require 'drupal/media_alias_display:^2.1'
composer require 'drupal/media_alias_display:^1.0'
Overview
Media Alias Display is a module that transforms how media entities are accessed via their URLs. Instead of displaying the standard media entity page with all its fields, this module serves the actual file directly when visiting a media alias URL.
This functionality is particularly useful for organizations that need clean, readable URLs for documents like PDFs, images, or other downloadable files. For example, instead of users seeing the media entity wrapper, they can directly view or download the file using a friendly URL like /annual-report-2024 instead of /sites/default/files/annual-report-2024.pdf.
A key benefit is that when a media entity is referenced in multiple locations across your site, updating the file in one place automatically updates it everywhere. The URL alias remains consistent while the underlying file can be changed as needed.
Features
- Displays files directly via media alias URLs instead of rendering the full media entity page
- Works with both current media revisions and specific revision URLs
- Supports quick navigation to media edit page by appending ?edit-media to the URL (requires edit permissions)
- Forces file download instead of inline display by appending ?download or ?dl query parameter
- Provides a kill switch setting to completely disable the module functionality
- Allows limiting functionality to specific media bundles
- Handles both public and private file systems correctly
- Includes comprehensive caching with proper cache contexts and tags
- Logs notices when media items lack file sources or files don't exist on disk
- Includes submodule for per-entity override of the display behavior
Use Cases
Document Library with Clean URLs
Create a document library where PDFs, Word documents, and other files are accessible via friendly URLs like /policies/privacy-policy or /forms/application-form. Users can share these clean URLs, and when the document needs updating, simply replace the file in the media entity - the URL remains the same.
Image Gallery Direct Access
Allow direct access to high-resolution images via URL aliases. Visitors can bookmark or share image URLs directly without seeing the media entity wrapper page.
Forced Downloads for Sensitive Documents
Use the ?download or ?dl query parameter to force browsers to download files instead of displaying them inline. Useful for forms that users need to print or documents that shouldn't be viewed in-browser.
Quick Admin Access to Edit Media
Content editors can quickly navigate to edit a media item by appending ?edit-media to the URL. This is especially useful when viewing a file and needing to make immediate updates without navigating through the admin interface.
Selective Bundle Configuration
Enable direct file display only for specific media types like Documents while keeping Image or Video media types rendering as full entity pages with thumbnails and metadata.
Emergency Disable Switch
Use the kill switch feature to quickly disable the module's functionality without uninstalling it. Useful for troubleshooting or temporarily reverting to standard media entity display.
Per-Entity Override for Featured Content
Using the Field Override submodule, mark specific media entities to display as full entity pages. Useful when certain featured documents need additional context, related content, or metadata displayed alongside the file.
Tips
- Use Pathauto to automatically generate clean URL aliases for media entities based on their names or other fields
- Append ?edit-media to any media alias URL to quickly jump to the media edit form (requires edit permissions)
- Use ?download or ?dl query parameters to force file downloads instead of inline display
- The module works with both public and private file systems, automatically setting appropriate cache headers
- When the Field Override submodule is enabled, you can selectively disable alias display on specific media entities
- Cache is properly invalidated when configuration changes, but clear caches manually if you notice stale behavior
Technical Details
Admin Pages 1
/admin/config/media/media_alias_display
Configure which media bundles should display files directly via their URL aliases, and control the module's overall functionality with the kill switch option.
Troubleshooting 5
Verify that 'Standalone media URL' is enabled at /admin/config/media/media-settings. Check the Status Report page for any warnings. Ensure the kill switch is not enabled at /admin/config/media/media_alias_display.
Check the bundle settings at /admin/config/media/media_alias_display. If specific bundles are selected, only those will use the alias display feature. Clear all selections to enable for all bundles.
The module automatically handles private files with appropriate Cache-Control headers. Ensure your private file system is configured correctly in Drupal's settings.
This feature requires the user to have appropriate edit permissions for the media bundle - either 'edit own [bundle] media', 'edit any [bundle] media', or 'administer media'.
Append ?download or ?dl to the URL to force the browser to download the file instead of displaying it inline.
Security Notes 4
- The module respects Drupal's access control system - files are only served for accessible media entities
- Private files are served with private Cache-Control headers to prevent unauthorized caching
- The ?edit-media redirect only works for users with appropriate media edit permissions
- No new permissions are added by this module - it relies on existing media and site configuration permissions