May 28, 2014 9:39:06 PM lutece lutece avatar   521    

Créer un formulaire avec FormEngine

Introduction


Ce document décrit les étapes nécessaires au développement d'un formulaire utilisant le plugin formengine . Un tel formulaire se décompose en sous-formulaires composés de champs et de boutons. Des contrôles peuvent être déclarés sur les champs.

Il est nécessaire d'écrire un fichier Xml qui décrit les composant du formulaire. Associé à des feuilles de styles Xsl, ce fichier Xml permet de gérer aussi l'affichage des sous-formulaires. Les actions à réaliser, et l'enchaînement de sous-formulaires lié à ces actions sont à décrire dans un ensemble de classes Java.

Les objets métier


Les objets métier servent à générer le flux Xml de sortie et sont générés à l'aide de Jaxb grâce au schéma Xsd décrivant le flux Xml.

Pour plus d'information concernant l'utilisation de Jaxb, se reporter à la documentation officielle, ainsi qu'aux Recommandations relatives à l'utilisation de JAXB.

Le fichier Xml de définition du formulaire


Ce fichier permet de décrire rapidement les éléments qui constituent un formulaire. Sa structure est décrite par le schéma "form-declaration.xsd".

Les informations générales concernant le formulaire

Elles correspondent au titre et au nom du formulaire ainsiqu'au nom de la classe principale à utiliser.

<formDefinition name="..." className="fr.paris.lutece.plugins.formengine.modules.....web.classForm">
    <title>Titre du formulaire</title>
    ...
 </formDefinition>

Les informations concernant chaque sous-formulaire

Elles correspondent aux titre, nom, nom de la classe associée, champs, boutons, contrôles associés aux champs (contrôles sur un champ ou plusieurs), remarques, ...

1. Les informations concernant le sous-formulaire Comme au niveau du formulaire, on définit un nom unique, un titre et une classe associée.

<subFormDefinition name="..." className="fr.paris.lutece.plugins.formengine.modules.....web.classSubForm">
    <title>Saisie des objets</title>
    <formElements>...</formElements>
 </subFormDefinition>

2. Les champs La liste de champs est fournie dans l'élément formElements. Les types de champs disponibles sont :

  • text : champ texte libre
  • checkbox : case à cocher
  • radio : liste de radio buttons
  • combo : liste déroulante
  • textarea : zone de texte
  • upload : champ permettant d'uploader des fichiers
 
<fields>
    <field name="nomChamp" type="text">
        <label>Titre du champ</label>
        <value>Valeur par défaut (peut-être vide)</value>
        <additionalInfo>Informations sur le champ</additionalInfo>
        <checkFieldRules>Cf. point suivant </checkFieldRules>
    </field>
...
</fields>

Pour un champ de liste (radio ou combo), on peut de plus préciser les éléments constituant la liste. Notons que ces éléments peuvent aussi être ajoutés ou modifiés via le code java dans la classe de sous-formulaire associée (chargement d'une base par exemple).

Exemple :

<field name="arrondissement" type="combo">
    <label>Arrondissement</label>
    <value>1</value>
    <choiceList>
         <choice value="1" label="1er"/>
	 <choice value="2" label="2ème"/>
	 <choice value="3" label="3ème"/>
	 ...
    </choiceList>
</field>

3. Les boutons Le sous-formulaire fournit aussi la liste de boutons (et donc des actions) disponibles :

<buttons>
    <button name="Retour" type="submit"/>
    <button name="Valider" type="submit"/> 
</buttons>

Deux types sont disponibles : submit pour un bouton et link pour un lien. Il est obligatoire de définir au moins un bouton par sous-formulaire.

4. Les validateurs Les validateurs permettent de contrôler les données saisies dans les champs. Ils peuvent être définis au niveau d'un champ (dans la balise checkFieldRules ) ou au niveau d'un sous-formulaire (contrôle multi-champ, dans la balise checkSubFormRules )). On peut écrire des validateurs spécifiques ou accéder aux validateurs génériques disponibles.

Ceux-ci sont identifiés par leur type :

  • fieldRequired : champ obligatoire
<checkRule type="fieldRequired" parameter="true" />
  • fieldNumeric : champ texte dont le contenu est numérique. On peut définir une valeur minimum et une valeur maximum.
