Structure de l’apparence des formulaires adaptatifs et HTML5 appearance-framework-for-adaptive-and-html-forms

Les formulaires (formulaires adaptatifs et HTML5) utilisent jQuery, Backbone.js et Underscore.js pour l’apparence et les scripts. Les formulaires utilisent également l’architecture des jQuery UI widgets pour tous les éléments interactifs (comme les champs ou les boutons) qu’ils contiennent. Cette architecture permet aux développeurs et aux développeuses de formulaires d’utiliser un riche ensemble de widgets et de modules externes jQuery disponibles dans des formulaires. Vous pouvez également implémenter une logique spécifique au formulaire lors de l’acquisition des données des utilisateurs comme les restrictions leadDigits/trailDigits ou l’implémentation de clauses d’image. Les développeurs et développeuses de formulaires peuvent créer et utiliser des apparences personnalisées pour améliorer l’expérience d’acquisition des données et la rendre plus facile d’utilisation.

Cet article est destiné aux développeurs et aux développeuses possédant des connaissances suffisantes de jQuery et des widgets jQuery. Il fournit des informations sur la structure de l’apparence et permet aux développeurs et aux développeuses de créer une apparence alternative pour un champ de formulaire.

La structure de l’apparence repose sur différentes options, événements (déclencheurs) et fonctions pour capturer les interactions de l’utilisateur ou de l’utilisatrice avec le formulaire, et répond aux changements de modèle pour informer l’utilisateur final. En outre :

  • La structure offre un ensemble d’options pour l’apparence d’un champ. Ces options sont des paires clé/valeur et sont divisées en deux catégories : les options communes et les options spécifiques à un type de champ.
  • L’apparence, en tant que partie du contrat, déclenche un ensemble d’événements, par exemple, entrer et quitter.
  • L’apparence est requise pour implémenter un ensemble de fonctions. Certaines fonctions sont communes, tandis que d’autres sont spécifiques au type de champ.

Options communes common-options

Les options globales définies sont décrites ci-après. Ces options sont disponibles pour chaque champ.

Propriété
Description
name
Identificateur qui permet de désigner un objet ou un événement dans les expressions de script. Par exemple, cette propriété indique le nom de l’application hôte.
value
Valeur réelle du champ.
displayValue
Cette valeur du champ est affichée.
screenReaderText
Les lecteurs d’écran utilisent cette valeur pour énoncer des informations sur le champ. Le formulaire fournit la valeur et vous pouvez la remplacer.
tabIndex
Position du champ dans la séquence de tabulation du formulaire. Remplacez tabIndex uniquement si vous souhaitez modifier l’ordre de tabulation par défaut du formulaire.
role
Rôle de l’élément, par exemple, un en-tête ou un tableau.
height
Hauteur du widget. Elle est spécifiée en pixels.
width
Largeur du widget. Elle est spécifiée en pixels.
access
Définit l’accès au contenu d’un objet conteneur, tel qu’un sous-formulaire.
paraStyles
La propriété Para d’un élément XFA au widget.
dir
La direction du texte. Les valeurs possibles sont ltr (de gauche à droite) et rtl (de droite à gauche).

En plus de ces options, la structure offre quelques autres options qui varient selon le type de champ. Les détails des options propres aux champs sont répertoriés ci-dessous.

Interaction avec la structure des formulaires interaction-with-forms-framework

Pour interagir avec la structure des formulaires, un widget déclenche certains événements pour activer l’exécution du script de formulaire. Si le widget n’exécute pas ces événements, certains des scripts écrits dans le formulaire qui concernent ce champ ne fonctionnent pas.

Événements déclenchés par un widget events-triggered-by-widget

Événement
Description
XFA_ENTER_EVENT
Cet événement est déclenché chaque fois que le champ est ciblé. Il autorise l’exécution du script « enter » dans le champ. La syntaxe de déclenchement de l’événement est
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_ENTER_EVENT)
XFA_EXIT_EVENT
Cet événement est déclenché chaque fois que l’utilisateur ou l’utilisatrice quitte le champ. Il permet au moteur de définir la valeur du champ et d’exécuter le script « exit ». La syntaxe de déclenchement de l’événement est
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_EXIT_EVENT)
XFA_CHANGE_EVENT
Cet événement est déclenché pour permettre au moteur d’exécuter le script « change » écrit dans le champ. La syntaxe de déclenchement de l’événement est
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)
XFA_CLICK_EVENT
Cet événement est déclenché chaque fois que l’utilisateur ou l’utilisatrice clique sur le champ. Il permet au moteur d’exécuter le script « click » écrit dans le champ. La syntaxe de déclenchement de l’événement est
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

