Jak edytować hooki w PrestaShop

Hooki to serce mechanizmu rozszerzeń w sklepach opartych na PrestaShop. Dzięki nim dołączasz lub modyfikujesz elementy interfejsu i logiki bez dotykania plików rdzenia. Ten praktyczny poradnik prowadzi krok po kroku: od prostego zarządzania pozycjami modułów, przez edycję widoków i logiki, aż po tworzenie własnych hooków. Zadbamy o bezpieczeństwo, kopie zapasowe, tryb deweloperski, zgodność wersji i dobre praktyki, aby Twoje zmiany były stabilne, skalowalne i łatwe w utrzymaniu.

Zrozumienie hooków i przygotowanie środowiska

Czym są hooki i jak działają

Hook to nazwany punkt zaczepienia w kodzie lub szablonie, w którym mogą wyświetlać się treści modułów albo wykonywać ich logika. Na froncie widzisz hooki typu display (np. displayHeader, displayTop, displayFooter), które renderują HTML. W warstwie serwerowej działają hooki akcji (np. actionProductSave), które pozwalają reagować na zdarzenia. Moduł podłącza się do hooka i dostarcza wynik: treść, styl, skrypt lub akcję.

Najważniejsze konsekwencje pracy z hookami:

• Możesz przenosić, włączać i wyłączać elementy bez edycji rdzenia.
• Ten sam moduł może być podpięty do wielu punktów zaczepienia.
• Kolejność modułów w hooku ma znaczenie dla wyglądu i logiki.
• Wyjątki, warunki i priorytety decydują, kiedy i gdzie coś się pokaże.

Rodzaje hooków: wyświetlanie, akcje i widżety

W praktyce spotkasz trzy kategorie:

• Hooki wyświetlania (display*): renderują HTML na froncie sklepu.
• Hooki akcji (action*): uruchamiają się przy zdarzeniach, bez bezpośredniego renderowania (np. zapis produktu, zamówienia).
• Hooki widgetowe: moduły implementują interfejs widgetu i renderują się w określonych miejscach, podobnie jak display, ale przez kontrakt widgetu.

Zrozumienie, czy problem dotyczy widoku, czy logiki, podpowie, czy pracować w szablonie, czy w kodzie modułu.

Przygotowanie: kopie zapasowe i środowisko testowe

Zanim zaczniesz:

• Utwórz kopię bazy i plików (pełny backup).
• Pracuj na środowisku testowym lub stagingu, nie bezpośrednio na produkcji.
• Włącz kontrolę wersji (np. Git), by mieć historię i możliwość cofania.
• Ustal okno wdrożeniowe, gdy ruch jest najmniejszy.

To minimalizuje ryzyko przerw w działaniu sklepu.

Tryb deweloperski i pamięć podręczna

Podczas pracy przyda się tryb deweloperski i zarządzanie pamięcią podręczną. Włącz debug w panelu administracyjnym (Parametry zaawansowane > Wydajność > Tryb debugowania) lub, jeśli to konieczne, przez plik konfiguracyjny. W trakcie edycji szablonów tymczasowo ustaw wymuszanie kompilacji i wyłącz keszowanie szablonów.

Po każdej zmianie czyszcz cache (Parametry zaawansowane > Wydajność > Wyczyść pamięć podręczną). Gdy zakończysz prace, przywróć ustawienia produkcyjne: kompilacja według potrzeb, włączone łączenie i minifikacja zasobów oraz buforowanie.

Edycja hooków bez kodowania: pozycje modułów i transplantacje

Gdzie znaleźć zarządzanie pozycjami

Przejdź do panelu administracyjnego: Projekt > Pozycje (w starszych wersjach: Moduły > Pozycje). Tu zobaczysz listę hooków i modułów do nich przypiętych. Wyszukiwarka pomaga znaleźć konkretny hook, np. displayHeader, displayTop, displayHome, displayFooter.

Przenoszenie modułu do innego hooka (Transplantacja)

Aby zmienić miejsce wyświetlania modułu:

• Wejdź w Projekt > Pozycje.
• Kliknij Dodaj moduł do hooka (Transplantacja modułu).
• Wybierz moduł, wskaż docelowy hook z listy.
• Ustal warunki wyświetlania (strony, wyjątki).
• Zapisz i odśwież stronę sklepu.

Ta operacja nie wymaga edycji kodu i zwykle rozwiązuje większość potrzeb.

Ustalanie kolejności modułów w hooku

W widoku hooka zobaczysz listę modułów. Przeciągnij je myszą, aby zmienić kolejność. Najwyższe pozycje renderują się wcześniej. Warto testować, jak wpływa to na CSS i układ kolumn; niektóre motywy zakładają konkretną kolejność.

