Product Features - instalacja, konfiguracja i zarządzanie atrybutami

Ten dokument opisuje konfigurację modułu kowal/module-product-features, znaczenie wszystkich pól administracyjnych oraz pracę z atrybutami po stronie produktu.

Instalacja

Moduł jest przeznaczony do instalacji przez Composer.

composer config repositories.module.product.features vcs https://github.com/kowalco/product-features
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>
composer require kowal/module-product-features
bin/magento module:enable Kowal_ProductFeatures
bin/magento setup:upgrade
bin/magento cache:flush

Po wdrożeniu produkcyjnym należy uruchomić standardowe komendy właściwe dla projektu, np. kompilację DI i deploy statycznych assetów, zgodnie z trybem działania Magento.

Lokalizacja konfiguracji

Konfiguracja modułu znajduje się w panelu administracyjnym Magento:

Stores > Configuration > Catalog > Product Features

Ustawienia wyglądu znajdują się w osobnej grupie:

Stores > Configuration > Catalog > Product Features Appearance

Pola konfiguracji są dostępne na poziomie Default, Website i Store View. Dzięki temu różne widoki sklepu mogą mieć inne sekcje cech albo inny wygląd.

Product Features

Enabled

Włącza lub wyłącza moduł dla danego zakresu konfiguracji.

Wartości:

• Yes - sekcje cech produktu są renderowane na karcie produktu,
• No - moduł nie zwraca sekcji i blok nie pojawia się na frontendzie.

Zastosowanie: szybkie wyłączenie modułu dla całego sklepu, wybranego Website albo Store View bez usuwania konfiguracji sekcji.

Feature Sections

Lista sekcji renderowanych na karcie produktu. Każdy wiersz definiuje jedną sekcję frontendową albo grupę sekcji, jeżeli używany jest typ cms_blocks.

Enabled

Włącza lub wyłącza pojedynczą sekcję.

Wartości:

• Yes - sekcja bierze udział w renderowaniu,
• No - sekcja jest pomijana.

Zastosowanie: tymczasowe ukrycie jednej sekcji bez kasowania jej ustawień.

Section Title

Tytuł sekcji widoczny na karcie produktu.

Przykłady:

• Cechy produktu,
• Zastosowanie Sportowe,
• Specyfikacja,
• Technologie,
• Dostawa.

Zastosowanie: nazwa powinna być zrozumiała dla klienta, nie musi odpowiadać technicznej nazwie atrybutu.

Uwaga: dla typu cms_blocks tytuł sekcji potomnej jest pobierany z tytułu bloku CMS.

Attribute Code

Pojedynczy atrybut produktu używany przez sekcję. Pole ma formę dropdownu z listą atrybutów produktu.

Zastosowanie: użyj tego pola, gdy sekcja opiera się na jednym atrybucie, np. sport_usage, blocks_id, material, technology_icon.

Attribute Codes

Lista wielu atrybutów produktu używanych przez jedną sekcję. Pole ma formę multiselectu.

Zastosowanie: użyj tego pola, gdy jedna sekcja ma agregować kilka cech, np. kilka skal w sekcji Cechy produktu albo kilka parametrów w sekcji Specyfikacja.

Przykład: sekcja Cechy produktu może zawierać atrybuty fit, resistance, stretch i breathability, wszystkie renderowane jako skale.

Display Type

Określa sposób prezentacji wartości atrybutu.

Wartość pusta Auto oznacza automatyczny dobór renderera:

• blocks_id jest renderowany jako cms_blocks,
• swatch multiselect jako swatch_list,
• select z 2 lub 3 opcjami jako scale,
• select z większą liczbą opcji jako selected_label,
• multiselect jako text_list,
• boolean jako checkmark,
• date jako date,
• price jako price,
• textarea jako text_block,
• image/media_image jako image,
• pozostałe typy jako text_inline.

Dostępne typy:

W panelu administracyjnym część pozycji jest oznaczona jako available in future release. Dotyczy to typów, które są już widoczne na liście konfiguracji, ale nie mają jeszcze własnej, docelowej prezentacji frontendowej:

• table,
• badge,
• badge_list,
• icon_value,
• icon_list,
• swatch_grid.

Sort Order

Kolejność sekcji na karcie produktu. Niższa liczba oznacza wcześniejsze wyświetlenie.