<checkRule type="fieldNumeric" min="1" max="20" />
  • minLength : champ texte devant contenir un nombre minimum de caractères
<checkRule type="minLength" parameter="3" />
  • maxLength : champ texte pouvant contenir un nombre maximum de caractères
<checkRule type="maxLength" parameter="150" />
  • pattern : champ texte devant être validé par une expression régulière
<checkRule type="pattern" parameter="([0-9]{2})/([0-9]{2})" />
  • email : champ texte au format email valide
<checkRule type="email" />
  • dateFormat : champ texte correspondant à un date. L'attribut parameter donne le format à contrôler (suivant la syntaxe de la classe java.text.SimpleDateFormat ). On peut définir une date minimum et une date maximum. Le mot-clé "now " peut être utilisé pour faire référence à la date du jour.
<checkRule type="dateFormat" parameter="dd/MM/yyyy" min=21/12/2000 max="now" />
  • phoneNumber : champ texte correspondant à un numéro de téléphone français à 10 chiffres.
<checkRule type="phoneNumber" />
  • xss : champ texte ne pouvant contenir certains caractères. Sont interdits les caractères pouvant être utilisés dans le cadre d'attaques xss.
<checkRule type="xss" />
  • maxFiles : restriction d'un champ d'upload à un certain nombre de fichiers
<checkRule type="maxFiles" parameter="5" />
  • fileTypes : restriction d'un champ d'upload à certains types de fichiers
<checkRule type="fileTypes" parameter="pdf, jpg, bmp" />
  • specific : permet de définir un validateur spécifique
<checkRule type="specific" parameter="nompackage.NomClasse" />

Un contrôle non respecté provoque l'affichage d'un message par défaut. Ce message peut être personnalisé en utilisant :

  • l'attribut errorMessage : écriture du message dans le fichier Xml.
  • l'attribut errorKey : fournit la propriété contenant le message à afficher.

5. Les blocs de remarques On peut aussi fournit dans le fichier xml des informations textuelles exploitables au niveau du sous-formulaire. Ces informations peuvent être groupées et identifées par un nom unique :

<notices>
     <noticeGroup name="warning" >
     <notice>blab la bla</notice>
	 ...
      </noticeGroup>
      ...
 </notices>

Les informations de configuration des sorties à utiliser

Le fichier Xml permet enfin de définir les générateurs à utiliser. Il est ainsi possible de choisir si on ajoute ou non des informations de transaction génériques, et si c'est le cas, de définir le générateur d'identifiants à utiliser.

Exemple :

<outputs>
      <outputSet useTransactionHeaders="false" >
      <output outputProcessorClassName="....DBOutputProcessor" />
      <output outputProcessorClassName="....MailOutputProcessor" />
      </outputSet>
            <outputSet useTransactionHeaders="true" specificTransactionIdGeneratorClassName="....IdGeneratorClass" >
            <output outputProcessorClassName="....XmlFileOutputProcessor"/>
      </outputSet>
 </outputs>

Les fichiers Xml peuvent être dupliqués pour fournir plusieurs instances d'un formulaire configurées différemment. Notons cependant que les noms (attribut name ) de formulaires, de sous-formulaires, de champs, ... servent d'identifiant et sont utilisés par les classes Java. Ils ne doivent donc pas être modifiés d'une instance à l'autre.

Les classes Java


Il est nécessaire de créer une classe dérivant de Form , et une classe par sous-formulaire dérivant de SubForm . On pourra de plus écrire des services spécifiques (par exemple un service de validation spécifique, ou encore un service de sortie spécifique).

La classe de formulaire

Cette classe hérite de la classe Form et permet de définir les informations propres au formulaire et nécessaires au formengine : nom d'instance, code de transaction, chemin de stockage des feuilles Xsl, ...

Les classes de sous-formulaire

Pour chaque sous-formulaire, il est nécessaire de créer une classe héritant de SubForm .