Wyjątki, strony i urządzenia

Dla wielu modułów możesz ustawić:

• Wyjątki kontrolerów (np. nie pokazuj na stronach koszyka, kasy, konta).
• Wyświetlanie tylko na wybranych stronach (np. tylko karta produktu).
• Ograniczenie do urządzeń (desktop/mobile), jeśli moduł to wspiera.

To precyzyjnie steruje, gdzie moduł w hooku jest widoczny.

Przykłady bez grzebania w kodzie

Scenariusze możliwe do ustawienia „z palca”:

• Przenieś pasek wyszukiwania z displayTop do displayNav1, aby zwolnić miejsce w nagłówku.
• Dodaj baner promocyjny do displayHome z priorytetem nad sliderem.
• Ukryj moduł zaufanych opinii na stronie kasy przez wyjątek kontrolera.
• Podłącz moduł breadcrumbs do hooka w szablonie strony kategorii (jeśli motyw go używa).

Te zmiany są szybkie, odwracalne i odporne na aktualizacje.

Edycja hooków w kodzie: szablony, Smarty i logika modułu

Override szablonów modułów w motywie

Gdy chcesz zmienić HTML renderowany przez moduł, nie edytuj jego plików w katalogu modules. Zamiast tego zastosuj override szablonu w motywie. Struktura:

• themes/nazwatematu/modules/nazamodulu/views/templates/hook/nazwapliku.tpl

Jeśli ten plik istnieje, PrestaShop użyje go zamiast oryginału. Skopiuj oryginał z modules/nazamodulu/views/templates/hook, wklej do motywu, a następnie wprowadź zmiany. Dzięki temu aktualizacja modułu nie nadpisze Twojej pracy.

Edycja szablonów i zasady Smarty

Widoki renderują szablony TPL. Silnik Smarty pozwala stosować instrukcje warunkowe, pętle i filtry. Zasady bezpiecznej edycji:

• Nie usuwaj znaczników wymaganych przez logikę (np. formularze, tokeny).
• Uważaj na modyfikację identyfikatorów i klas CSS używanych przez JS.
• Stosuj escapowanie danych, jeśli dodajesz nowe zmienne użytkownika.
• Po edycji wymuś kompilację i wyczyść pamięć podręczną.

Jeśli tworzysz nowe bloki, staraj się trzymać istniejącej struktury BEM i siatki motywu.

Dodawanie stylów i skryptów przez hooki nagłówka

Style i skrypty najlepiej wstrzykiwać przez hook displayHeader (FO) lub displayBackOfficeHeader (BO). W module dodaj rejestrację zasobów w odpowiedniej metodzie hooka, aby ładowały się tylko tam, gdzie trzeba. Unikaj wklejania CSS/JS bezpośrednio do TPL; korzystaj z kolejki zasobów motywu, wersjonowania plików i warunkowego ładowania.

Zmiana logiki: rejestracja hooków i metody modułu

Jeśli musisz dołożyć logikę lub podpiąć moduł do nowego miejsca, potrzebna będzie rejestracja hooka przez moduł oraz metoda hookXxx. W skrócie:

• Podczas instalacji moduł wywołuje registerHook z nazwą hooka.
• W klasie modułu implementujesz metodę, np. hookDisplayFooter($params).
• Metoda zwraca HTML (TPL) lub wykonuje akcję (dla hooków action*).

Takie podejście jest czytelne i pozwala precyzyjnie kontrolować, co i kiedy się dzieje.

Bezpieczne aktualizacje: motyw potomny i kontrola wersji

Aby chronić zmiany, korzystaj z motywu potomnego (child theme), gdy to możliwe. Pliki override TPL i zasobów trzymaj w motywie, a nie w katalogu modułu. Wersjonuj zmiany w repozytorium. To zmniejsza ryzyko konfliktów przy aktualizacji motywu lub modułów i ułatwia powrót do poprzedniego stanu.

Tworzenie i używanie własnych hooków

Dodanie hooka z poziomu panelu administracyjnego

Możesz dodać własny hook w Projekcie > Pozycje, wybierając opcję utworzenia nowego hooka. Nadaj mu nazwę techniczną (bez spacji, z prefiksem display lub action, zgodnie z przeznaczeniem) i tytuł. Następnie:

• Wywołaj go w szablonie motywu, np. {hook h=’displayMyCustomArea’} w odpowiednim miejscu TPL.
• Podłącz moduł do nowego hooka na stronie Pozycje lub przez kod (registerHook).

To szybki sposób na umieszczenie własnych bloków w motywie bez hakowania istniejących miejsc.

Definiowanie hooka w module i wywołanie w PHP

Jeśli potrzebujesz hooka akcji lub bardziej zaawansowanej integracji:

