Structure de l’apparence des formulaires adaptatifs et HTML5

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 de formulaires d’utiliser un riche ensemble de widgets et modules externes jQuery disponibles dans les 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 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 conviviale.

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

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

  • La structure propose un ensemble d’options pour l’apparence d’un champ. Ces options sont des paires clé/valeur et divisées en deux catégories : les options courantes 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 courantes, tandis que d’autres sont spécifiques aux fonctions de type champ.

Options communes

Vous trouverez ci-après une définition des options globales. 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 fournir 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 de l’utilisateur 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 les ltr (de gauche à droite) et rtl (de droite à gauche).

En dehors de ces options, la structure fournit 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 de formulaires

Pour interagir avec la structure de 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 sur le formulaire de ce champ ne fonctionnent pas.

Événements déclenchés par un 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 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 le champ est activé. 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

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() Place l’accent sur 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 au formulaires HTML5.

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

Options spécifiques du type de champ

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

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 au formulaires HTML5.

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

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 au 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

Fonction Description

addItem: function(itemValues)
itemValues : objet contenant la valeur affichée 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 : champ numérique, champ décimal

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 le nombre décimal.
fracDigits Nombre maximal de chiffres de fraction autorisés dans le nombre décimal.
zero Représentation sous forme de chaîne du zéro dans la langue du champ.
decimal Représentation sous forme de chaîne des décimales dans la langue du champ.

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. valeurs[0] représente la valeur lorsque l’état est ACTIVE, valeurs[1] lorsque l’état est DESACTIVE,
valeurs[2] est la valeur lorsque l’état est NEUTRE. La longueur de la gamme de valeurs est égale à la valeur de l’option d’état.
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)

Option Description
jours Nom localisé des jours pour ce champ.
months Nom localisé des mois pour ce champ.
zero Texte localisé pour le nombre 0.
clearText Texte localisé pour le bouton Effacer.

Sur cette page