UI Widgets in Primeforms

I UI Widget in Primeforms servono per arricchire i campi del modulo con comportamenti avanzati lato interfaccia. In pratica, permettono di trasformare un normale input in un campo più evoluto: per esempio un telefono con prefisso internazionale, un datepicker, un campo con maschera, una select con ricerca, un rating a stelle o un upload file migliorato.

Questa guida ti mostra come usare i widget UI in Primeforms, quando conviene attivarli, quali sono gli esempi più utili da implementare nei tuoi moduli e quali custom attributes puoi usare per configurare il comportamento di ciascun widget.

Che cosa sono i UI Widget in Primeforms #

Un widget UI è un’estensione visiva o funzionale applicata a un campo del form. Il campo rimane lo stesso a livello di raccolta dati, ma l’esperienza utente migliora in modo netto.

Ecco alcuni casi pratici:

• Numero di telefono internazionale con bandiera, prefisso e formattazione automatica
• Input mask per codici, CAP, partita IVA, date e numeri documento
• Datepicker o timepicker per una selezione guidata di date e orari
• Select avanzate con ricerca interna e multi-selezione
• Upload file evoluto con anteprima, limiti e messaggi migliori
• Rating a stelle per feedback, recensioni o valutazioni rapide

Il vantaggio principale è semplice: meno errori, compilazione più veloce e un modulo più professionale.

Quando usare un UI Widget #

Non tutti i campi hanno bisogno di un widget avanzato. In generale, conviene usarlo quando:

• il campo ha un formato preciso da rispettare
• vuoi ridurre gli errori di digitazione
• il dato è più complesso da inserire manualmente
• vuoi migliorare la percezione di qualità del form
• devi aiutare l’utente in modo visivo durante la compilazione

La regola migliore è questa: usa i widget per semplificare, non per complicare. Se un campo standard è sufficiente, lascia il campo standard.

Come usare i UI Widget in Primeforms #

La logica di lavoro in Primeforms è questa:

1. crei o selezioni un campo del modulo
2. apri le impostazioni del campo
3. raggiungi l’area dedicata alla personalizzazione UI o ai widget
4. colleghi il widget al campo target
5. carichi eventuali librerie CSS e JavaScript necessarie
6. inserisci lo script di inizializzazione, se richiesto
7. salvi e testi il comportamento in anteprima

In molti casi la configurazione ruota attorno a questi elementi:

• Nome del widget
• Campo target o selettore CSS
• File CSS da includere
• File JavaScript da includere
• Script di inizializzazione
• Opzioni del plugin
• Custom attributes per personalizzare il comportamento del widget

Flusso consigliato di configurazione #

Per evitare problemi, segui sempre questo ordine:

1. crea prima il campo
2. verifica l’ID, il name o la classe del campo
3. carica le librerie del widget
4. inizializza il plugin solo quando il form è già renderizzato
5. prova il widget su desktop e mobile
6. controlla che il valore venga salvato correttamente nel submit

Questo passaggio è fondamentale: un widget può vedersi bene, ma se non scrive il valore corretto nel campo finale il modulo raccoglierà dati sbagliati.

Esempio 1: campo telefono con prefisso internazionale #

Uno degli usi più comuni dei widget UI in Primeforms è il campo telefono internazionale. È utile per form di contatto, richieste commerciali, booking, assistenza o lead generation internazionale.

Con un widget di questo tipo puoi ottenere:

• bandiera del Paese
• prefisso automatico
• placeholder dinamico
• validazione più chiara
• migliore leggibilità del numero

Esempio di inizializzazione:

Questo tipo di widget è ideale quando vuoi aumentare la qualità dei lead raccolti e uniformare i numeri in arrivo.

Esempio 2: input mask per campi strutturati #

Le maschere di input sono perfette per tutti i campi che seguono un formato preciso. Per esempio:

• data nel formato gg/mm/aaaa
• CAP a 5 cifre
• telefono nazionale
• partita IVA
• codice fiscale

Esempio pratico per una data:

Per un CAP:

Le input mask migliorano molto la qualità dei dati, soprattutto nei form lunghi o nei moduli usati da utenti poco esperti.

Esempio 3: datepicker in Primeforms #

Se l’utente deve scegliere una data, quasi sempre un datepicker è meglio di un input testo libero. Riduce errori, velocizza la compilazione e rende il modulo più intuitivo.

