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. dreipc_pdf rozwiązuje ten problem własnym podejściem do renderowania: rozszerzenie generuje pliki PDF z treści stron TYPO3 z dedykowanym układem druku, niezależnym od prezentacji w przeglądarce.

W przeciwieństwie do EXT:web2pdf, który konwertuje wyrenderowaną stronę HTML jako zrzut ekranu do PDF, dreipc_pdf pracuje w oparciu o dane. Renderuje elementy treści strony TYPO3 przez własne szablony 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. dreipc_pdf 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. dreipc_pdf 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

dreipc_pdf wykorzystuje bibliotekę PHP PDF (typowo mPDF lub TCPDF) do generowania. Rozszerzenie rejestruje się jako Page-Type w TYPO3. 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 rozszerzenie 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

dreipc_pdf to niszowe rozszerzenie z ograniczoną społecznością. Ostatnia stabilna wersja obsługuje TYPO3 v10 i v11. Dla v12 nie ma oficjalnej aktualizacji - nakład portowania jest umiarkowany (dostosowania Extbase, aktualizacje TCA).

Alternatywy dla TYPO3 v12/v13: EXT:web2pdf (oparte na zrzutach ekranu, 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 dreipc_pdf na niestandardowe rozwiązanie, może przejąć istniejące 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ń.