Form Widget (Embed Code)

Il Form Widget di Primeforms ti permette di incorporare un modulo all’interno di un sito web usando poche righe di HTML e JavaScript. È il metodo più semplice e affidabile per pubblicare un form su una pagina esterna.

Uno dei vantaggi principali del widget è che il modulo incorporato si aggiorna automaticamente ogni volta che modifichi il form nel builder. Questo significa che non devi rigenerare o sostituire il codice embed a ogni modifica.

Panoramica #

Il Form Widget è progettato per funzionare su qualsiasi pagina web. Il widget crea un iframe in modo dinamico e carica il modulo al suo interno.

Questo approccio offre diversi vantaggi:

• il modulo può adattarsi automaticamente in altezza
• non è necessario aggiornare manualmente il codice a ogni modifica del form
• il form resta isolato da CSS e JavaScript già presenti sul sito
• si riduce il rischio di conflitti con il tema o con altri script della pagina

Quale codice embed usare #

Primeforms può offrire due modalità principali di pubblicazione del modulo:

• Embed con design: pubblica il modulo con il tema applicato nel form builder
• Embed senza design: pubblica il modulo senza tema, anche se nel form è stato configurato uno stile

Nella maggior parte dei casi, conviene usare Embed con design, perché mantiene l’aspetto visivo già definito nel modulo.

L’opzione senza design è utile quando vuoi gestire lo stile direttamente dal sito esterno o integrarlo in un layout molto personalizzato.

Come funziona il codice embed #

Il codice del Form Widget contiene normalmente due parti:

• una parte HTML, che mostra un contenuto di fallback se JavaScript è disabilitato nel browser
• una parte JavaScript, che crea l’iframe, carica il form e inizializza eventuali funzionalità aggiuntive come il tracking

Di default, il fallback HTML mostra un link al modulo dentro un elemento div.

Come popolare un campo tramite query string #

Puoi precompilare i campi del modulo passando valori nell’URL. Per farlo, usa come chiave il Field ID oppure il Field Alias del campo.

Il valore associato a quel parametro verrà mostrato automaticamente nel campo corrispondente.

Esempio concettuale:

• chiave del parametro: ID o alias del campo
• valore del parametro: contenuto da precompilare

Questa funzione è utile, ad esempio, per:

• passare il nome di una campagna
• precompilare un’email o un nome
• associare il form a una pagina o a una sorgente specifica
• personalizzare il flusso in base al link cliccato

Multi-Step Form e parametro pagina #

Se stai usando un form multistep, puoi anche aprire direttamente una pagina specifica del modulo aggiungendo il parametro p all’URL.

Esempio:

• p=2 apre la seconda pagina del modulo

Come ascoltare i postMessage inviati dal Form Widget #

Il Form Widget può inviare messaggi alla pagina che lo ospita. Questo è utile quando vuoi reagire a eventi del modulo direttamente dal tuo sito, per esempio per leggere l’ID di una submission appena salvata.

Per intercettare questi messaggi, puoi aggiungere un event listener nella pagina che contiene il widget.

Esempio:

Questo approccio è utile quando vuoi integrare il form con script personalizzati presenti sul sito esterno.

Impostazioni del Form Widget #

Il widget supporta diverse opzioni che possono essere modificate direttamente nel codice embed.

Id #

L’ID del modulo in Primeforms.

Esempio:

• 'id': 132

Sid #

L’ID della submission. Può essere usato per modificare una submission già esistente.

Per trovare il Submission ID, vai in Submission Manager.

Esempio:

• 'sid': 964

Container #

L’ID dell’elemento HTML che conterrà l’iframe del modulo.

Esempio:

• 'container': 'c132'

Width #

Definisce la larghezza dell’iframe del modulo.

Esempio:

• 'width': '100%'

Height #

Definisce l’altezza dell’iframe. Di solito il codice embed imposta già un valore iniziale in pixel.

Esempio:

• 'height': '846px'

Auto Resize #

È attivo di default. Consente all’iframe di adattarsi automaticamente all’altezza reale del modulo, per esempio quando compaiono messaggi di validazione.

Se disattivato, il modulo manterrà l’altezza definita nell’opzione height.

Esempio:

• 'autoResize': !0

Theme #

Valore numerico 1 o 0 che consente di attivare o disattivare il tema del modulo al volo.

Esempio:

• 'theme': 1

Custom JS #

Valore numerico 1 o 0 che consente di attivare o disattivare il caricamento di file JavaScript esterni collegati al form.

Esempio:

• 'customJS': 1

Record #

Valore numerico 1 o 0 che consente di attivare o disattivare il Form Tracker.

Esempio:

• 'record': 1

Reset #

Valore numerico 1 o 0 che controlla se il modulo deve essere resettato dopo l’invio.

Esempio:

• 'reset': 0

Page #

Nei moduli multistep indica la pagina da mostrare come predefinita.

Esempio:

• 'page': 2

Form #

Definisce il percorso dell’embed del modulo. Non contiene parametri.

addToOffsetTop #

