# Box Builder (Mix & Match) — Guida completa > Presentazione Il modulo Box Builder (Mix & Match) (dfboxbuilder) aggiunge una pagina in cui i tuoi clienti compongono la propria box a partire da una selezione di prodotti che hai… - Pagina: - Lingua: it - Aggiornato il: 2026-06-25 - Altre lingue: [fr](https://www.datafirefly.com/documentation/dfboxbuilder/index.md), [en](https://www.datafirefly.com/en/documentation/dfboxbuilder/index.md), [es](https://www.datafirefly.com/es/documentation/dfboxbuilder/index.md), [de](https://www.datafirefly.com/de/documentation/dfboxbuilder/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfboxbuilder/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfboxbuilder/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfboxbuilder/index.md) - Indice: ## Presentazione Il modulo **Box Builder (Mix & Match)** (`dfboxbuilder`) aggiunge una pagina in cui i tuoi clienti **compongono la propria box** a partire da una selezione di prodotti che hai scelto. Scelgono gli articoli da una griglia, seguono una **barra di avanzamento**, vedono il **prezzo aggiornarsi in tempo reale** e aggiungono la box completa al carrello con un solo clic. Ideale per box gourmet, beauty box, cesti, pacchetti «compra 3», abbonamenti scoperta e altro. Crei tutte le box che vuoi, ciascuna con i propri prodotti, le proprie regole (minimo / massimo di articoli) e il proprio **modello di prezzo**. Uno stesso catalogo può alimentare più box molto diverse tra loro. ## Compatibilità - PrestaShop 1.7.6 a 8.x e 9.x - PHP 7.4 a 8.x - Negozio singolo e multinegozio - 5 lingue: FR, EN, ES, DE, IT (completamente tradotto, senza ripiego) - Tema Classic e temi personalizzati (compositore in JavaScript nativo, senza dipendenza da jQuery) - Nessuna dipendenza (né Composer né framework) ## Installazione 1. Nel back office, apri **Moduli > Gestione moduli**. 2. Clicca su **Carica un modulo** e seleziona il file `dfboxbuilder.zip`. 3. Una volta installato, apri la scheda **Box Builder** aggiunta al menu per creare la tua prima box. All'installazione, il modulo crea le sue tabelle, registra i suoi hook (`displayHeader`, `actionFrontControllerSetMedia`, `displayHome` e `actionValidateOrder`) e aggiunge una scheda di amministrazione **Box Builder**. Al primo salvataggio di una box, viene generato automaticamente un **prodotto contenitore nascosto**: porta la riga della box nel carrello e non è visibile nel catalogo. ## Configurare una box Il modulo di modifica di una box è organizzato in cinque schede. ### Scheda Generale - **Nome, descrizione, etichetta del pulsante**: traducibili in tutte le 5 lingue. - **Articoli min / max**: limiti della composizione. Il massimo determina l'obiettivo della barra di avanzamento. - **Consenti duplicati** e **unità max per articolo**: consentono (o no) di aggiungere più volte lo stesso prodotto, con un tetto per prodotto. - **Nascondi prodotti esauriti**: rimuove dalla griglia i prodotti non disponibili (rispettando l'impostazione di esaurimento di ciascun prodotto). - **Attiva «Sorprendimi»** e **Attiva salva e condividi**: mostrano o nascondono queste azioni del cliente. - **Attivo**: pubblica o no la box. ### Scheda Prezzi Sono disponibili quattro modelli di prezzo: - **Prezzo fisso**: un prezzo unico per la box, qualunque sia il contenuto. - **Scaglioni di volume**: il prezzo cambia in base al numero di articoli (es. 3 articoli = 25 €, 6 articoli = 45 €). Definisci tutti gli scaglioni «a partire da X articoli» che servono. - **Somma dei prodotti con sconto**: il prezzo è la somma dei prodotti nella box, meno una percentuale di sconto. - **Prezzo per slot**: ogni slot contribuisce con un prezzo unitario fisso; il totale dipende dagli slot riempiti. Questa scheda gestisce anche la **gamification**: **regalo quando la box è completa** (scelta del prodotto in regalo, aggiunto gratis al carrello) e **spedizione gratuita al completamento**. Il prezzo base / fisso si inserisce **al netto delle imposte**. Il modulo applica poi l'imposta del prodotto contenitore e mostra al cliente il prezzo IVA inclusa. ### Scheda Composizione (fonti e slot) Definisci i **prodotti idonei** che appariranno nella griglia del compositore, tramite due tipi di fonti: - **Prodotti**: aggiunti uno per uno tramite una **ricerca con completamento automatico**. - **Categorie**: tutti i prodotti attivi della categoria diventano idonei. L'opzione **Usa slot per categoria** attiva una composizione «per passi». Ogni slot ha il proprio nome, i propri limiti **min / max**, un eventuale **prezzo dello slot** e le **proprie fonti**. Puoi così richiedere, ad esempio, «2 piatti + 3 contorni + 1 dessert». Senza slot, il cliente sceglie liberamente dalla lista globale. ### Scheda Modelli (box predefinite) Offri **box «pronte all'uso»** che il cliente sceglie con un clic e poi modifica a piacere. Ogni modello ha un nome, una descrizione e un elenco di prodotti (aggiunti tramite ricerca con completamento automatico). Ideale per guidare il cliente indeciso o mettere in evidenza un assortimento best-seller. ### Scheda Vincoli Dichiari **coppie di prodotti incompatibili** che non possono comparire insieme nella stessa box. Il compositore ne impedisce allora la selezione congiunta e la validazione lato server la rifiuta. ## Utilizzo lato cliente ### Il compositore interattivo La pagina di composizione mostra la griglia dei prodotti (immagine, nome, avviso «scorte basse» quando pertinente) e un **pannello riepilogo fisso**: barra di avanzamento, elenco degli articoli scelti, **prezzo calcolato in tempo reale** (chiamata AJAX ottimizzata) e messaggi di validazione. Il pulsante di aggiunta al carrello si attiva solo quando la composizione rispetta tutte le regole. ### Slot per categoria Quando gli slot sono attivati, delle **schede** guidano il cliente da uno slot all'altro, ciascuna con il proprio contatore (per esempio «Piatti 2/3») e la propria selezione di prodotti. ### Sorprendimi Il pulsante **Sorprendimi** riempie automaticamente la box con prodotti idonei, rispettando il massimo di articoli, i limiti di ogni slot e le incompatibilità. Il cliente può poi modificare la selezione proposta. ### Salva e condividi Il cliente può **salvare la propria composizione** e ottenere un **link di condivisione**. Chiunque apra quel link ritrova la box precompilata, pronta da modificare e ordinare. ### Aggiungi al carrello e ordine Al momento dell'aggiunta al carrello, la **composizione viene salvata come personalizzazione** della riga (e resta visibile nel carrello e poi nell'ordine), e viene applicato il **prezzo calcolato della box**. Se la gamification è attiva, il **regalo** viene aggiunto gratis. Alla validazione dell'ordine, il modulo **decrementa lo stock di ogni prodotto componente** della box e registra la vendita per le statistiche. ## Statistiche (back office) La scheda **Statistiche** aggrega le box ordinate: fatturato, numero di ordini, media di articoli per box, performance **per box** e **combinazioni più popolari**. Tutto ciò che serve per individuare i tuoi assortimenti vincenti e affinare le tue fonti. ## Visualizzazione in home page (opzionale) Un blocco home opzionale elenca le tue box attive con un link diretto al loro compositore. La pagina di una box è anche raggiungibile direttamente tramite il suo indirizzo: `index.php?fc=module&module=dfboxbuilder&controller=builder&id_dfbox=ID`. Puoi collegarla dal tuo menu, da una pagina CMS o da un banner. ## Funzionamento tecnico Per ogni box, un **prodotto contenitore nascosto** (visibilità «da nessuna parte», non navigabile) porta la riga nel carrello. Il prezzo della box viene applicato tramite un **prezzo specifico limitato al carrello**, così che il prezzo di catalogo del contenitore non venga mai mostrato. La composizione viene salvata come personalizzazione e lo stock dei componenti viene decrementato alla validazione dell'ordine. Nel modello **Somma con sconto**, se un cliente aggiunge due box della **stessa** definizione con composizioni dal prezzo diverso, l'ultimo prezzo calcolato si applica a entrambe le righe (il prezzo specifico è portato dal prodotto contenitore). Con prezzo **fisso**, **a scaglioni** o **per slot** a parità di numero di articoli, non c'è alcun impatto. L'eliminazione di una box non elimina automaticamente il suo prodotto contenitore nascosto (v1). Se elimini una box di prova, puoi rimuovere manualmente il prodotto contenitore associato dal catalogo. ## FAQ e risoluzione dei problemi ### Il compositore non si visualizza o i pulsanti non rispondono Svuota la cache di PrestaShop (Parametri avanzati > Prestazioni) e, durante i test, disattiva la combinazione/compressione dei file (CCC). Assicurati che la box sia **attiva** e abbia almeno una fonte di prodotti. ### La griglia è vuota Verifica che le fonti (prodotti o categorie) contengano prodotti **attivi** per il negozio corrente. Se «Nascondi prodotti esauriti» è attivato, i prodotti non disponibili non appaiono. ### Il prezzo mostrato non corrisponde alle mie aspettative Controlla il modello di prezzo scelto: il prezzo fisso ignora il contenuto, gli scaglioni dipendono dal numero di articoli, la somma con sconto dipende dal prezzo dei prodotti e il prezzo per slot dipende dagli slot riempiti. Il prezzo base si inserisce al netto delle imposte. ### Lo stock dei componenti non viene decrementato Il decremento avviene alla **validazione dell'ordine** (hook `actionValidateOrder`), non all'aggiunta al carrello. Verifica che l'ordine raggiunga uno stato valido. ### Posso richiedere una struttura precisa (per categorie)? Sì: attiva gli **slot** e definisci per ciascuno un minimo / massimo e le sue fonti. Ottieni una composizione guidata del tipo «2 + 3 + 1». ### È compatibile con PrestaShop 9? Sì. Il modulo è compatibile con PrestaShop 8 e 9, in multinegozio e multilingue (FR, EN, ES, DE, IT).