PDF.js para TYPO3

PDF.js incrusta el visor probado de Mozilla directamente en páginas TYPO3 y es la solución ligera cuando los redactores quieren mostrar PDF en el navegador sin forzar la descarga y sin el peso de un flipbook

Cuando los visitantes hacen clic en un PDF, el navegador lo abre en una pestaña nueva, lo descarga o lo deriva a un visor externo. Ninguna de esas variantes satisface a los redactores que quieren presentar un documento en el contexto de una página. PDF.js lo resuelve integrando el visor que Firefox y Chrome utilizan internamente como un módulo JavaScript autónomo directamente en la página TYPO3. El resultado es una visualización consistente en todos los navegadores y dispositivos, sin que los usuarios tengan que instalar un plugin ni abandonar el documento.

Una ventaja pasada a menudo por alto: el usuario no deja la página. Mientras que un PDF abierto en una nueva pestaña suele significar el fin de la sesión, el visor incrustado mantiene la conexión analítica. Quien mide cuánto tiempo pasan los visitantes realmente leyendo un documento puede atribuir ese tiempo directamente a la página de contenido y ver qué documentos se leen de verdad.

Escenarios típicos de uso

El caso de uso más frecuente es la incrustación de documentos individuales en páginas de contenido: un white paper en una página de producto, un formulario de solicitud en una página de servicio o un programa de jornada junto a la descripción del evento. La redacción sube el PDF al FAL y lo referencia mediante un elemento de contenido; PDF.js lo renderiza inline. Al hacerlo, la identidad visual de la página se mantiene, porque marcos, sombras y controles se estilizan mediante la plantilla del sitepackage propio.

El segundo caso son los centros de descargas donde varios PDF se presentan mediante una vista previa. En lugar de iconos ciegos de archivo, los usuarios ven la primera página del documento y pueden decidir con un clic si siguen leyendo o inician la descarga completa. Para catálogos, formularios y fichas informativas, esa vista previa es a menudo el factor decisivo para que un documento llegue siquiera a ser pulsado.

Tercer caso: la puesta a disposición con baja barrera de documentos de administraciones e universidades. PDF.js expone la capa de texto del PDF, de modo que los lectores de pantalla pueden leer el contenido, siempre que el PDF se haya exportado correctamente como “Tagged PDF”.

Arquitectura técnica

Para TYPO3 PDF.js existe en dos variantes: como extensión TYPO3 clásica que entrega la librería JavaScript y amplía el backend con un elemento de contenido, o como integración puramente de sitepackage, en la que los assets de PDF.js acaban directamente en el build del frontend propio. La variante extensión es más cómoda para los redactores, porque pueden configurar selección, zoom por defecto y parámetros de vista previa mediante el backend de TYPO3. La variante sitepackage es más limpia para los desarrolladores, porque controla la versión y se integra en el proceso de build existente.

Técnicamente PDF.js consta de dos partes: un parser que carga el archivo PDF y lo descompone en un grafo de objetos interno, y un viewer que renderiza esos objetos en un elemento Canvas. Ambas partes corren completamente del lado del cliente. El enfoque worker garantiza que el parseo ocurra en un hilo aparte y no bloquee el main thread, lo que es importante para un scroll fluido en documentos extensos.

La integración se realiza mediante un bloque TypoScript y un partial Fluid que incluye un iframe o un contenedor con el viewer. La URL del PDF se pasa como query parameter; la configuración de los elementos de interfaz (botones de zoom, navegación de páginas, enlace de descarga) se realiza mediante el bloque de configuración del viewer de PDF.js.

Problemas frecuentes y soluciones

El primer problema es Cross-Origin. Cuando el PDF se carga desde otro dominio o desde un bucket S3, el navegador bloquea el acceso por motivos de seguridad. La solución es o bien una configuración CORS correcta en el file server o bien un proxy del lado del servidor mediante una middleware TYPO3 que entregue el PDF bajo el mismo dominio.

Segundo problema: rendimiento con documentos grandes. Un manual de 200 páginas carga rápido, el viewer solo muestra las páginas visibles. Se vuelve problemático cuando el propio PDF no está optimizado para la web y cada imagen se ha incrustado en plena resolución de impresión. Aquí solo ayuda reducir el documento original previamente con Ghostscript o una herramienta equivalente antes de que entre al FAL.

Tercer problema: accesibilidad sin capa de texto. Si el PDF es un escaneo puro sin OCR, los lectores de pantalla no reciben texto. Entonces PDF.js por sí solo no sirve de nada: el PDF debe pasar antes por una pasada de OCR. Para administraciones y organismos públicos eso no es una opción, sino una obligación según el Real Decreto 1112/2018 sobre accesibilidad web y la EN 301 549.

Migración y compatibilidad de versiones

PDF.js como librería la mantiene Mozilla de forma continua y es en principio independiente de la versión de TYPO3. Las envolturas de extensión TYPO3 que integran PDF.js van a menudo por detrás de la versión de la librería. Quien actualiza a TYPO3 v12 o v13 debería comprobar si la extensión utilizada tiene una versión compatible o si un cambio a la integración en el sitepackage es el mejor camino.

En comparación directa con pdfviewhelpers (generación de PDF en el servidor) y rflipbook (efecto flipbook), PDF.js es la opción con menor sobrecarga y mayor compatibilidad entre navegadores. Para incrustaciones individuales de PDF casi siempre es mejor elección que una solución flipbook pesada.

Quien integra PDF.js directamente en el sitepackage debería fijar una estrategia de versiones clara. La librería recibe actualizaciones de seguridad periódicas, porque los parsers PDF son históricamente un objetivo de ataque muy habitual. Un ritmo anual de actualización es el mínimo; para administraciones e infraestructuras críticas, más bien trimestral. La integración vía npm y un proceso de build de frontend lo hace mucho más fácil que la clásica copia al directorio del proyecto.

Gosign integra PDF.js como componente del sitepackage o como extensión TYPO3, según cuánta control necesiten los redactores. En proyectos existentes con visores legacy, Gosign acompaña la migración y se asegura de que la accesibilidad y el tiempo de carga no se sacrifiquen al confort.