Astra FAQ 1.3.1 dla PrestaShop

0. Szybki start

Najbezpieczniejsza kolejność wdrożenia modułu to wybór trybu zarządzania, dodanie testowych pytań i dopiero potem przypisywanie ich do miejsc na froncie.

1. Wgraj moduł i wyczyść cache PrestaShop / Smarty.
2. Wybierz sposób zarządzania FAQ: tematy legacy albo kategorie i pytania osobno.
3. Uzupełnij tytuły i podstawowe ustawienia strony FAQ dla wszystkich języków.
4. Dodaj testową kategorię/temat FAQ oraz pytanie z odpowiedzią w PL i EN.
5. Przypisz pytanie do produktu, kategorii, koszyka, CMS albo checkoutu.
6. Sprawdź wyświetlanie na froncie i dopiero potem dodawaj kolejne wpisy.
7. W multistore sprawdź sklep ID 1 i pozostałe sklepy bez duplikowania danych.

1. Tryby zarządzania FAQ

Moduł ma dwa sposoby pracy. Aktywna jest tylko jedna ścieżka, a druga jest wygaszona i przekierowuje do właściwego trybu.

AdminAstraFaqTopics

AdminAstraFaqCategories
AdminAstraFaqQuestions

1.1. Przekierowania między trybami

2. Ustawienia modułu

Poniżej jest rozpiska najważniejszych sekcji konfiguracji i tego, co realnie robią na froncie oraz w panelu administracyjnym.

2.1. Zarządzanie FAQ

2.2. Publiczna strona FAQ

2.3. Wygląd FAQ

2.4. Hooki i miejsca automatyczne

2.5. SEO

3. Pola wielojęzyczne

Pytania, odpowiedzi, tytuły, opisy i wprowadzenie nad pytaniami są multilang.

• Przy polach językowych widoczny jest znacznik języka, np. PL, EN, DE.
• Pytanie powinno mieć uzupełnioną treść w każdym aktywnym języku sklepu.
• Jeżeli treść w aktualnym języku jest pusta, moduł używa fallbacku: aktualny język → domyślny język PrestaShop → język ID 1 → pierwszy język, w którym pytanie i odpowiedź są uzupełnione.
• Wprowadzenie nad pytaniami też ma oddzielne pola dla języków.

4. Multistore

FAQ jest globalne dla całego multistore. Nowe przypisania są wspólne, a stare przypisania zapisane dla sklepu ID 1 są traktowane jako wspólne.

4.1. Widoczność pytania w sklepach

4.2. Dlaczego koszyk może działać inaczej w multistore

W jednym sklepie koszyk może mieć URL /koszyk?action=show, a w drugim /cart?action=show. Moduł nie opiera się tylko na polskim slugu, tylko rozpoznaje koszyk po kilku sygnałach:

• php_self / nazwa kontrolera, jeśli PrestaShop poprawnie ją ustawi.
• REQUEST_URI, np. /cart?action=show albo /koszyk?action=show.
• controller, controller_name, page_name.
• Klasy strony ze Smarty, jeżeli motyw je udostępnia.

4.3. Jak działa odczyt przypisań w multistore

Front zawsze najpierw szuka bezpośrednich przypisań pytań w astra_faq_item_binding. Dopiero gdy nie znajdzie żadnego pasującego pytania, robi fallback do legacy przypisań tematów w astra_faq_binding.

5. Pytania i przypisania

W nowym trybie każde pytanie ma treść, odpowiedź, aktywność, pozycję oraz przypisania do miejsc wyświetlania.

5.1. Podstawowe pola pytania

5.2. Typy przypisań

6. Strona FAQ i liczniki

6.1. Publiczna strona FAQ

Moduł ma publiczną stronę FAQ, domyślnie pod adresem:

/faq

Adres można zmienić w ustawieniu Friendly URL.

6.2. Liczniki otwarć

Moduł zlicza tylko ręczne kliknięcia użytkownika. Nie zwiększa licznika, gdy pytanie jest otwarte automatycznie przez ustawienie widoku.

7. Produkty i kategorie

7.1. Produkty

FAQ do produktów można przypisać przez wyszukiwarkę produktów w edycji pytania. Sposób podpisywania produktów w panelu zależy od ustawienia formatu etykiety.

7.2. Kategorie

FAQ do kategorii przypisujesz przez wyszukiwarkę kategorii. W konfiguracji można ustawić, czy FAQ ma pojawiać się tylko na pierwszej stronie paginacji kategorii.

8. Koszyk

Koszyk może działać automatycznie przez hooki albo ręcznie przez customowy hook w tpl.

8.1. Automatyczne hooki koszyka

8.2. Ręczne miejsce w koszyku

Jeżeli klient chce konkretne miejsce w tpl, wklej:

{hook h='displayAstraFaq' page='cart'}

Pytanie musi mieć zaznaczone przypisanie do koszyka.

9. Checkout

