Czym są PrestaShop JS events i gdzie działają

W front office PrestaShop od wersji 1.7 działa globalny obiekt prestashop. To event bus oparty na wzorcu publish/subscribe: jeden fragment kodu (core, moduł albo motyw) emituje zdarzenie, a inne fragmenty się w nie wpinają. Nic nie trzeba instalować — obiekt jest dostępny na każdej podstronie sklepu razem z metodami emit() i on(). Najprostszy test: otwórz konsolę przeglądarki na karcie produktu i wpisz typeof prestashop. Jeśli zwróci object, mechanizm jest dostępny; jeśli undefined, Twój motyw go nie ładuje i żaden listener nie zadziała.

Kodu szukaj w plikach motywu — core.js oraz theme.js w motywie classic. Pełną listę zdarzeń w konkretnym sklepie zobaczysz, wyszukując w katalogu motywu frazę prestashop.emit. Zdarzenia dotyczą tego, co dzieje się bez przeładowania strony, czyli przede wszystkim ruchu AJAX-owego:

• koszyka — dodanie, usunięcie, zmiana ilości, minikoszyk i licznik w nagłówku,
• karty produktu — zmiana kombinacji, ilości, ceny,
• listy produktów — filtrowanie, sortowanie i paginacja przez AJAX,
• quick view — modal z szybkim podglądem produktu,
• filtrów fasetowych, jeśli masz włączony moduł wyszukiwania fasetowego.

Dwie rzeczy warto wiedzieć, zanim cokolwiek podepniesz. Po pierwsze, mechanizm jest ten sam w PrestaShop 1.7 i 8, ale lista konkretnych zdarzeń i kształt przekazywanych danych zależą od motywu i modułów — nie istnieje jedna uniwersalna lista, która zadziała w każdym sklepie. Po drugie, motywy zbudowane na page builderach albo mocno przerobione potrafią nie emitować nic poza zdarzeniami z core. Dlatego test na docelowej instalacji jest obowiązkowy, a nie opcjonalny. Przy wdrożeniach PrestaShop sprawdzamy to w pierwszej kolejności, bo od wyniku zależy, czy integrację da się w ogóle napisać w rozsądnym czasie.

Najważniejsze zdarzenia JS w PrestaShop – tabela i zastosowania

Poniższe pięć zdarzeń pokrywa większość wdrożeń, z jakimi mamy do czynienia: odświeżenie koszyka, karta produktu, lista produktów, quick view i fasety. Nazwy są standardowe dla motywu classic, ale przed użyciem potwierdź je w kodzie swojego motywu.

Jak nasłuchiwać zdarzeń: prestashop.on() w praktyce

Podpięcie listenera to kilka linijek, ale dwie pułapki potrafią zjeść pół dnia pracy. Pierwsza: obiekt prestashop tworzy theme.js, więc jeśli Twój skrypt załaduje się wcześniej, w zmiennej będzie undefined. Druga: callback wykonuje się przy każdym zdarzeniu, także wtedy, gdy akurat nie chcesz nic robić.

document.addEventListener('DOMContentLoaded', function () {
  if (typeof prestashop === 'undefined' || typeof prestashop.on !== 'function') {
    return;
  }

  prestashop.on('updateCart', function (event) {
    console.log('updateCart', event);
    // tu Twoja logika, np. odświeżenie własnego licznika
  });
});

Jeżeli theme.js ładuje się z opóźnieniem, sam DOMContentLoaded nie wystarczy — sprawdzenie wypadnie na undefined i listener nigdy się nie podepnie. Rozwiązania są dwa: doładować własny plik JS po theme.js (na przykład przez registerJavascript modułu z pozycją bottom) albo poczekać na obiekt w krótkiej pętli.

function whenPrestashopReady(callback) {
  if (typeof prestashop !== 'undefined' && typeof prestashop.on === 'function') {
    callback();
    return;
  }
  setTimeout(function () { whenPrestashopReady(callback); }, 50);
}

