Media PDF Thumbnail
Genera imágenes en miniatura a partir de archivos PDF para entidades Media usando ImageMagick y las muestra como formateadores de campo.
media_pdf_thumbnail
Install
composer require 'drupal/media_pdf_thumbnail:^6.1'
Overview
El módulo Media PDF Thumbnail genera una imagen en miniatura a partir de archivos PDF y permite usarla como miniatura para entidades Media. Cuando una entidad Media contiene un archivo PDF, este módulo puede generar automáticamente una imagen de una página específica del PDF y mostrarla en lugar de la miniatura predeterminada.
El módulo utiliza ImageMagick (a través de la extensión Imagick de PHP) y la biblioteca spatie/pdf-to-image para realizar la conversión de PDF a imagen. Las imágenes generadas se almacenan en un tipo de entidad personalizado (pdf_image_entity) que rastrea la relación entre el PDF de origen y la imagen generada.
Las capacidades clave incluyen soporte para PDFs de múltiples páginas (seleccionando qué página usar), elección del formato de salida (JPG o PNG), rutas de destino configurables para las imágenes generadas, y generación de imágenes tanto síncrona como asíncrona (basada en cron). El módulo se integra con el sistema de tokens de Drupal para acceso programático y proporciona hooks para personalización.
Features
- Genera imágenes en miniatura a partir de archivos PDF usando ImageMagick y la biblioteca spatie/pdf-to-image
- Soporte para PDFs de múltiples páginas - especifica de qué página extraer la miniatura (por defecto es la página 1)
- Soporta formatos de imagen de salida JPG y PNG
- Formateador de campo (Media PDF Thumbnail Image) para el campo de miniatura de entidades Media
- Modos de generación de imágenes síncronos (en el momento) o asíncronos (cola de cron)
- Tipo de entidad personalizado (pdf_image_entity) para almacenar mapeos PDF-a-imagen con soporte de revisiones e idiomas
- Rutas de destino configurables para almacenamiento de archivos públicos y privados
- Integración con Views para gestionar entidades de imagen PDF con filtros y operaciones masivas
- Integración con el sistema de tokens para acceso programático a imágenes generadas y renderizados
- Control de acceso a archivos privados con permiso dedicado para ver miniaturas privadas
- Hooks alter para personalizar el renderizado de imágenes y rutas de destino
- Opciones de enlace de imagen: enlazar al contenido, enlazar al archivo de imagen generado o enlazar al archivo PDF original
- Configuración de atributos HTML para enlaces (download, target, rel)
- Operaciones por lotes para procesamiento de cola y purga de entidades
- Invalidación automática de cache cuando se generan las miniaturas
- Soporte para almacenamiento de archivos remotos (S3, etc.) con manejo automático de archivos temporales
Use Cases
Biblioteca de documentos con vistas previas de PDF
Crea un tipo de Media de biblioteca de documentos para almacenar documentos PDF. Configura el formateador Media PDF Thumbnail en el campo de miniatura para generar automáticamente imágenes de vista previa de la primera página de cada PDF subido. Los usuarios pueden ver vistas previas visuales de los documentos sin descargarlos, mejorando la experiencia de navegación.
Archivo de revistas o publicaciones
Para un archivo de revistas digitales, configura el formateador para extraer miniaturas de páginas específicas (ej., la portada). Enlaza la imagen de miniatura directamente al archivo PDF para descarga fácil. Usa el atributo 'download' para que al hacer clic se abra un diálogo de descarga en lugar de navegar fuera de la página.
Miniaturas de documentos multipágina
Para documentos multipágina donde la primera página es una portada, configura el formateador para usar la página 2 u otra página significativa para la miniatura. Esto asegura que la vista previa muestre contenido significativo en lugar de una página de título genérica.
Repositorio de documentos privados
Para documentos sensibles almacenados en el sistema de archivos privados, configura URIs de destino privadas para las miniaturas. Otorga el permiso 'ver miniaturas PDF privadas' solo a usuarios autenticados que deban acceder a los documentos. Las miniaturas permanecen protegidas junto con los PDFs de origen.
Procesamiento de PDF de alto volumen
Para sitios con muchas subidas de PDF, habilita la opción 'Usar cron' en el formateador. Esto encola la generación de miniaturas para procesamiento en segundo plano, previniendo cargas de página lentas durante la subida de media o visualización inicial. Monitorea la página de administración de cola para asegurar que el procesamiento se mantenga al día con las subidas.
Acceso programático a miniaturas vía tokens
Usa el sistema de tokens para acceder a miniaturas generadas en código personalizado, Views o Rules. Ejemplos: [media_pdf_thumbnail:field_media_file:1:jpg:image_uri] devuelve la URI del archivo, [media_pdf_thumbnail:field_media_file:1:jpg:render:medium] devuelve HTML renderizado con un estilo de imagen.
Tips
- Usa generación basada en cron para mejor rendimiento en sitios de alto tráfico - las miniaturas se generan en segundo plano
- Limpia los caches después de cambiar los ajustes del formateador para que los cambios surtan efecto en el contenido existente
- La función 'Limpiar' en /admin/media-pdf-thumbnail/settings/purge puede regenerar todas las miniaturas eliminando las entidades - las miniaturas se recrearán en la próxima visualización
- Para sitios multilingües, las miniaturas se generan por idioma y revisión
- Usa el sistema de tokens para acceso programático: [media_pdf_thumbnail:field_name:page:format:image_uri]
- Configura estilos de imagen en el formateador para tamaño consistente y reducir ancho de banda
- La opción 'Enlazar imagen a Archivo PDF' es conveniente para funcionalidad de descarga de documentos
Technical Details
Admin Pages 4
/admin/media-pdf-thumbnail/settings/list
Muestra una lista basada en Views de todas las entidades de imagen PDF creadas por el módulo. Esta tabla muestra la relación entre las entidades de origen y sus miniaturas generadas, incluyendo tipo de entidad, bundle, ID de entidad, ID de revisión, idioma, nombre del campo PDF, ID y URI del archivo PDF, número de página, ID y URI del archivo de imagen generado, formato de imagen y marca de tiempo. La vista incluye filtros expuestos para tipo de entidad, bundle, idioma, ID de entidad y fecha. Cada fila tiene enlaces de operación de eliminación para gestión individual de entidades.
/admin/media-pdf-thumbnail/settings/global
Configura los ajustes globales para la generación de miniaturas PDF, incluyendo rutas de destino personalizadas para las imágenes generadas.
/admin/media-pdf-thumbnail/settings/queue
Gestiona la cola de generación de imágenes PDF. Cuando se usa la generación basada en cron, las miniaturas se añaden a una cola y se procesan durante las ejecuciones de cron. Esta página permite ver el estado de la cola y activar manualmente el procesamiento.
/admin/media-pdf-thumbnail/settings/purge
Elimina todas las entidades de imagen PDF y sus archivos de imagen asociados. Esta es una operación destructiva que elimina todas las miniaturas generadas del sistema.
Permissions 8
Hooks 2
hook_media_pdf_thumbnail_image_render_alter
Permite a los módulos alterar el elemento de imagen de miniatura PDF renderizado antes de mostrarlo. Útil para modificar texto alternativo, título u otros atributos de imagen.
hook_media_pdf_thumbnail_image_destination_alter
Permite a los módulos alterar las rutas de origen y destino para la generación de imágenes PDF. Útil para personalizar dónde se almacenan las miniaturas.
Troubleshooting 6
Verifica que la extensión PHP Imagick esté instalada y habilitada. Confirma que ImageMagick está instalado en el servidor (versión 6.3.7+). Revisa los registros de Drupal en busca de mensajes de error del canal de registro 'Media PDF Thumbnail'. Asegúrate de que el directorio de destino sea escribible.
Asegúrate de que cron se ejecute regularmente. Revisa la página de administración de Cola en /admin/media-pdf-thumbnail/settings/queue. Usa el botón 'Ejecutar' para procesar manualmente la cola. Verifica que no estén ocurriendo errores durante el procesamiento revisando los registros.
Otorga el permiso 'ver miniaturas PDF privadas' a los roles de usuario apropiados. Verifica que el sistema de archivos privados esté correctamente configurado en los ajustes de Drupal.
El archivo PDF puede ser inválido, estar corrupto o la extensión Imagick no puede procesarlo. Comprueba que el campo de archivo realmente contenga un PDF (tipo MIME application/pdf). Revisa los registros de errores para errores específicos de ImageMagick.
La versión de ImageMagick debe ser 6.3.7 o superior. La biblioteca spatie/pdf-to-image debe ser versión 2.1.0 o superior. Ejecuta 'composer require spatie/pdf-to-image:^2.1.0' para actualizar si es necesario.
El módulo soporta almacenamiento remoto copiando PDFs a almacenamiento local temporal para procesamiento. Si ocurren problemas, verifica que el stream wrapper temporary:// esté correctamente configurado y tenga espacio suficiente.
Security Notes 4
- El permiso 'administer_media_pdf_thumbnail' solo debe otorgarse a administradores de confianza ya que permite purgar todos los datos de miniaturas
- El permiso 'ver miniaturas PDF privadas' controla el acceso a miniaturas generadas a partir de archivos privados - revísalo cuidadosamente antes de otorgarlo
- Las miniaturas generadas heredan la ubicación del sistema de archivos (público/privado) del PDF de origen a menos que se configuren URIs de destino personalizadas
- El módulo implementa hook_file_download() para aplicar verificaciones de permisos en miniaturas privadas