Zastosowanie: ustaw najważniejsze sekcje na początku, np. 10 dla cech głównych, 20 dla zastosowań, 30 dla specyfikacji.

Default State

Stan początkowy sekcji na karcie produktu.

Wartości:

• Expanded - sekcja jest domyślnie rozwinięta,
• Collapsed - sekcja jest domyślnie zwinięta.

Zastosowanie: najważniejsze treści można pokazać od razu, a dłuższe informacje pomocnicze zostawić zwinięte.

Hide Empty

Decyduje, czy sekcja ma zostać ukryta, gdy nie ma danych do pokazania.

Wartości:

• Yes - sekcja jest ukrywana, jeżeli produkt nie ma wartości atrybutu albo renderer nie zwróci żadnych elementów,
• No - sekcja może pozostać widoczna nawet bez elementów.

Zastosowanie: najczęściej zalecane jest Yes, aby nie pokazywać klientowi pustych sekcji.

Appearance Profile

Wybór profilu wyglądu zdefiniowanego w polu Appearance Profiles.

Pole ma formę dropdownu. Administrator nie wpisuje już kodu ręcznie, tylko wybiera gotowy profil z listy, zwykle w formacie code - label.

Zastosowanie: pozwala nadać konkretnej sekcji inny wygląd niż globalny, np. profil compact, highlight albo plain.

Jeżeli pole jest puste i wybrana jest opcja Use global appearance, sekcja używa wyglądu globalnego.

Rekomendowana kolejność pracy:

1. zdefiniuj profil w Appearance Profiles,
2. zapisz konfigurację,
3. wróć do Feature Sections,
4. wybierz profil w kolumnie Appearance Profile dla odpowiedniej sekcji.

CSS Class

Dodatkowa klasa CSS dodawana do sekcji.

Zastosowanie: indywidualne dopasowanie wyglądu w motywie frontendowym, np. product-features-section--technical.

Renderer Options JSON

Opcjonalne ustawienia przekazywane do renderera w formacie JSON.

Zastosowanie zależy od typu prezentacji. Przykłady:

{"unit":"cm","precision":1}

Dla number_with_unit:

• unit - jednostka, np. cm, %, g/m2,
• precision - liczba miejsc po przecinku.

Dla range_bar:

• min - minimalna wartość zakresu,
• max - maksymalna wartość zakresu,
• low_label - etykieta początku zakresu,
• high_label - etykieta końca zakresu.

Dla rating_dots:

• steps - liczba kropek lub poziomów.

Typ radial_chart nie wymaga dodatkowych opcji. Renderer czyta wartość atrybutu albo etykietę opcji w formacie x/y, np. 1/6, 4/6, 7/10.

Przykład dla paska zakresu:

{"min":0,"max":100,"low_label":"Niska","high_label":"Wysoka"}

Przykład dla kropek:

{"steps":5}

Uwaga: pole musi zawierać poprawny JSON. Niepoprawna wartość jest ignorowana przez renderer.

Appearance Profiles

Lista opcjonalnych profili wyglądu, które można przypisać do sekcji przez pole Appearance Profile.

Code

Techniczny kod profilu.

Przykłady:

• compact,
• highlight,
• plain.

Zastosowanie: kod identyfikuje profil wewnętrznie i jest używany jako wartość opcji w dropdownie Appearance Profile przy sekcji.

Label

Opisowa nazwa profilu widoczna dla administratora.

Zastosowanie: ułatwia rozpoznanie profilu w konfiguracji, np. Kompaktowy, Wyróżniony, Neutralny. W połączeniu z kodem tworzy czytelną etykietę na liście wyboru profili w Feature Sections.

Background

Kolor tła sekcji dla profilu.

Zastosowanie: wyróżnienie wybranych sekcji lub dopasowanie do motywu.

Text

Kolor podstawowego tekstu w sekcji.

Heading

Kolor tytułu sekcji.

Accent

Kolor akcentu, np. elementów aktywnych, kropek skali albo wyróżnień.

Accent Background

Kolor tła elementów akcentowych.

Border

Kolor linii, separatorów, osi skali i obramowań.

Icon

Kolor ikony rozwijania i zwijania sekcji.

Radius, e.g. 18px

Zaokrąglenie rogów sekcji.

Przykłady: 0, 8px, 18px.

Padding, e.g. 28px

Wewnętrzny odstęp sekcji.

Przykłady: 16px, 24px, 28px.

Label Font Size, e.g. 21px