Praktyczne zasady, które oszczędzają problemów na produkcji:

• nie edytuj theme.js bezpośrednio — aktualizacja motywu nadpisze zmiany, a Ty stracisz je bez ostrzeżenia,
• trzymaj logikę w jednym pliku JS zamiast rozrzucać listenery po modułach,
• w callbacku odczytaj dane z event i przekaż je do jednej funkcji, która decyduje, co się stanie,
• pamiętaj, że po odświeżeniu listy produktów przez AJAX ten sam handler może zadziałać wielokrotnie — jeśli sam ładujesz kod dynamicznie, łatwo o duplikaty,
• przed użyciem metody zdejmującej listener sprawdź, czy Twój motyw ją udostępnia; standardowy interfejs to on() i emit().

Jeśli i tak planujesz zmiany w warstwie frontu, zrób je razem z decyzją o motywie — pisaliśmy o tym w artykule o tym, jak wybrać i wdrożyć motyw PrestaShop.

Jak emitować własne zdarzenia i łączyć je z modułem

Własne zdarzenie to najczystszy sposób, żeby moduł i motyw wymieniały dane bez dotykania plików core. Schemat jest zawsze taki sam: PHP rejestruje skrypt i przekazuje konfigurację, JavaScript nasłuchuje, a moduł w odpowiednim momencie wywołuje prestashop.emit('nazwaZdarzenia', dane).

1. Rejestracja skryptu w module. W metodzie hookDisplayHeader() dodaj plik JS przez addJS(), a dane z PHP przekaż przez Media::addJsDef():

public function hookDisplayHeader()
{
    $this->context->controller->addJS($this->_path.'views/js/mymodule.js');
    Media::addJsDef([
        'mymodule' => [
            'ajaxUrl'   => $this->context->link->getModuleLink('mymodule', 'ajax'),
            'threshold' => (float) Configuration::get('MYMODULE_THRESHOLD'),
        ],
    ]);
}

2. Emisja zdarzenia. W pliku JS modułu, po udanej akcji AJAX:

prestashop.emit('mymodule:cartThreshold', { step: 50, reached: true });

3. Odbiór w motywie. W theme.js albo w skrypcie ładowanym z child theme:

prestashop.on('mymodule:cartThreshold', function (payload) {
    var bar = document.querySelector('#free-shipping-bar');
    if (bar) { bar.style.width = payload.step + '%'; }
});

4. Data-atrybuty zamiast zmiennych globalnych. Gdy dane dotyczą konkretnego elementu (próg darmowej dostawy, ID produktu), wypisz je w szablonie: <div id="mymodule-widget" data-threshold="299"></div> i czytaj w JS przez document.getElementById('mymodule-widget').dataset.threshold. Praktyczna zaleta: działa też przy doczytywaniu fragmentów przez AJAX, bo dane jadą razem z HTML-em.

Trzy zasady, które oszczędzają godziny: prefiksuj nazwy zdarzeń nazwą modułu (mymodule:), bo bez tego łatwo o kolizję z motywem; emituj tylko po sprawdzeniu typeof prestashop !== 'undefined'; nie edytuj core ani motywu nadrzędnego — logikę trzymaj w module lub w child theme, co opisujemy przy okazji wyboru i wdrożenia motywu PrestaShop. Szerszy obraz wdrożeń PrestaShop znajdziesz w naszym hubie.

Debugowanie JS events krok po kroku

Zanim zaczniesz grzebać w kodzie, ustal dwie rzeczy: czy zdarzenie w ogóle leci i czy Twój listener jest zarejestrowany w momencie jego emisji. Najszybciej zrobisz to, podmieniając metody event busa na wersje logujące.