Checkout działa ręcznie. To celowe, bo motywy checkoutu różnią się strukturą i automatyczne hooki były nieczytelne.

9.1. Hooki do wklejenia w tpl

9.2. Przykład na dole order confirmation

Wklej wewnątrz bloku page_content_container, najlepiej przed końcowym {/block}:

{block name='astrafaq_order_confirmation'}
  <section id="content-astrafaq-order-confirmation" class="card card_trans mb-3">
    <div class="card-block">
      {hook h='displayAstraFaq' page='checkout-step4'}
    </div>
  </section>
{/block}

10. CMS

CMS może działać przez standardowy hook CMS albo przez customowy hook wklejony w tpl strony CMS.

10.1. Standardowy hook CMS

displayCMSDisputeInformation

Jeżeli motyw renderuje ten hook, moduł pobierze aktualne id_cms i pokaże FAQ przypisane do tej strony CMS.

10.2. Customowy hook CMS w tpl

Dla CMS o ID 1 wklej:

{hook h='displayAstraFaq' page='cms-1'}

Dla CMS o ID 7:

{hook h='displayAstraFaq' page='cms-7'}

11. Blog / STBlog

FAQ może być przypisane do wpisu blogowego po ID wpisu. Dla modułu STBlog / Transformer hook wkleja się bezpośrednio w szablonie artykułu, gdzie dostępna jest zmienna $blog.id.

11.1. Hook do artykułu blogowego

W szablonie artykułu blogowego, np. w pliku artykułu STBlog, wklej w wybranym miejscu:

{hook h='displayAstraFaq' page="blog-{$blog.id}"}

Najczęściej można go wkleić po treści artykułu, np. po:

<div class="blog_content style_content m-b-1">
  {hook h='displayStBlogContent'}
  {$blog.content nofilter}
</div>

Przykład z FAQ pod treścią artykułu:

<div class="blog_content style_content m-b-1">
  {hook h='displayStBlogContent'}
  {$blog.content nofilter}
</div>

{hook h='displayAstraFaq' page="blog-{$blog.id}"}

11.2. Przypisanie pytania

W edycji pytania w polu Blog dodaj ID wpisu blogowego. Dla wpisu ID 15 moduł będzie szukał przypisania blogowego 15, a hook użyje klucza blog-15.

12. Strony statyczne i strony modułów

12.1. Strony statyczne PrestaShop

Przykładowe klucze stron statycznych:

contact
stores
sitemap
new-products
best-sales
prices-drop

Customowe miejsce w tpl:

{hook h='displayAstraFaq' page='contact'}

12.2. Strony modułów i custom URL

Przykład strony ostatnio oglądanych produktów:

module/stlovedproduct/myloved

Customowy hook:

{hook h='displayAstraFaq' page='module/stlovedproduct/myloved'}

12.3. Automatyczne dopasowanie przez page.tpl

{block name='astrafaq_page_content_bottom'}{if isset($page.page_name) && $page.page_name}{hook h='displayAstraFaq' page=$page.page_name}{/if}{/block}

Moduł pobierze wartość $page.page_name i porówna ją z przypisaniami FAQ. Dla strony kontaktu wartość contact odpowiada przypisaniu strony statycznej contact.

Moduł normalizuje każdy klucz PrestaShop module-NAZWAMODULU-KONTROLER do module/NAZWAMODULU/KONTROLER, np. module-stlovedproduct-myloved do module/stlovedproduct/myloved. Własny URL jest zapisywany jako identyfikator strony w bazie przypisań.

13. SEO i rich snippets

Moduł może generować dane strukturalne FAQPage oraz kontrolować meta dane strony FAQ.

14. Wdrożenie i diagnostyka

14.1. Checklist po aktualizacji

• Wyczyść cache PrestaShop i Smarty.
• Wejdź w instrukcję w module i sprawdź, czy nie ładuje listy pytań.
• Sprawdź aktywny tryb zarządzania i przekierowania między kontrolerami.
• Dodaj pytanie testowe w PL i EN.
• Sprawdź produkt, kategorię, CMS, koszyk i stronę modułu.
• W checkout wklej hook ręcznie w odpowiedni template.
• W multistore sprawdź sklep ID 1 i sklep ID 2 bez duplikowania pytań.

14.2. Gdy FAQ nie wyświetla się w koszyku na multistore

1. Sprawdź, czy pytanie ma przypisanie do koszyka.
2. Sprawdź, czy pytanie jest aktywne.
3. Sprawdź, czy pole widoczności sklepów jest puste albo zawiera aktualny ID sklepu.
4. Sprawdź, czy w konfiguracji zaznaczony jest hook koszyka renderowany przez motyw.
5. Jeżeli używasz fallbacku displayFooter, sprawdź, czy URL koszyka jest rozpoznawany jako cart / koszyk.

14.3. Czego nie powinno być w kodzie

stare globalne aliasy SQL
robocze wyjścia diagnostyczne
stare warianty parametru widget
zbędne helpery PrestaShop i DB
debug po IP