Show Menu
SUJETS×

Structure d'un formulaire

La description d'un formulaire est un document XML structuré respectant la grammaire du schéma des formes xtk:form .
Le document XML du formulaire de saisie doit contenir l’élément racine <form> avec les attributs name et namespace pour renseigner respectivement le nom du formulaire et son namespace.
<form name="form_name" namespace="name_space">
...
</form>

Par défaut, un formulaire est associé au schéma de données possédant un nom et un namespace identiques. Pour associer un formulaire avec un nom différent, définissez l’attribut entity-schema de l’élément <form> sur le nom de la clé de schéma. Pour illustrer la structure d'un formulaire de saisie, nous allons décrire une interface à partir du schéma d'exemple "cus:recipient" :
<srcSchema name="recipient" namespace="cus">
  <enumeration name="gender" basetype="byte">    
    <value name="unknown" label="Not specified" value="0"/>    
    <value name="male" label="Male" value="1"/>   
    <value name="female" label="Female" value="2"/>   
  </enumeration>

  <element name="recipient">
    <attribute name="email" type="string" length="80" label="Email" desc="E-mail address of recipient"/>
    <attribute name="birthDate" type="datetime" label="Date"/>
    <attribute name="gender" type="byte" label="Gender" enum="gender"/>
  </element>
</srcSchema>

Le formulaire de saisie à partir du schéma d'exemple :
<form name="recipient" namespace="cus">
  <input xpath="@gender"/>
  <input xpath="@birthDate"/>
  <input xpath="@email"/>
</form>

La description des contrôles d’édition commence à partir de l’élément <form> . Un contrôle d’édition est renseigné sur un élément <input> avec l’attribut xpath qui contient le chemin du champ dans son schéma.
Le contrôle d'édition s'adapte automatiquement au type de données correspondant et utilise le libellé défini dans le schéma.
Vous pouvez surcharger le libellé défini dans son schéma de données en ajoutant l’attribut label à l’élément <input>  : <input label="E-mail address" xpath="@name" />
Par défaut, chaque champ est affiché sur une seule ligne et occupe tout l'espace disponible selon le type de données.

Mise en forme

La disposition des contrôles entre eux ressemble à celle utilisée dans les tableaux HTML, avec la possibilité de diviser un contrôle en plusieurs colonnes, utiliser des imbrications d'éléments ou de spécifier l'occupation de l'espace disponible. Il faut cependant retenir que la mise en page autorise seulement des répartitions de proportions, il n'est pas possible de spécifier des dimensions fixes pour un objet.
Pour afficher les contrôles de l'exemple précédent sur deux colonnes :
<form name="recipient" namespace="cus">
  <container colcount="2">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email"/>
  </container>
</form>

L’élément <container> avec l'attribut colcount permet de forcer l’affichage des contrôles fils sur deux colonnes.
L'attribut colspan sur un contrôle étend celui-ci avec le nombre de colonnes renseignées dans sa valeur :
<form name="recipient" namespace="cus">
  <container colcount="2">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
</form> 

En renseignant l'attribut type="frame" , le conteneur ajoute un habillage autour des contrôles fils avec le libellé contenu dans l'attribut label :
<form name="recipient" namespace="cus">
  <container colcount="2" type="frame" label="General">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
</form>

Un élément <static> peut être utilisé pour mettre en forme le formulaire de saisie :
<form name="recipient" namespace="cus">
  <static type="separator" colspan="2" label="General"/>
  <input xpath="@gender"/>
  <input xpath="@birthDate"/>
  <input xpath="@email" colspan="2"/>
  <static type="help" label="General information about recipient with date of birth, gender, and e-mail address." colspan="2"/>
</form>

La balise <static> avec le type separator permet d’ajouter une barre de séparation avec un libellé contenu dans l’attribut label .
Un texte d’aide a été ajouté à l’aide de la balise <static> avec le type d’aide. Le contenu du texte est saisi dans l’attribut label .

Les conteneurs

Les conteneurs permettent de regrouper un ensemble de contrôles. Ils sont représentés par l’élément <container> . Ils ont été utilisés ci-dessus pour mettre en forme les contrôles sur plusieurs colonnes.
L’attribut xpath sur un <container> permet de simplifier le référencement des contrôles fils. Le référencement des contrôles est alors relatif au <container> parent.
Exemple de conteneur sans "xpath" :
<container colcount="2">
  <input xpath="location/@zipCode"/>
  <input xpath="location/@city"/>