Permette di aggiungere o sottrarre pixel al calcolo della posizione del form. È utile quando il sito usa elementi fissi, come un header con CSS position: fixed.

Esempio:

• 'addToOffsetTop': '-60'

Default Values #

Se vuoi precompilare campi del modulo dal codice embed, puoi usare l’opzione defaultValues. Si tratta di un oggetto JSON in cui la chiave è l’ID del campo e il valore è il contenuto da inserire.

Esempio:

Per checkbox e radio button, la selezione può essere controllata con valori booleani.

Interagire con il form via JavaScript #

Il Form Widget consente di aggiungere logiche personalizzate tramite file JavaScript esterni.

Nota: per caricare un file JavaScript esterno devi andare in:

• Forms → Actions → Settings → UI Settings

Di default è disponibile un oggetto jQuery, quindi puoi interagire con il modulo in modo diretto.

Esempio base:

L’elemento formEl #

L’oggetto formEl è un oggetto jQuery che rappresenta il modulo. Può essere usato per leggere informazioni sul form o manipolarlo direttamente.

Esempio:

Eventi disponibili #

Il Form Widget attiva diversi eventi quando il form esegue azioni specifiche.

view #

Si attiva quando il modulo viene visualizzato.

fill #

Si attiva la prima volta che l’utente interagisce con il form, per esempio compilando un campo o selezionando una risposta.

error #

Si attiva quando il server restituisce un errore di validazione.

success #

Si attiva quando il modulo viene inviato correttamente.

nextStep #

Si attiva ogni volta che l’utente passa allo step successivo in un modulo multistep.

previousStep #

Si attiva ogni volta che l’utente torna allo step precedente in un modulo multistep.

Esempio di listener per gli errori:

Eventi del Rule Engine #

Quando una regola condizionale mostra o nasconde un campo, il Rule Engine può attivare eventi specifici:

• ef.shown: il campo è stato mostrato
• ef.hidden: il campo è stato nascosto

Esempio:

Event handler previousStep e nextStep #

Oltre agli eventi, Primeforms mette a disposizione gli handler previousStep e nextStep per controllare la navigazione dei moduli multistep via JavaScript.

Questa funzione è utile quando vuoi far avanzare o retrocedere il form senza far cliccare i pulsanti di navigazione standard.

Auto-advance nei Multi-Step Form #

In alcuni casi, ad esempio survey o test, puoi voler far avanzare automaticamente il modulo allo step successivo non appena l’utente seleziona una risposta.

Esempio:

Se vuoi nascondere i pulsanti di navigazione, puoi aggiungere questo CSS nel tema assegnato al modulo:

Caricare più file JavaScript e CSS nel form #

Avendo a disposizione jQuery, puoi usare jQuery.when().done() per caricare più file esterni e usarli una volta pronti.

Questa possibilità è utile quando vuoi estendere il comportamento del modulo con librerie esterne.

Esempio: mostrare un jQuery UI DatePicker nei campi data #

L’esempio seguente:

• carica il file CSS di jQuery UI
• carica il file JavaScript di jQuery UI
• trasforma i campi date in campi testo con datepicker
• mantiene il valore finale in formato coerente con HTML5

Quando usare il Form Widget #

Il Form Widget è la scelta consigliata quando vuoi pubblicare un modulo su un sito esterno in modo rapido, stabile e aggiornabile.

È particolarmente utile quando:

• vuoi incorporare un modulo in una pagina del sito
• vuoi evitare conflitti con CSS o JavaScript del tema
• vuoi mantenere il form aggiornato automaticamente
• vuoi interagire con il modulo tramite JavaScript
• vuoi usare query string o valori predefiniti per personalizzare il form

Buone pratiche #

• usa il widget con design nella maggior parte dei casi
• usa query string e default values solo quando c’è una logica chiara
• testa sempre il modulo dopo aver aggiunto script esterni
• verifica il comportamento del widget su desktop e mobile
• controlla eventuali integrazioni con header fissi usando addToOffsetTop
• usa gli eventi JavaScript per estensioni reali, non per aggiungere complessità inutile

Errori comuni #

• usare il container sbagliato nel codice embed
• disattivare auto resize e dimenticare di aggiornare l’altezza manualmente
• passare query string con chiavi errate
• confondere ID del modulo e ID della submission
• aggiungere JavaScript esterni senza testarli con il form reale
• nascondere i pulsanti di navigazione nei multistep senza prevedere una logica alternativa

Note #

• Il widget aggiorna automaticamente il modulo incorporato quando il form viene modificato nel builder.
• L’iframe aiuta a prevenire conflitti con il sito che ospita il form.
• Le opzioni disponibili nel widget dipendono dalla configurazione del modulo e dell’account.
• Per script avanzati, è consigliato lavorare tramite file JavaScript esterni caricati dalle UI Settings del modulo.

Conclusione #

Il Form Widget di Primeforms è il metodo consigliato per incorporare un modulo in un sito esterno in modo semplice, flessibile e sicuro. Oltre alla pubblicazione del form, offre opzioni avanzate per precompilazione, tracking, gestione multistep ed estensioni via JavaScript.