Struttura di aspetto per moduli adattivi e HTML5

Forms (moduli adattivi e moduli HTML5) utilizza le librerie jQuery, Backbone.js e Underscore.js per l’aspetto e lo scripting. I moduli utilizzano inoltre l'architettura jQuery UI Widget per tutti gli elementi interattivi (come campi e pulsanti) del modulo. Questa architettura consente agli sviluppatori di moduli di utilizzare un set completo di widget e plug-in jQuery disponibili in Forms. È inoltre possibile implementare una logica specifica per il modulo durante l'acquisizione dei dati da parte di utenti quali le restrizioni leadDigits/trailDigits o l'implementazione di clausole illustrazione. Gli sviluppatori di moduli possono creare e utilizzare apparenze personalizzate per migliorare l'esperienza di acquisizione dei dati e renderla più semplice da utilizzare.

Questo articolo è destinato agli sviluppatori che dispongono di conoscenze sufficienti sui widget jQuery e jQuery. Fornisce informazioni approfondite sul framework di aspetto e consente agli sviluppatori di creare un aspetto alternativo per un campo modulo.

Il framework dell'aspetto si basa su varie opzioni, eventi (attivatori) e funzioni per acquisire le interazioni dell'utente con il modulo e risponde alle modifiche apportate al modello per informare l'utente finale. Inoltre:

  • Il framework fornisce una serie di opzioni per l'aspetto di un campo. Queste opzioni sono coppie chiave-valore e sono suddivise in due categorie: opzioni comuni e opzioni specifiche per il tipo di campo.
  • L'aspetto, come parte del contratto, attiva un set di eventi come enter ed exit.
  • L'aspetto è necessario per implementare un set di funzioni. Alcune delle funzioni sono comuni, mentre altre sono specifiche per le funzioni dei tipi di campo.

Opzioni comuni

Di seguito sono riportate le opzioni globali impostate. Queste opzioni sono disponibili per ogni campo.

Proprietà Descrizione
name Identificatore utilizzato per specificare questo oggetto o evento nelle espressioni di script. Ad esempio, questa proprietà specifica il nome dell'applicazione host.
valore Valore effettivo del campo.
displayValue Questo valore del campo viene visualizzato.
screenReaderText Gli Reader dello schermo utilizzano questo valore per fornire informazioni sul campo. Il modulo fornisce il valore ed è possibile sostituire il valore.
tabIndex Posizione del campo nella sequenza di tabulazione del modulo. Sostituire tabIndex solo se si desidera modificare l'ordine di tabulazione predefinito del modulo.
role Ruolo dell'elemento, ad esempio, Intestazione o Tabella.
altezza Altezza del widget. È specificata in pixel.
larghezza Larghezza del widget. È specificata in pixel.
access Controlli utilizzati per accedere al contenuto di un oggetto contenitore, ad esempio un sottomodulo.
paraStyles La proprietà para di un elemento XFA al widget.
dir La direzione del testo. I valori possibili sono ltr (da sinistra a destra) e rtl (da destra a sinistra).

Oltre a queste opzioni, il framework offre altre opzioni che variano a seconda del tipo di campo. I dettagli delle opzioni specifiche dei campi sono elencati di seguito.

Interazione con il framework dei moduli

Per interagire con il framework dei moduli, un widget attiva alcuni eventi per consentire il funzionamento dello script del modulo. Se il widget non genera questi eventi, alcuni script scritti nel modulo per tale campo non funzionano.

Eventi attivati dal widget

Evento Descrizione
XFA_ENTER_EVENT Questo evento viene attivato ogni volta che il campo è nello stato attivo. Consente l'esecuzione dello script "enter" sul campo. La sintassi per attivare l'evento è
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_ENTER_EVENT)
XFA_EXIT_EVENT Questo evento viene attivato ogni volta che l'utente esce dal campo. Consente al motore di impostare il valore del campo ed eseguire lo script "exit". La sintassi per attivare l'evento è
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_EXIT_EVENT)
XFA_CHANGE_EVENT Questo evento viene attivato per consentire al motore di eseguire lo script "change" scritto sul campo. La sintassi per attivare l'evento è
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)
XFA_CLICK_EVENT Questo evento viene attivato ogni volta che si fa clic sul campo. consente al motore di eseguire lo script "click" scritto sul campo. La sintassi per attivare l'evento è
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