</container>

Exemple avec ajout du "xpath" sur l'élément de nom "location" :
<container colcount="2" xpath="location">
  <input xpath="@zipCode"/>
  <input xpath="@city"/>
</container>

Types de conteneurs

Les conteneurs sont utilisés pour construire des contrôles complexes ayant recours à un ensemble de champs mis en forme dans des pages.

Conteneur à onglets

Un conteneur à onglets met en forme les données dans des pages accessibles depuis des onglets.
<container type="notebook">
  <container colcount="2" label="General">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
  <container colcount="2" label="Location">
    ...
  </container>
</container>

Le conteneur principal est défini par l'attribut type="notebook" . Les onglets sont déclarés dans les conteneurs fils, le libellé des onglets est renseigné à partir de l'attribut label .
Une propriété style="down|up (par défaut) " force le positionnement vertical des libellés des onglets en bas ou en haut du contrôle. Cette propriété est optionnelle. <container style="down" type="notebook"> ... </container>

Liste à icônes

Ce conteneur affiche une barre d'icônes verticale permettant de sélectionner les pages à afficher.
<container type="iconbox">
  <container colcount="2" label="General" img="xtk:properties.png">
    <input xpath="@gender"/>
    <input xpath="@birthDate"/>
    <input xpath="@email" colspan="2"/>
  </container>
  <container colcount="2" label="Location" img="nms:msgfolder.png">
    ...
  </container>
</container>

Le conteneur principal est défini par l'attribut type="iconbox" . Les pages associées aux icônes sont déclarées dans les conteneurs fils. Le libellé des icônes est renseigné à partir de l'attribut label .
L’icône d’une page est renseignée à partir de l’attribut img="<image>" , où <image> est le nom de l’image correspondant à sa clé construite avec le nom et le namespace (par exemple « xtk:properties.png »).
Les images sont disponibles à partir du noeud Administration > Paramétrage > Images .

Conteneur de visibilité

Vous pouvez masquer un ensemble de contrôles à partir d'une condition dynamique.
Cet exemple illustre la visibilité des contrôles sur la valeur du champ "Genre" :
<container type="visibleGroup" visibleIf="@gender=1">
  ...
</container>
<container type="visibleGroup" visibleIf="@gender=2">
  ...
</container>

Un conteneur de visibilité est défini par l'attribut type="visibleGroup" . L'attribut visibleIf contient la condition de visibilité.
Exemples de syntaxes de conditions :
  • visibleIf="@email='peter.martinezATneeolane.net'"  : teste l’égalité sur les données de type chaîne. La valeur de comparaison doit être entre guillemets.
  • visibleIf="@gender >= 1 and @gender != 2" : condition sur une valeur numérique.
  • visibleIf="@boolean1==true or @boolean2==false" : test sur des champs booléens.

Conteneur d'activation

Ce conteneur pemet l'activation ou la désactivation d'un ensemble de données à partir d'une condition dynamique. La désactivation d'un contrôle empêche son édition. L'exemple suivant illustre l'activation des contrôles à partir de la valeur du champ "Genre" :
<container type="enabledGroup" enabledIf="@gender=1">
  ...
</container>
<container type="enabledGroup" enabledIf="@gender=2">
  ...
</container>

Un conteneur d'activation est défini par l'attribut type="enabledGroup" . L'attribut enabledIf contient la condition d'activation.

Contrôles liste mémoire

Les listes mémoire permettent d'éditer les éléments de collection avec le préchargement des données la liste. Cette liste ne peut être ni filtrée, ni configurée.
Ces listes sont utilisées sur les éléments de collections mappés en XML ou sur les liens à faible volume.

Liste en colonnes

Ce contrôle affiche une liste à colonnes éditable avec une barre d'outils contenant les boutons d'ajout et de suppression.
<input xpath="rcpEvent" type="list">
  <input xpath="@label"/>
  <input xpath="@date"/>
</input>

