Proprietà campo di blocco Forms adattivo

In questo documento viene riepilogato il modo in cui lo schema JSON viene mappato su HTML sottoposto a rendering in blocks/form/form.js, concentrandosi su come vengono identificati e renderizzati i campi, sui pattern comuni e sulle differenze specifiche dei campi.

Identificazione Dei Campi (fieldType)

Ogni campo nello schema JSON ha una proprietà fieldType che determina come viene eseguito il rendering. fieldType può essere:

Se fieldType corrisponde a un tipo speciale, viene utilizzato un renderer personalizzato. In caso contrario, verrà trattato come tipo di input predefinito.

Vedere le sezioni seguenti per la struttura e le proprietà complete di HTML per ogni tipo di campo.

Proprietà comuni utilizzate dai campi

Di seguito sono riportate le proprietà utilizzate dalla maggior parte dei campi:

Struttura comune di HTML

Il rendering della maggior parte dei campi viene eseguito all'interno di un wrapper che include un'etichetta e un testo di aiuto facoltativo. Lo snippet seguente illustra la struttura:

<div class="<fieldType>-wrapper field-wrapper field-<name>" data-id="<id>">
<label for="<id>" class="field-label">Label</label>
<!-- Field-specific input/element here -->
<div class="field-description" id="<id>-description">Description or error
message</div>
</div>

Per i gruppi (radio/casella di controllo) e i pannelli, viene utilizzato <fieldset> con <legend> invece di <div>/<label>. Testo della guida

è presente solo se è impostata la descrizione.

Visualizzazione messaggio di errore

I messaggi di errore vengono visualizzati nello stesso elemento .field-description utilizzato per il testo della Guida, che viene aggiornato dinamicamente.

Quando un campo non è valido:

• Al wrapper (ad esempio, .field-wrapper) viene assegnata la classe .field-invalid.
• Il contenuto di .field-description viene sostituito con il messaggio di errore corrispondente.

Quando il campo diventa valido:

• La classe .field-invalid è stata rimossa.
• .field-description viene ripristinato al testo della Guida originale (se disponibile) o rimosso se non ne esiste alcuno.

I messaggi di errore personalizzati possono essere definiti utilizzando la proprietà constraintMessages nel JSON.
Questi vengono aggiunti come data-<constraint>ErrorMessage attributi nel wrapper (ad esempio, data-requiredErrorMessage).

Tipi di input predefiniti (HTML Input o *-input)

Se fieldType non è un tipo speciale, verrà considerato come un tipo di input HTML standard o come <type>-input, ad esempio text, number, email, date, text-input, number-input.

• Il suffisso -input è rimosso e il tipo di base viene utilizzato come attributo type dell'input.
• Questi tipi vengono gestiti per impostazione predefinita in renderField().
  I tipi di input predefiniti comuni sono text, number, email, date, password, tel, range, file e così via. Accettano anche text-input, number-input, ecc., che sono normalizzati al tipo di base.

Vincoli per i tipi di input predefiniti

I vincoli vengono aggiunti come attributi sull’elemento di input in base alle proprietà JSON.

Questi attributi vengono impostati automaticamente dal renderer del modulo in base alla definizione JSON del campo.

Esempio: struttura HTML con vincoli

L’esempio seguente illustra come viene eseguito il rendering di un campo numerico con vincoli di convalida e attributi di gestione degli errori.

<div class="number-wrapper field-wrapper field-age" data-id="age"
data-required="true"
data-minimumErrorMessage="Too small" data-maximumErrorMessage="Too large">
<label for="age" class="field-label">Age</label>
<input type="number"
id="age" name="age"
value="30" required min="18"
max="99" step="1"
placeholder="Enter your age" />
<div class="field-description" id="age-description"> Description or error message
</div>
</div>

Ogni parte della struttura di HTML svolge un ruolo nell'associazione dati, nella convalida e nella visualizzazione di messaggi di aiuto o di errore.

Proprietà specifiche dei campi e relative strutture HTML

Elenchi a discesa

Proprietà aggiuntive:

• enum / enumNames: definire i valori delle opzioni e le relative etichette di visualizzazione per il menu a discesa.
• type: abilita la selezione multipla se impostata su array.
• placeholder: aggiunge un'opzione segnaposto disabilitata per guidare gli utenti prima della selezione.

Esempio:

<div class="drop-down-wrapper field-wrapper field-<name>" data-id="<id>"
data-required="true"
data-requiredErrorMessage="This field is required">
<label for="<id>" class="field-label">Label</label>
<select id="<id>" name="<name>" required title="Tooltip" multiple>
<option disabled selected value="">Placeholder</option>
<option value="opt1">Option 1</option>
<option value="opt2">Option 2</option>
</select>
<div class="field-description" id="<id>-description"> Description or error message
</div>
</div>

Testo normale

Proprietà aggiuntive:

• richText: se true, esegue il rendering di HTML nel paragrafo.

Esempio:

<div class="plain-text-wrapper field-wrapper field-<name>" data-id="<id>">
<label for="<id>" class="field-label">Label</label>
<p>Text or <a href="..." target="_blank">link</a></p>
</div>

Casella di controllo

Proprietà aggiuntive:

• enum: definisce i valori per lo stato selezionato e deselezionato della casella di controllo.
• properties.variant / properties.alignment: specifica lo stile di visualizzazione e l'allineamento per le caselle di controllo di tipo switch.

Esempio:

<div class="checkbox-wrapper field-wrapper field-<name>" data-id="<id>"
data-required="true"
data-requiredErrorMessage="Please check this box">
<label for="<id>" class="field-label">Label</label>
<input type="checkbox"
id="<id>"
name="<name>" value="on"
required
data-unchecked-value="off" />
<div class="field-description" id="<id>-description"> Description or error message
</div>
</div>

