dreipc_pdf dla TYPO3

Gdy odwiedzający chcą pobrać strony TYPO3 jako PDF, wynik potrzebuje własnego układu

Odwiedzający klikają “Zapisz jako PDF” i oczekują schludnego dokumentu: identyfikacja wizualna firmy, logo, numery stron, bez nawigacji. To, co dostarcza funkcja drukowania przeglądarki, jest przeciwieństwem: obcięte kolumny, zbędne nagłówki i stopki, brakujące obrazy. Rozwiązaniem jest własny układ druku, według którego z treści stron TYPO3 powstają pliki PDF niezależne od prezentacji w przeglądarce. Rozszerzenie dreipc_pdf nie jest opublikowane ani w TER, ani na Packagist, ani na GitHubie, dlatego nie da się sprawdzić jego funkcji. Kolejne sekcje opisują podejście, jakie stosuje takie rozwiązanie w TYPO3.

W przeciwieństwie do EXT:web2pdf, który konwertuje wyrenderowaną stronę HTML do PDF za pomocą biblioteki PHP mPDF, podejście oparte na danych korzysta z własnych szablonów: renderuje elementy treści strony TYPO3 przez szablony PDF i tworzy z nich sformatowany plik PDF. Pozwala to na pełną kontrolę nad marginesami stron, nagłówkami i stopkami, rozmiarami czcionek i podziałami stron.

Typowe scenariusze zastosowania

Karty katalogowe produktów z CMS. Producenci maszyn, firmy chemiczne i producenci sprzętu medycznego zarządzają danymi produktów w TYPO3. Handlowcy potrzebują tych danych jako drukowalnego PDF na spotkania z klientami. Rozwiązanie PDF oparte na danych tworzy ze strony produktu TYPO3 plik PDF z korporacyjnym układem: logo na górze, dane techniczne w tabelach, zdjęcie produktu, dane kontaktowe na dole. U klienta z 400 stronami produktów pliki PDF są automatycznie dostępne przyciskiem na każdej stronie, bez ręcznego tworzenia.

Komunikaty prasowe i raporty biznesowe. Działy komunikacji publikują komunikaty prasowe na stronie i jednocześnie oferują je do pobrania jako PDF. Takie rozwiązanie generuje PDF przy kliknięciu przycisku pobierania, zawsze na podstawie aktualnej treści. Bez ręcznego tworzenia PDF, bez ryzyka przestarzałych wersji do pobrania.

Urzędowe materiały informacyjne. Instytucje publiczne udostępniają formularze, broszury i pisma informacyjne jako PDF. Treści są zarządzane w TYPO3 i przy zmianach automatycznie dostarczane jako zaktualizowany PDF. Wersja PDF ma oficjalny układ z nagłówkiem urzędowym i sygnaturą.

Architektura techniczna

Takie rozwiązanie wykorzystuje do generowania bibliotekę PHP PDF, np. mPDF lub TCPDF, i rejestruje w TYPO3 własny typ strony. Przy wywołaniu strony z parametrem PDF-Type (?type=123) zamiast wyjścia HTML generowany jest plik PDF i oferowany do pobrania.

Pipeline renderowania działa w trzech krokach. Po pierwsze rozwiązanie odczytuje elementy treści żądanej strony TYPO3 z bazy danych. Po drugie renderuje każdy element przez dedykowany szablon PDF Fluid (nie standardowy szablon webowy). Po trzecie przekazuje wyrenderowany ciąg HTML do mPDF/TCPDF, który tworzy z niego PDF ze skonfigurowanymi ustawieniami stron.

Szablony PDF to szablony Fluid z HTML/CSS, który rozumie mPDF. mPDF obsługuje podzbiór CSS2 i CSS3: marginesy stron (@page), nagłówki/stopki, tabele, obrazy, czcionki (osadzalne fonty TTF) i podziały stron (page-break-before, page-break-after). Flexbox i Grid nie są obsługiwane - praca nad układem odbywa się przez tabele lub Float.

Konfiguracja obejmuje: format strony (A4, Letter, niestandardowy), orientację strony (pionowa/pozioma), marginesy stron, domyślną czcionkę, szablony nagłówków/stopek i przypisanie typów elementów treści do szablonów PDF. Każdy element treści może mieć własny szablon PDF, różniący się od prezentacji webowej.

Częste problemy i rozwiązania

Obrazy brakują w PDF. mPDF ładuje obrazy przez HTTP. Gdy serwer działa za reverse proxy lub w środowisku Docker, mPDF nie może rozwiązać własnych adresów URL obrazów. Rozwiązanie: osadzanie obrazów przez lokalną ścieżkę pliku zamiast URL. W szablonach PDF Fluid używanie absolutnej ścieżki serwera (/var/www/html/fileadmin/...) zamiast adresu webowego.

Generowanie PDF wolne przy złożonych stronach. Strona z 30 elementami treści i 15 obrazami może potrzebować 5-10 sekund na generowanie PDF. Przy jednoczesnych żądaniach obciąża to serwer. Rozwiązanie: cachowanie wygenerowanych PDF. Przy pierwszym wywołaniu PDF jest generowany i zapisywany w systemie plików. Kolejne wywołania dostarczają wersję z cache. Cache jest unieważniany przy zmianach treści.

Podziały stron w niewłaściwych miejscach. mPDF dzieli strony tam, gdzie treść przekracza wysokość strony - nawet w środku tabeli lub akapitu. Rozwiązanie: w szablonach PDF ustawianie jawnych podziałów stron (<div style="page-break-before: always;">) i ochrona tabel przed dzieleniem (<table style="page-break-inside: avoid;">).

Migracja i kompatybilność wersji

Rozszerzenie dreipc_pdf nie jest opublikowane ani w TER, ani na Packagist, ani na GitHubie. Nie da się więc sprawdzić, które wersje TYPO3 obsługuje, a aktualizacji dla bieżących wersji nie można publicznie pobrać.

Alternatywy dla TYPO3 v12/v13: EXT:web2pdf (konwertuje stronę HTML przez mPDF, prostsze, mniejsza kontrola nad układem), EXT:pdfviewhelpers (oparte na ViewHelperach, współpracuje z TCPDF), EXT:fluid_fpdf (szablony Fluid z backendem FPDF) lub niestandardowe rozwiązanie z mPDF jako pakietem Composer. Niestandardowe rozwiązanie ma zaletę pełnej kontroli i niezależności od rozszerzeń zewnętrznych.

Kto migruje z istniejącego rozszerzenia PDF na niestandardowe rozwiązanie, może przejąć dotychczasowe szablony PDF Fluid, o ile używają HTML/CSS kompatybilnego z mPDF. Wrapper renderowania musi być przepisany, ale szablony pozostają. Przy typowym projekcie z 5 szablonami PDF nakład migracji to 2-3 dni. Gosign wdrożył generowanie PDF w TYPO3 z różnymi bibliotekami i rekomenduje odpowiednie rozwiązanie w zależności od wymagań.