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 espace de noms.

<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 espace de noms 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.

REMARQUE

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.

REMARQUE

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 l’espace de noms (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.

Pour rappel, un lien est déclaré dans le schéma de données de la façon suivante :

<element label="Company" name="company" target="cus:company" type="link"/>

Le contrôle d'édition du lien dans son formulaire de saisie est :

<input xpath="company"/>

Le choix de la cible est accessible à partir de la zone d'édition. Une aide à la saisie par auto-complétion permet de retrouver facilement un élément de la cible en fonction des premiers caractères renseignés. La recherche se base alors sur la Compute string définie dans le schéma ciblé. Si la cible n'existe pas après validation dans le contrôle, un message de confirmation de création à la volée de la cible est affiché. La confirmation crée un nouvel enregistrement de la table cible et l'associe sur le lien.

Une liste déroulante permet de sélectionner un élément de la cible parmi la liste des enregistrements déjà créés.

L'icône Modifier le lien (dossier) lance une forme de sélection avec la liste des éléments ciblés et une zone de filtrage :

L'icône Editer le lien (loupe) lance la forme d'édition de l'élément lié. La forme utilisée est déduite par défaut sur la clé du schéma ciblé, l'attribut form permet de forcer le nom de la forme d'édition (par exemple "cus:company2").

Vous pouvez restreindre le choix des éléments de la cible en ajoutant l’élément <sysfilter> à partir de la définition du lien dans le formulaire de saisie :

<input xpath="company">
  <sysFilter>
    <condition expr="[location/@city] =  'Newton"/>
  </sysFilter>
</input>

Vous pouvez aussi trier la liste avec l’élément <orderby> :

<input xpath="company">
  <orderBy>
    <node expr="[location/@zipCode]"/>
  </orderBy>
</input>

Propriétés du contrôle

  • noAutoComplete : désactive l'auto-complétion (avec la valeur "true")

  • createMode : crée le lien à la volée s'il n'existe pas, les valeurs possibles sont :

    • none : désactive la création, un message d'erreur est affiché si le lien n'existe pas
    • inline : crée le lien avec le contenu dans la zone d'édition
    • edition : affiche la forme d'édition sur le lien, la validation de la forme enregistre les données (mode par défaut)
  • noZoom : pas de forme d'édition sur le lien (avec la valeur "true")

  • form : surcharge la forme d'édition de l'élément ciblé

Un lien renseigné dans le schéma de données en tant que élément de collection (@unbound="true") doit obligatoirement passer par une liste afin de visualiser l'ensemble des éléments qui lui sont associés.

Le principe consiste à afficher la liste des éléments liés avec un chargement des données optimisé (récupération par batch des données, exécution de la liste uniquement si elle est visible).

Exemple de lien de collection dans un schéma :

<element label="Events" name="rcpEvent" target="cus:event" type="link" unbound="true">
...
</element>

La liste dans son formulaire de saisie :

 <input xpath="rcpEvent" type="linklist">
  <input xpath="@label"/>
  <input xpath="@date"/>
</input>

Le contrôle liste est defini par l'attribut type="linklist", le chemin de la liste doit porter sur le lien de collection.

Les colonnes sont déclarées via les éléments <input> fils de la liste. L’attribut xpath fait référence au chemin du champ dans le schéma cible.

Une barre d'outils avec un libellé (défini sur le lien dans le schéma) est automatiquement positionnée au-dessus de la liste.

La liste peut être filtrée à partir du bouton Filtres et configurée pour ajouter et trier les colonnes.

Les boutons Ajouter et Supprimer permettent l'ajout et la suppression des éléments de collection du lien. L'ajout d'un élément lance par défaut la forme d'édition du schéma cible.

Le bouton Détail est automatiquement ajouté lorsque l’attribut zoom="true" est renseigné sur la balise <input> de la liste : il permet de lancer la forme d’édition de la ligne sélectionnée.

Un filtre et un tri peuvent être appliqués lors du chargement de la liste :

 <input xpath="rcpEvent" type="linklist">
  <input xpath="@label"/>
  <input xpath="@date"/>
  <sysFilter>
    <condition expr="@type = 1"/>
  </sysFilter>
  <orderBy>
    <node expr="@date" sortDesc="true"/>
  </orderBy>
</input>

Table de relation

Une table de relation permet de lier deux tables avec une cardinalité N-N. La table de relation contient uniquement les liens vers les deux tables.

L'ajout d'un élément dans la liste doit donc permettre de renseigner une liste à partir d'un des deux liens de la table de relation.

Exemple de table de relation dans un schéma :

<srcSchema name="subscription" namespace="cus">
  <element name="recipient" type="link" target="cus:recipient" label="Recipient"/>
  <element name="service" type="link" target="cus:service" label="Subscription service"/>
</srcSchema>

Pour notre exemple, nous partirons du formulaire de saisie du schéma "cus:recipient". La liste doit afficher les associations avec les abonnements aux services et permettre d'ajouter un abonnement en sélectionnant un service déjà existant.

<input type="linklist" xpath="subscription" xpathChoiceTarget="service" xpathEditTarget="service" zoom="true">
  <input xpath="recipient"/>
  <input xpath="service"/>
</input>

L'attribut xpathChoiceTarget permet de lancer une forme de choix à partir du lien renseigné. La création de l'enregistrement de la table de relation va automatiquement mettre à jour le lien sur le destinataire courant et le service sélectionné.

REMARQUE

L'attribut xpathEditTarget permet de forcer l'édition de la ligne sélectionnée sur le lien renseigné.

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 la géométrie verticale ou horizontale 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é
  • xpathEditTarget : fixe l'édition sur le lien renseigné
  • xpathChoiceTarget : pour l'ajout, lance la forme de choix sur le lien renseigné

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.

REMARQUE

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.

REMARQUE

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"/>

Ce contrôle construit une arborescence sur un ensemble de champs à éditer.

Les contrôles à éditer sont regroupés dans un <container> renseigné sous la balise <input> du contrôle arborescent :

<input nolabel="true" type="treeEdit">
  <container label="Text fields">
    <input xpath="@text1"/>
    <input xpath="@text2"/>
  </container>
  <container label="Boolean fields">
    <input xpath="@boolean1"/>
    <input xpath="@boolean2"/>
  </container>
</input>

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?lang=fr" /> : 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?lang=fr" /> : 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>
REMARQUE

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%20!=%20''?lang=fr">
    <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?lang=fr"/>         
    <param type="DOMElement" exprIn="/tmp/choiceList?lang=fr"/>         
    <param type="boolean"    exprIn="true"/>       
  </soapCall>
</leave>

Sur cette page

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now