Mar 8, 2018 12:20:08 PM seb leridon avatar   1268

Create a form with FormEngine

Introduction


This document describes the steps required to develop a form using the formengine plugin. Such a form is broken down into subforms consisting of fields and buttons. Controls can be declared on the fields.

It is necessary to write an Xml file that describes the components of the form. Associated with Xsl stylesheets, this Xml file also manages the display of subforms. The actions to be performed, and the sequence of sub-forms related to these actions are to be described in a set Java classes.

The business objects


Business objects are used to generate the output Xml stream and are generated using Jaxb using the Xsd schema describing the Xml stream.

For more information on using Jaxb, refer to the official documentation, as well as Recommandations relatives à l'utilisation de JAXB.

The Xml file for defining the form


This file is used to quickly describe the elements that make up a form. Its structure is described by the schema "form-declaration.xsd".

General information about the form

They correspond to the title and the name of the form as well as the name of the main class to use.

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

Information about each subform

They correspond to the title, name, name of the associated class, fields, buttons, controls associated with the fields (controls on a field or several), remarks, ...

1. Information about the subform Like the form, we define a unique name, a title and an associated class.

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

2. The fields The field list is provided in the formElements element. The available field types are:

  • text: free text field
  • checkbox: check box
  • radio: radio list buttons
  • combo: drop-down list
  • textarea: text box
  • upload: field for uploading files
<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>

For a list field (radio or combo), one can further specify the elements constituting the list. Note that these elements can also be added or modified via the java code in the associated subform class (for example, loading a database).

Example:

<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. Buttons The subform also provides the list of buttons (and therefore actions) available:

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

Two types are available: submit for a button and link for a link. It is mandatory to define at least one button per subform.

4. Validators The validators allow to control the data entered in the fields. They can be defined at a field level (in the checkFieldRules tag) or at a subform level (multi-field control, in the checkSubFormRules tag)). Specific validators can be written or access to generic validators available.

These are identified by their type:

  • fieldRequired : required field
<checkRule type = "fieldRequired" parameter = "true" />
  • fieldNumeric : text field whose content is numeric. We can define a minimum value and a maximum value.
<checkRule type = "fieldNumeric" min = "1" max = "20" />
  • minLength: text field to contain a minimum number of characters
<checkRule type = "minLength" parameter = "3" />
  • maxLength: text field that can contain a maximum number of characters
<checkRule type = "maxLength" parameter = "150" />
  • pattern: text field to be validated by a regular expression
<checkRule type = "pattern" parameter = "([0-9] {2}) / ([0-9] {2})" />
  • email: text field in valid email format
<checkRule type = "email" />
  • dateFormat: text field corresponding to a date. The parameter attribute gives the format to control (following the syntax of the java.text.SimpleDateFormat class). You can set a minimum date and a maximum date. The keyword " now " can be used to refer to today's date.
<checkRule type = "dateFormat" parameter = "dd / MM / yyyy" min = 21/12/2000 max = "now" />
  • phoneNumber: text field corresponding to a 10-digit French telephone number.
<checkRule type = "phoneNumber" />
  • xss: text field that can not contain certain characters. The characters that can be used in the context of xss attacks are prohibited.
<checkRule type = "xss" />
  • maxFiles: restricting an upload field to a number of files
<checkRule type = "maxFiles" parameter = "5" />
  • fileTypes: restrict an upload field to certain file types
<checkRule type = "fileTypes" parameter = "pdf, jpg, bmp" />
  • specific: allows to define a specific validator
<checkRule type = "specific" parameter = "packagename.ClassName" />

A failed control causes a default message to appear. This message can be customized using:

  • errorMessage attribute: writing the message in the Xml file.
  • errorKey attribute: provides the property containing the message to be displayed.

5. Notes blocks We can also provide in the xml file textual information exploitable at the subform level. This information can be grouped and identified by a unique name:

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

Configuration information of the outputs to use

The Xml file finally allows to define the generators to use. It is thus possible to choose whether to add generic transaction information or not, and if so, to define the identifier generator to use.

Exemple :

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

Xml files can be duplicated to provide multiple instances of a form configured differently. Note, however, that the names (attribute name ) of forms, subforms, fields, ... serve as identifier and are used by Java classes. They should not be changed from one instance to another.

Java classes


It is necessary to create a class derived from Form , and a class by subform derived from SubForm . In addition, it will be possible to write specific services (for example a specific validation service, or a specific exit service).

The form class

This class inherits from the Form class and allows to define the information specific to the form and necessary for the formengine: instance name, transaction code, Xsl sheets storage path, ...

Subform classes

For each subform, it is necessary to create a class inheriting from SubForm .

This implies :

  • the implementation of the doAction () method, which allows you to define the actions to perform (memorizing information, move to the next / previous form) according to the button clicked.
  • the implementation of the getSubFormXslStylesheet () method, which returns the path of the style sheet to use for displaying the form elements of the subform.
  • the implementation of the displaySummary () method. This allows you to insert information about the elements entered in the previous steps. For example, you can use existing Jaxb business objects by generating their associated Xml code and applying a specific style sheet to it. If you do not want to display a summary, this method should return the empty string ("").
  • in some cases, overloading the displayForm () method. The implementation provided by the parent class SubForm is appropriate in many cases. However, if it is necessary to pass variables to the style sheet associated with the form elements, or if it is necessary to initialize certain data of forms (filling of drop-down lists starting from a data base for example ), this method will have to be overloaded. After performing the specific operations, she will have to call the buildHtmlForm () method.
  • in some cases, overloading the displayHeader () method. The implementation provided by the SubForm parent class displays the title of the form and the title of the subform. It uses for this a template Html common to all subforms. If one is in a case where one must use different templates according to the subform, it will be necessary to overload the method displayHeader () , and to define the associated template.

Specific services

The services can be used to provide specific validators or to provide new types of outputs.

  • Specific validators must implement one of the child classes of the Validator class, or inherit from one of the package classes fr.paris.lutece.plugins.formengine.validator .
  • New output types must implement the OutputProcessor class or inherit from one of the formengine classes implementing it.
  • Specific identifier generators must implement IdGenerator or inherit from one of its child classes.

Objects in sessions

It may be necessary to manage in-session objects whose scope is either at the form level or at a subform level. To avoid edge effects, it is imperative to use the session parameter management methods provided by Form and SubForm .

Note also that the session is cleaned when the last subform is displayed. This must only serve to confirm the smooth running of operations. You can no longer display information about the current entry or provide input elements that impact business objects. However, we can display the identifier that has just been generated thanks to the method getTransactionId () of Form : We must pass this variable to the Xsl sheet associated with the subform in question.

Style sheets Xsl


Xsl stylesheets are used for displaying subforms.

At least one stylesheet must be defined per subform: the one responsible for displaying the form elements (fields, buttons, ...). In this style sheet, it is advisable to import "formelements.xsl": this Xsl sheet provides a large number of predefined templates (including hidden forms fields, allowing the correct sequence of screens). If you do not want to use this generic style sheet, it is strongly recommended to use the principle to define a number of templates that can be used by all subforms.

For some subforms, you may also have to define a second style sheet: the one responsible for displaying the "summary" part in a subform.

Remarque: Il est 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 plus permettre d'effectuer 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 le sous-formulaire sont automatiquement passés à la Xsl. Pour le dernier sous-formulaire, l'url de redirection définie dans le fichier de propriétés et aussi permanent automatiquement à la Xsl.