Pulsante

Proprietà aggiuntive:

• buttonType: specifica il comportamento del pulsante impostandone il tipo (pulsante, invio o ripristino).

Esempio:

<div class="button-wrapper field-wrapper field-<name>" data-id="<id>">
<button id="<id>" name="<name>" type="submit" class="button"> Label
</button>
</div>

Ingresso multiriga

Proprietà aggiuntive:

• minLength: specifica il numero minimo di caratteri consentito in un input di testo o di area di testo.
• maxLength: specifica il numero massimo di caratteri consentito in un input di testo o di area di testo.
• pattern: definisce un'espressione regolare che il valore di input deve corrispondere per essere considerata valida.
• placeholder: visualizza il testo segnaposto all'interno dell'area di input o di testo fino all'immissione di un valore.

Esempio:

<div class="multiline-wrapper field-wrapper field-<name>" data-id="<id>"
data-minLengthErrorMessage="Too short" data-maxLengthErrorMessage="Too long">
<label for="<id>" class="field-label">Label</label>
<textarea id="<id>"
name="<name>" required
minlength="2"
maxlength="100"
pattern="[A-Za-z]+"
placeholder="Type here..."></textarea>
<div class="field-description" id="<id>-description"> Description or error message
</div>
</div>

Pannello

Proprietà aggiuntive:

• repeatable: specifica se il pannello può essere ripetuto dinamicamente.
• minOccur: imposta il numero minimo di istanze del pannello richieste. maxOccur: imposta il numero massimo di istanze di pannello consentite.
• properties.variant: definisce lo stile visivo o la variante del pannello.
• properties.colspan: specifica il numero di colonne contenute nel pannello in un layout griglia.
• index: indica la posizione del pannello all'interno del relativo contenitore principale.
• fieldset: raggruppa campi correlati in un elemento <fieldset> con una legenda o un'etichetta.

Esempio:

<fieldset class="panel-wrapper field-wrapper field-<name>" data-id="<id>"
name="<name>"
data-repeatable="true" data-index="0">
<legend class="field-label">Label</legend>
<!-- Nested fields here -->
<button type="button" class="add">Add</button>
<button type="button" class="remove">Remove</button>
<div class="field-description" id="<id>-description"> Description or error message
</div>
</fieldset>

Pulsante di scelta

Proprietà aggiuntive:

• enum: definisce il set di valori consentiti per il campo di opzione, utilizzato come attributo di valore per ogni opzione del pulsante di opzione.

Esempio:

<div class="radio-wrapper field-wrapper field-<name>" data-id="<id>"
data-required="true">
<label for="<id>" class="field-label">Label</label>
<input type="radio" id="<id>" name="<name>" value="opt1" required />
<div class="field-description" id="<id>-description"> Description or error message
</div>
</div>

Gruppo pulsanti di scelta

Proprietà aggiuntive:

• enum: definisce l'elenco di valori di opzione per il gruppo di opzioni, utilizzato come valore di ogni pulsante di opzione.
• enumNames: fornisce etichette di visualizzazione per i pulsanti di scelta, che corrispondono all'ordine di enumerazione.

Esempio:

<fieldset class="radio-group-wrapper field-wrapper field-<name>" data-id="<id>"
data-required="true">
<legend class="field-label">Label</legend>
<div>
<input type="radio" id="<id>-0" name="<name>" value="opt1" required />
<label for="<id>-0">Option 1</label>
</div>
<div>
<input type="radio" id="<id>-1" name="<name>" value="opt2" />
<label for="<id>-1">Option 2</label>
</div>
<div class="field-description" id="<id>-description"> Description or error message
</div>
</fieldset>

Gruppo di caselle di controllo

Proprietà aggiuntive:

• enum: definisce l'elenco di valori di opzione per il gruppo di caselle di controllo, utilizzato come valore di ogni casella di controllo.
• enumNames: fornisce etichette di visualizzazione per le caselle di controllo, che corrispondono all'ordine di enumerazione.
• minItems: imposta il numero minimo di caselle di controllo che devono essere selezionate per la validità.
• maxItems: imposta il numero massimo di caselle di controllo che è possibile selezionare prima di attivare un errore.

Esempio:

<fieldset class="checkbox-group-wrapper field-wrapper field-<name>" data-id="<id>"
data-required="true" data-minItems="1"
data-maxItems="3">
<legend class="field-label">Label</legend>
<div>
<input type="checkbox" id="<id>-0" name="<name>" value="opt1" required />
<label for="<id>-0">Option 1</label>
</div>
<div>
<input type="checkbox" id="<id>-1" name="<name>" value="opt2" />
<label for="<id>-1">Option 2</label>
</div>
<div class="field-description" id="<id>-description"> Description or error message
</div>
</fieldset>

Immagine

Proprietà aggiuntive:

• value / properties['fd:repoPath']: definisce il percorso di origine dell'immagine o il percorso dell'archivio per il rendering dell'immagine.
• altText: fornisce testo alternativo per l'immagine (attributo alt) per migliorare l'accessibilità.

Esempio:

<div class="image-wrapper field-wrapper field-<name>" data-id="<id>">
<picture>
<img src="..." alt="..." />
<!-- Optimized sources -->
</picture>
</div>

Intestazione

Proprietà aggiuntive:

• value: specifica il contenuto del testo da visualizzare nell'elemento intestazione (ad esempio, <h2>).

Esempio:

<div class="heading-wrapper field-wrapper field-<name>" data-id="<id>">
<h2 id="<id>">Heading Text</h2>
</div>

Per ulteriori dettagli, vedere l'implementazione in blocks/form/form.js e blocks/form/util.js.