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.

Konfiguracja widgetu standardowego

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.

Konfiguracja widgetu wyróżnionych firm

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

Widget nie linkuje do strony case study

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.