Ceci implique :

  • l'implémentation de la méthode doAction() , qui permet de définir les actions à réaliser (mémorisation d'information, passage au formulaire suivant/précédent) en fonction du bouton cliqué.
  • l'implémentation de la méthode getSubFormXslStylesheet() , qui retourne le chemin de la feuille de style à utiliser pour l'affichage des éléments de formulaire du sous-formulaire.
  • l'implémentation de la méthode displaySummary(). Celle-ci permet d'insérer des informations sur les éléments renseignés aux étapes précédentes. On pourra par exemple utiliser les objets métiers Jaxb déjà crées, en générant leur code Xml associé et en appliquant à celui-ci une feuille de style spécifique. Si on ne désire pas afficher de récapitulatif, cette méthode devra renvoyer la chaîne vide ("").
  • dans certains cas, la surcharge de la méthode displayForm(). L'implémentation fournie par la classe mère SubForm convient dans bien des cas. Cependant s'il est nécessaire de passer des variables à la feuille de style associée aux éléments de formulaire, ou bien s'il est nécessaire d'initialiser certaines données de formulaires (remplissage de listes déroulantes à partir d'une base de données par exemple), il faudra surcharger cette méthode. Après avoir réalisé les opérations spécifiques, elle devra appeler la méthode buildHtmlForm() .
  • dans certains cas, la surcharge de la méthode displayHeader(). L'implémentation fournie par la classe mère SubForm affiche le titre du formulaire et le titre du sous-formulaire. Elle utilise pour cela un template Html commun à tous les sous-formulaires. Si on se trouve dans un cas où on doit utiliser des templates différents suivant le sous-formulaire, il faudra surcharger la méthode displayHeader() , et définir le template associé.

Les services spécifiques

Les services peuvent être utilisés pour fournir des validateurs spécifiques ou pour fournir des nouveaux types de sorties.

  • Les validateurs spécifiques doivent implémenter l'une des classes filles de la classe Validator , ou hériter de l'une des classes du package fr.paris.lutece.plugins.formengine.validator .
  • Les nouveaux types de sorties doivent implémenter la classe OutputProcessor ou hériter d'une des classes de formengine l'implémentant.
  • Les générateurs d'identifiants spécifiques doivent implémenter IdGenerator ou hériter d'une de ses classes filles.

Les objets en sessions

Il peut-être nécessaire de gérer des objets en session dont la portée est soit au niveau du formulaire, soit au niveau d'un sous-formulaire. Pour éviter tout effet de bord, il est impératif d'utiliser les méthodes de gestion de paramètres de session fournies par Form et SubForm .

Notons de plus que la session est nettoyée lors de l'affichage du dernier sous-formulaire. Celui-ci ne doit donc servir qu'à confirmer le bon déroulement des opérations. On ne peut plus ni y afficher des informations concernant la saisie en cours, ni y fournir des éléments de saisie impactant les objets métier. On peut cependant afficher l'identifiant qui vient d'être généré grâce à la méthode getTransactionId() de Form : Il faut passer cette variable à la feuille Xsl associée avec le sous-formulaire en question.

Les feuilles de styles Xsl


Les feuilles de styles Xsl sont utilisées pour l'affichage des sous-formulaires.

On doit définir au moins une feuille de styles par sous-formulaire : celle responsable de l'affichage des éléments de formulaire (champs, boutons, ...). Dans cette feuille de styles, il est conseillé d'importer "formelements.xsl" : cette feuille Xsl fournit un nombre important de templates prédéfinis (notamment les champs cachés des formulaires, permettant l'enchaînement correct des écrans). Si on ne désire pas utiliser cette feuille de styles générique, il est fortement conseillé d'en reprendre le principe pour définir un certain nombre de templates utilisables par tous les sous-formulaires.

Pour certains sous-formulaires, on peut de plus avoir à définir une deuxième feuille de styles : celle responsable de l'affichage de la partie "récapitulatif" dans un sous-formulaire.

Remarque : Il est souvent intéressant de passer des variables Java aux feuilles de styles lors de la transformation Xsl. En effet ces variables peuvent servir à définir des champs cachés des formulaires, ou à afficher des informations contextuelles. Elles peuvent de plus permettre de réaliser des tests conditionnels au niveau de la feuille de style.

En utilisant la méthode buildHtmlForm() de la classe SubForm , le nom du formulaire et du sous-formulaire sont automatiquement passés à la Xsl. Pour le dernier sous-formulaire, l'url de redirection définie dans le fichier de properties et aussi passée automatiquement à la Xsl.