Dans le navigateur, les formulaires HTML5 génèrent des modèles XFA au format HTML5. Les formulaires HTML5 utilisent les bibliothèques jQuery, Backbone.js et Underscore.js pour l’apparence et les scripts. Les formulaires utilisent également l’architecture des widgets jQuery UI pour tous les éléments interactifs (comme les champs ou les boutons) qu’ils contiennent. Tous les éléments du widget à l’intérieur des éléments de champ XFA sont associés à un widget jQuery. 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 à XFA 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 widgets personnalisés 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. 

Pour brancher un widget aux formulaires mobiles, remplissez les conditions préalables suivantes :

  • Les formulaires HTML5 fournissent un ensemble d’options pour tous les widgets d’un champ. Ces options sont des paires clé/valeur et sont divisées en deux catégories : les options globales et les options spécifiques d'un type de champ.
  • Le widget, en tant que partie du contrat, déclenche un ensemble d’événements XFA, par exemple entrer et quitter.
  • Le widget est requis pour implémenter un ensemble de fonctions ; certaines fonctions sont globales, d’autres sont propres au type de champ.

Options communes

Vous trouverez ci-après une définition des options globales. Ces options sont disponibles pour chaque champ. 

Propriété Description
nameIdentificateur 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.
valueValeur réelle du champ. Dans la terminologie XFA, la propriété de la valeur correspond à la valeur rawValue du champ.
displayValueCette valeur du champ est affichée. Dans la terminologie XFA, la propriété displayValue correspond à la valeur formattedValue du champ.
screenReaderTextLes lecteurs d’écran utilisent cette valeur pour fournir des informations sur le champ. Le formulaire XFA fournit la valeur et vous pouvez remplacer la valeur.
tabIndexPosition 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.
roleRôle de l’élément, par exemple, un en-tête ou un tableau.
heighthauteur du widget. La hauteur est indiquée en pixels. 
widthlargeur du widget.La hauteur est indiquée en pixels.
accessDéfinit l’accès de l’utilisateur au contenu d’un objet conteneur, tel qu’un sous-formulaire.
paraStylesla propriété Para d’un élément XFA au widget
dirorientation du texte. Les valeurs possibles sont les ltr (de gauche à droite) et rtl (de droite à gauche).

En dehors de ces options, les formulaires HTML5 fournissent plusieurs 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 les formulaires HTML5

Pour interagir avec des formulaires HTML5, 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.

Evénements à déclencher

Evénement Description
XFA_ENTER_EVENT
Cet événement est déclenché chaque fois que le widget est ciblé. Il autorise l’exécution du script « enter » sur 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 ferme le widget. 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 widget 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émenter

Les formulaires HTML5 appellent certaines fonctions du widget qui sont implémentées dans les widgets personnalisés. Le widget doit implémenter les fonctions suivantes :

FonctionDescription
focus:function()place l’accent sur le widget.
click:function()place l’accent sur le widget et appelle XFA_CLICK_EVENT.

markError:function(errorMessage, errorType)

erorrMessage: string représente l'erreur
errorType : chaîne (« avertissement »/« erreur »)

Cette fonction envoie le message d’erreur et le type d’erreur au widget. Le widget affiche l’erreur.
clearError : function()Si les erreurs dans le champ ont été corrigées, cette fonction est appelée. Il est de la responsabilité du widget de masquer 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

OptionDescription
multilineValeur True si le champ prend en charge la saisie d’un caractère de saut de ligne, valeur False dans le cas contraire.
maxCharsNombre maximum de caractères pouvant être entrés dans le champ.
limitLengthToVisibleAreaIndique le comportement du champ de texte lorsque la largeur du texte dépasse la largeur du widget.

ChoiceList: DropDownList, ListBox

OptionDescription
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.

editable
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

FonctionDescription

addItem: function(itemValues)
itemValues : objet contenant la valeur affichée et d'enregistrement
{sDisplayVal : , sSaveVal : }

Ajouter un élément à la liste.
deleteItem : function(nIndex)
nIndex : index de l'élément à supprimer de la liste


Supprimer une option de la liste.
clearItems : function() Effacer toutes les options de la liste.

NumericEdit : champ numérique, champ décimal

OptionsDescription
dataTypeChaîne représentant le type de données du champ (entier/décimal/champ).
leadDigitsNombre maximal de chiffres autorisés dans le nombre décimal.
fracDigitsNombre maximal de chiffres de fraction autorisés dans le nombre décimal.
zeroReprésentation sous forme de chaîne du zéro dans la langue du champ.
decimalReprésentation sous forme de chaîne des décimales dans la langue du champ.

CheckButton: RadioButton, CheckBox

OptionsDescription
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.

statesNombre d’états autorisés. 3, si neutre est autorisé, sinon 2.
stateEtat actuel de l’élément (0 : activé, 1 : désactivé, 2 : neutre).

DateTimeEdit: (DateField)

OptionDescription
days 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.

Enregistrement du widget personnalisé avec le moteur de script XFA

Lorsque le code d’un widget personnalisé est prêt, enregistrez le widget avec le moteur de script à l’aide de l'API registerConfig pour Form Bridge. widgetConfigObject est utilisé comme entrée.

 

window.formBridge.registerConfig("widgetConfig" , widgetConfigObject);

widgetConfigObject

La configuration du widget est fournie sous la forme d’un objet JSON (ensemble de paires clé/valeur) où la clé identifie les champs et la valeur représente le widget à utiliser avec ces champs. Voici un exemple de configuration :

{

« identifier1 » : « customwidgetname »,
« identifier2 » : « customwidgetname2 »
..
}

Où « identifier » est un sélecteur CSS jQuery qui représente un champ spécifique, un ensemble de champs d’un type particulier ou tous les champs. La liste suivante regroupe les valeurs de l’identificateur dans différents cas :

Type d’identificateurIdentificateur Description
Champ particulier avec le nom fieldnameIdentificateur : « div.fieldname »Toutes les zones appelées « fieldname » sont générées à l’aide du widget.
Tous les champs de type « type » (où « type » correspond à NumericField, DateField, etc.) :Identificateur : « div.type »Le texte dans Timefield et DateTimeField est de type textfield, ces champs n’étant plus pris en charge.
Tous les champsIdentificateur :  « div.field »

Ce produit est distribué sous licence Creative Commons Attribution - Pas d’utilisation commerciale - Partage à l’identique 3.0 non transposé  Les publications Twitter™ et Facebook ne sont pas couvertes par les dispositions Creative Commons.

Mentions légales   |   Politique de confidentialité en ligne