Baner kategorii: kompletny przewodnik
Instalacja, konfiguracja i obsługa banerów kategorii: pozycja i rozmiar w siatce, obraz mobilny, link dla każdego języka, harmonogram dat według czasu sklepu, podkategorie, Creative Elements, wielosklepowość i rozwiązywanie problemów w PrestaShop 1.7, 8 i 9.
Wprowadzenie i wymagania
Baner kategorii wstawia grafiki do siatki produktów na stronach kategorii, w wybranym przez Ciebie miejscu. Wskazujesz kategorię, numer produktu, po którym ma pojawić się baner, oraz obraz dla każdego języka. Resztą zajmuje się moduł, także po użyciu filtra fasetowego lub zmianie strony.
- Zgodny z PrestaShop od 1.7.6 do 9.x, sprawdzony na 1.7.8, 8.2.1 i 9.1.5: motywy Classic i Hummingbird, motywy pochodne, listy Creative Elements, motywy z siatką CSS.
- PHP 7.4 do 8.5.
- Wielosklepowość i wielojęzyczność (fr, en, es, de, it, nl, pl, pt).
- Bez override’ów, bez zmian w szablonach, bez zadań CRON.
- Kod HTML baneru powstaje po stronie serwera z szablonu Smarty; JavaScript jedynie wstawia go we właściwe miejsce, bez jQuery i bez zewnętrznych bibliotek.
Przesłane obrazy trafiają do /img/datafireflycategorybanner/, poza katalog modułu. Dzięki temu przetrwają aktualizacje modułu.

Instalacja
- Pobierz archiwum
datafireflycategorybanner.zipze swojego konta klienta. - W panelu administracyjnym otwórz Moduły > Menedżer modułów.
- Kliknij Wyślij moduł i upuść archiwum.
- Kliknij Konfiguruj, aby przejść do listy banerów.
Podczas instalacji moduł tworzy trzy tabele (banery, tłumaczenia, powiązanie ze sklepami), tworzy katalog /img/datafireflycategorybanner/ i rejestruje swoje hooki.

Tworzenie baneru
Na stronie konfiguracji kliknij Dodaj nowy baner. Formularz grupuje następujące ustawienia.
Kierowanie
- Kategoria: kategoria, w której pojawia się baner. Lista odwzorowuje drzewo sklepu, a kategorie wyłączone są oznaczone.
- Zastosuj do podkategorii: rozszerza baner na wszystkie podkategorie wybranej kategorii, niezależnie od głębokości.
- Po produkcie numer: baner jest wstawiany po tym produkcie listy. Wartość 4 umieszcza baner po czwartym wyświetlonym produkcie.
- Tylko na pierwszej stronie: wyświetla baner wyłącznie na pierwszej stronie listy, bez powtarzania go na stronach 2, 3 itd.

