PDF.js dla TYPO3

PDF.js osadza sprawdzony renderer PDF od Mozilli bezpośrednio w stronach TYPO3, lekkie rozwiązanie, gdy redaktorzy chcą pokazywać PDF-y w przeglądarce, bez przymusu pobierania i bez ciężkiego otoczenia flipbooka

Gdy odwiedzający klika PDF, przeglądarka albo otwiera go w nowej zakładce, pobiera lub przekazuje do zewnętrznego viewera. Żaden z tych wariantów nie jest zadowalający dla redaktorów, którzy chcą prezentować dokument w kontekście strony. PDF.js rozwiązuje to, wbudowując viewer, którego wewnętrznie używają Firefox i Chrome, jako samodzielny moduł JavaScript bezpośrednio w stronę TYPO3. Wynikiem jest spójna prezentacja na wszystkich przeglądarkach i urządzeniach, bez konieczności instalowania przez użytkowników pluginu lub opuszczania dokumentu.

Często pomijaną zaletą jest: użytkownik nie opuszcza strony. Podczas gdy otwarty PDF w nowej zakładce zazwyczaj oznacza koniec sesji, w przypadku wbudowanego viewera połączenie analityczne pozostaje zachowane. Kto mierzy, jak długo odwiedzający faktycznie oglądają dokument, może przypisać czas bezpośrednio stronie contentowej i zobaczyć, które dokumenty są rzeczywiście czytane.

Typowe scenariusze zastosowania

Najczęstszym zastosowaniem jest osadzanie pojedynczych dokumentów na stronach contentowych, na przykład whitepaper na stronie produktu, formularz wniosku na stronie serwisowej lub program wydarzenia obok opisu wydarzenia. Redakcja ładuje PDF do FAL i odwołuje się do niego przez element treści, PDF.js renderuje go inline. Przy tym zachowana jest stylistyka CI strony, bo ramki, cienie i elementy sterujące są stylizowane przez własny szablon sitepackage.

Drugim przypadkiem są centra pobrań, w których kilka PDF-ów jest prezentowanych przez podgląd. Zamiast ślepych ikon plików użytkownicy widzą pierwszą stronę dokumentu i jednym kliknięciem decydują, czy chcą czytać dalej czy rozpocząć pełne pobieranie. Dla katalogów, formularzy i ulotek informacyjnych ten podgląd jest często decydującym czynnikiem, dlaczego dokument jest w ogóle klikany.

Po trzecie: dostępne udostępnianie dokumentów urzędowych i akademickich. PDF.js udostępnia warstwę tekstową PDF, dzięki czemu screen-readery mogą odczytywać treść, pod warunkiem że PDF został poprawnie wyeksportowany jako “Tagged PDF”.

Architektura techniczna

Dla TYPO3 PDF.js istnieje w dwóch wariantach: jako klasyczne rozszerzenie TYPO3, które dostarcza bibliotekę JavaScript i dodaje element treści w backendzie, lub jako czysta integracja sitepackage, w której assety PDF.js lądują bezpośrednio we własnym frontendowym build. Wariant rozszerzenia jest bardziej komfortowy dla redaktorów, bo mogą konfigurować wybór, standardowy zoom i parametry podglądu przez backend TYPO3. Wariant sitepackage jest czystszy dla deweloperów, bo kontroluje wersję i integruje się w istniejący proces build.

Technicznie PDF.js składa się z dwóch części: parsera, który ładuje plik PDF i rozkłada go na wewnętrzny graf obiektów, oraz viewera, który renderuje te obiekty w elemencie Canvas. Obie części działają kompletnie po stronie klienta. Podejście worker zapewnia, że parsowanie odbywa się w oddzielnym wątku i nie blokuje main-thread, ważne dla płynnego scrollowania w obszernych dokumentach.

Integracja odbywa się przez blok TypoScript i partial Fluid, który osadza iframe lub kontener z viewerem. URL PDF jest przekazywany jako parametr query, konfiguracja elementów UI (przyciski zoom, nawigacja stron, link pobierania) odbywa się przez blok konfiguracji viewera PDF.js.

Częste problemy i rozwiązania

Pierwszym problemem jest Cross-Origin. Gdy PDF jest ładowany z innej domeny lub z S3, przeglądarka blokuje dostęp ze względów bezpieczeństwa. Rozwiązaniem jest albo prawidłowa konfiguracja CORS na serwerze plików, albo serwerowe proxy przez middleware TYPO3, które dostarcza PDF pod tą samą domeną.

Drugi problem: wydajność przy dużych dokumentach. 200-stronicowy podręcznik ładuje się szybko, viewer pokazuje również tylko widoczne strony. Problematyczne staje się, gdy sam PDF nie jest zoptymalizowany pod web i każdy pojedynczy obraz został osadzony w pełnej rozdzielczości druku. Pomaga tylko przeliczenie dokumentu źródłowego wcześniej za pomocą Ghostscript lub podobnego narzędzia, zanim trafi do FAL.

Trzeci problem: dostępność bez warstwy tekstowej. Gdy PDF jest czystym skanem bez OCR, screen-readery nie otrzymują tekstu. Wtedy sam PDF.js nic nie daje, PDF musi najpierw przejść przez OCR. Dla urzędów i instytucji publicznych to nie jest opcja, tylko obowiązek zgodnie z ustawą o dostępności cyfrowej i EN 301 549.

Migracja i kompatybilność wersji

PDF.js jako biblioteka jest ciągle utrzymywane przez Mozillę i jest zasadniczo niezależne od wersji TYPO3. Powłoki rozszerzeń TYPO3, które integrują PDF.js, często jednak opóźniają się za wersją biblioteki. Kto aktualizuje na TYPO3 v12 lub v13, powinien sprawdzić, czy używane rozszerzenie ma kompatybilną wersję lub czy przejście na integrację sitepackage jest lepszą drogą.

W bezpośrednim porównaniu do pdfviewhelpers (serwerowe generowanie PDF) i rflipbook (efekt flipbooka) PDF.js jest opcją z najmniejszym overhead i najwyższą kompatybilnością przeglądarek. Dla pojedynczych osadzeń PDF to prawie zawsze lepszy wybór niż ciężkie rozwiązanie flipbook.

Kto sam wbudowuje PDF.js w sitepackage, powinien ustalić jasną strategię wersji. Biblioteka otrzymuje regularne aktualizacje bezpieczeństwa, bo parsery PDF są historycznie popularnym celem ataków. Roczny rytm update to minimum, dla urzędów i krytycznej infrastruktury raczej kwartalny. Integracja przez npm i frontendowy proces build czyni to zdecydowanie prostszym niż klasyczne kopiowanie do katalogu projektu.

Gosign integruje PDF.js jako komponent sitepackage lub jako rozszerzenie TYPO3, w zależności od tego, ile kontroli potrzebują redaktorzy. Przy projektach istniejących z viewerami legacy Gosign towarzyszy migracji i dba o to, aby dostępność cyfrowa i czas ładowania nie były poświęcane na rzecz komfortu.