File Entity Browser
Proporciona una experiencia moderna y atractiva de biblioteca multimedia para Drupal utilizando diseño de cuadrícula Masonry y carga con DropzoneJS, construido sobre las APIs de Entity Browser y Entity Embed.
file_browser
Install
composer require 'drupal/file_browser:^2.0'
Overview
El módulo File Entity Browser proporciona una experiencia intuitiva de navegación de archivos para los editores de contenido de Drupal. Muestra los archivos en un diseño Masonry adaptable basado en cuadrícula, facilitando la navegación, carga y selección de imágenes y otros archivos.
El objetivo principal es recuperar la experiencia amigable de la biblioteca multimedia de Drupal 7 aprovechando las APIs modernas de Drupal, incluyendo Entity Browser y Entity Embed. El módulo integra DropzoneJS para la carga de archivos mediante arrastrar y soltar y utiliza Backbone.js para la selección inteligente de elementos con soporte de cardinalidad.
Proporciona navegadores de entidades preconfigurados que funcionan de forma inmediata tanto con modos de visualización iframe como modal, junto con estilos de imagen personalizados optimizados para la interfaz del navegador.
Features
- Diseño de cuadrícula Masonry adaptable para navegar archivos con detección automática de carga de imágenes
- Integración con DropzoneJS para carga de archivos mediante arrastrar y soltar con validación de tipos de archivo compatibles
- Entity Browsers preconfigurados con modos de visualización iframe (100% de ancho, 768px de alto) y modal (1100x650px)
- Selección inteligente de archivos con Backbone.js que soporta selección simple y múltiple según la cardinalidad del campo
- Plugin de campo Views personalizado para renderizar vistas previas de archivos con visualización de miniaturas
- Bloque Image Embed para colocar múltiples imágenes con soporte de texto alternativo y ordenación
- Widget de campo compatible con tipos de campo File e Image
- Modal de vista previa con selección de estilo de imagen para visualizar archivos en diferentes tamaños
- Visualización de selección multipaso mostrando miniaturas de los archivos seleccionados
- Integración con el módulo Libraries para gestión flexible de rutas de bibliotecas
- Submódulo de ejemplo que proporciona configuraciones listas para usar de tipo de contenido y tipo de bloque
Use Cases
Edición de contenido rico en multimedia
Los editores de contenido pueden navegar fácilmente por los archivos multimedia existentes y cargar nuevos a través de una interfaz visual basada en cuadrícula al crear o editar nodos. El diseño Masonry proporciona una experiencia de navegación moderna similar a Pinterest que se adapta desde dispositivos móviles hasta escritorio.
Incrustación de imágenes en el editor WYSIWYG
Usando la integración con Entity Embed, los editores pueden insertar imágenes directamente en las áreas de texto de CKEditor. El botón File Browser en la barra de herramientas del editor abre un navegador modal para seleccionar archivos, con soporte de vista previa para diferentes estilos de imagen.
Selección de campos de múltiples imágenes
Para campos que requieren múltiples imágenes (galerías, presentaciones), la interfaz de selección rastrea los elementos seleccionados con indicadores visuales, soporta ordenación mediante arrastre y aplica límites de cardinalidad con retroalimentación visual cuando se alcanza el límite.
Galerías de imágenes en bloques personalizados
Los constructores de sitios pueden usar el plugin de bloque Image Embed para crear bloques de galería de imágenes con estilos de imagen configurables, texto alternativo para accesibilidad y ordenación de imágenes mediante arrastrar y soltar.
Prototipado rápido con el módulo de ejemplo
Los desarrolladores pueden habilitar el submódulo File Browser Example para tener inmediatamente un tipo de contenido y un tipo de bloque funcionales con campos de File Browser configurados, útil para demostraciones o como punto de partida para implementaciones personalizadas.
Tips
- Use Composer con Wikimedia Composer Merge Plugin para la gestión automática de bibliotecas JavaScript incluyendo composer.libraries.json en la configuración de merge-plugin
- Habilite el submódulo File Browser Example para una demostración rápida de cómo configurar campos con File Browser
- Se recomienda la visualización modal (browse_files_modal) para la mayoría de los casos de uso ya que no requiere recarga de página y proporciona una experiencia de usuario más limpia
- Haga doble clic en un archivo en el navegador para seleccionarlo automáticamente y cerrar el navegador, útil para campos de selección única
- El campo de búsqueda en el navegador de archivos usa entrada con debounce (retraso de 600ms) para evitar filtrado excesivo durante la escritura
- Para bibliotecas de archivos grandes, considere personalizar la configuración del paginador de Views para equilibrar rendimiento con usabilidad
Technical Details
Admin Pages 1
/admin/file-browser-preview/{file}/{image_style}
Muestra una vista previa de un archivo en un diálogo modal. Para archivos de imagen, permite seleccionar diferentes estilos de imagen para previsualizar la imagen en varios tamaños. Los archivos que no son imágenes muestran un SVG de marcador de posición.
Hooks 4
hook_form_alter
Adjunta las bibliotecas y clases CSS de File Browser a los formularios de Entity Browser (formularios browse_files y browse_files_modal)
hook_preprocess_details
Adjunta la biblioteca CSS de iframe para campos de referencia de File Browser mostrados en elementos details
hook_library_info_alter
Se integra con el módulo Libraries para resolver dinámicamente las rutas de bibliotecas JavaScript para Backbone, Underscore, imagesLoaded y Masonry
hook_views_data_alter
Añade el campo personalizado file_browser_preview a la tabla file_managed para usar en Views
Troubleshooting 5
Asegúrese de que todas las bibliotecas JavaScript requeridas (Backbone, Underscore, imagesLoaded, Masonry) estén instaladas en el directorio /libraries con los nombres de carpeta correctos: /libraries/backbone/backbone-min.js, /libraries/underscore/underscore-min.js, /libraries/imagesloaded/imagesloaded.pkgd.min.js, /libraries/masonry/dist/masonry.pkgd.min.js
El widget File Browser solo aparece para campos que ya lo están usando (compatibilidad hacia atrás). Para nuevos campos, use el widget de Entity Browser y seleccione 'File Browser' o 'File Browser (Modal)' como Entity Browser.
Verifique la consola del navegador en busca de errores JavaScript. Asegúrese de que la biblioteca imagesLoaded esté correctamente instalada, ya que la inicialización de Masonry espera a que las imágenes se carguen antes de calcular el diseño de la cuadrícula.
Asegúrese de que el servidor web tenga permisos de escritura en el directorio de archivos public:// (típicamente sites/default/files). El módulo guarda un archivo de icono durante la instalación.
Verifique que Entity Browser y sus dependencias estén correctamente instalados. Compruebe que la configuración del Entity Browser browse_files_modal exista y que las bibliotecas JavaScript se carguen sin errores.
Security Notes 3
- El acceso a archivos se verifica usando el sistema de acceso a entidades de Drupal - los usuarios deben tener permiso 'view' en los archivos para ver las vistas previas
- El widget de carga respeta las restricciones de extensión de archivo configuradas (por defecto: jpg, jpeg, gif, png, txt, doc, xls, pdf, ppt, pps, odt, ods, odp)
- Los archivos cargados a través del navegador se guardan en public:// por defecto - asegúrese de que los archivos sensibles se carguen en private:// si es necesario personalizando la configuración del widget del Entity Browser