Wygląd i odnośnik
- Link baneru: docelowy adres URL, bezwzględny (
https://…) lub zaczynający się od ukośnika (/nowosci). Pozostaw puste, aby baner nie był klikalny. - Szerokość w siatce: liczba kolumn produktów zajmowanych przez baner, od 1 do 4, albo Cały wiersz. Na ekranach z mniejszą liczbą kolumn szerokość jest zmniejszana automatycznie.
- Wysokość w siatce: liczba wierszy produktów zajmowanych przez baner, od 1 do 3. Dostępne na listach z siatką CSS (Creative Elements, większość nowszych motywów).
- Wyświetlanie obrazu: Wypełnij obszar banera przycina obraz do rozmiaru komórki, Zachowaj proporcje obrazu pokazuje go w całości.
- Klasa CSS: dodatkowe klasy stosowane do komórki banera. Pozostaw puste, aby przejąć klasy komórek produktów Twojego motywu. Przy szerokości i wysokości 1 klasa rozmiaru Twojego motywu (na przykład ustawiająca
grid-area) nadal działa. - Własny CSS: deklaracje stosowane tylko do tego baneru, na przykład
border-radius: 12px; padding: 10px;.
Harmonogram i status
- Data rozpoczęcia i Data zakończenia: okno wyświetlania w formacie
RRRR-MM-DD GG:MM:SS. Puste pole oznacza brak ograniczenia po tej stronie. - Aktywny: pokazuje lub zawiesza baner bez usuwania go.
- Przypisanie do sklepów: w trybie wielosklepowym zaznacz odpowiednie sklepy.
Obrazy dla każdego języka
Pola Obraz baneru, Obraz mobilny, Tekst alternatywny i Link dla tego języka istnieją dla każdego aktywnego języka. Selektor języka umieszczony tuż nad tymi polami pokazuje pola wybranego języka. Gdy obraz już istnieje, pojawia się podgląd wraz z przełącznikiem Usuń obraz, który dotyczy tylko tego języka.
Akceptowane formaty: JPG, PNG, GIF, WebP i SVG, do 4 MB. Szerokość 1200 px pasuje do większości siatek.

Jak obliczana jest pozycja
Pozycja wyrażana jest w liczbie produktów i obowiązuje na każdej stronie listy. Baner ustawiony na 4 pojawia się po czwartym produkcie bieżącej strony, niezależnie od tego, czy odwiedzający jest na stronie 1 czy 3.
Kilka banerów może dotyczyć tej samej kategorii, każdy na swojej pozycji. Gdy dwa banery mają tę samą pozycję, są wstawiane jeden po drugim w kolejności zapisu. Jeśli pozycja przekracza liczbę produktów wyświetlonych na stronie, baner jest po prostu pomijany na tej stronie, bez przesuwania pozostałych.
Domyślnie baner zajmuje miejsce jednej komórki produktu. Pola Szerokość w siatce i Wysokość w siatce pozwalają go powiększyć, jak opisano poniżej.

Rozmiar banera w siatce
Każdy baner zajmuje blok komórek produktów: domyślnie 1 × 1, maksymalnie 4 kolumny na 3 wiersze, albo cały wiersz. Produkty po banerze wypełniają wolne komórki, więc w siatce nie zostają luki.
- Listy z siatką CSS (Creative Elements, większość nowszych motywów): działa i szerokość, i wysokość. Baner 2 × 2 umieszczony po 4. produkcie w siatce czterokolumnowej zajmuje dwie pierwsze kolumny wierszy 2 i 3, a produkty od 5 do 8 układają się obok.
- Wiersze Bootstrap (motyw Classic): działa szerokość, jako część wiersza. Wysokość wynika z obrazu.
- Małe ekrany: szerokość jest ograniczona do liczby wyświetlanych kolumn. Baner czterokolumnowy w dwukolumnowej siatce mobilnej zajmuje cały wiersz.
W trybie wypełnienia obraz pokrywa cały obszar, przyjmuje wysokość sąsiednich produktów i jest przycinany od środka. Baner na cały wiersz zawsze zachowuje proporcje, bo obok nie ma produktu, który nadałby mu wysokość: użyj do niego obrazu poziomego.
Dla banera 2 × 2 w trybie wypełnienia przygotuj obraz nieco wyższy niż szerszy i umieść najważniejszą treść na środku, ponieważ krawędzie mogą zostać przycięte.


Planowanie akcji
Ustaw datę rozpoczęcia i datę zakończenia, aby baner pojawiał się i znikał sam. To właściwe narzędzie do przygotowania wyprzedaży, Black Friday czy akcji na koniec roku z wielotygodniowym wyprzedzeniem.
- Tylko data rozpoczęcia: baner pojawia się w tym dniu i pozostaje widoczny.
- Tylko data zakończenia: baner jest widoczny od razu i znika w tym dniu.
- Obie daty: baner jest widoczny wyłącznie w tym oknie.
- Brak dat: baner jest stały.
Daty są wprowadzane i porównywane według czasu sklepu, czyli strefy czasowej ustawionej w Międzynarodowy > Lokalizacja, a nie według czasu odwiedzającego. Data zakończenia wpisana bez godziny obowiązuje do 23:59:59.

Objęcie całego drzewa
Opcja Zastosuj do podkategorii oszczędza tworzenia tego samego baneru w każdym dziale. Ustawiona na kategorii nadrzędnej sprawia, że baner pojawia się w tej kategorii i we wszystkich jej potomkach.
Wyszukiwanie opiera się na natywnym drzewie zagnieżdżonym PrestaShop (kolumny nleft i nright), więc nie generuje dodatkowych zapytań na stronę. Po przeniesieniu kategorii PrestaShop przelicza te wartości, a zasięg dostosowuje się automatycznie.
Obrazy i języki
Każdy baner przyjmuje grafikę i tekst alternatywny dla każdego języka, co pozwala dopasować komunikat lub cenę do rynku. Jeśli język nie otrzymał własnej grafiki, moduł pokazuje grafikę języka domyślnego sklepu zamiast ukrywać baner. Tekst alternatywny danego języka zostaje zachowany, jeśli został uzupełniony.
Każdą grafikę może uzupełnić opcjonalny obraz mobilny: jest wyświetlany na ekranach o szerokości do 767 px, z własnymi wymiarami. Do banera na całą szerokość przygotuj go w formacie pionowym.
Wymiary obrazu są odczytywane przy przesyłaniu i zapisywane w atrybutach width i height w HTML, co eliminuje przesunięcie układu podczas ładowania. Baner widoczny od razu po otwarciu strony ładuje się priorytetowo (fetchpriority="high"), pozostałe z opóźnieniem (loading="lazy"). Pliki są zmieniane na nazwy z losowym przyrostkiem i zapisywane w /img/datafireflycategorybanner/.
Tekst alternatywny czytają wyszukiwarki i czytniki ekranu. Opisz zawartość grafiki zamiast powtarzać nazwę kategorii.

Tryb wielosklepowy
Gdy funkcja wielosklepowa jest włączona, formularz pokazuje blok Przypisanie do sklepów. Baner pojawia się tylko w zaznaczonych sklepach, a lista w panelu pokazuje wyłącznie banery widoczne w bieżącym kontekście sklepu.
Jeśli nie zaznaczysz żadnego sklepu, moduł przypisze baner do bieżącego kontekstu, aby nigdy nie powstał baner bez sklepu.
Filtry fasetowe, sortowanie i stronicowanie
W PrestaShop 8 i 9 filtry fasetowe, sortowanie i stronicowanie przeładowują listę produktów przez AJAX bez przeładowania strony. Moduł obserwuje listę: gdy tylko pojawią się nowe komórki produktów, po filtrze, zmianie strony, przycisku „załaduj więcej” lub nieskończonym przewijaniu, umieszcza banery z powrotem na właściwych pozycjach. Nasłuchuje też zdarzenia updateProductList PrestaShop.
Siatka produktów jest rozpoznawana na podstawie samych produktów (znaczniki data-id-product i product-miniature), a nie klas konkretnego motywu. Obejmuje to motyw Classic, listy Creative Elements i większość motywów na zamówienie.
CSS i JavaScript ładują się tylko na stronach kategorii i tylko wtedy, gdy bieżąca kategoria ma co najmniej jeden aktywny i możliwy do wyświetlenia baner.
Ustawienia: selektor siatki produktów
Pod listą banerów panel Ustawienia zawiera jedno pole, Selektor siatki produktów. Pozostaw je puste: siatka jest wykrywana automatycznie.
Tylko jeśli banery nigdy się nie wyświetlają w motywie o nietypowej strukturze, wpisz selektor CSS elementu, który bezpośrednio zawiera komórki produktów, na przykład #js-product-list .products lub .ce-products. Gdy siatki nie da się znaleźć, moduł wypisuje ostrzeżenie [DataFirefly Category Banner] w konsoli przeglądarki.
Nowości w wersji 1.3.0
Wersja 1.3.0 usuwa kilka usterek wykrytych podczas pełnej weryfikacji na PrestaShop 1.7.8, 8.2.1 i 9.1.5 oraz dodaje kilka ustawień.
- Obraz mobilny: każdy język przyjmuje drugi obraz, wyświetlany na ekranach o szerokości do 767 px. Przydaje się przy banerze na całą szerokość, który w formacie poziomym jest mało czytelny na telefonie.
- Link dla każdego języka: opcjonalny link dla danego języka zastępuje wspólny link, dzięki czemu można kierować na stronę z przetłumaczonym adresem, na przykład
/en/content/1-delivery. - Tylko na pierwszej stronie: baner nie jest już powtarzany na stronach 2, 3 itd. listy. Pojawia się ponownie, gdy odwiedzający wróci na stronę 1 lub zastosuje filtr.
- Kalendarz dat: kalendarz w formularzu wpisuje teraz datę we właściwym formacie. Data zakończenia wpisana bez godziny obowiązuje do 23:59:59.
- Czas sklepu: daty są porównywane z czasem sklepu. Wcześniej zegar serwera MySQL, często ustawiony na UTC, przesuwał rozpoczęcie i zakończenie o jedną do dwóch godzin.
- Core Web Vitals: banery są wstawiane tuż po siatce produktów (hook
displayFooterCategory), przed pierwszym wyświetleniem, co eliminuje przesunięcie układu (CLS). Baner widoczny po otwarciu strony ładuje się priorytetowo, kolejne z opóźnieniem. - Bezpieczeństwo obrazów: pliki SVG zawierające skrypt, obsługę zdarzeń lub treść zewnętrzną są odrzucane, a katalog
/img/datafireflycategorybanner/otrzymuje własny plik.htaccess(tylko obrazy, izolowane pliki SVG). Odrzucony obraz nie tworzy już pustego baneru. - WebP w PrestaShop 1.7: obrazy WebP są akceptowane i poprawnie wyświetlane.
- Lista w panelu administracyjnym: kolumna Obrazy z językami, które mają grafikę, oraz oznaczenie banerów zakończonych lub zaplanowanych.
Aby zaktualizować moduł, zainstaluj archiwum 1.3.0 na obecnej wersji z poziomu menedżera modułów. Twoje banery i obrazy zostają zachowane. Następnie wyczyść pamięć podręczną PrestaShop oraz każdego modułu wydajności.
Aktualizacja do wersji 1.2.0
Zainstaluj archiwum 1.2.0 na poprzedniej wersji z poziomu menedżera modułów. Skrypt aktualizacji dodaje kolumny rozmiaru i wyświetlania obrazu oraz ustawienie selektora siatki. Istniejące banery zachowują obecny wygląd: 1 × 1, proporcje obrazu zachowane. Edytuj baner, aby nadać mu inny rozmiar lub przełączyć go w tryb wypełnienia.
W tej wersji zmienia się skrypt frontu. Po aktualizacji wyczyść pamięć podręczną PrestaShop oraz każdego modułu wydajności (CCC, cache stron, minifikacja), inaczej nadal będzie serwowany poprzedni skrypt.
Aktualizacja z wersji 1.0.0
Po prostu zainstaluj nowe archiwum na starym z poziomu menedżera modułów. Skrypt aktualizacji zajmie się:
- dodaniem kolumn zasięgu, harmonogramu i wymiarów obrazu;
- utworzeniem tabeli powiązań ze sklepami i przeniesieniem do niej pierwotnego sklepu każdego baneru;
- przeniesieniem istniejących obrazów z
views/img/banners/do/img/datafireflycategorybanner/i odczytaniem ich wymiarów; - usunięciem zbędnego już hooka.
Twoje banery, ich pozycje i grafiki zostają zachowane.
FAQ i rozwiązywanie problemów
Baner nie pojawia się na stronie kategorii
Sprawdź po kolei: baner jest aktywny; dzisiejsza data mieści się w oknie harmonogramu; wskazana kategoria to ta przeglądana albo włączony jest zasięg na podkategorie; wyświetlany język ma obraz, albo ma go język domyślny; w trybie wielosklepowym bieżący sklep jest zaznaczony. Na końcu wyczyść pamięć podręczną PrestaShop.
Na liście zbudowanej w Creative Elements lub innym kreatorze stron sprawdź, czy moduł ma wersję 1.2.0 lub nowszą: wcześniejsze wersje rozpoznawały tylko siatkę motywu Classic. Następnie otwórz konsolę przeglądarki: ostrzeżenie [DataFirefly Category Banner] oznacza, że nie znaleziono siatki, zobacz sekcję Ustawienia.
Baner pojawia się w złym miejscu
Pozycja liczy produkty bieżącej strony. Jeśli lista pokazuje 12 produktów na stronę, baner na pozycji 20 nie pojawi się nigdzie. Zmniejsz wartość lub zwiększ liczbę produktów na stronę.
Baner psuje układ siatki
Ustawiaj rozmiar polami Szerokość w siatce i Wysokość w siatce zamiast klasami siatki, a pole Klasa CSS pozostaw puste, chyba że motyw udostępnia klasę rozmiaru. Unikaj mieszania klas z różnych systemów siatki.
Baner znika po filtrowaniu
Od wersji 1.2.0 moduł ponownie wstawia banery, gdy tylko na liście pojawią się nowe komórki produktów, niezależnie od modułu filtrów. Jeśli baner nadal znika, otwórz konsolę przeglądarki: ostrzeżenie [DataFirefly Category Banner] oznacza, że po odświeżeniu nie znaleziono siatki. Wpisz wtedy selektor siatki w panelu Ustawienia i skontaktuj się z pomocą techniczną, jeśli problem nie ustępuje.
Obraz nie chce się przesłać
Moduł przyjmuje pliki JPG, PNG, GIF, WebP i SVG do 4 MB. Sprawdź też, czy katalog /img/datafireflycategorybanner/ ma prawo zapisu oraz czy dyrektywy PHP upload_max_filesize i post_max_size są większe od rozmiaru pliku.
Link baneru jest odrzucany
Akceptowane są wyłącznie adresy zaczynające się od http://, https:// lub od ukośnika. To zabezpieczenie przed wstrzyknięciem adresów javascript: lub data:.
Co dzieje się przy odinstalowaniu?
Moduł usuwa swoje tabele oraz katalog /img/datafireflycategorybanner/ wraz z zawartymi w nim grafikami. Zrób kopię obrazów, jeśli planujesz późniejszą ponowną instalację.