Instrukcja instalacji, konfiguracji i wdrożenia modułu Kowal TrustedUs
Cel modułu
Kowal TrustedUs to uniwersalny moduł Magento 2 do prezentowania firm, klientów, partnerów, dostawców, marek i case studies w sklepie.
Moduł może być używany jako:
- sekcja "Zaufali nam",
- lista partnerów lub dostawców,
- portfolio realizacji,
- baza case studies,
- sekcja pokazująca zastosowania produktów,
- narzędzie wzmacniające linkowanie wewnętrzne w sklepie.
Po najnowszej rozbudowie widgety mogą prowadzić do wewnętrznych stron case study, np.:
/trusted-us/vitcas
Na takiej stronie wyświetlane są wpisy z tej samej grupy oraz przypisane do nich produkty.
Wymagania
Przed instalacją upewnij się, że sklep spełnia wymagania:
- działa na Magento 2,
- ma dostęp do Composer,
- ma dostęp do repozytorium modułu,
- ma skonfigurowany token GitHub, jeśli repozytorium jest prywatne,
- ma możliwość uruchamiania komend
bin/magento,
- ma wykonany backup kodu i bazy danych przed wdrożeniem produkcyjnym.
Instalacja przez Composer
1. Dodanie repozytorium Composer
W katalogu głównym Magento uruchom:
composer config repositories.kowal.trusted.us vcs https://github.com/kowalco/trusted-us
2. Dodanie tokena dostępu
Jeśli repozytorium jest prywatne, dodaj token GitHub:
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
3. Instalacja modułu
composer require kowal/module-trustedus
4. Włączenie modułu
Nazwa modułu Magento:
Kowal_TrustedUs
Włącz moduł:
php bin/magento module:enable Kowal_TrustedUs
5. Aktualizacja schematu bazy danych
php bin/magento setup:upgrade
Ta komenda utworzy lub zaktualizuje tabele modułu, w tym pole group_slug używane do wewnętrznych stron case study.
6. Czyszczenie cache
php bin/magento cache:flush
Instalacja w trybie produkcyjnym
Na środowisku produkcyjnym zalecany jest standardowy proces wdrożeniowy Magento.
Przykładowa sekwencja:
composer require kowal/module-trustedus
php bin/magento module:enable Kowal_TrustedUs
php bin/magento setup:upgrade --keep-generated
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
Jeśli sklep ma własny pipeline CI/CD, powyższe kroki należy dopasować do procesu wdrożeniowego sklepu.
Aktualizacja istniejącej instalacji
Jeśli moduł jest już zainstalowany, zaktualizuj go przez Composer:
composer update kowal/module-trustedus
Następnie uruchom:
php bin/magento setup:upgrade
php bin/magento cache:flush
W trybie produkcyjnym:
php bin/magento setup:upgrade --keep-generated
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
Konfiguracja w panelu administracyjnym
Przejście do listy firm
Po instalacji przejdź w panelu Magento do:
Content -> Zaufali nam -> Firmy
W zależności od konfiguracji menu wpis może być też dostępny w sekcji:
Trusted Us -> Firmy
Dodanie firmy lub case study
Dodając nowy wpis, uzupełnij podstawowe dane:
- Nazwa firmy - nazwa klienta, partnera, dostawcy, marki lub projektu.
- Adres strony (URL) - opcjonalny adres zewnętrzny; obecnie widgety linkują wewnętrznie, jeśli wpis ma ustawiony slug grupy.
- Grupa case study / slug URL - globalny slug używany do grupowania wpisów i budowania linku wewnętrznego.
- Nazwa projektu - tytuł realizacji lub opisowego case study.
- Krótki opis projektu - treść prezentowana przy wpisie.
- Ikona - logo firmy lub marki.
- Aktywna - decyduje, czy wpis jest widoczny na froncie.
- Pokaż w widgecie wyróżnionych firm - decyduje, czy wpis trafi do widgetu wyróżnionego.
- Kolejność - sortowanie wpisów.
- Products - produkty powiązane z wpisem.
Konfiguracja grupowania i linków wewnętrznych
Pole Grupa case study / slug URL służy do połączenia kilku wpisów tej samej firmy na jednej wewnętrznej stronie.
Przykład:
vitcas
Wszystkie aktywne wpisy z takim samym slugiem będą widoczne na stronie:
/trusted-us/vitcas
Jeśli wpiszesz wartość ze spacjami lub wielkimi literami, moduł zapisze ją jako bezpieczny slug.
Przykład:
Tandem Baits
zostanie zapisane jako:
tandem-baits
Konfiguracja powiązanych produktów
W sekcji Powiązane produkty / moduły wybierz produkty, które mają być przypisane do danej firmy, realizacji lub case study.
Te powiązania są używane w dwóch miejscach:
- na karcie produktu, gdzie moduł może pokazać powiązane firmy lub realizacje,
- na stronie case study
/trusted-us/{slug}, gdzie produkty są prezentowane w gridzie podobnym do kategorii produktów.
W edycji strony CMS, strony głównej, landing page lub bloku CMS dodaj widget:
Kowal: Zaufali nam
Dostępne parametry:
- Tytuł - nagłówek sekcji.
- Limit - maksymalna liczba wyświetlanych wpisów.
- Pokaż nazwę projektu - czy pod logo ma być widoczna nazwa projektu.
Jeśli wpis ma uzupełnione pole group_slug, kliknięcie w logo prowadzi na wewnętrzną stronę:
/trusted-us/{slug}
Jeśli group_slug jest pusty, wpis pozostaje bez linku.
W edycji CMS dodaj widget:
Kowal: Zaufali nam - wyróżnione firmy
Dostępne parametry:
- Nagłówek - główny tekst sekcji.
- Limit - maksymalna liczba wyświetlanych wpisów.
Widget pokazuje tylko aktywne wpisy, które mają zaznaczone:
Pokaż w widgecie wyróżnionych firm
Tak samo jak widget standardowy, może linkować do wewnętrznych stron case study na podstawie pola group_slug.
Sekcja na karcie produktu
Jeśli produkt ma przypisane firmy lub case studies, moduł może automatycznie pokazać sekcję na karcie produktu.
Sekcja prezentuje:
- logo firmy,
- nazwę firmy,
- nazwę projektu,
- krótki opis projektu.
To pozwala pokazać realne użycie produktu i wzmocnić wiarygodność oferty.
Strony case study
Strony case study są dostępne pod adresem:
/trusted-us/{slug}
Przykład:
/trusted-us/vitcas
Na stronie wyświetlane są:
- wszystkie aktywne wpisy z tym samym
group_slug,
- opisy case studies,
- logo firmy,
- produkty przypisane do każdego wpisu,
- grid produktów podobny do gridu kategorii.
Te strony zwiększają liczbę linków wewnętrznych i tworzą dodatkową ścieżkę:
widget -> case study -> produkt
Obsługa wielu store view
Moduł obsługuje treści zależne od store view dla pól:
- nazwa projektu,
- krótki opis projektu.
Pola globalne, takie jak nazwa firmy, logo, status aktywności, sortowanie, powiązane produkty i group_slug, są wspólne dla całego wpisu.
Katalog mediów
Logo są zapisywane w katalogu:
pub/media/kowal/trustedus/
Przed wdrożeniem upewnij się, że katalog pub/media jest poprawnie współdzielony lub synchronizowany między środowiskami, jeśli sklep działa w architekturze wieloserwerowej.
Checklist wdrożeniowy
Przed wdrożeniem:
- wykonaj backup bazy danych,
- wykonaj backup kodu lub upewnij się, że wdrożenie jest odtwarzalne z repozytorium,
- sprawdź dostęp do repozytorium Composer,
- sprawdź token GitHub, jeśli jest wymagany,
- zaplanuj okno wdrożeniowe, jeśli sklep działa produkcyjnie.
Po wdrożeniu:
- uruchom
setup:upgrade,
- wyczyść cache,
- w trybie produkcyjnym uruchom kompilację DI i deployment static content,
- sprawdź, czy moduł jest aktywny,
- dodaj lub edytuj testową firmę,
- ustaw
group_slug,
- przypisz produkt,
- dodaj widget na testowej stronie CMS,
- kliknij w logo i sprawdź stronę
/trusted-us/{slug},
- sprawdź, czy grid produktów wyświetla produkty przypisane do case study,
- sprawdź kartę produktu z przypisanymi wpisami.
Komendy diagnostyczne
Sprawdzenie statusu modułu:
php bin/magento module:status Kowal_TrustedUs
Sprawdzenie listy modułów Kowal:
php bin/magento module:status | grep Kowal
Czyszczenie cache:
php bin/magento cache:flush
Ponowna kompilacja DI:
php bin/magento setup:di:compile
Najczęstsze problemy
Sprawdź, czy wpis ma uzupełnione pole:
Grupa case study / slug URL
Element bez group_slug nie jest linkowany do wewnętrznej strony.
Strona /trusted-us/{slug} nie działa
Sprawdź:
- czy istnieje aktywny wpis z danym
group_slug,
- czy uruchomiono
setup:upgrade,
- czy wyczyszczono cache,
- czy moduł
Kowal_TrustedUs jest aktywny.
Produkty nie pojawiają się na stronie case study
Sprawdź:
- czy produkty są przypisane do wpisu firmy,
- czy produkty są aktywne,
- czy produkty są widoczne w katalogu lub wyszukiwarce,
- czy produkty są dostępne w aktualnym store view.
Zmiany nie są widoczne po wdrożeniu
Wyczyść cache Magento:
php bin/magento cache:flush
W trybie produkcyjnym wykonaj również:
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
Deinstalacja
Wyłączenie modułu:
php bin/magento module:disable Kowal_TrustedUs
php bin/magento setup:upgrade
php bin/magento cache:flush
Usunięcie paczki Composer:
composer remove kowal/module-trustedus
Przed usunięciem modułu z produkcji należy sprawdzić, czy sklep nie korzysta z widgetów, bloków CMS lub treści zależnych od modułu.