PrestaShop Entity Selector: reguły wyboru i bezpieczna integracja

Wybierz encje i metody wyboru

Używaj Entity Selector, gdy moduł potrzebuje zapisanej reguły wyboru, na przykład produktów z kategorii z określonymi wykluczeniami. Wyszukuj i wybieraj pojedyncze rekordy lub zdefiniuj warunek sprawdzany względem aktualnego katalogu.

Moduł osadzający komponent decyduje, których bloków encji i metod możesz użyć. Obecność dostawcy w pakiecie współdzielonym nie udostępnia każdej encji w każdym formularzu.

Wybór odwiedzających opisuje warunki dotyczące odwiedzającego sprawdzane podczas działania. Nie jest obietnicą eksportu identyfikowalnych anonimowych kupujących. Wartości atrybutów, wartości cech i tagi służą też jako elementy wyszukiwane dla warunków produktów. Moduły mogą rejestrować dodatkowych dostawców.

Metody produktów obejmują konkretne produkty, kategorie, producentów, dostawców, tagi, wartości atrybutów lub cech, kombinacje, stan produktu, widoczność, zapasy i status aktywności. Metody wzorców obejmują pola takie jak nazwa, indeks produktu i opis. Metody zakresowe obejmują identyfikatory, cenę, wagę, ilość, pozycję i daty. Dopasowywanie wzorców obsługuje symbole wieloznaczne * i opcję rozróżniania wielkości liter. Dostępność metod i akceptowane wartości zależą od wybranego bloku.

Twórz grupy, wykluczenia i modyfikatory wyników

Każda grupa ma warunek włączenia, opcjonalne wykluczenia i opcjonalne modyfikatory. Grupy produktów łączą się operatorem OR. Wykluczenia należą do grupy, w której je wpisano: inna grupa może ponownie uwzględnić ten sam produkt.

Na przykład wybierz produkty z kategorii 3, wyklucz produkty 42 i 99, posortuj od najnowszych i zachowaj dziesięć. Druga grupa może niezależnie wybierać pięć konkretnych produktów. Jej limit nie zmienia limitu pierwszej grupy.

Przy ustalaniu typowanych celów produktowych kolejność jest następująca: włączenie, opcjonalne filtrowanie i rozwinięcie kombinacji, wykluczenia, deduplikacja, sortowanie i limit grupy. Następnie grupy są scalane po kolei, z zachowaniem pierwszego wystąpienia każdego celu. Możesz też przekazać modyfikatory bloku do resolveTargets(), aby posortować lub ograniczyć scalony wynik po zastosowaniu osobnych ustawień grup.

Obsługiwane pola sortowania produktów obejmują identyfikator, nazwę, cenę, ilość, indeks produktu, datę utworzenia, datę modyfikacji, pozycję w kategorii i sprzedaż. Limit zerowy lub pominięty oznacza brak limitu grupy w granicach zasobów resolvera. Miarodajny resolver typowanych celów odrzuca sortowanie losowe.

Sortowanie według ceny produktu w tym resolverze używa ceny bazowej produktu w sklepie bez podatku, powiększonej o wpływ wybranego wariantu, bez rabatów i przeliczania walut. Sortowanie według sprzedaży używa ilości brutto z prawidłowych zamówień w bieżącym sklepie. Znaczenie tych wartości może różnić się od kolumn cen wyświetlanych w selektorze.

Odróżniaj produkty od kombinacji

Identyfikator produktu i identyfikator kombinacji określają różne obiekty, nawet jeśli ich liczby są takie same. Zachowaj to rozróżnienie przy zapisie i wykonywaniu wyboru.

Miarodajnym API produktów jest ProductConditionResolver::resolveTargets($groups, $expansionMode, $maxTargets = 10000, $modifiers = []). Każdy zwrócony element ma wyłącznie klucze id_product i id_product_attribute z wartościami całkowitymi. Identyfikator atrybutu równy zero oznacza cel będący produktem.

Użyj expand, gdy chcesz uwzględnić warianty produktu z wyjątkiem jednej konkretnej kombinacji. Wykluczenie produktu nadrzędnego usuwa jego reprezentowane warianty w tej grupie. Wykluczenie dokładnej kombinacji usuwa tylko ten wariant. Dokładne wykluczenie nie może odjąć jednego wariantu od produktu nadrzędnego, który nigdy nie został rozwinięty.

Ustalanie celów sprawdza przynależność produktu i kombinacji oraz powiązanie z bieżącym sklepem. Traktuj status nieaktywności zgodnie z wybraną metodą: jawnie wskazany istniejący produkt może zachowywać się inaczej niż wybór aktywnych produktów dokonywany przez all.

Sprawdź podgląd reguły i wybierz układ

Wyniki wyszukiwania mogą pokazywać metadane, takie jak miniatury produktów, indeksy, zapasy i ceny. Wybrane elementy pojawiają się jako etykiety. Liczniki i stronicowane podglądy pomagają sprawdzić regułę przed zapisem. Dokładny zestaw kolumn zależy od encji i konfiguracji modułu osadzającego.

Aby uzyskać liczbę produktów istotną dla wykonania bez modyfikatorów bloku, użyj previewTargets() z tymi samymi grupami, trybem rozwinięcia i limitem celów co w resolveTargets(). Licznik uwzględnia modyfikatory grup, ale nie przyjmuje dodatkowych modyfikatorów bloku. Gdy wykonanie używa modyfikatorów bloku, policz i podziel na strony wynik tego samego wywołania resolveTargets(). Stronicowanego podglądu selektora nie należy traktować jako pełnego zbioru elementów używanych przy wykonaniu.