(function () {
    var emit = prestashop.emit.bind(prestashop);
    prestashop.emit = function (name, data) {
        console.log('[emit]', name, JSON.parse(JSON.stringify(data || {})));
        return emit(name, data);
    };
    var on = prestashop.on.bind(prestashop);
    prestashop.on = function (name, cb) {
        console.log('[on]', name, cb);
        return on(name, cb);
    };
})();

Kluczowa jest kolejność: snippet musi wykonać się przed rejestracją listenerów motywu, czyli przed theme.js. W DevTools zapisz go jako Snippet i uruchom z włączonym „Disable cache”, albo tymczasowo doładuj własnym modułem w hookDisplayHeader().

Loguj pełny obiekt, nie sklejony string. console.log('[emit]', name, data) pokazuje obiekt rozwijany leniwie — po kliknięciu w konsoli zobaczysz stan z momentu rozwijania, a nie z momentu emisji. Dlatego w snippecie siedzi JSON.parse(JSON.stringify(...)): dostajesz zamrożoną kopię payloadu i widzisz dokładnie, co poleciało.

Breakpoint w Sources. Event Listener Breakpoints tu nie zadziała — to nie zdarzenia DOM, tylko własny bus PrestaShop. Otwórz DevTools → Sources, wciśnij Ctrl+Shift+F i wyszukaj prestashop.emit lub fragment nazwy zdarzenia, np. updateCart. Kliknij w numer linii, żeby ustawić breakpoint, i przejdź przez dodanie produktu do koszyka. Ten sam trik działa dla callbacku — breakpoint w linii z function (payload) {.

Wyłącz minifikację i cache. W PrestaShop: Zaawansowane → Wydajność → wyłącz CCC (Combine, Compress and Cache) oraz cache szablonów i kompilacji. W DevTools: Network → Disable cache, z panelem otwartym przez cały test. Jeśli front stoi za CDN, wyczyść też cache po stronie Cloudflare czy LiteSpeed. Bez tego oglądasz zminifikowany kod sprzed zmian.

Gdzie szukać emisji. themes/<twoj_motyw>/assets/js/theme.js, themes/core.js oraz modules/*/views/js/*.js. W wersjach produkcyjnych szukaj po fragmencie nazwy zdarzenia, nie po spacjach. Nazwy zdarzeń i konwencje frontowe opisuje dokumentacja deweloperska PrestaShop.

Najczęstsze pułapki i jak je wykryć

1. Zdarzenie nie odpala, bo motyw go nie emituje. Najczęstsza przyczyna w sklepach na motywie custom: ktoś wyciął fragment theme.js. Sprawdź Ctrl+Shift+F w DevTools frazą prestashop.emit('updateCart'. Jeśli w całym załadowanym froncie nie ma ani jednego wystąpienia, żaden listener nie zadziała — trzeba dopisać emisję we własnym module po swojej akcji AJAX.

2. Listener dodany przed załadowaniem prestashop. Objaw: Uncaught TypeError: Cannot read properties of undefined (reading 'on') albo brak reakcji, gdy skrypt modułu wykona się przed core.js. Rejestruj listener w DOMContentLoaded i sprawdzaj typeof prestashop. Kolejność ładowania kontroluj parametrami addJS() w swojej wersji PrestaShop — a jeśli nie jesteś pewien, oprzyj się na zdarzeniu DOM i nie zgaduj.

3. Duplikaty listenerów po kolejnych żądaniach AJAX. Jeśli rejestrujesz listener wewnątrz funkcji obsługującej odpowiedź, każde dodanie produktu do koszyka dokłada kolejny callback. Wykryjesz to licznikiem: window.__hits = (window.__hits || 0) + 1; w środku callbacku. Trzy kliknięcia i licznik pokazuje 3 zamiast 1 — masz duplikat. Rejestruj raz, poza funkcją AJAX, albo zabezpiecz flagą.

4. Cache i minifikacja ukrywają zmiany. Klasyk: „w pliku mam poprawkę, w przeglądarce stary kod”. Sprawdź cztery miejsca: CCC w PrestaShop, cache szablonów, CDN (Cloudflare) i Service Worker z modułu PWA. Szybki test — dopisz ?v=123 do adresu pliku i sprawdź w Network, czy wraca nowa wersja.

5. Różnice między 1.6, 1.7, 8 i motywami custom. PrestaShop 1.6 opierał się na jQuery i ajaxCart, 1.7 i 8 używają event busa z core.js. Motyw custom bywa forkiem theme.js z 1.7 wklejonym do sklepu na 8 — wtedy payload zdarzenia może się różnić od tego, czego oczekujesz. Nigdy nie zakładaj zgodności, porównaj emisję w Sources. Przy planowaniu aktualizacji warto śledzić wydania PrestaShop.

Wydajność, bezpieczeństwo i SEO przy JS events

Event bus jest wygodny, ale każdy listener wykonuje się w tym samym wątku, w którym przeglądarka renderuje stronę. Jeśli w handlerze odpalasz zapytanie AJAX albo przeliczasz całą listę produktów, użytkownik dostaje opóźnioną reakcję na klik, a Google liczy to jako gorszy Core Web Vitals (INP). Trzy zasady, które stosujemy w każdym wdrożeniu:

• Debounce, gdy liczy się stan końcowy. Wyszukiwarka odpalająca żądanie po każdej literze przy 8 znakach generuje do 8 zapytań. Debounce 300 ms zbija to do jednego.
• Throttle, gdy liczy się płynność. scroll i resize odpalają się dziesiątki razy na sekundę; ogranicz do jednego wywołania na klatkę przez requestAnimationFrame albo 100–150 ms.
• Jedna funkcja renderująca. Gdy kilka modułów nasłuchuje tego samego zdarzenia koszyka, każde przerysowanie to osobny reflow. Debounce 250 ms i wspólny render.

Sprzątanie listenerów. Modal, quick view czy widget doklejany AJAX-em może zniknąć z DOM, a listener zostaje. Zanim podepniesz kolejny, zapisz referencję do handlera i wywołaj odpowiednik off() — zweryfikuj nazwę w core.js, bo część motywów nadpisuje ten plik. Jeśli off() nie ma, użyj flagi: w handlerze sprawdzaj document.contains(element) i przerwij, gdy węzła już nie ma.

Nie blokuj renderowania. Nie odpalaj ciężkich obliczeń w momencie kliknięcia „Dodaj do koszyka”; przenieś je po pierwszej klatce. W motywie klienta sprawdź, co dokłada się do theme.js — wybór i wdrożenie motywu wpływa tu bardziej niż sam kod core. Testuj DevTools → Performance (Long tasks powyżej 50 ms) i dane polowe w Search Console.

SEO. Ceny, nazwy i dostępność kombinacji muszą być w HTML. Treści generowane wyłącznie przez JS po interakcji użytkownika (klik w filtr, doładowanie listy) Google może nigdy nie zobaczyć. Nie traktuj eventów jako źródła treści, tylko jako warstwę wygody.

Checklista wdrożeniowa i co dalej

Poniżej kolejność, którą stosujemy przy każdej zmianie w eventach — od debugowania do produkcji.

1. Debug na kopii. Pracuj na stagingu z klonem bazy i plików. Na czas testów wyłącz CCC (Zaawansowane parametry → Wydajność) i cache Smarty; przy włączonej kompresji JS stack trace w konsoli pokazuje linie z pliku zbiorczego, nie z theme.js.
2. Sprawdź liczbę emisji. Podepnij w konsoli tymczasowy nasłuch i policz wywołania przy jednym kliknięciu. Jeśli ten sam handler odpala się trzy razy, masz podwójne podpięcie — typowe, gdy kilka modułów ładuje własny skrypt na różnych hookach.
3. Test na motywie classic. Jest w paczce 1.7 i 8.x i daje szybką odpowiedź, gdzie leży problem. Jeśli działa tam, a nie działa na motywie klienta, szukaj w theme.js i plikach nadpisanych w katalogu motywu.
4. Test na motywie klienta. Te same akcje: dodanie do koszyka, zmiana kombinacji, filtr, quick view — desktop i mobile. Nie poprzestawaj na classicu.
5. Deploy i monitoring. Wgraj pliki z wersjonowaniem (parametr ?v= przy skryptach), wyczyść cache Smarty i przeglądarki, włącz CCC z powrotem. Przez dobę obserwuj konsolę błędów i raport Core Web Vitals.

Po wsparcie zgłoś się, gdy zdarzenie emituje się z plików core, moduł nadpisuje core.js, sklep stoi na 1.6 lub starszym, albo nie masz stagingu do bezpiecznego testu. Nazwy metod i sygnatury zdarzeń weryfikuj w dokumentacji deweloperskiej PrestaShop, zakres prac i stawki opisujemy w cenniku wdrożeń PrestaShop, a punktem startowym jest nasza strona o PrestaShop.

Najczęstsze błędy i jak je wykryć

Lista kontrolna do odklikania

• Ustal wersję PrestaShop i nazwę motywu — Sprawdź w panelu lub w pliku konfiguracyjnym. Od tego zależy, które zdarzenia istnieją i czy motyw je emituje.
• Znajdź miejsce emisji zdarzeń — Przeszukaj theme.js i pliki modułów pod kątem frazy prestashop.emit. Zapisuje nazwy zdarzeń razem z plikiem i linią.
• Wyłącz minifikację i łączenie JS — Zrób to na czas prac w ustawieniach wydajności. Bez tego w DevTools widzisz kod sprzed zmian.
• Dodaj guard na obiekt prestashop — Każdy własny skrypt startuje od sprawdzenia typeof prestashop !== 'undefined'. Testuj to na czystym cache.
• Zaloguj pełny payload zdarzenia — Jednorazowo wypisz cały obiekt event w konsoli, żeby poznać jego strukturę w Twojej wersji i motywie.
• Sprawdź kolejność ładowania skryptów — W Sources potwierdź, że Twój plik wykonuje się po theme.js. Jeśli nie, przenieś podpięcie do DOMContentLoaded.
• Przetestuj zdarzenia koszyka — Dodaj, zmień ilość i usuń produkt. Sprawdź, czy updateCart odpala się raz, a nie kilka razy na jedną akcję.
• Przetestuj kartę produktu i kombinacje — Zmień wariant, ilość i sprawdź reakcję na updatedProduct, w tym aktualizację ceny i dostępności.
• Przetestuj listę produktów i filtry — Użyj sortowania, paginacji i filtrów fasetowych. Sprawdź updateProductList oraz updateFacets po każdym odświeżeniu AJAX.
• Sprawdź quick view i mobile — clickQuickView zachowuje się inaczej na wąskim ekranie. Przetestuj też widok listy z siatką i listą.
• Wykryj duplikaty listenerów — Policz wywołania callbacku po serii kliknięć. Jeśli liczba rośnie, zdejmij stary handler przed rejestracją nowego.
• Sprawdź zachowanie bez JavaScriptu — Kluczowe treści i linki muszą działać także wtedy, gdy JS się nie wykona lub zostanie zablokowany.
• Zmierzyć Core Web Vitals po zmianach — Porównaj INP, LCP i CLS przed wdrożeniem i po nim. Ciężkie listenery najczęściej psują INP.
• Zapisz zmiany poza core — Potwierdź, że cała logika siedzi w child theme lub module, a nie w core.js i theme.js motywu nadrzędnego.

Najczęściej zadawane pytania

Źródła i materiały

• PrestaShop – dokumentacja dla deweloperów
• Google Search Central – tworzenie treści dla ludzi
• Google Search Central – Core Web Vitals
• web.dev – Core Web Vitals
• WooCommerce – dokumentacja