Katalog PDF PrestaShop — Kompletny przewodnik

Prezentacja

DFPDFCatalog publikuje Twoje katalogi PDF bezpośrednio w sklepie PrestaShop 8 lub 9. Moduł działa na dwa uzupełniające się sposoby. Najpierw tworzy własne strony we front-office: stronę-witrynę z listą wszystkich katalogów w formie klikalnych banerów (/catalogues-pdf) oraz stronę przeglądarki dla każdego katalogu (/catalogue-pdf/{id}-{slug}). Pozwala też osadzić dowolny katalog na dowolnej stronie sklepu przez shortcode, widget Smarty lub iframe.

W obu przypadkach PDF wyświetla się w profesjonalnym wbudowanym czytniku: tryb podwójnej strony jak w magazynie, klikalne miniatury, pełny ekran, zoom, klikalne linki i zaznaczalny tekst.

Instalacja

1. Pobierz plik ZIP modułu z Twojego konta DataFirefly.
2. W back-office PrestaShop przejdź do Moduły → Menedżer modułów → Zainstaluj moduł.
3. Wybierz plik dfpdfcatalog.zip i zatwierdź.
4. Moduł instaluje się automatycznie: tabele bazy danych, zakładka administracyjna i trasy front są tworzone bez ręcznej konfiguracji.

Po instalacji w menu Katalog back-office pojawia się nowa zakładka Katalogi PDF.

To samo archiwum instaluje się na PrestaShop 8.0 do 8.2 i na PrestaShop 9.x. Nie trzeba pobierać osobnej wersji dla danej generacji.

Aktualizacja z wcześniejszej wersji

1. Wgraj nową wersję przez Moduły → Menedżer modułów → Zainstaluj moduł (lub podmień katalog /modules/dfpdfcatalog/ przez FTP).
2. Wyczyść cache PrestaShop: Zaawansowane → Wydajność → Wyczyść cache.

Aktualizacja zachowuje istniejące katalogi: tabele bazy danych i wgrane pliki (banery i PDF-y) pozostają nietknięte. Przy przejściu na 1.2.0 moduł automatycznie rejestruje hooki potrzebne do osadzania na stronach.

Dodawanie katalogu

1. Przejdź do Katalog → Katalogi PDF i kliknij Dodaj katalog.
2. Uzupełnij tytuł (tłumaczony per język) — służy też do generowania slugu URL i meta title strony.
3. Uzupełnij opis (tłumaczony) — wyświetlany na stronie przeglądarki i używany jako meta description.
4. Wgraj obraz baneru — pojawia się w siatce strony-witryny i pełni rolę plakatu otwierającego, gdy katalog jest osadzony na stronie.
5. Wgraj plik PDF.
6. Ustaw pozycję (kolejność wyświetlania w siatce) i status aktywny/nieaktywny.
7. W trybie multistore zaznacz sklepy, w których katalog ma się pojawić.
8. Zapisz: katalog jest natychmiast widoczny na /catalogues-pdf.

Po zapisaniu katalogu otwórz go ponownie: formularz wyświetla blok Kody osadzania z czterema gotowymi do skopiowania kodami do wyświetlania go w innych miejscach sklepu. Kliknij pole, aby je zaznaczyć.

Osadzanie katalogu na stronie

Strona-witryna nie pasuje do wszystkich zastosowań. Dla branżowej landing page, strony przetargowej czy kategorii, która ma prezentować własny katalog, możesz umieścić przeglądarkę dokładnie tam, gdzie chcesz.

Zalecana metoda: shortcode

Wklej ten znacznik w treści strony, dokładnie w miejscu, gdzie katalog ma się pojawić:

[dfpdfcatalog id="3"]

Zastąp 3 identyfikatorem katalogu, widocznym w kolumnie ID listy Katalog → Katalogi PDF. Shortcode działa w:

• treści stron CMS;
• opisach kategorii;
• opisach produktów.

W tych trzech kontekstach moduł podmienia znacznik po stronie serwera, przed wysłaniem strony. Dla wszystkich pozostałych kontekstów (bloki motywu, moduły zewnętrzne, page buildery) fallback JavaScript wykrywa znacznik na stronie i montuje przeglądarkę w tym samym miejscu. Nie musisz nic konfigurować: zachowanie dla odwiedzającego jest identyczne.

Opcje shortcode’u

• id — identyfikator katalogu. Wymagany.
• mode — click (domyślnie) wyświetla najpierw plakat z banerem katalogu i ładuje przeglądarkę dopiero po kliknięciu. inline wyświetla przeglądarkę od razu, ładowaną przy zbliżaniu się do viewportu.
• height — wysokość przeglądarki w pikselach. Domyślnie przeglądarka zajmuje 80% wysokości ekranu.
• title — etykieta wyświetlana na plakacie otwierającym. Domyślnie tytuł katalogu.

