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 de formulaires d’utiliser un riche ensemble de widgets et modules externes jQuery disponibles dans Forms. 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 de capture 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 autre apparence pour un champ de formulaire.

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

  • La structure fournit un ensemble d’options pour l’aspect 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 au type de champ.
  • L’aspect, dans le cadre du contrat, déclenche un ensemble d’événements tels que enter et quitter.
  • L’aspect est requis 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 common-options

Vous trouverez ci-dessous les options globales définies. 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 Readers d’écran utilisent cette valeur pour narrer les 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.
rôle
Rôle de l’élément, par exemple, En-tête ou Tableau.
hauteur
Hauteur du widget. Il est spécifié en pixels.
width
Largeur du widget. Il est spécifié en pixels.
access
Contrôles utilisés pour accéder au contenu d’un objet conteneur, tel qu’un sous-formulaire.
paraStyles
La propriété para d’un élément XFA au widget.
dir
Orientation du texte. Les valeurs possibles sont ltr (de gauche à droite) et rtl (de droite à gauche).

Outre ces options, la structure fournit d’autres options qui varient selon le type de champ. Les détails des options spécifiques aux champs sont répertoriés ci-dessous.

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

Pour interagir avec la structure de formulaires, un widget déclenche certains événements pour permettre au script de formulaire de fonctionner. Si le widget ne génère pas ces événements, certains des scripts écrits dans le formulaire pour ce champ ne fonctionnent pas.

Événements déclenchés par le 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 la suivante :
(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 la suivante :
(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 la suivante :
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CHANGE_EVENT)
XFA_CLICK_EVENT
Cet événement est déclenché chaque fois que l’utilisateur 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 la suivante :
(widget)._trigger(xfalib.ut.XfaUtil.prototype.XFA_CLICK_EVENT)

API implémentées par 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()
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 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
True si le champ prend en charge la saisie d’un caractère de saut de ligne, sinon false.
maxChars
Nombre maximum de caractères pouvant être renseignés dans le champ.

limitLengthToVisibleArea

Remarque: applicable uniquement aux formulaires HTML5

Indique 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 d’objets à afficher en tant qu’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 de valeurs à afficher.
multiselect
True si plusieurs sélections sont autorisées, sinon false.

API api

Fonction
Description
addItem: function(itemValues)
itemValues : objet contenant la valeur display et save
{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 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 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 de 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 checkbutton-radiobutton-checkbox

Options
Description
values

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

Il s’agit d’un tableau de valeurs pour les différents états de checkButton. values[0] est la valeur lorsque l’état est activé, values[1] est la valeur lorsque l’état est désactivé,
values[2] est la valeur lorsque l’état est NEUTRAL. La longueur du tableau 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

Etat 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
Noms de mois localisés pour ce champ.
zero
Texte localisé pour le nombre 0.
clearText
Texte localisé pour le bouton Effacer.
recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2