Instrukcja instalacji i konfiguracji Countdown Promotion dla Magento 2

Moduł Kowal_CountdownPromotion dodaje do Magento 2 licznik końca promocji. Licznik może być widoczny na listingu kategorii oraz na karcie produktu, gdy produkt ma aktywną cenę specjalną i ustawioną datę końca promocji.

Widoczny licznik jest tworzony przez JavaScript po załadowaniu strony. Backend przekazuje do frontendu tylko dane techniczne, między innymi ID produktu oraz timestamp końca promocji.

Wymagania

Przed instalacją upewnij się, że sklep spełnia wymagania:

• Magento Open Source lub Adobe Commerce 2.4.x,
• PHP 7.4 albo PHP 8.1+ zgodnie z wersją Magento,
• możliwość instalacji paczek Composer typu magento2-module,
• dostęp do CLI Magento,
• dostęp do repozytorium modułu.

Instalacja przez Composer

Przejdź do katalogu głównego projektu Magento.

Dla repozytorium Git dodaj repozytorium modułu do konfiguracji Composer:

composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
composer config repositories.kowal-countdown-promotion vcs https://github.com/kowalco/countdown-promotion
composer require kowal/module-countdown-promotion

Po instalacji Composer umieści moduł w katalogu:

vendor/kowal/module-countdown-promotion

Włączenie modułu w Magento

Uruchom komendy Magento z katalogu głównego sklepu:

bin/magento module:enable Kowal_CountdownPromotion
bin/magento setup:upgrade
bin/magento cache:flush

Na środowisku produkcyjnym zwykle należy uruchomić również komendy wdrożeniowe używane w projekcie:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento indexer:reindex
bin/magento cache:flush

Konfiguracja produktu

Dla każdego produktu, przy którym ma pojawić się licznik:

1. Ustaw Countdown Promotion na Yes.
2. Ustaw Special Price.
3. Ustaw Special Price To Date.
4. Opcjonalnie ustaw Special Price From Date.

Licznik pojawi się tylko wtedy, gdy spełnione są wszystkie warunki:

• atrybut countdown_promotion jest włączony,
• special_price jest ustawiony,
• cena specjalna jest niższa niż cena regularna,
• special_from_date jest puste albo promocja już się rozpoczęła,
• special_to_date jest ustawione w przyszłości.

Dla produktów konfigurowalnych włącz Countdown Promotion na produkcie nadrzędnym. Moduł może użyć daty promocji z produktu nadrzędnego albo aktywnych dat promocji z powiązanych produktów prostych, gdy promocja jest ustawiona na wariantach.

Konfiguracja modułu

Opcje modułu są dostępne w panelu administracyjnym Magento:

Stores > Configuration > Catalog > Countdown Promotion > Appearance

Po zmianie konfiguracji wyczyść cache:

bin/magento cache:flush

Ustawienia położenia licznika

Pole Category Placement określa położenie licznika na listingu kategorii.

Dostępne opcje:

• Below price - licznik pod ceną,
• Bottom of product image - licznik na dole zdjęcia produktu,
• Top of product image - licznik na górze zdjęcia produktu,
• Custom CSS selector - licznik przy elemencie wskazanym własnym selektorem CSS.

Gdy wybierzesz Custom CSS selector, uzupełnij pole Category Custom CSS Selector. Wybrany element powinien mieć data-product-id albo znajdować się w kafelku produktu, który zawiera .price-box[data-product-id].

Przykładowe selektory:

.price-box[data-product-id]
.product-item-info .price-box[data-product-id]
.product-item-details .price-box[data-product-id]

Pole Product Page Custom CSS Selector dotyczy tylko karty produktu. Wpisz selektor elementu, po którym licznik ma zostać dodany.

Przykłady:

.product-info-main .product-info-price
#custom-price-target

Jeżeli pole jest puste, moduł używa domyślnego selektora:

.product-info-main .price-box

Ustawienia tekstów i formatu czasu

Pole Text Before Countdown ustawia tekst przed licznikiem, na przykład:

Promocja kończy się za:

Jeżeli pole jest puste, etykieta przed licznikiem nie jest wyświetlana, a sama wartość odliczania jest wyśrodkowana.

Pole Text Before End Date ustawia tekst przed datą końca promocji, na przykład:

Promocja do:

Jeżeli pole jest puste, pod licznikiem wyświetlana jest sama data.

Pole Displayed Time Template pozwala wybrać zakres jednostek czasu pokazywanych w liczniku.

Dostępne szablony:

• 00d 00g 00m 00s,
• 00d 00g 00m,
• 00d 00g,
• 00d,
• 00g 00m 00s,
• 00m 00s.

Symbole jednostek czasu można zmienić osobnymi polami:

• Days Symbol, domyślnie d,
• Hours Symbol, domyślnie g,
• Minutes Symbol, domyślnie m,
• Seconds Symbol, domyślnie s.

Przykład: jeżeli ustawisz Hours Symbol na h, licznik może wyświetlić 02d 05h 30m 10s zamiast 02d 05g 30m 10s.

Pokazywanie licznika dopiero przed końcem promocji

Pole Show Countdown Days Before End określa, ile dni przed końcem promocji licznik ma stać się widoczny.

Przykłady:

• puste pole - licznik jest pokazywany od razu po spełnieniu warunków promocji,
• 1 - licznik pojawi się w ostatnim dniu promocji,
• 3 - licznik pojawi się w ostatnich 3 dniach promocji,
• 7 - licznik pojawi się w ostatnich 7 dniach promocji.

Pole przyjmuje liczby całkowite. Wartość pusta oznacza brak ograniczenia.

Ustawienia wyglądu

Moduł pozwala skonfigurować wygląd licznika bez zmian w kodzie.

Dostępne pola:

• Background Color - kolor tła,
• Text Color - bazowy kolor tekstu,
• Label Color - kolor etykiety przed licznikiem,
• Timer Color - kolor wartości odliczania,
• Border Color - kolor obramowania,
• Font Size - rozmiar czcionki.

Pola kolorów używają color pickera i zapisują wartości hex, na przykład:

#ffffff
#333333
#d32f2f

Rozmiar czcionki jest wybierany z listy:

• 12px,
• 14px,
• 16px,
• 18px.

Kontrola po wdrożeniu

Po instalacji i konfiguracji sprawdź:

1. Produkt prosty z aktywną promocją na karcie produktu.
2. Produkt prosty z aktywną promocją na listingu kategorii.
3. Produkt bez aktywnej ceny specjalnej.
4. Produkt z datą Special Price To Date w przeszłości.
5. Produkt z pustym Special Price To Date.
6. Produkt z ceną specjalną równą lub wyższą od ceny regularnej.
7. Konfigurację Show Countdown Days Before End.
8. Różne szablony Displayed Time Template.
9. Zmianę symboli jednostek czasu.
10. Zmianę kolorów i rozmiaru czcionki po wyczyszczeniu cache.
11. Konsolę przeglądarki, czy nie ma błędów JavaScript.
12. Surowe źródło HTML, czy nie zawiera gotowego elementu .countdown-promotion.

Znane ograniczenia

Moduł korzysta z promocji opartych o standardowe pola Magento:

• special_price,
• special_from_date,
• special_to_date.

Reguły katalogowe, Adobe Commerce Scheduled Updates oraz warianty produktów konfigurowalnych z całkowicie niezależnymi datami promocji mogą wymagać osobnej integracji.

Motywy, które mocno zmieniają renderowanie ceny albo strukturę kafelka produktu, mogą wymagać ustawienia własnych selektorów CSS.

Najczęstsze problemy

Licznik nie jest widoczny

Sprawdź, czy:

• produkt ma Countdown Promotion = Yes,
• produkt ma ustawione Special Price,
• cena specjalna jest niższa niż cena regularna,
• Special Price To Date jest ustawione w przyszłości,
• Special Price From Date nie wskazuje przyszłej daty,
• cache Magento został wyczyszczony,
• dla kategorii ustawiony selektor CSS wskazuje właściwy element produktu.

Licznik jest w złym miejscu

Zmień Category Placement albo ustaw własny Category Custom CSS Selector. Na karcie produktu użyj Product Page Custom CSS Selector.

Zmiany wyglądu nie są widoczne

Wyczyść cache Magento:

bin/magento cache:flush

Na produkcji może być potrzebne również odświeżenie statycznych assetów zgodnie z procesem wdrożeniowym sklepu.