• Podczas instalacji modułu zarejestruj niestandardowy hook przez add or registerHook.
• Wywołaj go w kodzie PHP przez odpowiednią funkcję wykonującą hook (np. Hook::exec), podając nazwę i parametry.
• Inne moduły mogą podpiąć się do tego hooka, rozszerzając Twoją funkcjonalność.

To buduje elastyczną architekturę i ułatwia współpracę wielu modułów.

Dobre praktyki nazewnictwa i parametrów

Stosuj spójne nazwy: displayCoGdzie (dla widoków) i actionCoKiedy (dla zdarzeń). Przekazuj parametry w tablicy, dokumentuj je w komentarzach i dbaj o domyślne wartości. Dzięki temu inni deweloperzy zrozumieją Twoją integrację i łatwiej ją rozszerzą.

Zgodność wersji i motywów

Nie każdy motyw wywołuje wszystkie hooki. Jeśli Twój hook nie pojawia się w widoku, sprawdź, czy TPL zawiera jego wywołanie. Dodatkowo, w różnych wersjach PrestaShop (1.6, 1.7, 8.x) zmieniają się nazwy części hooków i układy sekcji. Warto sprawdzić dokumentację motywu i listę dostępnych hooków dla danej wersji.

Diagnostyka i rozwiązywanie problemów

Jak znaleźć, który hook rysuje dany element

Metody identyfikacji:

• Sprawdź źródło strony i klasy CSS; często zawierają nazwy modułów.
• Włącz tryb deweloperski i użyj paska debugowania, by zobaczyć, które moduły się renderują.
• Przeszukaj pliki motywu pod kątem wystąpień {hook h=’…’}.
• Sprawdź w panelu Projekt > Pozycje, czy moduł jest podpięty do podejrzanego hooka.

To zwykle wystarcza, by zlokalizować właściwe miejsce.

Najczęstsze kłopoty i szybkie naprawy

Brak widocznych zmian po edycji:

• Wyczyść pamięć podręczną i wymuś kompilację TPL.
• Upewnij się, że edytujesz kopię TPL w motywie, a nie oryginał w modules.
• Zweryfikuj, czy plik override ma prawidłową ścieżkę i nazwę.

Zduplikowany element:

• Moduł może być podpięty jednocześnie do kilku hooków; usuń zbędne powiązanie na stronie Pozycje.
• Motyw mógł wywołać dodatkowy hook o podobnej funkcji; sprawdź TPL.

Konflikty CSS/JS:

• Ustal kolejność modułów; czasem JS wymaga inicjalizacji po HTML innego modułu.
• Unikaj globalnych stylów nadpisujących siatkę motywu.
• Zadbaj o izolację selektorów i namespacing zdarzeń JS.

Problemy wydajnościowe:

• Minimalizuj liczbę modułów w ciężkich hookach (header, footer).
• Ładuj skrypty warunkowo i tylko tam, gdzie są potrzebne.
• Włącz mechanizmy optymalizacji i buforowania po zakończeniu prac.

Profilowanie i pomiar czasu

Gdy sklep spowalnia, profiluj:

• W trybie deweloperskim sprawdź czasy renderowania hooków i modułów.
• Zmniejsz obciążenie ciężkich hooków (np. usuwając nadmiarowe karuzele, trackery).
• Optymalizuj zapytania w modułach, korzystaj z paginacji i indeksów w DB.

Monitoruj metryki Core Web Vitals po każdej zmianie layoutu i zasobów.

Lista kontrolna przed wdrożeniem na produkcję

Przed publikacją:

• Sprawdź, czy wszystkie zmiany są w motywie/override, nie w rdzeniu.
• Przetestuj ścieżki zakupowe, logowanie, wyszukiwanie, koszyk i kasę.
• Włącz ustawienia produkcyjne optymalizacji i wydajność sklepu.
• Zweryfikuj responsywność (mobile/desktop) i dostępność (ARIA, kontrast).
• Utwórz kopię zapasową po zaakceptowanych poprawkach.

Praktyczne wskazówki utrzymaniowe

Planuj cykliczne przeglądy hooków i podpiętych modułów. Usuwaj nieużywane moduły z ciężkich hooków (header, home). Dokumentuj zmiany: jakie pliki TPL nadpisano, jakie hooki dodano i dlaczego. Ustal wewnętrzne standardy nazewnictwa i struktur katalogów w motywie, by każdy członek zespołu wiedział, gdzie szukać konkretnych elementów.

Jeśli pracujesz zespołowo, uzgodnij zasady commitów, code review i testów automatycznych (np. smoke-testy ścieżek zakupowych). To zmniejsza ryzyko regresji i ułatwia skalowanie sklepu wraz z rozwojem oferty i ruchu.