Product Features - installazione, configurazione e gestione degli attributi

Questo documento descrive la configurazione del modulo kowal/module-product-features, il significato di tutti i campi amministrativi e il lavoro con gli attributi lato prodotto.

Installazione

Il modulo è destinato all'installazione tramite Composer.

composer config repositories.module.product.features vcs https://github.com/kowalco/product-featurescomposer config --global --auth github-oauth.github.com composer require kowal/module-product-featuresbin/magento module:enable Kowal_ProductFeaturesbin/magento setup:upgradebin/magento cache:flush

Dopo il deploy in produzione è necessario eseguire i comandi standard previsti dal progetto, ad esempio compilazione DI e deploy degli asset statici, in base alla modalità operativa di Magento.

Posizione della configurazione

La configurazione del modulo si trova nel pannello amministrativo Magento:

Stores > Configuration > Catalog > Product Features

Le impostazioni dell'aspetto si trovano in un gruppo separato:

Stores > Configuration > Catalog > Product Features Appearance

I campi di configurazione sono disponibili a livello Default, Website e Store View. Grazie a questo, diverse viste del negozio possono avere sezioni caratteristiche o aspetto differenti.

Product Features

Enabled

Abilita o disabilita il modulo per il relativo ambito di configurazione.

Valori:

• Yes - le sezioni delle caratteristiche del prodotto vengono renderizzate nella scheda prodotto,
• No - il modulo non restituisce sezioni e il blocco non appare nel frontend.

Utilizzo: disattivazione rapida del modulo per l'intero negozio, un Website selezionato o uno Store View senza rimuovere la configurazione delle sezioni.

Feature Sections

Elenco delle sezioni renderizzate nella scheda prodotto. Ogni riga definisce una sezione frontend oppure un gruppo di sezioni, se viene utilizzato il tipo cms_blocks.

Enabled

Abilita o disabilita una singola sezione.

Valori:

• Yes - la sezione partecipa al rendering,
• No - la sezione viene ignorata.

Utilizzo: nascondimento temporaneo di una sezione senza eliminarne le impostazioni.

Section Title

Titolo della sezione visibile nella scheda prodotto.

Esempi:

• Caratteristiche del prodotto,
• Applicazione sportiva,
• Specifiche,
• Tecnologie,
• Consegna.

Utilizzo: il nome dovrebbe essere comprensibile per il cliente, non deve necessariamente corrispondere al nome tecnico dell'attributo.

Nota: per il tipo cms_blocks il titolo della sezione figlia viene prelevato dal titolo del blocco CMS.

Attribute Code

Singolo attributo prodotto utilizzato dalla sezione. Il campo ha la forma di un dropdown con l'elenco degli attributi prodotto.

Utilizzo: usa questo campo quando la sezione si basa su un solo attributo, ad esempio sport_usage, blocks_id, material, technology_icon.

Attribute Codes

Elenco di più attributi prodotto utilizzati da una sola sezione. Il campo ha la forma di un multiselect.

Utilizzo: usa questo campo quando una sezione deve aggregare più caratteristiche, ad esempio più scale nella sezione Caratteristiche del prodotto oppure più parametri nella sezione Specifiche.

Esempio: la sezione Caratteristiche del prodotto può contenere gli attributi fit, resistance, stretch e breathability, tutti renderizzati come scale.

Display Type

Definisce il modo di presentare il valore dell'attributo.

Il valore vuoto Auto indica la selezione automatica del renderer:

• blocks_id viene renderizzato come cms_blocks,
• swatch multiselect come swatch_list,
• select con 2 o 3 opzioni come scale,
• select con un numero maggiore di opzioni come selected_label,
• multiselect come text_list,
• boolean come checkmark,
• date come date,
• price come price,
• textarea come text_block,
• image/media_image come image,
• gli altri tipi come text_inline.

Tipi disponibili:

Nel pannello amministrativo alcune voci sono contrassegnate come available in future release. Si tratta di tipi che sono già visibili nell'elenco di configurazione, ma non hanno ancora una propria presentazione frontend finale:

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

Sort Order

Ordine delle sezioni nella scheda prodotto. Un numero più basso significa visualizzazione anticipata.

