DropzoneJS
Integración de Drupal con la biblioteca DropzoneJS, proporcionando funcionalidad de carga de archivos mediante arrastrar y soltar con vista previa de imágenes.
dropzonejs
Install
composer require 'drupal/dropzonejs:8.x-2.11'
Overview
DropzoneJS es un módulo de Drupal que proporciona integración con la popular biblioteca JavaScript DropzoneJS, habilitando la funcionalidad moderna de carga de archivos mediante arrastrar y soltar en todo tu sitio Drupal. El módulo proporciona un elemento de formulario personalizado que puede usarse en cualquier lugar de Drupal donde se necesiten cargas de archivos.
El módulo reemplaza automáticamente el formulario de carga predeterminado en Media Library para fuentes de medios de imagen, video, audio y archivo, proporcionando una experiencia fluida de arrastrar y soltar. Soporta cargas de múltiples archivos, validación de tamaño de archivo, filtrado de extensiones de archivo permitidas, y muestra el progreso de carga con vista previa de imágenes.
Las características adicionales incluyen redimensionamiento opcional de imágenes del lado del cliente antes de la carga (usando la biblioteca exif-js), transliteración y saneamiento de nombres de archivo por seguridad, y cargas fragmentadas para archivos grandes. El módulo también proporciona un submódulo para integración con Entity Browser, permitiendo que el cargador DropzoneJS se use dentro de widgets de Entity Browser para seleccionar y cargar archivos o entidades de medios.
Features
- Interfaz de carga de archivos mediante arrastrar y soltar con retroalimentación visual e indicadores de progreso
- Integración automática con Media Library de Drupal para tipos de medios de imagen, video, audio y archivo
- Elemento de formulario 'dropzonejs' personalizado que puede usarse en cualquier formulario de Drupal
- Redimensionamiento de imágenes del lado del cliente antes de la carga (opcional, requiere la biblioteca exif-js)
- Configuración de carga configurable incluyendo tamaño máximo de archivo, extensiones permitidas y número máximo de archivos
- Saneamiento y transliteración de nombres de archivo para archivos cargados para garantizar la seguridad
- Eliminar archivos cargados antes del envío del formulario con iconos visuales de eliminación
- Protección CSRF en el endpoint de carga por seguridad
- Soporte para versiones 5 y 6 de la biblioteca Dropzone
- Sistema de eventos que permite a otros módulos reaccionar a la creación de entidades de medios durante las cargas
Use Cases
Cargas de archivos en Media Library
Los constructores de sitios quieren proporcionar a los editores de contenido una experiencia intuitiva de carga de archivos mediante arrastrar y soltar en Media Library. Después de instalar DropzoneJS, los editores pueden simplemente arrastrar archivos al área de carga en lugar de navegar a través de diálogos del explorador de archivos. Se pueden soltar múltiples archivos a la vez, y el progreso de carga se muestra en tiempo real.
Cargas de archivos en formularios personalizados
Los desarrolladores que construyen formularios personalizados pueden usar el tipo de elemento de formulario 'dropzonejs' para agregar cargas de archivos mediante arrastrar y soltar. Configura propiedades como #max_filesize, #extensions y #max_files para controlar el comportamiento de carga. El elemento devuelve un array de rutas de archivos temporales que pueden procesarse en el manejador de envío del formulario.
Selección de medios en Entity Browser
Los sitios que usan Entity Browser para selección de medios pueden habilitar el submódulo dropzonejs_eb_widget para proporcionar widgets de carga potenciados por DropzoneJS. Elige entre cargas básicas de archivos, creación automática de entidades de medios, o creación de entidades de medios con edición en línea para población inmediata de campos.
Optimización de imágenes del lado del cliente
Para reducir el ancho de banda del servidor y acelerar las cargas, instala la biblioteca exif-js y habilita el redimensionamiento del lado del cliente en tu elemento DropzoneJS. Las imágenes se redimensionan en el navegador antes de la carga, manteniendo la orientación correcta desde los datos EXIF. Configura el ancho máximo, altura, calidad y método de redimensionamiento.
Cargas de imágenes de alto volumen
Los sitios de fotografía o galerías necesitan cargar muchas imágenes rápidamente. DropzoneJS permite arrastrar carpetas enteras de imágenes, muestra miniaturas como vistas previas, y procesa las cargas en paralelo. La función de auto-selección en widgets de Entity Browser puede guardar y seleccionar archivos automáticamente a medida que terminan de cargarse.
Tips
- Otorga el permiso 'Dropzone upload files' a usuarios autenticados o roles específicos que necesiten usar la funcionalidad de carga
- Usa reemplazos de token en la configuración upload_location (ej., public://[date:custom:Y]-[date:custom:m]) para organizar archivos por fecha
- Para el submódulo Entity Browser, habilita 'Heredar configuración del tipo de medio' para usar automáticamente la configuración del campo de archivo para tamaño máximo y extensiones permitidas
- El elemento dropzone soporta #max_files establecido en 0 para cargas de archivos ilimitadas, o un entero positivo para limitar las cargas
- Considera habilitar el redimensionamiento del lado del cliente para cargas de imágenes para reducir el uso de ancho de banda y mejorar la velocidad de carga para imágenes grandes
Technical Details
Permissions 1
Hooks 1
hook_media_source_info_alter
Usado internamente por el módulo para reemplazar el formulario de agregar de media library predeterminado con la versión DropzoneJS para fuentes de medios de imagen, video_file, audio_file y archivo.
Troubleshooting 5
Asegúrate de que la biblioteca DropzoneJS esté instalada en la carpeta libraries/dropzone. El módulo busca dropzone-min.js o dropzone.min.js en varias ubicaciones posibles. Descarga el archivo dist.zip de la biblioteca desde GitHub y extráelo correctamente.
Verifica que el usuario tenga el permiso 'Dropzone upload files'. Sin este permiso, el elemento dropzone no será accesible y las cargas fallarán silenciosamente.
Instala la biblioteca exif-js en libraries/exif-js/exif.js. La biblioteca es requerida para la funcionalidad de redimensionamiento del lado del cliente. Sin ella, la opción clientside_resize estará deshabilitada en la configuración del widget.
Verifica la configuración de PHP para upload_max_filesize y post_max_size. El módulo respeta estos límites. También verifica la configuración upload_timeout_ms si las cargas están expirando.
El módulo sanea los nombres de archivo por seguridad. Si usas Drupal 10.2+, configura el saneamiento de nombres de archivo en la configuración del núcleo. La configuración heredada filename_transliteration está obsoleta y se eliminará en una versión futura.
Security Notes 5
- Todas las cargas requieren validación de token CSRF para protección contra ataques de falsificación de solicitudes entre sitios
- Las extensiones de archivo ejecutables (php, pl, py, cgi, asp, js) se renombran automáticamente con extensión .txt para prevenir la ejecución de código
- Los archivos se cargan inicialmente con una extensión .txt agregada por seguridad, que se elimina solo después de la validación
- El endpoint de carga requiere el permiso 'dropzone upload files', asegurando que solo usuarios autorizados puedan cargar archivos
- La validación de archivos incluye verificación de extensión, límites de tamaño de archivo y validación de longitud de nombre de archivo