Do etykiet używaj integracji tłumaczeń modułu osadzającego i sprawdzaj obsługiwane języki. Nadaj każdemu selektorowi na stronie unikalny identyfikator i nazwę pola wejściowego. Tryb prosty może przedstawiać pusty lub prosty wybór konkretnych elementów jako wyszukiwarkę i etykiety z przyciskiem Więcej opcji. Używaj trybu pełnego, gdy formularz wymaga natychmiast widocznych warunków, wykluczeń lub modyfikatorów.

Zintegruj komponent z kontrolerem panelu administracyjnego

Zachowaj zgodność renderowania, kierowania żądań i wykonania. API komponentu używa MyPrestaRocks\EntitySelector\Component\EntitySelector. Istniejące integracje oparte na traitach używają MyPrestaRocks\EntitySelector\EntitySelector.

1. Zadeklaruj dokładnie te encje, które udostępnia formularz. Gdy pominięto entities, komponent domyślnie wybiera produkty.
2. Zarejestruj zasoby podczas setMedia() po wywołaniu metody nadrzędnej. Wyrenderuj selektor z zapisanymi danymi.
3. Jeśli selektor jest ładowany przez AJAX, zwróć jego mapę getClientConfigPayload() razem z HTML, aby klient mógł zarejestrować konfigurację.
4. Kieruj żądania selektora do handleAjax() lub handleEntitySelectorAjax() starszego traita.
5. Zapisuj i waliduj przesłany wybór przez standardową ścieżkę zapisu formularza osadzającego.
6. Ustalaj wyniki we właściwym sklepie i języku podczas działania funkcji.

Używaj EntitySelectorRequest::isAddressed() do rozpoznawania żądań trait=EntitySelector. Obsługiwane są zarówno treści JSON, jak i zwykłe żądania formularzy. Tekst wyszukiwania używa entity_query. Zaadresowane żądanie zwraca JSON i kończy działanie; tylko żądanie spoza przestrzeni nazw selektora zwraca false.

Jeśli dodajesz autoryzację specyficzną dla modułu osadzającego według akcji, odczytaj EntitySelectorRequest::action(), autoryzuj tę wartość i przekaż tę samą wartość do funkcji obsługi. Dispatcher obsługuje wyłącznie trasy tylko do odczytu: wyszukiwanie, hydratację, liczenie i podgląd. Nie zapisuje konfiguracji funkcji modułu.

Starsze integracje oparte na traitach wywodzą uprawnienia kierowania żądań z bieżących deklaracji bloków. Zachowaj spójność tych deklaracji dla żądań renderowania i AJAX. Dostawca zarejestrowany w innym miejscu nie upoważnia do użycia niezadeklarowanej encji.

Waliduj zapisany JSON i egzekwuj uprawnienia

Ukryte pole formularza przenosi JSON nadający się do serializacji. Zachowaj blok encji, grupy, metodę włączenia, wartości, wykluczenia i modyfikatory. Poniższy przykład wybiera do dziesięciu produktów z kategorii 3 z wykluczeniem produktu 42.

{
  "products": {
    "groups": [
      {
        "name": "Category selection",
        "include": {"method": "by_category", "values": [3]},
        "excludes": [{"method": "specific", "values": [42]}],
        "modifiers": {"limit": 10, "sort_by": "date_add", "sort_dir": "DESC"}
      }
    ]
  }
}

Waliduj strukturę JSON i wartości specyficzne dla metod na serwerze. Odrzucaj nieznane klucze, nieobsługiwane metody i nieprawidłowe zakresy. Ukryte pole po stronie klienta można edytować w przeglądarce, więc autoryzuj przesłany wybór na serwerze.

Zachowaj standardowe uwierzytelnianie administratora PrestaShop, tokeny i kontrole dostępu kontrolera osadzającego. Entity Selector dodatkowo ogranicza encje do deklaracji serwera i sprawdza dostęp do ich ekranów w panelu administracyjnym. Dostęp do wyszukiwania i podglądu nie daje uprawnienia do zapisywania, usuwania ani zmieniania wybranych encji.

Zapisuj przez standardowe kontrole uprawnienia do edycji i CSRF formularza. Przekazuj jawny zakres sklepu i języka do ustalania wyników podczas działania. Zachowuj tożsamość kombinacji i obsługuj pusty lub nieudany wynik bez cichego poszerzania go do wszystkich produktów.

Testuj razem moduł korzystający z komponentu i pakiet

Selektor jest komponentem współdzielonym. Aktualizacja pakietu przynosi korzyść modułowi korzystającemu z niego dopiero wtedy, gdy moduł otrzyma i załaduje zaktualizowany pakiet. Testuj wersje rzeczywiście dołączone do modułu i obsługiwane przez jego środowisko PrestaShop i PHP.

• Zapisz, wczytaj ponownie i edytuj jawny wybór oraz grupę warunkową.
• Sprawdź wykluczenia, kolejność i limity poszczególnych grup na znanych rekordach.
• Przetestuj produkty i kombinacje z takimi samymi identyfikatorami liczbowymi.
• Sprawdź więcej niż jeden selektor na tej samej stronie i każdy używany układ.
• Przetestuj pracownika, który może przeglądać, ale nie edytować, oraz żądanie niezadeklarowanej encji.
• Przetestuj granice multistore, usunięte rekordy i rekordy spoza wybranego sklepu.
• Porównaj miarodajny podgląd z celami używanymi przez rzeczywistą funkcję.

Ponownie ustalaj wyniki, gdy wykonanie wymaga aktualnego składu katalogu. Zapisana reguła warunkowa może prawidłowo dawać inne wyniki po zmianie zapasów, kategorii lub produktów. Jeśli funkcja wymaga utrwalonego wyboru, jawnie określ zasady takiej migawki w module korzystającym z komponentu.