Media Entity File Replace
Permite a los editores de contenido reemplazar archivos de origen asociados con entidades de medios basadas en archivos, preservando el nombre de archivo y la ruta originales.
media_entity_file_replace
Install
composer require 'drupal/media_entity_file_replace:8.x-1.3'
composer require 'drupal/media_entity_file_replace:8.x-1.2'
composer require 'drupal/media_entity_file_replace:8.x-1.0'
Overview
Media Entity File Replace proporciona un flujo de trabajo optimizado para editores de contenido que necesitan actualizar archivos adjuntos a entidades de medios sin cambiar las URL ni romper enlaces existentes. Cuando un documento, imagen, archivo de audio u otro medio basado en archivos necesita actualizarse, este módulo permite que el nuevo archivo sobrescriba completamente el existente, manteniendo el mismo nombre de archivo y ruta en el sistema de archivos.
Esto es particularmente valioso en escenarios donde los archivos se han compartido mediante enlaces directos, incrustados en correos electrónicos o referenciados en materiales impresos. En lugar de subir un nuevo archivo (lo que crearía una nueva URL), los editores pueden reemplazar el contenido del archivo manteniendo todo lo demás intacto.
El módulo añade un widget de formulario "Replace file" a los formularios de edición de medios, que puede habilitarse por tipo de medio a través de la configuración de visualización del formulario. Maneja de forma inteligente las traducciones de contenido, evitando sobrescrituras accidentales de archivos compartidos entre versiones de idiomas.
Features
- Añade un widget 'Replace file' a los formularios de edición de entidades de medios para tipos de medios basados en archivos (Document, Image, Audio, Video, etc.)
- Dos modos de reemplazo: sobrescribir el archivo original (preserva nombre de archivo y ruta) o usar el nombre del archivo de reemplazo (crea una nueva referencia de archivo)
- Exige la misma extensión de archivo al sobrescribir para asegurar el manejo adecuado del tipo MIME por los servidores web
- Limpia automáticamente los derivados de estilos de imagen cuando se reemplazan archivos de imagen, asegurando que las miniaturas e imágenes estilizadas se regeneren
- Maneja inteligentemente las traducciones de contenido - evita que el widget de reemplazo aparezca cuando afectaría al archivo del idioma predeterminado
- Hereda los validadores de carga del campo de origen (límites de tamaño de archivo, extensiones permitidas) y los muestra a los usuarios
- Oculta los botones 'Remove' y 'Upload' en el widget de archivo estándar cuando el widget de reemplazo está habilitado, evitando flujos de trabajo conflictivos
- Valida que los archivos de reemplazo cumplan todos los requisitos originales del campo antes de procesarlos
- Mantiene el seguimiento adecuado del uso de archivos - los archivos antiguos referenciados solo por revisiones anteriores se marcan automáticamente para limpieza
Use Cases
Actualizar un documento PDF preservando los enlaces compartidos
Una empresa tiene un PDF de catálogo de productos que se ha compartido por correo electrónico y enlazado desde múltiples páginas web. Cuando una nueva versión del catálogo está lista, el editor de contenido puede usar el widget Replace file para subir el nuevo PDF. Al marcar 'Overwrite original file', el nuevo contenido reemplaza el archivo antiguo manteniendo exactamente la misma URL, por lo que todos los enlaces existentes continúan funcionando y los visitantes obtienen automáticamente el documento actualizado.
Actualizar imágenes de productos sin romper la caché
Un sitio de comercio electrónico necesita actualizar las fotos de productos. Usando la función de reemplazo de archivos con 'Overwrite original file' marcado, los editores pueden reemplazar imágenes manteniendo la misma ruta de archivo. El módulo limpia automáticamente los derivados de estilos de imagen, asegurando que las miniaturas y otras versiones estilizadas se regeneren con el nuevo contenido de imagen.
Cambiar un documento a un archivo completamente nuevo
Cuando un documento se está reemplazando con algo completamente diferente (p. ej., reemplazar un borrador con una versión final que tiene un nombre de archivo diferente), desmarque la opción 'Overwrite original file'. Esto sube el reemplazo como un archivo nuevo, actualiza la entidad de medios para referenciarlo y permite que el archivo antiguo se limpie si ningún otro contenido lo referencia.
Gestionar medios traducidos con archivos separados por idioma
Para un sitio multilingüe donde las traducciones de documentos se almacenan como archivos separados, el módulo maneja los reemplazos de forma inteligente. Cuando una entidad de medios tiene traducciones con diferentes archivos, los editores pueden reemplazar de forma segura el archivo de un idioma sin afectar otras traducciones. El módulo evita que el widget de reemplazo aparezca cuando usarlo modificaría accidentalmente el archivo del idioma predeterminado.
Tips
- Coloque el widget 'Replace file' directamente debajo del widget estándar File o Image en la visualización del formulario para un flujo de edición intuitivo
- Al sobrescribir el archivo original, el reemplazo debe tener la misma extensión de archivo (p. ej., no puede reemplazar un .pdf con un .docx)
- El módulo respeta todos los validadores de carga del campo original, incluyendo límites de tamaño de archivo y extensiones permitidas
- Si necesita cambiar tipos de archivo, desmarque 'Overwrite original file' para subir como un archivo nuevo en su lugar
- Para medios de imagen, los derivados de estilos de imagen se limpian automáticamente cuando se reemplazan archivos, por lo que la regeneración ocurre en la siguiente solicitud
- El widget de reemplazo solo aparece al editar medios existentes - está oculto en el formulario 'Add media' ya que no hay nada que reemplazar todavía
- Si el archivo de origen se ha eliminado del sistema de archivos, el widget de reemplazo no aparecerá hasta que se vuelva a adjuntar un archivo
Technical Details
Admin Pages 1
/admin/structure/media/manage/{media_type}/form-display
Configura la visualización del formulario para un tipo de medio para habilitar o deshabilitar el widget de reemplazo de archivos. El pseudo-campo 'Replace file' aparece en la lista de componentes de formulario disponibles para tipos de medios basados en archivos (aquellos que usan plugins de origen File, Image, Audio o Video). Arrástrelo desde la sección 'Disabled' al área principal del formulario para habilitar la funcionalidad de reemplazo de archivos para ese tipo de medio.
Hooks 3
hook_help
Proporciona texto de ayuda para la página de ayuda del módulo, explicando cómo habilitar y usar la función de reemplazo de archivos.
hook_entity_extra_field_info
Declara el pseudo-campo 'replace_file' para las visualizaciones de formularios en todos los tipos de medios basados en archivos. Este pseudo-campo permite a los constructores de sitios habilitar o deshabilitar el widget de reemplazo de archivos a través de la interfaz estándar de configuración de visualización de formularios.
hook_form_BASE_FORM_ID_alter (media_form)
Modifica el formulario de edición de entidades de medios para añadir el widget de reemplazo de archivos cuando está configurado. Añade un fieldset que contiene un campo de carga de archivos y una casilla de verificación para controlar el comportamiento del reemplazo. También añade manejadores personalizados de validación y envío, y oculta los botones Remove/Upload del widget de archivo estándar.
Troubleshooting 5
Asegúrese de haber habilitado el widget en la configuración de visualización del formulario. Vaya a Administration > Structure > Media types > [Su tipo de medio] > Manage form display, y arrastre 'Replace file' desde la sección Disabled a la región Content.
Este es el comportamiento esperado. El módulo solo añade el widget de reemplazo para tipos de medios basados en archivos (aquellos que usan plugins de origen File, Image, Audio o Document). Remote Video usa una fuente oEmbed que no tiene un archivo para reemplazar.
Al sobrescribir el archivo original, el reemplazo debe tener la misma extensión para asegurar que los servidores web sirvan el tipo MIME correcto. Desmarque 'Overwrite original file' para subir un archivo con una extensión diferente.
Esto es intencional cuando la traducción usa el mismo archivo que el idioma predeterminado. Mostrar el widget arriesgaría reemplazar el archivo para todos los idiomas. Primero suba un archivo diferente para la traducción, luego aparecerá el widget de reemplazo.
Al usar 'Overwrite original file', se mantiene la misma entidad de archivo y se reemplaza su contenido. Cuando no se sobrescribe, el archivo antiguo permanece si otras revisiones aún lo referencian. Los archivos solo se eliminan por Cron cuando nada los referencia.
Security Notes 3
- El módulo depende de los permisos de medios existentes de Drupal - los usuarios necesitan 'administer media' o los permisos apropiados de edición de tipo de medio para acceder a la funcionalidad de reemplazo
- Los validadores de carga de archivos del campo de origen se aplican, evitando la carga de tipos de archivo no permitidos
- El módulo no introduce ningún permiso nuevo - el acceso se controla mediante el acceso estándar a entidades de medios