API implémentées par un widget apis-implemented-by-widget

La structure de l’apparence appelle certaines fonctions du widget qui sont implémentées dans les widgets personnalisés. Le widget doit implémenter les fonctions suivantes :

Fonction
Description
focus: function()
Sélectionne le champ.
click: function()
Se concentre sur le champ et appelle XFA_CLICK_EVENT.

markError:function(errorMessage, errorType)

errorMessage : chaîne  représente l’erreur
errorType : chaîne ("avertissement"/"erreur")

Remarque: applicable uniquement aux formulaires HTML5.

Envoie le message d’erreur et le type d’erreur au widget. Le widget affiche l’erreur.

clearError: function()

Remarque  : applicable uniquement aux formulaires HTML5.

Appelé si les erreurs dans le champ sont corrigées. Le widget masque l’erreur.

Options spécifiques au type de champ options-specific-to-type-of-field

Tous les widgets personnalisés doivent être conformes aux spécifications ci-dessus. Pour utiliser les fonctions de différents champs, le widget doit être conforme aux directives de ce champ particulier.

TextEdit : champ de texte textedit-text-field

Option
Description
multiLine
Valeur True si le champ prend en charge la saisie d’un caractère de saut de ligne, valeur False dans le cas contraire.
maxChars
Nombre maximum de caractères pouvant être entrés dans le champ.

limitLengthToVisibleArea

Remarque  : applicable uniquement aux formulaires HTML5

Spécifie le comportement du champ de texte lorsque la largeur du texte dépasse la largeur du widget.

ChoiceList: DropDownList, ListBox choicelist-dropdownlist-listbox

Option
Description
value
Tableau des valeurs sélectionnées.
items
Tableau des objets à afficher comme des options. Chaque objet contient deux propriétés :
save : valeur à enregistrer, display : valeur à afficher.

dans un état modifiable

Remarque  : applicable uniquement aux formulaires HTML5.

Si la valeur est True, la saisie de texte personnalisé est activée dans le widget.
displayValue
Tableau des valeurs à afficher.
multiselect
Valeur True si plusieurs sélections sont autorisées, valeur False dans le cas contraire.

API api

Fonction
Description
addItem: function(itemValues)
itemValues : objet contenant les valeurs d’affichage et d’enregistrement
{sDisplayVal: <displayValue>, sSaveVal: <save Value>}
Ajoute un élément à la liste.
deleteItem  : function(nIndex)
nIndex : index de l’élément à supprimer de la liste
Supprime une option de la liste.
clearItems: function()
Efface toutes les options de la liste.

NumericEdit: NumericField, DecimalField numericedit-numericfield-decimalfield

Options
Description
dataType
Chaîne représentant le type de données du champ (entier/décimal).
leadDigits
Nombre maximal de chiffres autorisés dans la partie entière du nombre décimal.
fracDigits
Nombre maximal de chiffres autorisés dans la partie décimale du nombre décimal.
zero
Chaîne représentant zéro selon la langue du champ.
decimal
Chaîne représentant les décimales selon la langue du champ.

CheckButton : RadioButton, CheckBox checkbutton-radiobutton-checkbox

Options
Description
values

Gamme de valeurs (activé/désactivé/neutre).

Il s’agit d’une gamme de valeurs pour les différents états de l’objet checkButton. values[0] représente la valeur lorsque l’état est Activé, values[1] lorsque l’état est Désactivé,
 values[2] lorsque l’état est Neutre. La longueur de la gamme de valeurs est égale à la valeur de l’option des états.

states

Nombre d’états autorisés.

Deux pour les formulaires adaptatifs (activé, désactivé) et trois pour des formulaires HTML5 (activé, désactivé, neutre).

state

État actuel de l’élément.

Deux pour les formulaires adaptatifs (activé, désactivé) et trois pour des formulaires HTML5 (activé, désactivé, neutre).

DateTimeEdit: (DateField) datetimeedit-datefield

Option
Description
jours
Nom localisé des jours pour ce champ.
mois
Nom localisé des mois pour ce champ.
zero
Texte localisé pour le chiffre 0.
clearText
Texte localisé pour le bouton Effacer.
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2