API implementate da widget

Il framework di aspetto richiama alcune funzioni del widget implementate nei widget personalizzati. Il widget deve implementare le seguenti funzioni:

Funzione Descrizione
focus: function() Attiva il campo.
fate clic su: function() Attiva il campo e richiama XFA_CLICK_EVENT.

markError:function(errorMessage, errorType)

errorMessage: stringa che rappresenta l'errore
errorType: string ("warning"/"error")

Nota: Applicabile solo ai moduli HTML5.

Invia un messaggio di errore e un tipo di errore al widget. Il widget visualizza l'errore.

clearError: function()

Nota: Applicabile solo ai moduli HTML5.

Chiamata eseguita se gli errori nel campo sono corretti. Il widget nasconde l’errore.

Opzioni specifiche per il tipo di campo

Tutti i widget personalizzati devono essere conformi alle specifiche di cui sopra. Per utilizzare le funzioni di campi diversi, il widget deve essere conforme alle linee guida per quel particolare campo.

TextEdit: Campo di testo

Opzione Descrizione
multiline True se il campo supporta l'immissione di un carattere nuova riga, altrimenti false.
maxChars Numero massimo di caratteri che è possibile immettere nel campo.

limitLengthToVisibleArea

Nota: Applicabile solo ai moduli HTML5

Specifica il comportamento del campo di testo quando la larghezza del testo supera la larghezza del widget.

ChoiceList: DropDownList, ListBox

Opzione Descrizione
valore
Matrice di valori selezionati.
items
Array di oggetti da visualizzare come opzioni. Ciascun oggetto contiene due proprietà:
salvare: per salvare, visualizzare: da visualizzare.

modificabile

Nota: Applicabile solo ai moduli HTML5.

Se il valore è true, l'immissione di testo personalizzata è abilitata nel widget.
displayValue
Array di valori da visualizzare.
multiselect
True se sono consentite selezioni multiple, altrimenti false.

API

Funzione Descrizione

addItem: function(itemValues)
itemValues: oggetto contenente il valore di visualizzazione e salvataggio
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}

Aggiunge una voce all'elenco.
deleteItem: function(nIndex)
nIndex: indice della voce da rimuovere dall'elenco


Elimina un'opzione dall'elenco.
clearItems: function() Cancella tutte le opzioni dall'elenco.

NumericEdit: NumericField, DecimalField

Opzioni Descrizione
dataType Stringa che rappresenta il tipo di dati del campo (numero intero/decimale).
leadDigits Numero massimo di cifre iniziali consentito nel numero decimale.
fracDigits Numero massimo di cifre della frazione consentito nel numero decimale.
zero Rappresentazione stringa di zero nelle impostazioni internazionali del campo.
decimale Rappresentazione stringa del separatore decimale nelle impostazioni internazionali del campo.

CheckButton: RadioButton, CheckBox

Opzioni Descrizione
values

Matrice di valori (on/off/neutrale).

È un array di valori per i diversi stati del checkButton. values[0] è il valore quando lo stato è ON, i valori[1] è il valore quando lo stato è OFF,
i valori[2] è il valore quando lo stato è NEUTRAL. La lunghezza dell'array dei valori è uguale al valore dell'opzione state.

stati

Numero di stati consentiti.

Due per i moduli adattivi (attivato, disattivato) e tre per i moduli HTML5 (attivato, disattivato, neutro).

stadio

Stato corrente dell’elemento.

Due per i moduli adattivi (attivato, disattivato) e tre per i moduli HTML5 (attivato, disattivato, neutro).

DateTimeEdit: (DateField)

Opzione Descrizione
giorni Nome localizzato dei giorni per il campo.
mesi Nomi dei mesi localizzati per quel campo.
zero Testo localizzato per il numero 0.
clearText Testo localizzato per il pulsante Cancella.

In questa pagina