[dfpdfcatalog id="3" mode="inline" height="800"]

Widget Smarty w szablonie motywu

Aby osadzić katalog bezpośrednio w pliku .tpl motywu:

{widget name='dfpdfcatalog' id_catalog=3 mode='inline'}

Ta składnia działa tylko w szablonach. Treść stron CMS nie jest interpretowana przez Smarty — w tym przypadku użyj shortcode’u.

Iframe, także poza PrestaShop

Moduł udostępnia stronę osadzania bez nagłówka i stopki sklepu, do umieszczenia w iframe:

<iframe src="/catalogue-pdf-embed/3" width="100%" height="800" style="border:0;" loading="lazy"></iframe>

To metoda do wyświetlania katalogu na zewnętrznej stronie. Te strony osadzania mają noindex i nigdy nie konkurują z Twoimi właściwymi stronami w wynikach wyszukiwania. Pamiętaj, że wysokość iframe jest stała: we własnym sklepie preferuj shortcode, który dostosowuje się do treści.

Wiele katalogów na jednej stronie

Na jednej stronie możesz umieścić dowolną liczbę katalogów. Każde osadzenie tworzy niezależną przeglądarkę z własnymi przyciskami nawigacji, zoomem i trybem wyświetlania. Skróty klawiaturowe działają tylko na przeglądarce pod kursorem, a nie na wszystkich naraz.

Ładowanie jest zoptymalizowane pod ten scenariusz:

• w trybie click żaden PDF nie jest pobierany, dopóki odwiedzający nie otworzy katalogu;
• w trybie inline ładowanie uruchamia się przy zbliżaniu do viewportu;
• biblioteka renderująca i arkusz stylów są pobierane tylko raz na całą stronę, i tylko jeśli katalog faktycznie na niej występuje.

Strona prezentująca osiem katalogów w trybie click ładuje więc na start tylko osiem obrazów banerów.

Strony front-office

Strona-witryna

Strona /catalogues-pdf wyświetla wszystkie aktywne katalogi bieżącego sklepu w siatce banerów, posortowane według pozycji. Każdy baner prowadzi do przeglądarki katalogu. Strona generuje własny meta title i meta description oraz integruje się z natywnymi okruszkami PrestaShop.

Strona przeglądarki

Każdy katalog ma własną stronę /catalogue-pdf/{id}-{slug}. PDF wyświetla się we wbudowanej przeglądarce, z przyciskiem powrotu do witryny i przyciskiem bezpośredniego pobrania. PDF jest serwowany przez kontroler PHP w trybie inline, co wymusza wyświetlanie w przeglądarce. Obsługiwane są żądania HTTP Range, dzięki czemu duże katalogi ładują się progresywnie, a nie w całości naraz.

Korzystanie z przeglądarki

Przeglądarka opiera się na PDF.js (Mozilla) i oferuje w pasku narzędzi następujące funkcje:

• Miniatury — pokazuje lub ukrywa boczny pasek miniatur stron. Miniatury są klikalne i generują się podczas przewijania (leniwe renderowanie), nawet dla bardzo długich katalogów. Aktywna strona (lub strony) jest podświetlona.
• Podwójna strona — przełącza między widokiem strona po stronie a trybem podwójnej strony jak w magazynie: sama okładka, potem pary 2-3, 4-5 itd. Ten tryb jest domyślnie aktywny na ekranach o szerokości co najmniej 1024 px.
• Nawigacja — przyciski poprzednia/następna, wskaźnik strony (np. „Strona 4-5 / 24” w trybie podwójnym). Strzałki lewo/prawo na klawiaturze także działają.
• Zoom — powiększanie/pomniejszanie co 25% i przycisk automatycznego dopasowania do szerokości.
• Pełny ekran — przełącza przeglądarkę w tryb pełnoekranowy przez natywne API przeglądarki. Na iOS Safari automatycznie używany jest symulowany tryb pełnoekranowy. Klawisz Escape wychodzi z trybu.

Hiperłącza zawarte w PDF pozostają klikalne: linki zewnętrzne otwierają się w nowej karcie, a linki wewnętrzne (spis treści, odsyłacze) nawigują bezpośrednio w przeglądarce. Jeśli PDF zawiera warstwę tekstową, tekst można zaznaczać i kopiować, a wyszukiwanie Ctrl+F przeglądarki działa na treści.

Renderowanie wykorzystuje gęstość pikseli ekranu (HiDPI): strony są ostre na ekranach Retina i 4K.

SEO i adresy URL

Moduł deklaruje swoje trasy przez hook moduleRoutes PrestaShop:

• /catalogues-pdf — strona-witryna z dedykowanym meta title i meta description.
• /catalogue-pdf/{id}-{slug} — czysty URL dla każdego katalogu, gdzie slug jest generowany automatycznie z tytułu. Meta title przejmuje tytuł katalogu, a meta description jego opis.
• /catalogue-pdf-embed/{id} — strona osadzania przeznaczona do iframe’ów, z noindex.

Nie trzeba tworzyć żadnej strony CMS: trasy rejestrują się automatycznie przy instalacji.

Wielojęzyczność i multistore

Tytuły i opisy tłumaczy się pole po polu w formularzu edycji (standardowy selektor języka PrestaShop). Każdy język generuje własny slug i własne metatagi. W multistore przypisanie katalog/sklep zarządzane jest checkboxami: każdy sklep wyświetla tylko przypisane mu katalogi. To filtrowanie obejmuje też bezpośredni dostęp przez URL i osadzenia na stronach: katalog nieprzypisany do bieżącego sklepu nigdy nie jest w nim serwowany.

Rozwiązywanie problemów

Shortcode wyświetla się jako zwykły tekst na stronie

• Sprawdź, czy identyfikator odpowiada istniejącemu, aktywnemu katalogowi przypisanemu do bieżącego sklepu. Nieznaleziony identyfikator pozostawia znacznik nietknięty, zamiast wyświetlać pustą przeglądarkę.
• Sprawdź, czy katalog rzeczywiście zawiera plik PDF.
• Wyczyść cache PrestaShop i przeładuj stronę w trybie prywatnym.
• Jeśli właśnie zaktualizowałeś moduł, odinstaluj go i zainstaluj ponownie, aby wymusić rejestrację hooków osadzania.

PDF się nie wyświetla

• Sprawdź, czy plik PDF został poprawnie wgrany (edytuj ponownie katalog w back-office).
• Wyczyść cache PrestaShop i przeładuj stronę w trybie prywatnym.
• Jeśli w przeglądarce pojawia się komunikat błędu, awaryjnie proponowany jest link bezpośredniego pobrania PDF-a.

Tekst nie daje się zaznaczyć lub Ctrl+F nic nie znajduje

Zaznaczanie tekstu wymaga, aby PDF zawierał warstwę tekstową. Zeskanowane PDF-y lub eksporty czysto bitmapowe jej nie mają: wtedy możliwy jest tylko widok graficzny. Przepuść dokument przez narzędzie OCR, jeśli potrzebujesz tekstu.

Linki w PDF nie są klikalne

Linki muszą być prawdziwymi adnotacjami linków w PDF (tworzonymi przez narzędzie eksportu: InDesign, Word, LibreOffice…). Tekst wyglądający jak URL, ale bez adnotacji, nie będzie klikalny.

Strony wyglądają na rozciągnięte lub rozmyte

Ten problem z wersji 1.0.0 jest naprawiony od wersji 1.0.1 (renderowanie HiDPI i neutralizacja resetów CSS motywów). Zaktualizuj moduł i wyczyść cache PrestaShop.

Historia wersji

• 1.2.0 (2026-08-10) — Osadzanie katalogu na dowolnej stronie przez shortcode, widget Smarty lub iframe; podmiana po stronie serwera na stronach CMS, w kategoriach i kartach produktu, z fallbackiem JavaScript; przeglądarka przepisana na niezależne instancje (wiele katalogów na stronę); leniwe ładowanie; kody osadzania gotowe do skopiowania w back-office; obsługa żądań HTTP Range.
• 1.1.0 (2026-08-10) — Kompatybilność z PrestaShop 9; poprawka przypisania sklepu w formularzu edycji; filtrowanie per sklep stosowane też przy bezpośrednim dostępie przez URL; kontrola rzeczywistej zawartości wgrywanych plików.
• 1.0.4 (2026-05-11) — Tryb pełnoekranowy (natywne API + fallback iOS Safari); poprawka fit-width okładki w trybie podwójnej strony; podświetlanie aktywnych przycisków.
• 1.0.3 (2026-05-11) — Tryb podwójnej strony jak w magazynie (sama okładka, potem 2-3, 4-5…); auto-aktywacja na szerokich ekranach; czyste anulowanie renderów przy szybkiej nawigacji.
• 1.0.2 (2026-05-11) — Boczny pasek klikalnych miniatur z leniwym renderowaniem; warstwa tekstowa (zaznaczanie + Ctrl+F); przycisk pokazywania miniatur.
• 1.0.1 (2026-05-11) — Ostre renderowanie HiDPI na Retina/4K; klikalne linki PDF (warstwa adnotacji); poprawka pionowego rozciągania stron.
• 1.0.0 (2026-05-08) — Wersja początkowa: strona-witryna, wbudowana przeglądarka, URL-e SEO, wielojęzyczność, multistore.