Esempio di inizializzazione:

Puoi usarlo per:

• prenotazioni
• richieste appuntamento
• date di nascita
• date evento
• check-in e check-out

Esempio 4: timepicker o selezione orario #

Quando il modulo prevede la scelta di un orario, conviene usare un widget dedicato invece di lasciare l’utente libero di scrivere. In questo modo eviti valori incoerenti come “9”, “09.00”, “9h” o “ore 9”.

Esempio semplificato:

È molto utile nei moduli di booking, nelle richieste commerciali con appuntamento e nei flussi di assistenza.

Esempio 5: Select2 per select avanzate #

Se hai una select con molte opzioni, la UX può peggiorare rapidamente. In questi casi, un widget come Select2 è perfetto perché aggiunge ricerca interna, selezione più elegante e multi-selezione gestibile.

Esempio:

Usalo per:

• elenchi nazioni
• elenchi province o città
• servizi disponibili
• categorie prodotto
• settori aziendali

Esempio 6: rating a stelle #

Il rating a stelle è ideale per sondaggi rapidi, feedback post-servizio, recensioni o micro-valutazioni. Invece di chiedere un voto numerico freddo, il widget rende l’interazione più naturale.

Esempio:

Funziona molto bene in combinazione con un campo textarea finale per raccogliere un commento libero.

Esempio 7: upload file avanzato #

Il campo file standard può andare bene, ma in alcuni progetti conviene migliorarlo con un widget dedicato. Per esempio quando vuoi:

• mostrare l’anteprima del file
• limitare meglio formati e peso
• migliorare i messaggi di errore
• rendere più chiaro il numero massimo di file caricabili

In Primeforms questo approccio è utile soprattutto per candidature, raccolta documenti, preventivi e richieste tecniche.

Esempio 8: checkbox e radio personalizzati #

Le checkbox e i radio button possono essere migliorati esteticamente con librerie UI specifiche. Questo ha senso quando il modulo deve avere una grafica più curata o coerente con il brand.

I casi tipici sono:

• consensi privacy
• scelta di opzioni tariffarie
• preferenze di contatto
• questionari con risposte chiuse

Attenzione però: la personalizzazione grafica non deve mai compromettere accessibilità, focus, area cliccabile e leggibilità.

Custom Attributes per i UI Widgets #

Una delle parti più utili dei widget UI in Primeforms è la possibilità di personalizzarli tramite custom attributes. In pratica, puoi aggiungere attributi data-* per controllare direttamente il comportamento del widget senza dover riscrivere tutto da zero.

Questa parte è fondamentale perché ti permette di trasformare una configurazione base in una configurazione molto più precisa, soprattutto quando lavori con date, orari, maschere, file upload, rating o select avanzate.

Flatpickr #

Flatpickr sostituisce un normale campo data con un datepicker leggero, moderno e cross-browser.

• data-alt-format: formato usato per mostrare la data nel campo. Esempio: F j, Y
• data-allow-invalid-preload: consente il preload di una data non valida. Valori: true o false
• data-aria-date-format: definisce il formato usato nell’aria-label dei giorni del calendario
• data-default-date: imposta la data iniziale in formato HTML5. Esempio: 2021-12-31
• data-default-hour: imposta l’ora iniziale. Esempio: 12
• data-default-minute: imposta i minuti iniziali. Esempio: 0
• data-disable: elenco di date da disabilitare separate da virgola. Esempio: 2022-01-01,2022-01-02
• data-disable-mobile: forza il picker custom anche su mobile. Valori: true o false
• data-enable-time: abilita la selezione dell’orario
• data-enable-seconds: abilita anche i secondi
• data-hour-increment: step di incremento delle ore. Esempio: 1
• data-inline: mostra il calendario inline invece che come popup
• data-locale: imposta la lingua del calendario. Esempi: it, es, fr, de
• data-max-date: data massima selezionabile
• data-min-date: data minima selezionabile
• data-minute-increment: step di incremento dei minuti. Esempio: 5
• data-mode: modalità di selezione. Valori: single, multiple, range
• data-next-arrow: HTML della freccia del mese successivo
• data-no-calendar: nasconde il calendario e lascia solo la selezione oraria
• data-position: posizione del calendario rispetto al campo. Esempi: above, auto center
• data-prev-arrow: HTML della freccia del mese precedente
• data-shorthand-current-month: usa il nome abbreviato del mese
• data-show-months: numero di mesi mostrati contemporaneamente
• data-time-24hr: usa il formato 24 ore senza AM/PM
• data-week-numbers: mostra i numeri delle settimane
• data-month-selector-type: visualizzazione del mese nell’header. Valori: dropdown o static