Le contrôle liste doit être renseigné avec l'attribut type="list" , le chemin de la liste doit porter sur l'élément de collection.
Les colonnes sont déclarées dans les balises <input> de la liste. Le libellé et la taille de colonne peuvent être forcés avec les attributs label et colSize .
Les flèches d'ordonnancement sont ajoutées automatiquement lorsque l'attribut ordered="true" est ajouté sur l'élément de collection dans le schéma de données.
Les boutons de la barre d'outils peuvent être alignés horizontalement :
<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent" zoom="true">
  <input xpath="@label"/>
  <input xpath="@date"/>
</input>

L'attribut toolbarCaption force l'alignement horizontal de la barre d'outils et renseigne le titre au dessus de la liste.

Zoom dans les listes

L'insertion et l'édition des données d'une liste peut être renseigné dans une forme d'édition séparée.
<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent" zoom="true" zoomOnAdd="true">
  <input xpath="@label"/>
  <input xpath="@date"/>

  <form colcount="2" label="Event">
    <input xpath="@label"/>
    <input xpath="@date"/>
  </form>
</input>

Le formulaire d’édition est rempli à partir de l’élément <form> sous la définition de liste. Sa structure est identique à celle d’un formulaire de saisie. Le bouton Détail est ajouté automatiquement lorsque l’attribut zoom="true" est renseigné sur la balise <input> de la liste. Cet attribut permet de lancer le formulaire d’édition de la ligne sélectionnée.
L'ajout de l'attribut zoomOnAdd="true" force l'appel de la forme d'édition sur l'insertion d'un élément de la liste.

Propriétés de la liste

  • noToolbar : cache la barre d'outils (avec la valeur "true")
  • toolbarCaption : surcharge le libellé de la barre d'outils
  • toolbarAlign : modifie le positionnement de la barre d'outils (valeurs possibles : "vertical"|"horizontal")
  • img : affiche l'image associée à la liste
  • form : surcharge la forme d'édition de l'élément ciblé
  • zoom : ajoute le bouton Zoom pour l'édition de l'élément ciblé
  • zoomOnAdd : lance le forme d'édition sur l'ajout
  • xpathChoiceTarget : pour l'ajout, lance la forme de choix sur le lien renseigné

Champs non éditables

Pour afficher un champ et empêcher son édition, vous devez utiliser la balise <value> ou renseigner l’attribut readOnly="true" sur la balise <input> .
Exemple sur le champ "Genre" :
<value value="@gender"/>
<input xpath="@gender" readOnly="true"/>

Bouton radio

Un bouton radio permet d’effectuer un choix parmi plusieurs options. Les balises <input> sont utilisées pour répertorier les options possibles et l’attribut checkedValue spécifie la valeur associée au choix.
Exemple sur le champ "Genre" :
<input type="RadioButton" xpath="@gender" checkedValue="0" label="Choice 1"/>
<input type="RadioButton" xpath="@gender" checkedValue="1" label="Choice 2"/>
<input type="RadioButton" xpath="@gender" checkedValue="2" label="Choice 3"/>

Bouton à cocher

Un bouton à cocher permet de refléter un état boolean (pressé ou non). Par défaut ce contrôle est utilisé par les champs de type "boolean" (true/false). On peut associer à ce bouton une variable qui prendra par défaut la valeur 0 ou 1 ; cette valeur peut être surchargée à partir de l'attribut checkValue .
<input xpath="@boolean1"/>
<input xpath="@field1" type="checkbox" checkedValue="Y"/>

Champ d'expression

Un champ d’expression permet de mettre à jour dynamiquement un champ à partir d’une expression ; la balise <input> est utilisée avec un attribut xpath pour renseigner le chemin du champ à mettre à jour et un attribut expr contenant l’expression de mise à jour.
<!-- Example: updating the boolean1 field from the value contained in the field with path /tmp/@flag -->
<input expr="Iif([/tmp/@flag]=='On', true, false)" type="expr" xpath="@boolean1"/>
<input expr="[/ignored/@action] == 'FCP'" type="expr" xpath="@launchFCP"/>

Contexte des formes

L'exécution d'un formulaire de saisie initialise un document XML contenant les données de l'entité en cours d'édition. Ce document représente le contexte du formulaire et peut être utilisé comme espace de travail.

Mise à jour du contexte

