# Form builder per PrestaShop 8 e 9: documentazione

> DataFirefly Form Builder aggiunge a PrestaShop 8 e 9 un builder di moduli drag & drop. Ogni modulo si mostra nelle posizioni del tema, in una pagina CMS, in una…

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

DataFirefly Form Builder aggiunge a PrestaShop 8 e 9 un builder di moduli drag & drop. Ogni modulo si mostra nelle posizioni del tema, in una pagina CMS, in una finestra popup o in una pagina propria. Le risposte vengono salvate nel back-office, inviate via email ed esportabili in CSV.

## Installazione

1. In **Moduli > Gestione moduli**, clicchi su **Carica un modulo** e trascini il file `dfformbuilder.zip`.
2. In **Servizio clienti** compaiono due menu: **Moduli** e **Risposte ai moduli**.
3. Il pulsante **Configura** del modulo apre le impostazioni generali (vedi sotto) e mostra il numero di moduli e di risposte non lette.

Requisiti: PrestaShop da 8.0.0 a 9.x, PHP 7.2 o superiore. I file inviati dai visitatori sono salvati in `/upload/dfformbuilder/`, che deve essere scrivibile. Il modulo non usa override.

Aggiornamento: installi il nuovo ZIP sopra il precedente. Moduli e risposte vengono conservati e gli script di aggiornamento aggiungono le nuove tabelle.

## Creare un modulo

In **Servizio clienti > Moduli**, clicchi su **Nuovo modulo** e scelga un punto di partenza:

- **Modulo di contatto**: nome, email, oggetto e messaggio. Il campo Riferimento ordine compare solo se l'oggetto riguarda un ordine.
- **Richiesta di preventivo**: privato o azienda (i campi Azienda e Partita IVA compaiono solo per un'azienda), quantità, budget, scadenza, allegati. In una scheda prodotto il nome del prodotto si compila da solo.
- **Candidatura**: tre passaggi (dati di contatto, posizione, documenti), CV obbligatorio e allegato all'email.
- **Modulo vuoto**.

L'elenco dei moduli offre anche **Duplica**, **Esporta** (file JSON) e, nella barra degli strumenti, **Importa**. Un modulo importato viene creato disattivato e senza posizioni di visualizzazione.

## Il builder

La barra in alto contiene il nome interno del modulo, la casella **Attivo**, la **lingua di modifica**, i pulsanti Annulla e Ripristina, **Anteprima** e **Salva**. Sotto ci sono quattro schede: Campi, Impostazioni, Email, Visualizzazione e integrazione.

### Scheda Campi

- **Colonna sinistra**: i tipi di campo. Un clic aggiunge il campo sotto quello selezionato, trascinandolo lo mette dove vuole.
- **Centro**: il modulo come verrà mostrato, con le larghezze reali. I campi si spostano con il drag & drop o con le frecce di ogni scheda, e si possono duplicare o eliminare.
- **Colonna destra**: le impostazioni del campo selezionato.

Scorciatoie: Invio seleziona un campo, Alt + frecce lo sposta, Canc lo elimina, Ctrl+Z annulla, Ctrl+Y ripristina, Ctrl+S salva. Il browser avvisa se lascia la pagina con modifiche non salvate.

### Lingue

Tutti i testi (etichette, aiuti, opzioni, messaggi, email, URL) si inseriscono nella lingua scelta in alto. Un testo lasciato vuoto riprende quello della lingua predefinita del negozio, mostrato in grigio nel campo. Controlli ogni lingua prima di pubblicare.

### Chiave del campo

Ogni campo di inserimento ha una chiave tecnica generata dall'etichetta (ad esempio `email`, `order_reference`). È il nome della colonna nell'esportazione CSV e una variabile nelle email: `{email}`. Deve essere unica nel modulo.

## Tipi di campo

- **Testo, Email, Telefono, Sito web**: testo segnaposto, lunghezza massima, precompilazione. Un indirizzo web scritto senza `https://` viene completato automaticamente.
- **Numero**: minimo, massimo e passo.
- **Testo lungo**: altezza in righe, lunghezza massima con contatore di caratteri per il visitatore.
- **Data**: data più vicina e più lontana, nel formato AAAA-MM-GG o con la parola `today`.
- **Menu a tendina, Pulsanti radio, Caselle di controllo**: opzioni con etichetta per lingua e valore. Il valore viene salvato e usato dalla logica; se vuoto riprende l'etichetta. Il link **Aggiungi più opzioni insieme** accetta un'opzione per riga, nel formato `etichetta|valore` se serve.
- **Consenso**: una casella con un testo che accetta link (informativa privacy).
- **Valutazione a stelle**: da 3 a 10 stelle, salvata come 4/5.
- **Caricamento file**: estensioni ammesse, dimensione massima per file (limitata dall'impostazione globale), più file fino a 10.
- **Campo nascosto**: valore fisso o precompilato, invisibile al visitatore.
- **Titolo, Blocco di testo, Separatore**: solo impaginazione, non viene salvato nulla.
- **Nuovo passaggio**: divide il modulo in passaggi (vedi sotto).

Ogni campo ha una **larghezza**: intera, due terzi, metà o un terzo. I campi più stretti si affiancano sugli schermi grandi e si impilano su mobile.

### Precompilazione

I campi Testo, Email, Telefono e Nascosto possono essere compilati con email, nome, cognome, nome completo o azienda del cliente connesso, nome o riferimento del prodotto (in una scheda prodotto), URL della pagina o un **parametro URL**. Esempio: un campo nascosto precompilato con il parametro `utm_source` e un link a `/contatti?utm_source=newsletter` salvano `newsletter` con la risposta.

### Indirizzo di risposta

Spunti **Usa come indirizzo di risposta** su un campo Email: rispondendo all'email di notifica si scrive direttamente al visitatore.

## Logica condizionale

Nel pannello di un campo, spunti **Mostra o nascondi questo campo in base ad altre risposte** e scelga:

- Mostra o Nascondi questo campo;
- se tutte o almeno una delle condizioni sono soddisfatte;
- ogni condizione: un campo, un operatore (è, non è, contiene, non contiene, è vuoto, è compilato, è maggiore di, è minore di) e un valore.

Per un menu a tendina, pulsanti radio o caselle, il valore si sceglie tra le opzioni. Un campo nascosto non viene controllato, salvato né inviato. La stessa logica viene ricalcolata sul server all'invio.

## Moduli in più passaggi

Aggiunga un elemento **Nuovo passaggio** (gruppo Impaginazione) dove deve iniziare un passaggio e gli dia un titolo. I campi posti prima del primo indicatore formano il primo passaggio. Per il visitatore:

- vengono mostrati una barra di avanzamento e i titoli dei passaggi (disattivabili in Impostazioni > Modulo in più passaggi);
- i pulsanti Avanti e Indietro hanno un testo impostabile per lingua;
- ogni passaggio viene controllato prima di proseguire;
- un passaggio con tutti i campi nascosti dalla logica viene saltato.

## Scheda Impostazioni

- **Titolo e introduzione**: titolo mostrato ai visitatori e testo introduttivo.
- **Invio**: testo del pulsante, messaggio di conferma o reindirizzamento a un URL dopo l'invio.
- **Accesso**: modulo riservato ai clienti connessi (gli altri vedono un link alla pagina di accesso), classe CSS.
- **Disponibilità e limiti**: data di apertura e di chiusura (fuso orario del negozio), numero massimo di risposte, una sola risposta per persona (controllata sull'account cliente e sull'email inserita), messaggio di chiusura.
- **Bozza**: conserva le risposte 30 giorni nel browser del visitatore fino all'invio. Nulla viene trasmesso al negozio prima dell'invio e i file non vengono conservati.

## Scheda Email

### Notifica al negozio

Inviata nella lingua predefinita del negozio. Destinatari separati da virgole; se il campo è vuoto, si usano i destinatari predefiniti della configurazione del modulo, poi l'email del negozio. L'oggetto accetta le variabili `{form_name}` e `{chiave_del_campo}`, che si copiano con un clic. L'opzione **Allega i file caricati** aggiunge i file fino a 15 MB in totale.

### Destinatari condizionali

Ogni regola associa una condizione a degli indirizzi: ad esempio, se _Oggetto_ è _Preventivo_, inviare a `vendite@il-suo-negozio.it`. L'impostazione **Quando una condizione è soddisfatta** aggiunge questi indirizzi ai destinatari o li sostituisce.

### Conferma al visitatore

Richiede un campo Email nel modulo. L'email parte nella lingua usata dal visitatore, con l'oggetto e il messaggio che sceglie (variabili ammesse) e, a scelta, il riepilogo delle risposte.

### Webhook

Inserisca un URL (Zapier, Make, n8n, CRM) per ricevere ogni risposta in JSON tramite una richiesta POST. Esempio di contenuto:

```
{
  "event": "submission.created",
  "form": { "id": 3, "name": "Contatto" },
  "submission": { "id": 128, "date": "2026-09-30T10:12:00+02:00", "language": "it",
    "shop_id": 1, "customer_id": 0, "product_id": 0, "page_url": "https://..." },
  "fields": {
    "email": { "label": "Email", "type": "email", "value": "mario@esempio.it", "display": "mario@esempio.it" }
  }
}
```

Con un **segreto di firma**, l'intestazione `X-DFFB-Signature` contiene `sha256=` seguito dall'HMAC-SHA256 del corpo. Verifica in PHP:

```
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, 'IL_SUO_SEGRETO');
$valid = hash_equals($expected, $_SERVER['HTTP_X_DFFB_SIGNATURE'] ?? '');
```

La chiamata attende al massimo 5 secondi. Il risultato (consegnato, rifiutato con il codice HTTP, nessuna risposta) compare nella scheda di ogni risposta.

## Scheda Visualizzazione e integrazione

### Modalità di visualizzazione

**Direttamente nella pagina** o **dietro un pulsante, in una finestra popup**, con il testo del pulsante per lingua. Questa modalità vale per le posizioni, lo shortcode e il widget.

### Posizioni automatiche

Spunti le posizioni del tema: home page (`displayHome`), pagina contatti (`displayContactContent`, `displayContactRightColumn`), scheda prodotto (`displayProductAdditionalInfo`, `displayFooterProduct`), rassicurazione (`displayReassurance`), carrello (`displayShoppingCartFooter`), pagine CMS (`displayCMSDisputeInformation`), colonne (`displayLeftColumn`, `displayRightColumn`), sopra il footer (`displayFooterBefore`), fondo del contenuto (`displayWrapperBottom`). Una posizione non mostra nulla se il tema non la richiama.

### Pagina dedicata

Ogni modulo può avere la sua pagina, ad esempio `/forms/3-richiesta-di-preventivo`, con un URL semplificato per lingua. Il link **Anteprima** funziona anche con il modulo disattivato; gli invii vengono rifiutati finché non è attivo.

### Codici di integrazione

- Shortcode per pagina CMS: `[dfform id=3]`
- Widget Smarty in un template: `{widget name='dfformbuilder' id_form=3}`
- Hook personalizzato: `{hook h='displayDfForm' id_form=3}`

### Statistiche

Su 30 giorni: visualizzazioni (modulo mostrato o popup aperto), compilazioni iniziate (clic in un campo), risposte, tassi di conversione e di abbandono. I visitatori senza JavaScript e la maggior parte dei bot non vengono contati. Visualizzazioni e tasso di conversione compaiono anche nell'elenco dei moduli.

## Gestire le risposte

**Servizio clienti > Risposte ai moduli** elenca le risposte con il modulo, un riepilogo, lo stato e la data, tutti filtrabili. Azioni di gruppo: segna come letto, gestito, archivia, esporta in CSV, elimina (vengono eliminati anche i file).

Aprendo una risposta, questa passa a Letto e mostra:

- tutte le risposte e i file da scaricare;
- lo stato e una nota interna;
- il cliente (se connesso), il prodotto, la pagina di invio, la lingua, l'indirizzo IP, il risultato dell'email e del webhook;
- i pulsanti Stampa, Rispondi via email, risposta precedente e successiva.

### Rispondere al visitatore

Il pannello **Rispondi al visitatore** invia il suo messaggio all'indirizzo del campo Email (prima quello segnato come indirizzo di risposta), nella lingua usata dal visitatore, con l'impaginazione email del negozio. La risposta resta nello storico e la risposta può passare a Gestito nello stesso momento.

### Esportazione CSV

Il pannello sotto l'elenco esporta per modulo, stato e periodo. Scegliendo un modulo si ottiene una colonna per campo. Il file è in UTF-8 con punto e virgola come separatore e si apre direttamente in Excel, LibreOffice e Google Sheets.

## Impostazioni generali del modulo

- **Destinatari predefiniti**: usati quando un modulo non ha destinatari propri.
- **Dimensione massima dei file** (10 MB predefiniti): limite globale per file. Non può superare `upload_max_filesize` e `post_max_size` di PHP.
- **Conserva le risposte per** (giorni): dopo, le risposte e i loro file vengono eliminati automaticamente. 0 le conserva senza limiti.
- **Salva l'indirizzo IP**: se disattivato, si conserva solo un hash per il limite di invii.
- **Tempo minimo di compilazione** (3 secondi) e **invii all'ora per visitatore** (10): protezioni antibot.
- **reCAPTCHA v3**: chiave del sito, chiave segreta e punteggio minimo (0,5 consigliato). Lo script di Google si carica solo quando il visitatore inizia a compilare il modulo.

## Sicurezza e GDPR

- Ogni modulo contiene un campo trappola invisibile e una firma con data; un invio troppo rapido o oltre il limite viene rifiutato.
- Script, pagine HTML ed eseguibili vengono sempre rifiutati e il contenuto dei file viene controllato. I file vengono rinominati a caso in una cartella protetta e si scaricano solo dal back-office.
- Con il modulo ufficiale **psgdpr**, le risposte di un cliente (account o email inserita) sono incluse nell'esportazione dei suoi dati ed eliminate con il suo account.

## Traduzioni

L'interfaccia del modulo è disponibile in francese e inglese; le altre lingue del back-office la mostrano in inglese. I modelli email del modulo esistono in inglese, francese, tedesco, spagnolo, italiano, olandese, polacco e portoghese. I testi dei moduli stessi si inseriscono in tutte le lingue del negozio.

## Risoluzione dei problemi

### Il modulo non compare

Verifichi che il modulo sia attivo, che il tema richiami la posizione scelta e che le date di apertura non lo chiudano. Nel dubbio, provi lo shortcode in una pagina CMS o la pagina dedicata.

### Le email non arrivano

La scheda della risposta indica se la notifica è partita. Controlli **Parametri avanzati > Email** e invii un'email di prova da PrestaShop.

### Un file viene rifiutato

Controlli l'estensione ammessa nel campo, la dimensione massima del campo e del modulo e i limiti PHP `upload_max_filesize` e `post_max_size`.

### La protezione antispam blocca il modulo

Una pagina rimasta aperta per diverse settimane ha una firma scaduta: il visitatore deve ricaricare la pagina. Se usa reCAPTCHA, verifichi che il dominio sia registrato nella console Google e abbassi il punteggio minimo se vengono bloccati clienti reali.