International Telephone Input #

Questo widget aggiunge una tendina con bandiere ai campi telefono e mostra un placeholder coerente con il Paese selezionato. L’utente inserisce il numero nazionale, mentre il plugin può salvare il numero completo in formato internazionale.

• data-initial-country: Paese iniziale. Può essere auto oppure un codice a due lettere come it, us, gb

jQuery Mask #

jQuery Mask permette di applicare maschere di input ai campi del modulo per guidare l’utente nell’inserimento corretto dei dati.

• data-mask: definisce la maschera. Esempio: 00/00/0000
• data-mask-placeholder: aggiunge un placeholder alla maschera. Esempio: //____
• data-mask-reverse: attiva una maschera reversibile. Valori: true o false
• data-mask-clearifnotmatch: svuota il campo se il valore non rispetta la maschera
• data-mask-selectonfocus: seleziona il contenuto del campo al focus

Valori comuni che puoi usare in data-mask:

• Data: 00/00/0000
• Ora: 00:00:00
• Data e ora: 00/00/0000 00:00:00
• CAP: 00000-000
• Telefono: 0000-0000
• Telefono con DDD: (00) 0000-0000
• Telefono USA: (000) 000-0000
• Formato misto: AAA 000-S0S
• Indirizzo IP: 099.099.099.099
• Solo numeri: 0#

jQuery UI Datepicker #

Il widget jQuery UI Datepicker consente di selezionare una data da un calendario popup o inline su qualsiasi campo data.

• data-date-format: formato di visualizzazione della data. Esempio: mm/dd/yy
• data-show-button-panel: mostra il pannello pulsanti sotto il calendario
• data-change-month: mostra il mese come menu a tendina
• data-change-year: mostra l’anno come menu a tendina
• data-year-range: intervallo degli anni nel menu. Esempio: 2019:2022
• data-number-of-months: numero di mesi visibili insieme
• data-min-date: data minima selezionabile. Esempio: +1m +7d
• data-max-date: data massima selezionabile
• data-is-rtl: supporto lingue scritte da destra a sinistra
• data-show-week: mostra il numero della settimana
• data-first-day: primo giorno della settimana. Domenica = 0, lunedì = 1

jSuites JavaScript Input Mask #

Questo widget migliora l’esperienza di input grazie a maschere avanzate per diversi formati.

• data-mask: abilita la maschera e definisce il pattern. Esempio: $ #,##0.00

Esempi comuni di maschere:

• Data di nascita: dd/mm/yyyy
• Formato USA: US #.##0,00
• Percentuale: 0%
• Litri: 0.00 liters
• Formato euro francese: # ##0,00 €
• Data e ora: yyyy-mm-dd hh24:mi
• CPF: 000.000.000-00

Krajee File Input #

Per migliorare il campo file, puoi aggiungere la classe CSS file al campo e usare il widget Krajee File Input.

• data-browse-label: etichetta del pulsante Sfoglia
• data-browse-icon: icona del pulsante Sfoglia
• data-remove-label: etichetta del pulsante Rimuovi
• data-remove-icon: icona del pulsante Rimuovi
• data-cancel-label: etichetta del pulsante Annulla
• data-cancel-icon: icona del pulsante Annulla
• data-upload-label: etichetta del pulsante Upload
• data-upload-icon: icona del pulsante Upload
• data-show-preview: mostra l’anteprima del file. Valori: true o false
• data-show-browse: mostra il pulsante Sfoglia
• data-show-remove: mostra il pulsante Rimuovi
• data-show-upload: mostra il pulsante Upload

Krajee Star Rating #

Il widget Krajee Star Rating permette di mostrare una valutazione a stelle su qualsiasi campo con classe CSS rating.

Temi disponibili:

• .rating-theme-fas: Font Awesome 5.x Theme
• .rating-theme-uni: Unicode Theme
• .rating-theme-gly: Glyphicons Theme

Attributi di personalizzazione:

• data-container-class: classe CSS da aggiungere al contenitore
• data-empty-star: markup del simbolo per stella vuota
• data-filled-star: markup del simbolo per stella piena
• data-stars: numero di stelle da mostrare
• data-min: valore minimo
• data-max: valore massimo
• data-step: incremento per click
• data-rtl: orientamento da destra a sinistra. Valori: true o false
• data-show-caption: mostra la caption
• data-size: dimensione del controllo. Valori: xl, lg, md, sm, xs
• data-default-caption: testo caption di default
• data-star-caption: caption per una stella
• data-star-captions: caption per più stelle
• data-clear-button: markup del pulsante reset
• data-clear-button-title: titolo del pulsante reset
• data-clear-caption: caption mostrata dopo il reset

Select2 #

Select2 permette di trasformare una normale select in un campo avanzato con ricerca, placeholder, scelta multipla e tag dinamici. Va applicato a un campo Select List con classe CSS select2.

• data-theme: tema del widget. Valori: classic o bootstrap
• data-placeholder: placeholder da mostrare quando non è selezionata nessuna opzione
• data-allow-clear: permette di cancellare la selezione corrente
• data-tags: consente all’utente di creare nuove opzioni digitando testo
• data-maximum-selection-length: numero massimo di opzioni selezionabili
• data-minimum-input-length: numero minimo di caratteri prima di avviare la ricerca
• data-maximum-input-length: lunghezza massima del termine cercato
• data-minimum-results-for-search: nasconde il box di ricerca sotto una certa soglia di risultati

Librerie spesso usate con i UI Widget #

A seconda del tipo di widget, in Primeforms puoi integrare librerie esterne o componenti UI già presenti nel tuo stack. Le più comuni sono:

• intl-tel-input per numeri di telefono internazionali
• jQuery Mask per formati guidati
• jQuery UI Datepicker per date
• Select2 per select avanzate
• plugin di rating per stelle e valutazioni
• plugin upload per campi file migliorati

Il criterio corretto non è installare più librerie possibile, ma scegliere solo quelle che portano un miglioramento reale al modulo.

Buone pratiche per usare i widget in Primeforms #

• mantieni il campo originale compatibile con il valore finale da salvare
• non inizializzare due volte lo stesso widget
• carica CSS e JS solo quando servono
• testa sempre il widget anche da smartphone
• verifica submit, validazione e salvataggio
• usa placeholder e messaggi coerenti con la lingua del modulo
• non appesantire il form con effetti inutili
• parti da una configurazione minima e aggiungi solo gli attributi davvero necessari

Errori comuni da evitare #

Ecco gli errori più frequenti quando si lavora con i UI Widget in Primeforms:

• il selettore del campo è sbagliato
• la libreria JavaScript non è stata caricata
• il CSS del widget manca o viene sovrascritto dal tema
• il widget viene inizializzato prima del render del form
• il valore visualizzato non coincide con il valore realmente inviato
• su mobile il widget rompe il layout o diventa scomodo da usare
• vengono aggiunti troppi attributi senza testare il comportamento reale del campo

Quando qualcosa non funziona, il controllo da fare è sempre questo: il widget si vede bene, ma il dato viene anche salvato correttamente?

Consiglio pratico per chi usa Primeforms in produzione #

Se stai gestendo moduli reali per lead generation, booking o raccolta dati commerciali, il modo migliore per usare i widget è questo:

1. parti dal campo standard
2. aggiungi il widget solo dove semplifica davvero
3. prova il form completo
4. verifica email, esportazioni e integrazioni
5. solo dopo passa il modulo in produzione

Questo approccio ti evita uno dei problemi più classici: avere un modulo bellissimo da vedere ma fragile nella raccolta dei dati.

Conclusione #

I UI Widget in Primeforms sono una risorsa molto utile per trasformare un modulo normale in un’esperienza più chiara, fluida e professionale. Se usati bene, migliorano sia la compilazione sia la qualità dei dati raccolti.

I widget più utili nella maggior parte dei progetti sono questi:

• telefono internazionale
• input mask
• datepicker e timepicker
• Select2
• rating a stelle
• upload file avanzato

La regola finale è semplice: usa il widget quando riduce attrito, non quando aggiunge complessità. In Primeforms, la UI deve aiutare l’utente a completare il modulo nel modo più naturale possibile.