Pour modifier le contexte du formulaire, vous devez utiliser la balise <set expr="<value>" xpath="<field>"/> , où <field> est le chemin destination et <value> est la valeur ou expression de mise à jour.
Exemples d’utilisation de la balise <set>  :
  • <set expr="'Test'" xpath="/tmp/@test" />  : positionne la valeur 'Test' à l’emplacement temporaire /tmp/@test1
  • <set expr="'Test'" xpath="@lastName" />  : met à jour l’entité sur l’attribut "lastName" avec la valeur 'Test'
  • <set expr="true" xpath="@boolean1" />  : définit sur vrai ("true") la valeur du champ "boolean1"
  • <set expr="@lastName" xpath="/tmp/@test" />  : met à jour avec le contenu de l’attribut "lastName"
La mise à jour du contexte du formulaire peut être effectuée à l’initialisation et à la fermeture du formulaire, à partir des balises <enter> et <leave> .
<form name="recipient" namespace="cus">
  <enter>
    <set...
  </enter>
  ...
  <leave>
    <set...
  </leave>
</form>

Les balises <enter> et <leave> peuvent être utilisées sur les <container> de pages (types "notebook" et "iconbox").

Langage d'expression

Un macro-langage peut être utilisé dans la définition d'un formulaire afin d'effectuer des tests conditionnels.
La balise <if expr="<expression>" /> exécute les instructions spécifiées sous la balise si l’expression est vérifiée :
<if expr="([/tmp/@test] == 'Test' or @lastName != 'Doe') and @boolean2 == true">
  <set xpath="@boolean1" expr="true"/>
</if>

La balise <check expr="<condition>" /> combinée avec la balise <error> empêche la validation du formulaire et affiche un message d’erreur si la condition n’est pas respectée :
<leave>
  <check expr="/tmp/@test != ''">
    <error>You must populate the 'Test' field!</error> 
  </check>
</leave>

Assistants

Un assistant permet une saisie guidée à travers un ensemble d'étapes présentées sous forme de pages. La validation du formulaire enregistre les informations saisies.
Un assistant se construit de la façon suivante :
<form type="wizard" name="example" namespace="cus" img="nms:rcpgroup32.png" label="Wizard example" entity-schema="nms:recipient">
  <container title="Title of page 1" desc="Long description of page 1">
    <input xpath="@lastName"/>
    <input xpath="comment"/>
  </container>
  <container title="Title of page 2" desc="Long description of page 2">
    ...
  </container>
  ...
</form>

La présence de l’attribut type="wizard" sur l’élément <form> permet de définir le mode assistant dans la construction du formulaire. Les pages sont renseignées à partir d’éléments <container> qui sont des enfants de l’élément <form> . L’élément <container> d’une page est renseigné avec l’attribut title pour le titre, et l’attribut desc pour afficher la description sous le titre de la page. Les boutons Précédent et Suivant sont automatiquement ajoutés afin de naviguer de page en page.
Le bouton Terminer enregistre les informations saisies et ferme le formulaire.

Méthodes SOAP

L’exécution d’une méthode SOAP peut être lancée à partir d’une balise <leave> renseignée en fin de page.
La balise <soapcall> contient l’appel de la méthode avec les paramètres en entrée :
<soapCall name="<name>" service="<schema>">
  <param type="<type>" exprIn="<xpath>"/>  
  ...
</soapCall>

Le nom du service et son schéma d’implémentation sont renseignés à partir des attributs name et service de la balise <soapcall> .
Les paramètres en entrée sont décrits sur les éléments <param> sous la balise <soapcall> .
Le type du paramètre doit être spécifié à partir de l'attribut type . Les différents types possibles sont les suivants :
  • string : chaîne de caractères
  • boolean : booléen
  • byte : nombre entier 8 bits
  • short : nombre entier 16 bits
  • long : nombre entier 32 bits
  • short : nombre entier 16 bits
  • double : nombre flottant double précision
  • DOMElement : noeud de type élément
L'attribut exprIn contient l'emplacement de la donnée à passer en paramètre.
Exemple :
<leave>
  <soapCall name="RegisterGroup" service="nms:recipient">         
    <param type="DOMElement" exprIn="/tmp/entityList"/>         
    <param type="DOMElement" exprIn="/tmp/choiceList"/>         
    <param type="boolean"    exprIn="true"/>       
  </soapCall>
</leave>