PDF.js für TYPO3

PDF.js bettet Mozillas erprobten PDF-Renderer direkt in TYPO3-Seiten ein - die leichtgewichtige Lösung, wenn Redakteure PDFs im Browser zeigen wollen, ohne Download-Zwang und ohne schweres Flipbook-Drumherum

Wenn Besucher ein PDF anklicken, öffnet der Browser es entweder in einem neuen Tab, lädt es herunter oder zeigt ihn an einen externen Viewer weiter. Keine dieser Varianten ist für Redakteure befriedigend, die ein Dokument im Kontext einer Seite präsentieren wollen. PDF.js löst das, indem der Viewer, den Firefox und Chrome intern nutzen, als eigenständiges JavaScript-Modul direkt in die TYPO3-Seite eingebunden wird. Das Ergebnis ist eine konsistente Darstellung auf allen Browsern und Geräten, ohne dass Nutzer ein Plugin installieren oder das Dokument verlassen müssen.

Ein oft übersehener Vorteil: Der Nutzer verlässt die Seite nicht. Während ein geöffnetes PDF im neuen Tab in der Regel das Ende der Session bedeutet, bleibt die Analytics-Verbindung beim eingebetteten Viewer bestehen. Wer misst, wie lange Besucher sich ein Dokument tatsächlich ansehen, kann die Zeit direkt der Content-Seite zurechnen und sieht, welche Dokumente wirklich gelesen werden.

Typische Einsatzszenarien

Der häufigste Anwendungsfall ist die Einbettung einzelner Dokumente auf Content-Seiten - etwa ein Whitepaper auf einer Produktseite, ein Antragsformular auf einer Service-Seite oder ein Veranstaltungsprogramm neben der Event-Beschreibung. Die Redaktion lädt das PDF in FAL hoch und referenziert es über ein Content-Element, PDF.js rendert es inline. Dabei bleibt das gestalterische CI der Seite erhalten, weil Rahmen, Schatten und Steuerelemente über das eigene Sitepackage-Template gestylt werden.

Der zweite Fall sind Download-Zentren, in denen mehrere PDFs über eine Vorschau präsentiert werden. Statt blinder Datei-Icons sehen Nutzer die erste Seite des Dokuments und können mit einem Klick entscheiden, ob sie weiterlesen oder den vollständigen Download starten. Für Kataloge, Formulare und Merkblätter ist diese Vorschau oft der entscheidende Faktor, warum ein Dokument überhaupt angeklickt wird.

Drittens: barrierearme Bereitstellung von Behörden- und Hochschul-Dokumenten. PDF.js stellt den Textlayer des PDFs zur Verfügung, sodass Screenreader den Inhalt vorlesen können, sofern das PDF korrekt als “Tagged PDF” exportiert wurde.

Technische Architektur

Für TYPO3 existiert PDF.js in zwei Ausprägungen: als klassische TYPO3-Extension, die die JavaScript-Library ausliefert und ein Content-Element im Backend ergänzt, oder als reine Sitepackage-Integration, bei der die PDF.js-Assets direkt im eigenen Frontend-Build landen. Die Extension-Variante ist für Redakteure komfortabler, weil sie Auswahl, Standard-Zoom und Vorschau-Parameter über das TYPO3-Backend konfigurieren können. Die Sitepackage-Variante ist für Entwickler sauberer, weil sie die Version kontrolliert und in den bestehenden Build-Prozess integriert.

Technisch besteht PDF.js aus zwei Teilen: einem Parser, der die PDF-Datei lädt und in einen internen Objektgraphen zerlegt, und einem Viewer, der diese Objekte in einem Canvas-Element rendert. Beide Teile laufen komplett clientseitig. Der Worker-Ansatz sorgt dafür, dass das Parsen in einem separaten Thread passiert und den Main-Thread nicht blockiert - wichtig für flüssiges Scrollen in umfangreichen Dokumenten.

Die Integration erfolgt über einen TypoScript-Block und ein Fluid-Partial, das ein iframe oder einen Container mit dem Viewer einbindet. Die URL des PDFs wird als Query-Parameter übergeben, die Konfiguration der UI-Elemente (Zoom-Buttons, Seiten-Navigation, Download-Link) erfolgt über den Viewer-Konfigurationsblock von PDF.js.

Häufige Probleme und Lösungen

Das erste Problem ist Cross-Origin. Wenn das PDF von einer anderen Domain oder einem S3-Bucket geladen wird, blockt der Browser aus Sicherheitsgründen den Zugriff. Die Lösung ist entweder eine korrekte CORS-Konfiguration auf dem File-Server oder ein serverseitiger Proxy über eine TYPO3-Middleware, die das PDF unter derselben Domain ausliefert.

Zweites Problem: Performance bei großen Dokumenten. Ein 200-seitiges Handbuch lädt schnell - der Viewer zeigt auch nur die sichtbaren Seiten. Problematisch wird es, wenn das PDF selbst nicht für das Web optimiert ist und jedes einzelne Bild in voller Druckauflösung eingebettet wurde. Hier hilft nur, das Quelldokument vorab mit Ghostscript oder einem vergleichbaren Tool herunterzurechnen, bevor es ins FAL geht.

Drittes Problem: Barrierefreiheit ohne Textlayer. Wenn das PDF ein reiner Scan ohne OCR ist, bekommen Screenreader keinen Text. Dann bringt PDF.js allein nichts - das PDF muss vorher durch einen OCR-Durchlauf. Für Behörden und öffentliche Stellen ist das keine Option, sondern eine Pflicht nach BITV 2.0 und EN 301 549.

Migration und Versions-Kompatibilität

PDF.js als Library wird kontinuierlich von Mozilla gepflegt und ist grundsätzlich unabhängig von der TYPO3-Version. Die TYPO3-Extension-Hüllen, die PDF.js integrieren, hinken der Library-Version jedoch häufig hinterher. Wer auf TYPO3 v12 oder v13 aktualisiert, sollte prüfen, ob die verwendete Extension eine kompatible Version hat oder ob ein Umstieg auf die Sitepackage-Integration der bessere Weg ist.

Im direkten Vergleich zu pdfviewhelpers (serverseitige PDF-Generierung) und rflipbook (Flipbook-Effekt) ist PDF.js die Option mit dem geringsten Overhead und der höchsten Browser-Kompatibilität. Für einzelne PDF-Einbettungen ist es fast immer die bessere Wahl als eine schwere Flipbook-Lösung.

Wer PDF.js selbst im Sitepackage einbaut, sollte eine klare Versions-Strategie festlegen. Die Library erhält regelmäßige Sicherheits-Updates, weil PDF-Parser ein historisch beliebtes Angriffsziel sind. Ein jährlicher Update-Rhythmus ist das Minimum, für Behörden und kritische Infrastrukturen eher quartalsweise. Die Integration über npm und einen Frontend-Build-Prozess macht das wesentlich einfacher als die klassische Kopie ins Projektverzeichnis.

Gosign integriert PDF.js als Sitepackage-Komponente oder als TYPO3-Extension, je nachdem, wie viel Kontrolle Redakteure brauchen. Bei Bestandsprojekten mit Legacy-Viewern begleitet Gosign die Migration und sorgt dafür, dass Barrierefreiheit und Ladezeit nicht dem Komfort geopfert werden.