Utilizzo: imposta le sezioni più importanti all'inizio, ad esempio 10 per le caratteristiche principali, 20 per le applicazioni, 30 per le specifiche.

Default State

Stato iniziale della sezione nella scheda prodotto.

Valori:

• Expanded - la sezione è aperta per impostazione predefinita,
• Collapsed - la sezione è chiusa per impostazione predefinita.

Utilizzo: i contenuti più importanti possono essere mostrati subito, mentre le informazioni di supporto più lunghe possono rimanere chiuse.

Hide Empty

Decide se la sezione deve essere nascosta quando non ci sono dati da mostrare.

Valori:

• Yes - la sezione viene nascosta se il prodotto non ha un valore dell'attributo oppure il renderer non restituisce alcun elemento,
• No - la sezione può restare visibile anche senza elementi.

Utilizzo: nella maggior parte dei casi è consigliato Yes per non mostrare al cliente sezioni vuote.

Appearance Profile

Selezione del profilo di aspetto definito nel campo Appearance Profiles.

Il campo ha la forma di un dropdown. L'amministratore non inserisce più manualmente il codice, ma seleziona un profilo pronto dall'elenco, di solito nel formato code - label.

Utilizzo: consente di assegnare a una sezione specifica un aspetto diverso da quello globale, ad esempio il profilo compact, highlight oppure plain.

Se il campo è vuoto ed è selezionata l'opzione Use global appearance, la sezione usa l'aspetto globale.

Ordine di lavoro consigliato:

1. definisci il profilo in Appearance Profiles,
2. salva la configurazione,
3. torna a Feature Sections,
4. seleziona il profilo nella colonna Appearance Profile per la sezione appropriata.

CSS Class

Classe CSS aggiuntiva aggiunta alla sezione.

Utilizzo: personalizzazione individuale dell'aspetto nel tema frontend, ad esempio product-features-section--technical.

Renderer Options JSON

Impostazioni opzionali passate al renderer in formato JSON.

L'utilizzo dipende dal tipo di presentazione. Esempi:

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

Per number_with_unit:

• unit - unità, ad esempio cm, %, g/m2,
• precision - numero di cifre decimali.

Per range_bar:

• min - valore minimo dell'intervallo,
• max - valore massimo dell'intervallo,
• low_label - etichetta dell'inizio dell'intervallo,
• high_label - etichetta della fine dell'intervallo.

Per rating_dots:

• steps - numero di punti o livelli.

Il tipo radial_chart non richiede opzioni aggiuntive. Il renderer legge il valore dell'attributo oppure l'etichetta dell'opzione nel formato x/y, ad esempio 1/6, 4/6, 7/10.

Esempio per una barra di intervallo:

{'min':0,'max':100,'low_label':'Bassa','high_label':'Alta'}

Esempio per i punti:

{'steps':5}

Nota: il campo deve contenere un JSON corretto. Un valore non corretto viene ignorato dal renderer.

Appearance Profiles

Elenco di profili di aspetto opzionali che possono essere assegnati alle sezioni tramite il campo Appearance Profile.

Code

Codice tecnico del profilo.

Esempi:

• compact,
• highlight,
• plain.

Utilizzo: il codice identifica internamente il profilo ed è usato come valore dell'opzione nel dropdown Appearance Profile della sezione.

Label

Nome descrittivo del profilo visibile all'amministratore.

Utilizzo: facilita il riconoscimento del profilo nella configurazione, ad esempio Compatto, Evidenziato, Neutro. In combinazione con il codice crea un'etichetta leggibile nell'elenco di selezione dei profili in Feature Sections.

Background

Colore di sfondo della sezione per il profilo.

Utilizzo: evidenziazione di sezioni selezionate o adattamento al tema.

Text

Colore del testo principale nella sezione.

Heading

Colore del titolo della sezione.

Accent

Colore dell'accento, ad esempio elementi attivi, punti della scala o evidenziazioni.

Accent Background

Colore di sfondo degli elementi di accento.

Border

Colore di linee, separatori, asse della scala e bordi.

Icon

Colore dell'icona di apertura e chiusura della sezione.

Radius, e.g. 18px

Arrotondamento degli angoli della sezione.

Esempi: 0, 8px, 18px.