Rozmiar tekstu etykiet cech w sekcji.

Przykłady: 16px, 18px, 21px, 1.25rem.

Product Features Appearance

Ta grupa zawiera globalny wygląd sekcji. Ustawienia są zamieniane na zmienne CSS i stosowane do wrappera modułu.

Section Background Color

Kolor tła sekcji.

Domyślnie: #f4f4f4.

Section Text Color

Podstawowy kolor tekstu w sekcji.

Domyślnie: #000000.

Section Heading Color

Kolor nagłówka sekcji.

Domyślnie: #000000.

Muted Text Color

Kolor tekstów pomocniczych i mniej istotnych.

Domyślnie: #555555.

Accent Color

Kolor elementów aktywnych i wyróżnień.

Domyślnie: #000000.

Accent Background Color

Kolor tła elementów aktywnych, np. zaznaczeń.

Domyślnie: #ffffff.

Border Color

Kolor obramowań, separatorów i osi skali.

Domyślnie: #9b9b9b.

Icon Color

Kolor ikony + / - w nagłówku sekcji.

Domyślnie: #000000.

Selected Text Color

Kolor tekstu wybranej wartości.

Domyślnie: #000000.

Selected Font Weight

Grubość fontu wybranej wartości.

Domyślnie: 700.

Przykłady: 400, 500, 600, 700, bold.

Section Border Radius

Zaokrąglenie kontenera sekcji.

Domyślnie: 18px.

Section Padding

Wewnętrzny odstęp sekcji.

Domyślnie: 28px.

Section Gap

Odstęp pomiędzy sekcjami.

Domyślnie: 16px.

Heading Font Size

Rozmiar fontu nagłówka sekcji.

Domyślnie: 20px.

Przykłady: 18px, 20px, 1.25rem, clamp(18px, 2vw, 22px).

Label Font Size

Rozmiar fontu etykiet cech i etykiet wartości.

Domyślnie: 21px.

Body Font Size

Rozmiar fontu podstawowej treści sekcji.

Domyślnie: 16px.

Zarządzanie atrybutami po stronie produktu

Moduł nie tworzy osobnego systemu danych produktowych. Korzysta z atrybutów produktu Magento, dlatego zarządzanie treścią odbywa się głównie w edycji produktu.

Edycja pojedynczego produktu

1. Przejdź do Catalog > Products.
2. Otwórz produkt do edycji.
3. Uzupełnij atrybuty, które są używane przez sekcje modułu.
4. Jeżeli produkt ma korzystać z bloków CMS, przejdź do grupy Product Features i ustaw pole CMS Blocks.
5. Zapisz produkt.
6. Wyczyść cache, jeżeli projekt tego wymaga.

Sekcja pojawi się na frontendzie tylko wtedy, gdy:

• moduł jest włączony,
• sekcja jest włączona w konfiguracji,
• atrybut istnieje,
• produkt ma wartość atrybutu,
• renderer potrafi obsłużyć wybraną wartość,
• sekcja nie została ukryta przez Hide Empty.

Atrybut blocks_id / CMS Blocks

Podczas setup:upgrade moduł dodaje atrybut produktu:

• kod: blocks_id,
• etykieta: CMS Blocks,
• typ: text,
• input: multiselect,
• source model: aktywne bloki CMS,
• backend: standardowy backend Magento dla multiselect,
• scope: Store View,
• grupa: Product Features,
• widoczny w edycji produktu,
• dostępny w gridzie produktów i filtrowaniu gridu.

Pole CMS Blocks pozwala przypisać do produktu aktywne bloki CMS. Każdy wybrany blok zostanie wyrenderowany jako osobna sekcja, jeżeli w konfiguracji modułu istnieje sekcja z:

• Attribute Code: blocks_id,
• Display Type: cms_blocks.

Tytuł sekcji na frontendzie pochodzi z tytułu bloku CMS, a treść z zawartości bloku. Bloki nieaktywne albo niedostępne dla Store View nie są renderowane.

Zarządzanie blokami CMS

Bloki używane przez blocks_id tworzy się standardowo w Magento:

Content > Elements > Blocks

Zalecenia:

• używaj jasnych tytułów bloków, ponieważ mogą być widoczne jako tytuły sekcji,
• przypisuj bloki do właściwych Store View,
• ustawiaj blok jako aktywny,
• przechowuj w blokach treści opisowe, które mają być współdzielone przez wiele produktów, np. dostawa, zwroty, instrukcje, technologie.

