Skip to main content

Form

form​

Questa entità descrive un form definito a livello di sito, che può essere incluso in page element attraverso il relativo tipo di dati formReference.

I form:

  • Hanno un nome.
  • Appartengono ad un sito.
  • Possono essere di tre tipi: Custom, Login e Registration. Gli ultimi due sono usati dal frontend per creare le pagine di login e registrazione.
  • Hanno una proprietà submitButtonText che determina il testo contenuto nel pulsante di invio.
  • [TBD] Possono usare ReCAPTCHA se le proprietà useReCaptcha e reCaptchaKey sono configurate.
  • Permettono di impostare i messaggi di successo ed errore tramite le proprietà onSubmitSuccessMessage e onSubmitFailureMessage.
  • Possono contenere componenti.
  • Possono eseguire azioni al momento dell'invio.

Componenti​

I componenti sono ciò che definirà quali controlli saranno visibili nel form. I componenti si dividono in due categorie:

Contenitori​

Un contenitore, come dice il nome, raggruppa insieme altri componenti. I contenitori attualmente implementati sono:

  • Group: Un componente la cui unica funzione è raggruppare altri controlli sotto un nome. Il frontend potrebbe usare questo componente per delimitare graficamente un insieme di controlli.
  • Horizontal: Il frontend disporrà i componenti orizzontalmente invece che in colonna.

Input​

Gli input sono componenti con i quali l'utente può interagire. Ogni input ha una proprietà key che può essere usata tramite placeholder per inserire il valore del campo, ad esempio, in un messaggo email. Gli input hanno anche una proprietà label, che imposta l'etichetta da mostrare accanto al controllo nell'HTML renderizzato.

Gli input possono essere contrassegnati con required: true per rendere obbligatoria la compilazione e annullare l'invio del form quando il valore non è inserito. Quando un input non obbligatorio non viene inserito, si userà il suo defaultValue.

  • Text: Semplice textbox.
  • Password: Textbox offuscata.
  • Checkbox: Checkbox booleana: i suoi valori flaggato e non possono essere personalizzati tramite i campi checkedValue e uncheckedValue. Impostando questi input come required sarà obbligatorio spuntarlo.
  • MultipleSelection: L'utente può selezionare zero o più valori tra una lista di checkbox. Il valore restituito da questo controllo è una stringa composta dai valori selezionati, separati da virgola.
  • Stato: L'utente può selezionare un paese da una lista generata dal frontend.
  • PhoneNumber: Questo controllo valida il numero telefonico.
  • StaticHTML: Questo controllo non è interattivo, ma è utile per includere informazioni nel form. Particolarmente utile per privacy policy o informative "termini e condizioni".
  • Select: Questo controllo permette all'utente di scegliere tra diversi valori. La sua proprietà selectType può accettare due valori: dropdown e radio, il frontend visualizzerà il controllo nella modalità selezionata.

Invio​

Un form può essere inviato chiamando l'endpoint POST /forms/{formId}/submissions con un corpo di tipo multipart nel seguente formato:

"page": "{page id}", //Pagina da cui è stato inviato il form
"culture": "{page culture}", //La cultura della pagina
"campoEmail": "john.doe@acme.com",
"campoNome": "John Doe"
...

dove i nomi dei campi (a parte page e culture) corrispondono alle key degli input.

Azioni​

I form possono avere azioni collegate: le azioni sono comportamenti che vengono eseguiti all'invio.

Gli utenti possono collegare le seguenti azioni al form:

  • AutenticateMember: Prova ad autenticare un member del sito con credenziali passate tramite i campi del form. Se l'autenticazione ha successo, il campo session della risposta all'invio conterrà informazioni sul member, altrimenti sarà null. Nel dettaglio: AuthenticateMember.

  • AddMember: Aggiunge un nuovo member al sito, basandosi sulle informazioni passate dal form. Nel dettaglio: AddMember

Messaggi Email​

I form possono inviare dei messaggi alla sottoscrizione: i messaggi sono definiti nella proprietà emailMessages del form, che accetta oggetti nella forma:

{
    ...,
    "emailMessages": [
        {
            "from": string,
            "subject": string,
            "to": string[],
            "replyto": string,
            "cc": string[],
            "bcc": string[],
            "isHtml": bool,
            "message": string,
        }
    ]
}
tip

I contenuti dei campi della struttura dati mostrata qui sopra possono includere placeholder. I valori utilizzabili nei placeholder provengono dai dati della submission.