Padding, e.g. 28px

Spaziatura interna della sezione.

Esempi: 16px, 24px, 28px.

Label Font Size, e.g. 21px

Dimensione del testo delle etichette delle caratteristiche nella sezione.

Esempi: 16px, 18px, 21px, 1.25rem.

Product Features Appearance

Questo gruppo contiene l'aspetto globale delle sezioni. Le impostazioni vengono convertite in variabili CSS e applicate al wrapper del modulo.

Section Background Color

Colore di sfondo della sezione.

Predefinito: #f4f4f4.

Section Text Color

Colore base del testo nella sezione.

Predefinito: #000000.

Section Heading Color

Colore dell'intestazione della sezione.

Predefinito: #000000.

Muted Text Color

Colore dei testi di supporto e meno importanti.

Predefinito: #555555.

Accent Color

Colore degli elementi attivi e delle evidenziazioni.

Predefinito: #000000.

Accent Background Color

Colore di sfondo degli elementi attivi, ad esempio selezioni.

Predefinito: #ffffff.

Border Color

Colore di bordi, separatori e asse della scala.

Predefinito: #9b9b9b.

Icon Color

Colore dell'icona + / - nell'intestazione della sezione.

Predefinito: #000000.

Selected Text Color

Colore del testo del valore selezionato.

Predefinito: #000000.

Selected Font Weight

Peso del font del valore selezionato.

Predefinito: 700.

Esempi: 400, 500, 600, 700, bold.

Section Border Radius

Arrotondamento del contenitore della sezione.

Predefinito: 18px.

Section Padding

Spaziatura interna della sezione.

Predefinito: 28px.

Section Gap

Spaziatura tra le sezioni.

Predefinito: 16px.

Heading Font Size

Dimensione del font dell'intestazione della sezione.

Predefinito: 20px.

Esempi: 18px, 20px, 1.25rem, clamp(18px, 2vw, 22px).

Label Font Size

Dimensione del font delle etichette delle caratteristiche e delle etichette dei valori.

Predefinito: 21px.

Body Font Size

Dimensione del font del contenuto principale della sezione.

Predefinito: 16px.

Gestione degli attributi lato prodotto

Il modulo non crea un sistema separato di dati prodotto. Utilizza gli attributi prodotto di Magento, quindi la gestione dei contenuti avviene principalmente nella modifica del prodotto.

Modifica di un singolo prodotto

1. Vai a Catalog > Products.
2. Apri il prodotto in modifica.
3. Compila gli attributi utilizzati dalle sezioni del modulo.
4. Se il prodotto deve utilizzare blocchi CMS, vai al gruppo Product Features e imposta il campo CMS Blocks.
5. Salva il prodotto.
6. Svuota la cache, se il progetto lo richiede.

La sezione apparirà nel frontend solo se:

• il modulo è abilitato,
• la sezione è abilitata nella configurazione,
• l'attributo esiste,
• il prodotto ha un valore dell'attributo,
• il renderer è in grado di gestire il valore selezionato,
• la sezione non è stata nascosta da Hide Empty.

Attributo blocks_id / CMS Blocks

Durante setup:upgrade il modulo aggiunge l'attributo prodotto:

• codice: blocks_id,
• etichetta: CMS Blocks,
• tipo: text,
• input: multiselect,
• source model: blocchi CMS attivi,
• backend: backend standard Magento per multiselect,
• scope: Store View,
• gruppo: Product Features,
• visibile nella modifica prodotto,
• disponibile nella griglia prodotti e nel filtro della griglia.

Il campo CMS Blocks consente di assegnare al prodotto blocchi CMS attivi. Ogni blocco selezionato verrà renderizzato come sezione separata, se nella configurazione del modulo esiste una sezione con:

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

Il titolo della sezione nel frontend deriva dal titolo del blocco CMS e il contenuto dal contenuto del blocco. I blocchi non attivi o non disponibili per lo Store View non vengono renderizzati.

Gestione dei blocchi CMS

I blocchi usati da blocks_id vengono creati nel modo standard in Magento:

Content > Elements > Blocks

Raccomandazioni:

• usa titoli chiari per i blocchi, perché possono essere visibili come titoli delle sezioni,
• assegna i blocchi agli Store View corretti,
• imposta il blocco come attivo,
• conserva nei blocchi contenuti descrittivi che devono essere condivisi da molti prodotti, ad esempio consegna, resi, istruzioni, tecnologie.

Modifica massiva dei prodotti

L'attributo blocks_id è preparato per lavorare con la modifica massiva dei prodotti.

1. Vai a Catalog > Products.
2. Seleziona i prodotti nella griglia.
3. Scegli l'azione Update Attributes.
4. Imposta il valore del campo CMS Blocks.
5. Salva le modifiche.

Utilizzo: assegnazione rapida della stessa sezione CMS, ad esempio Consegna, Resi oppure Istruzioni per la cura, a molti prodotti contemporaneamente.

Attributi per la scala

Per il tipo scale usa attributi select con 2 o 3 opzioni attive.

Esempio:

• attributo fit,
• opzioni: Ampio, Regular, Aderente.

Il prodotto dovrebbe avere selezionata una delle opzioni. Il modulo mostrerà tutte le opzioni della scala ed evidenzierà quella assegnata al prodotto.

Se l'attributo ha meno di 2 o più di 3 opzioni, il renderer scale ignorerà questo attributo.

Attributi multiselect

Per elenchi di caratteristiche, applicazioni, tecnologie o certificazioni usa attributi multiselect.

Tipi di presentazione possibili:

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

Il prodotto può avere selezionati più valori. Il modulo renderizza solo i valori assegnati al prodotto.

Swatch Magento

Se l'attributo multiselect utilizza gli swatch Magento, si può usare il tipo swatch_list oppure swatch_grid.

Utilizzo:

• icone delle tecnologie,
• colori,
• pittogrammi di applicazione,
• marcature dei materiali.

Se l'opzione ha uno swatch immagine, il modulo mostrerà l'immagine. Se ha uno swatch colore o testuale, il modulo userà la variante appropriata.

Icone Amasty

Per il tipo multiselect_icon il modulo prova a recuperare l'icona dell'opzione da Amasty ShopbyBrand / ShopbyBase.

Fonte dell'icona:

Shop by Brand > Option Edit > Other > Small Image

Il testo alternativo proviene da Small Image Alt e, se manca, dall'etichetta dell'opzione.

Se Amasty non è installato oppure l'opzione non ha un'icona, il modulo mostrerà solo l'etichetta.

Attributi testuali e HTML

Per informazioni brevi usa text_inline, key_value oppure badge.

Per descrizioni più lunghe usa text_block, accordion_text oppure html_block.

Nota: html_block e accordion_text renderizzano HTML, quindi dovrebbero essere usati esclusivamente per contenuti amministrativi affidabili.

Attributi numerici

Per valori numerici si può usare:

• number_with_unit - quando il numero richiede un'unità,
• range_bar - quando il valore deve essere mostrato come avanzamento in un intervallo,
• rating_dots - quando il valore descrive un livello o una valutazione.

Esempio di Renderer Options JSON per numero con unità:

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

Attributi boolean

Per attributi sì/no usa:

• yes_no, quando il cliente deve vedere sia Yes sia No,
• checkmark, quando la caratteristica deve essere visibile solo se il prodotto la possiede.

Attributi immagine

Per attributi di tipo immagine si può usare:

• image,
• image_with_label,
• image_grid.

Il modulo costruisce l'indirizzo dell'immagine sulla base della directory media prodotto di Magento e usa l'etichetta dell'attributo come testo alternativo.

Configurazione di esempio

Sezione con più scale:

Sezione applicazioni con icone:

Sezioni CMS:

Diagnostica

Se una sezione non appare nel frontend, controlla:

• se Enabled del modulo ha valore Yes,
• se la sezione interessata ha Enabled = Yes,
• se il prodotto ha l'attributo compilato,
• se è stato selezionato il corretto Attribute Code oppure Attribute Codes,
• se Display Type corrisponde al tipo di attributo,
• se Hide Empty non nasconde una sezione vuota,
• se l'attributo è disponibile per il relativo Store View,
• se il blocco CMS è attivo e assegnato allo Store View corretto,
• se la cache Magento è stata aggiornata.