# Raggruppare Prodotti come Varianti in PrestaShop: Documentazione del Modulo (dfproductlinker)

> Il modulo DF ProductLinker (dfproductlinker) collega schede prodotto distinte per mostrarle come un unico articolo con un selettore di colore, taglia o qualsiasi altro attributo. Ogni variante resta un prodotto…

- Pagina: <https://www.datafirefly.com/it/documentation/dfproductlinker/>
- Lingua: it
- Aggiornato il: 2026-09-23
- Altre lingue: [fr](https://www.datafirefly.com/documentation/dfproductlinker/index.md), [en](https://www.datafirefly.com/en/documentation/dfproductlinker/index.md), [es](https://www.datafirefly.com/es/documentation/dfproductlinker/index.md), [de](https://www.datafirefly.com/de/documentation/dfproductlinker/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfproductlinker/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfproductlinker/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfproductlinker/index.md)
- Indice: <https://www.datafirefly.com/it/documentation/llms.txt>

Il modulo **DF ProductLinker** (dfproductlinker) collega schede prodotto distinte per mostrarle come un unico articolo con un selettore di colore, taglia o qualsiasi altro attributo. Ogni variante resta un prodotto completo con il proprio URL. È il movimento inverso di [DF ProductSplitter](https://www.datafirefly.com/it/product/separer-declinaisons-en-produits-prestashop/), che divide un prodotto con combinazioni in prodotti separati.

## Installazione

1. Scaricate lo ZIP dal vostro account cliente DataFirefly.
2. Nel back-office, andate in _Moduli > Gestione moduli > Carica un modulo_ e inviate lo ZIP.
3. All'installazione, il modulo crea le sue tabelle e la scheda _Catalogo > Varianti collegate_.
4. Aprite la configurazione del modulo per verificare la posizione del selettore.

Il modulo funziona su PrestaShop 8.0 - 9.x con lo stesso ZIP, in multinegozio e multilingua. I testi sono forniti in francese, inglese, spagnolo, tedesco, italiano, olandese, polacco e portoghese.

Durante un aggiornamento il modulo svuota la cache di Smarty. Se il negozio è impostato su _Non ricompilare mai i template_ e la visualizzazione non cambia, svuotate la cache da _Parametri avanzati > Prestazioni_.

## Principio: gruppi e assi

Un **gruppo** riunisce più prodotti. Un **asse** è un gruppo di attributi nativo di PrestaShop, ad esempio Colore o Taglia: valori, colori esadecimali, texture e traduzioni inseriti in _Catalogo > Attributi e caratteristiche_ vengono riutilizzati così come sono. Ogni prodotto del gruppo riceve un valore su ciascun asse.

Un prodotto può appartenere a un solo gruppo. I prodotti non vengono modificati: il gruppo è salvato nelle tabelle del modulo.

## Creare un gruppo

Andate in _Catalogo > Varianti collegate_ poi _Aggiungi un gruppo_.

1. Inserite il **nome del gruppo**. Serve internamente e come nome di riserva nei dati strutturati.
2. In **Assi**, cliccate su _Aggiungi un asse_. Il modulo propone prima un gruppo di attributi di tipo colore. Per ogni asse scegliete la **visualizzazione** (automatica, campione colore, miniatura foto del prodotto, pulsante di testo, menu a tendina) e la **proprietà dei dati strutturati** (colore, taglia, materiale, fantasia o non dichiarata).
3. In **Prodotti del gruppo**, cercate i prodotti per nome, riferimento o ID. Le frecce della tastiera e il tasto Invio selezionano un risultato. I prodotti già presenti in un altro gruppo sono in grigio.
4. Per ogni prodotto verificate il valore di ciascun asse. È precompilato quando compare nel nome del prodotto. Un valore mancante è evidenziato in arancione e la riga di stato sotto la tabella indica quanti prodotti sono interessati, o se due prodotti hanno gli stessi valori.
5. Salvate. Il modulo vi avvisa se lasciate la pagina con modifiche non salvate.

L'ordine delle righe del gruppo è l'ordine dei campioni nel negozio. Il pulsante _Ordina secondo l'ordine degli attributi_ dispone le righe nell'ordine definito nel catalogo, utile per le taglie S, M, L, XL.

## Cosa vede il cliente

Su ogni scheda del gruppo, il selettore mostra il nome dell'asse e il valore corrente, ad esempio _Colore: Rosso_, poi i valori disponibili. Al passaggio del mouse l'etichetta mostra il valore puntato. Il valore corrente è evidenziato; gli altri sono link alla scheda corrispondente.

- Con più assi, un clic su un colore apre il prodotto che mantiene la taglia corrente. Se quella combinazione non esiste, il modulo apre la variante più vicina privilegiando un prodotto disponibile, e il campione è disegnato con bordo tratteggiato.
- Una variante esaurita è sbiadita e barrata, oppure nascosta secondo l'impostazione.
- Un valore di colore senza codice esadecimale né texture è mostrato come testo in un campione allungato.
- Il selettore compare anche nella quick view delle pagine di categoria, sopra il pulsante di aggiunta al carrello.

## Impostazioni del modulo

- **Posizione del selettore**: prima del blocco nativo delle combinazioni (consigliata), dopo questo blocco, nell'hook `displayProductAdditionalInfo` o solo nell'hook del tema `displayDfProductLinker`.
- **Selettore CSS del blocco nativo delle combinazioni**: per impostazione predefinita `.product-variants, .product__variants`. Se nel vostro tema nulla corrisponde, il selettore resta nell'hook.
- **Etichetta dell'asse**, **prezzo di ogni variante** (modalità immagine e pulsante), **formato immagine** delle miniature.
- **Varianti esaurite**: sbiadite o nascoste.
- **Colore di accento**, **forma** (rotonda o quadrata con angoli arrotondati) e **dimensione** dei campioni. La dimensione media offre un'area tattile di 44 px, consigliata su mobile.
- **Campioni negli elenchi prodotti**, numero massimo di campioni e **cambio immagine al passaggio del mouse**.
- **Un solo prodotto per gruppo**, visibilità degli altri prodotti e prodotto mostrato: vedere la sezione seguente.
- **URL canonico delle varianti** e **dati strutturati ProductGroup**: vedere la sezione SEO.

Per un posizionamento su misura, scegliete la posizione _hook del tema_ e aggiungete questa riga nel template prodotto del vostro tema: `{hook h='displayDfProductLinker' product=$product}`.

## Un solo prodotto per gruppo nelle categorie

Questa opzione mostra una sola miniatura per gruppo negli elenchi di categoria. Gli altri prodotti del gruppo passano alla visibilità _Solo ricerca_ (o _Da nessuna parte_ secondo l'impostazione): le loro schede restano online con il proprio URL e i campioni della miniatura rimandano a esse.

- **Prodotto mostrato**: il primo del gruppo o il primo disponibile. Nel secondo caso viene ricalcolato a ogni movimento di stock.
- La visibilità originale di ogni prodotto viene salvata. È ripristinata quando disattivate l'opzione, disattivate il gruppo, togliete un prodotto dal suo gruppo o disinstallate il modulo.
- Se modificate a mano la visibilità di un prodotto nascosto, il vostro valore diventa il nuovo valore originale.
- Il pulsante _Risincronizza la visibilità_ della configurazione riapplica la regola a tutti i gruppi. Usatelo se un dipendente senza permessi sul modulo ha modificato dei prodotti, perché in quel caso PrestaShop non esegue gli hook del modulo.

Prima di attivare l'opzione, verificate che il generatore di sitemap includa i prodotti con visibilità _Solo ricerca_, altrimenti le varianti nascoste uscirebbero dalla sitemap.

## SEO: dati strutturati e URL canonico

Il modulo aggiunge su ogni scheda del gruppo un blocco JSON-LD `ProductGroup` con `hasVariant` e `variesBy`. Ogni variante vi compare con nome, URL, riferimento, EAN13 se valido, immagine, valore su ciascun asse, prezzo mostrato al cliente e disponibilità. Il nome del gruppo è ricavato dal nome del prodotto senza i suoi valori, nella lingua del visitatore. Disattivate l'opzione se un altro modulo genera già questo blocco.

Per impostazione predefinita ogni variante mantiene un URL canonico verso se stessa: ogni colore è indicizzato separatamente. Se le schede colore sono quasi identiche, l'opzione _Canonico verso il prodotto principale del gruppo_ fa puntare il canonico di tutte le varianti al prodotto principale, cioè il prodotto mostrato negli elenchi se l'opzione un solo prodotto per gruppo è attiva, altrimenti il primo prodotto attivo del gruppo.

## Assistente di raggruppamento automatico

Dall'elenco dei gruppi, cliccate su _Assistente di raggruppamento automatico_. Individua i prodotti che sono lo stesso articolo in più colori o taglie.

1. Scegliete una categoria o tutto il catalogo.
2. Spuntate i gruppi di attributi da rilevare, ad esempio Colore e Taglia. I valori devono esistere come valori di attributo e comparire nel nome del prodotto.
3. Scegliete la regola: nomi identici una volta rimossi i valori, oppure riferimenti con la stessa radice (TSH01-RED e TSH01-BLUE).
4. Cliccate su _Anteprima_, togliete la spunta ai gruppi da ignorare, poi _Crea i gruppi selezionati_.

I prodotti già presenti in un gruppo sono ignorati e l'analisi copre 5.000 prodotti per esecuzione.

## Importazione ed esportazione CSV

Il pulsante _Importa / esporta CSV_ apre la pagina dedicata. L'esportazione produce una riga per prodotto, nello stesso formato dell'importazione. Colonne:

```
group_id;group_name;group_active;axes;product_id;product_reference;product_name;values
;T-shirt Basic;1;Colore|Taglia;;TSH01-NAVY-M;;Colore:Blu navy|Taglia:M
```

- Un gruppo è riconosciuto tramite `group_id`, altrimenti tramite il nome esatto. Ogni gruppo presente nel file viene sostituito dalle sue righe; i gruppi assenti non vengono modificati.
- Un prodotto viene trovato tramite `product_id`, altrimenti tramite `product_reference`, che deve essere unico nel catalogo. `product_name` è informativo.
- `values` contiene coppie Asse:Valore separate da `|`, con i nomi dei gruppi di attributi e dei valori in qualsiasi lingua del negozio.
- Il separatore `;` o `,` è rilevato automaticamente. File UTF-8, massimo 5 MB.

L'importazione avviene in due passaggi: _Analizza il file_ mostra i gruppi creati o sostituiti, i valori di attributo che saranno creati e ogni riga scartata con il motivo; _Avvia l'importazione_ la esegue. Due opzioni: _Sposta i prodotti che appartengono già a un altro gruppo_ e _Crea i valori di attributo mancanti_ (il loro colore resta vuoto, da completare nel catalogo).

## Scheda prodotto del back-office

Nella scheda Moduli della pagina prodotto, il riquadro DF ProductLinker indica il gruppo del prodotto e il valore di ogni prodotto del gruppo, con un link per modificare il gruppo. Se il prodotto non è in alcun gruppo, un link crea un gruppo a partire da questo prodotto.

## Domande frequenti

### Il selettore non compare su una scheda

Verificate che il gruppo sia attivo, che la scheda faccia parte del gruppo, che almeno due prodotti del gruppo siano attivi e che almeno un asse abbia due valori diversi. Se avete scelto la posizione hook del tema, l'hook `displayDfProductLinker` deve essere presente nel template prodotto.

### Il selettore compare sotto il pulsante del carrello

Il selettore CSS del blocco nativo delle combinazioni non corrisponde ad alcun elemento del vostro tema. Indicate la classe del blocco combinazioni del vostro tema nella configurazione.

### I campioni non compaiono negli elenchi

L'opzione deve essere attiva e il primo asse del gruppo deve essere mostrato come campione colore o miniatura foto. Il tema deve richiamare l'hook nativo `displayProductListReviews` nella miniatura prodotto, come fa il tema Classic.

### Posso combinare il modulo con le combinazioni native?

Sì. Un caso frequente: un prodotto per colore, ciascuno con combinazioni di taglia. Il selettore del modulo gestisce i colori, il blocco nativo gestisce le taglie.