Masowa edycja produktów

Atrybut blocks_id jest przygotowany do pracy z masową edycją produktów.

1. Przejdź do Catalog > Products.
2. Zaznacz produkty na gridzie.
3. Wybierz akcję Update Attributes.
4. Ustaw wartość pola CMS Blocks.
5. Zapisz zmiany.

Zastosowanie: szybkie przypisanie tej samej sekcji CMS, np. Dostawa, Zwroty albo Instrukcja pielęgnacji, do wielu produktów jednocześnie.

Atrybuty dla skali

Dla typu scale używaj atrybutów select z 2 lub 3 aktywnymi opcjami.

Przykład:

• atrybut fit,
• opcje: Luźny, Regularny, Dopasowany.

Produkt powinien mieć wybraną jedną z opcji. Moduł pokaże wszystkie opcje skali i wyróżni tę przypisaną do produktu.

Jeżeli atrybut ma mniej niż 2 albo więcej niż 3 opcje, renderer scale pominie ten atrybut.

Atrybuty multiselect

Dla list cech, zastosowań, technologii lub certyfikatów używaj atrybutów multiselect.

Możliwe typy prezentacji:

• text_list,
• badge_list,
• swatch_list,
• swatch_grid,
• multiselect_icon,
• icon_list.

Produkt może mieć wybranych kilka wartości. Moduł renderuje tylko wartości przypisane do produktu.

Swatche Magento

Jeżeli atrybut multiselect korzysta ze swatchy Magento, można użyć typu swatch_list albo swatch_grid.

Zastosowanie:

• ikony technologii,
• kolory,
• piktogramy zastosowań,
• oznaczenia materiałów.

Jeżeli opcja ma swatch obrazkowy, moduł pokaże obraz. Jeżeli ma swatch kolorystyczny albo tekstowy, moduł użyje odpowiedniego wariantu.

Ikony Amasty

Dla typu multiselect_icon moduł próbuje pobrać ikonę opcji z Amasty ShopbyBrand / ShopbyBase.

Źródło ikony:

Shop by Brand > Option Edit > Other > Small Image

Tekst alternatywny pochodzi z Small Image Alt, a jeżeli go brakuje, z etykiety opcji.

Jeżeli Amasty nie jest zainstalowane albo opcja nie ma ikony, moduł pokaże samą etykietę.

Atrybuty tekstowe i HTML

Dla krótkich informacji używaj text_inline, key_value albo badge.

Dla dłuższych opisów używaj text_block, accordion_text albo html_block.

Uwaga: html_block i accordion_text renderują HTML, dlatego powinny być używane wyłącznie dla zaufanych treści administracyjnych.

Atrybuty liczbowe

Dla wartości liczbowych można użyć:

• number_with_unit - gdy liczba wymaga jednostki,
• range_bar - gdy wartość ma być pokazana jako postęp w zakresie,
• rating_dots - gdy wartość opisuje poziom lub ocenę.

Przykład Renderer Options JSON dla liczby z jednostką:

{"unit":"%","precision":0}

Atrybuty boolean

Dla atrybutów tak/nie użyj:

• yes_no, gdy klient ma zobaczyć zarówno Yes, jak i No,
• checkmark, gdy cecha ma być widoczna tylko wtedy, gdy produkt ją posiada.

Atrybuty obrazkowe

Dla atrybutów typu obraz można użyć:

• image,
• image_with_label,
• image_grid.

Moduł buduje adres obrazu na podstawie katalogu mediów produktu Magento i używa etykiety atrybutu jako tekstu alternatywnego.

Przykładowa konfiguracja

Sekcja kilku skal:

Sekcja zastosowań z ikonami:

Sekcje CMS:

Diagnostyka

Jeżeli sekcja nie pojawia się na frontendzie, sprawdź:

• czy Enabled modułu ma wartość Yes,
• czy dana sekcja ma Enabled = Yes,
• czy produkt ma uzupełniony atrybut,
• czy wybrano poprawny Attribute Code albo Attribute Codes,
• czy Display Type pasuje do typu atrybutu,
• czy Hide Empty nie ukrywa pustej sekcji,
• czy atrybut jest dostępny dla danego Store View,
• czy blok CMS jest aktywny i przypisany do właściwego Store View,
• czy cache Magento został odświeżony.