xml-1.1.gtw

~~LANG:EN@enman:jforms/xml-1.1~~

La version 1.1 du format décrit dans cette page est utilisable depuis Jelix 1.1.

===== Structure principale =====

Le document XML que vous écrivez dans un fichier jForms est composé d'une balise
@@E@<form>@@ comme racine.

<code xml>
<?xml version="1.0" encoding="utf-8"?>
<form xmlns="http://jelix.org/ns/forms/1.1">

</form>
</code>


Dans cette balise, vous indiquerez les balises correspondantes à chacun des
contrôles (champs de saisies) composant le formulaire. Le traitement et
l'affichage de ces contrôles se feront dans le même ordre que celui de leur
apparition dans le document.

Notez que le namespace pour cette version du format est
@@http://jelix.org/ns/forms/1.1@@

===== Propriétés communes aux contrôles =====



==== Identifiant ====

Chaque contrôle doit avoir un identifiant (= un nom). Vous devez en indiquer un
avec l'attribut @@A@ref@@. Cet identifiant correspond en fait à ce qu'on appelle
une variable de formulaire et qui contiendra la valeur saisie.

Exemple:
<code xml>
  <input ref="nom">
  </input>
</code>


Note : quand vous voulez utiliser un formulaire avec un ou plusieurs DAO, il est
judicieux d'utiliser les mêmes noms que les propriétés des DAO, afin de pouvoir
utiliser les mécanismes de chargement et sauvegarde automatique de jForms avec
les DAO.


==== Libellé ====

Tout champ de saisie doit contenir un libellé indiqué au moyen de la balise
@@E@<label>@@ :

<code xml>
  <input ref="nom">
    <label>Votre nom</label>
  </input>
</code>

On peut indiquer une [[/locales|locale]] plutôt qu'une chaine "en dur" :

<code xml>
  <input ref="nom">
    <label locale="mymodule~forms.input.name"/>
  </input>
</code>

==== Saisie obligatoire ====

Pour rendre la saisie obligatoire sur un champ de saisie, il faut mettre
l'attribut @@A@required@@ avec la valeur @@L@true@@. Cet attribut n'est pas
valable sur les éléments @@E@<submit>@@, @@E@<checkbox>@@, @@E@<group>@@,
@@E@<choice>@@, @@E@<hidden>@@ et @@E@<output>@@.


==== Lecture seule ====

Il est possible d'empêcher la modification d'un champ de saisie. Pour cela, il
faut mettre l'attribut @@A@readonly@@ avec la valeur @@L@true@@. Cet attribut
n'est pas valable sur l'élément @@E@<submit>@@ et @@E@<output>@@. Vous pouvez
modifier cette propriété en PHP.

==== Messages informatifs ====

Un message d'aide (optionnel) peut être affiché en même temps que le contrôle de
saisie, grâce à la balise @@E@<help>@@ : vous y inscrivez soit le message
d'aide, soit la locale (via l'attribut @@A@locale@@).

<code xml>
  <input ref="datenaissance" type="date">
    <label locale="mymodule~forms.input.naissance"/>
    <help>Indiquez votre date de naissance, en respectant le format aaaa-mm-jj</help>
  </input>

ou

  <input ref="datenaissance" type="date">
    <label locale="mymodule~forms.input.naissance"/>
    <help locale="mymodule~forms.input.naissance.help"/>
  </input>
</code>

Dans les formulaires en HTML, un point d'interrogation s'affichera à côté du
champ de saisie et le message d'aide s'affichera lors d'un clic sur ce point
d'interrogation. (Ce comportement peut être modifié en fournissant votre propre
générateur).

Un autre type de message informatif peut être affiché sous forme de tooltip. Il
faut pour cela utiliser la balise @@E@<hint>@@, qui s'utilise comme la balise
@@E@<help>@@.

==== Messages d'erreurs ====

Quand le contenu du champ de saisie est invalide (il n'est pas du type attendu
par exemple), ou que la saisie est manquante lorsqu'elle est requise (attribut
@@A@required@@), jForms affiche des messages d'erreurs prédéfinis. Cependant
vous pouvez fournir vous-mêmes ces messages au moyen de la balise @@E@<alert>@@.
Un attribut @@A@type@@ permet de définir soit le message pour l'erreur
d'invalidité, soit le message pour la saisie obligatoire. Et comme les balises
précédentes, vous pouvez indiquer le message complet, ou indiquer une locale au
moyen de l'attribut locale.

<code xml>
  <input ref="datenaissance" type="date">
    <label locale="mymodule~forms.input.naissance"/>
    <alert type="required" locale="mymodule~forms.input.naissance.error.required"/>
    <alert type="invalid">Le format de la date à respecter pour la saisie est aaaa-mm-jj</alert>
  </input>
</code>



===== Champs de saisie =====



==== Saisie de texte simple ====

Pour afficher un simple champ de saisie, il faut utiliser la balise
@@E@<input>@@. Vous devez y mettre l'attribut @@A@ref@@, et vous pouvez utiliser
les balises @@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que
les attributs @@A@readonly@@ et @@A@required@@. Vous pouvez indiquer aussi ces
attributs supplémentaires : @@A@type@@, @@A@defaultvalue@@, @@A@size@@,
@@A@minlength@@, @@A@maxlength@@ et @@A@pattern@@.

@@A@defaultvalue@@ permet d'indiquer une valeur par défaut qui sera affichée
quand le formulaire est vide. Vous pouvez mettre la valeur @@L@"now"@@ pour les
champs de saisie de dates. La valeur par défaut sera alors la date de
maintenant.

@@A@size@@ permet d'indiquer la largeur de la boîte de saisie en nombre de
caractères.

@@A@maxlength@@ et @@A@minlength@@ permet d'ajouter une contrainte sur la valeur
saisie : la longueur minimale et maximale de la chaine de caractère saisie. Ces
deux attributs ne sont utilisables que pour le @@A@type="string"@@.

@@A@pattern@@: Il doit contenir une expression rationnelle compatible avec PHP
et JS. Il n'est utilisatble que pour @@A@type="string"@@.

@@A@type@@ permet d'indiquer le format de données que l'utilisateur doit
respecter. Au moment de l'envoi du formulaire, il y aura une vérification en
javascript du contenu saisi, mais aussi une vérification côté serveur (au cas où
le javascript est désactivé notamment) lors de l'appel à la méthode
@@M@check()@@ sur l'objet formulaire.

Voici les valeurs possibles pour l'attribut @@A@type@@ et ce que doit taper
l'utilisateur :

  * @@L@"string"@@ : chaîne contenant n'importe quel caractère. (c'est le type par défaut)
  * @@L@"boolean"@@ : la valeur du champ doit être obligatoirement "true" ou "false"
  * @@L@"decimal"@@ : un nombre avec ou sans virgule
  * @@L@"integer"@@ : un nombre entier
  * @@L@"hexadecimal"@@ : un nombre hexadecimal (chiffres de 0 à 9 et lettres de
    a à f)
  * @@L@"datetime"@@, @@L@"date"@@, @@L@"time"@@ : une date et heure, une date
    ou une heure. Le format précis est respectivement "aaaa-mm-jj hh:mm:ss",
    "aaaa-mm-jj", "hh:mm:ss".
  * @@L@"localedatetime"@@, @@L@"localedate"@@, @@L@"localetime"@@ : une date et
    heure, une date ou une heure, mais dans le format de la langue de
    l'utilisateur. Par exemple, pour un site en français, le format de la date
    devra être "jj/mm/aaaa", et pour un site en anglais "mm/jj/aaaa".
  * @@L@"url"@@ : la chaîne doit être une URL valide
  * @@L@"email"@@ : un email
  * @@L@"ipv4"@@ : une adresse IP v4
  * @@L@"ipv6"@@ : une adresse IP v6
  * @@L@"html"@@ : du code HTML. Le contenu HTML sera "purifié" coté serveur,
    pour éviter les problèmes de sécurité comme CSS, XSS...

Un exemple de champ de saisie simple :

<code xml>
  <input ref="email" type="email">
     <label locale="monmodule~monform.email.label" />
     <hint>L'email doit être valide</hint>
  </input>
</code>

Un exemple de champ de saisie ave un pattern :

<code xml>
  <input ref="url" type="string" pattern="/^[a-z0-9\-]+$/">
      <label>Url</label>
  </input>
</code>

==== Saisie de texte multiligne ====

Pour permettre la saisie d'un texte de plusieurs lignes, il faut utiliser la
balise @@E@<textarea>@@. Vous devez y mettre l'attribut @@A@ref@@, et vous
pouvez utiliser les balises @@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@,
@@E@<help>@@ ainsi que les attributs @@A@readonly@@, @@A@required@@ et
@@A@type="html"@@. Il y a plusieurs attributs spécifiques à cette balise :
@@A@defaultvalue@@, @@A@rows@@, @@A@cols@@, @@A@minlength@@ et @@A@maxlength@@.

@@A@defaultvalue@@ permet d'indiquer une valeur à afficher automatiquement pour
un nouveau formulaire, tandis que @@A@rows@@ et @@A@cols@@ permettent de fixer
la taille du champs de saisie en hauteur et largeur (comme le textarea en HTML).

Un exemple :

<code xml>
  <textarea ref="message">
     <label locale="monmodule~monform.message.label" />
     <hint>Saisissez ici le message</hint>
  </textarea>
</code>

@@A@maxlength@@ et @@A@minlength@@ permettent d'ajouter une contrainte sur la
valeur saisie : la longueur minimale et maximale de la chaine de caractères
saisie.

Si vous voulez que l'utilisateur puisse saisir du HTML et qu'il y ait une
vérification du contenu coté serveur pour éviter les problèmes de sécurité,
mettez l'attribut @@A@type="html"@@.


==== Saisie de texte en HTML wysiwyg ====

Pour utiliser un éditeur HTML wysiwyg dans votre formulaire, il faut utiliser la
balise @@E@<htmleditor>@@.

<code xml>
  <htmleditor ref="description">
	<label>Description du produit</label>
  </htmleditor>
</code>

Par défaut, l'éditeur utilisé est wymeditor (pour le générateur "html" et
"htmllight"). On peut spécifier une configuration spécifique pour l'éditeur
ainsi que l'editeur, via l'attribut @@A@config@@, mais aussi une feuille de
style pour la décoration de l'éditeur, via l'attribut @@A@skin@@.

Vous pouvez changer d'éditeur (fckeditor, tinymce...), en l'indiquant dans la
configuration de l'editeur.

Pour savoir utiliser ces attributs et configurer un éditeur comme vous le
souhaitez, voir [[xml/htmleditor|la page sur htmleditor]].

==== Éditeur de contenu wiki ====

Vous pouvez utiliser un textarea pour éditer du contenu wiki. Cependant il y a
l'element @@E@<wikieditor>@@ qui permet de specifier que c'est du contenu wiki,
et les générateurs peuvent afficher une barre d'outils pour faciliter l'édition.
Il utiliseront automatiquement WikiRenderer (jWiki) pour transformer le contenu
en HTML et l'afficher.

<code xml>
  <wikieditor ref="description">
	<label>Description du produit</label>
  </wikieditor>
</code>

Vous pouvez indiquer une configuration pour la barre d'outil, avec l'attribut
@@A@config@@. Pour en savoir plus, voir [[xml/wikieditor|la page sur wikieditor]].


==== Saisie de date (datepicker) ====

La balise @@E@<date>@@ et @@E@<datetime>@@ facilitent la saisie d'une date par rapport à un simple @@E@<input>@@.

<code xml>
  <date ref="naissance">
	<label>Date de naissance</label>
  </date>
</code>

L'attribut @@A@ref@@ est obligatoire, et vous pouvez utiliser les attributs
@@A@defaultvalue@@, @@A@readonly@@, et @@A@required@@, ainsi que les balises
@@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, et @@E@<help>@@.

Il y aussi les attributs spécifiques @@A@mindate@@, @@A@maxdate@@ et
@@A@datepicker@@. Pour savoir comment utiliser @@A@datepicker@@, voir
[[xml/datepicker|la page dediée]].

Pour les attributs @@A@mindate@@ et @@A@maxdate@@, vous pouvez utiliser soit une
date absolue au format DB comme '2009-01-01', soit une chaine qui contient une
valeur qui sera analysée par la fonction PHP strtotime. Cette dernière solution
reste la plus pratique. Par exemple pour une date de naissance si l'on veut que
des dates de naissance des personnes de 18 à 70 ans :

<code xml>
  <date ref="naissance" mindate="-70 years" maxdate="-18 years">
	<label>Date de naissance</label>
  </date>
</code>

On peut aussi faire la même chose si l'on veut une date de début au minimum égale à aujourd'hui et une date maximum à 2 mois 1 jour

<code xml>
  <date ref="date_debut" mindate="now" maxdate="+2 months 1 day">
	<label>Début de l'évènement</label>
  </date>
</code>

==== Mot de passe ====

Pour la saisie d'un mot de passe ou tout autre renseignement qui doit être caché
lors de la saisie, vous utiliserez la balise @@E@<secret>@@. Vous devez y mettre
l'attribut @@A@ref@@, et vous pouvez utiliser les balises @@E@<label>@@,
@@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que les attributs @@A@readonly@@
et @@A@required@@.

<code xml>
  <secret ref="password">
     <label>Votre mot de passe</label>
     <hint>Indiquez le mot de passe que l'on vous a donné à l'inscription</hint>
  </secret>
</code>

Vous pouvez utiliser l'attribut @@A@size@@ pour indiquer la largeur du champ de
saisie.

Il est souvent utile de demander à l'utilisateur de saisir une deuxième fois un
nouveau mot de passe, lors d'une inscription par exemple. jForms gère cela
automatiquement. Il suffit d'indiquer la balise @@E@<confirm>@@ dans la balise
@@E@<secret>@@, et le formulaire HTML généré contiendra deux champs de saisie.
La balise @@E@<confirm>@@ doit contenir soit l'intitulé du libellé pour la
confirmation, soit un attribut @@A@locale@@ contenant le sélecteur de la locale
pour le libellé de la confirmation.

<code xml>
  <secret ref="newpassword">
     <label>Mot de passe</label>
     <hint>Indiquez un nouveau mot de passe</hint>
     <confirm>Retapez ce mot de passe</confirm>
  </secret>
</code>

Cela génèrera en gros, pour un formulaire html :

<code html>
   <label for="newpassword">Mot de passe</label>
        <input type="password" id="newpassword" name="newpassword" title="Indiquez un nouveau mot de passe"/>

   <label for="newpassword_confirm">Retapez ce mot de passe</label>
        <input type="password" id="newpassword_confirm" name="newpassword_confirm"/>
</code>

==== Case à cocher seule ====

Pour afficher une case à cocher, utiliser la balise @@E@<checkbox>@@. Vous devez
y mettre l'attribut @@A@ref@@, et vous pouvez utiliser les balises
@@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que l'attribut
@@A@readonly@@ et @@A@required@@.

<code xml>
  <checkbox ref="souvenir">
     <label>Se souvenir de moi</label>
     <help>Cochez cette case si vous voulez être identifié automatiquement la prochaine fois</help>
  </checkbox>
</code>

Par défaut, la valeur de la case à cocher, que vous récupèrerez une fois le
contenu du formulaire reçu, vaudra **0** si la case n'a pas été cochée, ou **1**
si elle l'a été.

Vous pouvez décider d'autres valeurs pour chacun de ces deux états. Il suffit
d'indiquer les attributs @@A@valueoncheck@@ et @@A@valueonuncheck@@ (qui valent
donc par défaut, respectivement 1 et 0). Exemple :

<code xml>
  <checkbox ref="souvenir" valueoncheck="O" valueonuncheck="N">
     <label>Se souvenir de moi</label>
     <help>Cochez cette case si vous voulez être identifier automatiquement la prochaine fois</help>
  </checkbox>
</code>

Notez que lorsque vous afficherez un formulaire pré-rempli, la case sera cochée
ou non en fonction de la valeur initiale, selon que celle-ci corresponde à la
valeur de @@A@valueoncheck@@ ou de @@A@valueonuncheck@@.

==== Liste de cases à cocher ====

On peut avoir à afficher une série de cases à cocher qui correspondent à des
choix multiples, par exemple afficher une liste de choses à acheter, et
l'utilisateur coche les articles qu'il veut acheter. Pour cela on utilisera la
balise <checkboxes> (avec un **S** à la fin).

Vous devez y mettre l'attribut @@A@ref@@, et vous pouvez utiliser les balises
@@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que les attributs
@@A@readonly@@ et @@A@required@@.

Il vous faut aussi indiquer la liste des valeurs possibles et leurs libellés.
Voir la section "sources de données" plus bas.

Exemple :

<code xml>
   <checkboxes ref="articles">
      <label>Sélectionnez les articles que vous voulez acheter :</label>
      <item value="54">sucre</item>
      <item value="27">steack</item>
      <item value="32">jus d'orange</item>
  </checkboxes>
</code>

Ceci affichera une série de trois cases à cocher, ayant pour intitulé "sucre",
"steack" et "jus d'orange". Quand le formulaire sera envoyé au serveur, la
valeur que vous recevrez pour la variable de formulaire "articles", sera un
tableau PHP contenant les valeurs des cases qui ont été cochées. Par exemple, si
l'utilisateur a coché "steack", coté serveur vous recevrez @@array(27)@@. Si en
plus "sucre" est coché, vous recevrez @@array(54, 27)@@.

(voir la page sur la [[utilisation|gestion du contenu d'un formulaire coté serveur]]).

==== Boutons radios ====

Les boutons radios vont toujours par groupe, d'au moins 2. Pour déclarer un
groupe de boutons radio, vous utiliserez la balise @@E@<radiobuttons>@@.

Vous devez y mettre l'attribut @@A@ref@@, et vous pouvez utiliser les balises
@@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que les attributs
@@A@readonly@@ et @@A@required@@. Comme pour les autres contrôles de type liste,
vous devez indiquer la liste des valeurs possibles et leurs libellés. Voir la
section "sources de données" plus bas.

Exemple :

<code xml>
   <radiobuttons ref="couleur">
      <label>Couleur de votre voiture:</label>
      <item value="r">Rouge</item>
      <item value="b">Bleue</item>
      <item value="v">Verte</item>
      <item value="j">Jaune</item>
  </radiobuttons>
</code>

Ceci affichera une série de 4 boutons radio, et la valeur choisie sera stockée
dans la variable de formulaire "couleur".


==== Liste déroulante ====

La balise @@E@<menulist>@@ affiche une liste déroulante (@@E@<select size="1">@@
en HTML), et de par sa nature, un seul choix est possible. Vous devez y mettre
l'attribut @@A@ref@@, et vous pouvez utiliser les balises @@E@<label>@@,
@@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que les attributs @@A@readonly@@
et @@A@required@@. Comme pour les autres contrôles de type liste, vous devez
indiquer la liste des valeurs possibles et leurs libellés. Voir la section
"sources de données" plus bas.

Exemple :

<code xml>
   <menulist ref="ville">
      <label>votre ville :</label>
      <item value="75000">Paris</item>
      <item value="37000">Tours</item>
      <item value="44000">Nantes</item>
      <item value="69000">Lyon</item>
  </menulist>
</code>

La variable de formulaire contiendra la valeur de l'item sélectionné.

Par défaut, si il n'y a pas l'attribut @@A@required="true"@@, il n'est pas
obligatoire de faire un choix dans la liste. Vous avez donc automatiquement un
premier choix "vide" qui est pré-selectionné. Si vous voulez indiquer le libellé
de ce choix vide, vous devez utiliser l'élement @@E@<emptyitem>@@.

<code xml>
   <menulist ref="ville">
      <label>votre ville :</label>
      <emptyitem>faites votre choix</emptyitem>
      <item value="75000">Paris</item>
      <item value="37000">Tours</item>
      <item value="44000">Nantes</item>
      <item value="69000">Lyon</item>
  </menulist>
</code>

Vous pouvez bien sûr utiliser une locale :
<code xml>
      <emptyitem locale="module~foo.bar"/>
</code>

==== Liste non déroulante ====

Les listes déroulantes, ou encore listbox (Équivalent de la balise
@@E@<select>@@ en HTML), sont déclarées au moyen de balise @@E@<listbox>@@. Vous
devez y mettre l'attribut @@A@ref@@, et vous pouvez utiliser les balises
@@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que les attributs
@@A@readonly@@ et @@A@required@@. Comme pour les autres contrôles de type liste,
vous devez indiquer la liste des valeurs possibles et leurs libellés. Voir la
section "sources de données" plus bas.

<code xml>
   <listbox ref="rubrique">
      <label>Rubrique préférée :</label>
      <item value="1">Tutoriels</item>
      <item value="2">Manuels</item>
      <item value="3">Forums</item>
  </listbox>
</code>

Vous pouvez indiquer un attribut @@A@size@@ qui permet d'indiquer le nombre
d'items affichables en même temps (donc la hauteur de la liste). Par défaut,
elle vaut 4.

Par défaut, un seul choix est possible. Cependant en ajoutant l'attribut
@@A@multiple="true"@@, l'utilisateur pourra sélectionner plusieurs éléments de
la liste (dans une page HTML, il faut que l'utilisateur appuie sur la touche
CTRL en même temps qu'il clique sur un item). Dans ce cas, dans la variable de
formulaire "rubrique", au lieu d'avoir une simple valeur correspondant à l'item
sélectionné, vous aurez un tableau PHP avec toutes les valeurs des items
choisis.

==== Téléchargement de fichier ====

Pour permettre à l'utilisateur de télécharger un fichier vers le serveur, vous
pouvez utiliser la balise @@E@<upload>@@ (équivalent de @@E@<input type="file">@@
en HTML). Comme pour les autres contrôles, vous devez y mettre
l'attribut @@A@ref@@, et vous pouvez utiliser les balises @@E@<label>@@,
@@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ ainsi que les attributs @@A@readonly@@
et @@A@required@@.

Deux attributs supplémentaires sont à votre disposition, pour contrôler la
nature et la taille des fichiers, qui sont respectivement @@A@mimetype@@ (devant
contenir un ou plusieurs type mime) et @@A@maxsize@@ (taille en octets).

Attention : sous IE, le type-mime des images .jpg et .jpeg sont considéré comme
du Progressive JPEG, soit image/pjpeg. Assurez vous de rajouter ce type-mime en
plus du image/jpeg si vous voulez autoriser le format JPEG.

<code xml>
  <upload ref="photo" mimetype="image/jpeg;image/pjpeg;image/png" maxsize="20000">
    <label>Votre photo</label>
  </upload>
</code>

À la réception du fichier, jForms vérifie s'il correspond au type et à la taille
indiqués, et l'on peut ensuite lui indiquer où stocker le fichier téléchargé. La
variable de formulaire contiendra le nom du fichier.

==== Groupement de champs de saisie ====

Il peut être utile de regrouper plusieurs contrôles dans un groupe, que ce soit
pour l'aspect visuel, ou pour les manipuler ensemble. Pour ce faire, il faut
placer les contrôles dans une balise @@E@<group>@@. Cette balise doit avoir un
attribut @@A@ref@@, mais peut avoir aussi un attribut @@A@readonly@@, ce qui met
en lecture seule tous les contrôles qui s'y trouvent. D'ailleurs, certaines
opérations faites sur l'objet PHP correspondant à @@E@<group>@@, impactent sur
les contrôles.

Un groupe doit aussi posséder un label.

Exemple de groupe :
<code xml>
  <group ref="un_groupe">
     <label>identité</label>
     <input ref="nom"><label>nom</label></input>
     <input ref="prenom"><label>prénom</label></input>
  </group>
</code>

==== Choix amélioré ====

Il arrive que l'on veuille proposer à l'utilisateur de faire un choix entre
plusieurs cas, et que pour certains choix, on doive donner des renseignements
complémentaires. jForms propose pour cela la balise @@E@<choice>@@. Elle
contient des balises @@E@<item>@@ pour chacun des choix, et dans chacune de ces
balises @@E@<item>@@, on indique un @@E@<label>@@, et 0,1 ou plusieurs champs de
saisie.

<code xml>
   <choice ref="status">
     <label>Status du bug</label>
     <item value="new"> <label>Nouveau</label> </item>
     <item value="res"> 
         <label>resolu</label>
         <menulist ref="resolution">
            <label>Résolution du bug</label>
            <item value="0">Corrigé</item>
            <item value="1">invalide</item>
            <item value="2">Ne sera pas corrigé</item>
         </menulist>
     </item>
     <item value="dup">
         <label>duplicata</label>
         <input ref="dup_bug"><label>Numéro du bug</label></input>
     </item>
   </choice>
</code>

Quand l'utilisateur choisit un des items, les champs des autres items sont
désactivés.

La balise @@E@<choice>@@ accepte les balises @@E@<help>@@, @@E@<hint>@@,
@@E@<alert>@@ ainsi que les attributs @@A@readonly@@, @@A@required@@ et
@@A@selectedvalue@@. Cet attribut peut comporter la valeur de l'item sélectionné
par défaut. Une autre façon de sélectionner par défaut un item est de mettre un
attribut @@A@selected="true"@@ sur la balise @@E@<item>@@ correspondant.

==== Captcha ====

Dans certain contexte, il est nécessaire d'empêcher la saisie automatique des
formulaire (par des robots spammeurs par exemple).

JForms fourni la balise @@E@<captcha>@@ pour inclure automatiquement un champs
de saisie qui permettra de vérifier que le formulaire est bien saisie par un
humain. Pour le moment, ce champs de saisie n'est pas une image à déchiffrer
comme on le voit sur certain site, mais une simple champs texte dans lequel il
faut indiquer la réponse à une question posée, affichée automatiquement par
jForms.

<code xml>
 <captcha ref="antispam">
    <label>Vérification anti-spam</label>
 </captcha>
</code>

La balise accepte les attributs communs et les balises d'aide.

Les questions posées sont stockées dans un fichier de locales, dans le module
jelix. Exemple pour le français :
@@F@lib/jelix/core-modules/jelix/locales/fr_FR/captcha.UTF-8.properties@@. Ce
fichier contient une première locale, @@number@@, qui indique le nombre de
question, et ensuite les questions et réponses numérotées. Vous pouvez redéfinir
ce fichier pour ajouter ou modifier les questions et réponses. Voir
[[/surcharge-de-fichiers|le chapitre sur la redéfinition des fichiers]].


==== Boutons de validation ====

Dans un formulaire, il faut bien sûr au moins un bouton qui permette à
l'utilisateur de valider la saisie et envoyer les données au serveur. Vous
déclarez un bouton de ce type avec la balise @@E@<submit>@@. Comme pour les
autres contrôles, vous devez y mettre l'attribut @@A@ref@@, et vous pouvez
utiliser les balises @@E@<label>@@, @@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@
(mais pas les attributs @@A@readonly@@ ni @@A@required@@).

<code xml>
  <submit ref="submit">
    <label>Ok</label>
  </submit>
</code>

La variable de formulaire correspondante ne contiendra rien d'intéressant. À
moins que vous ayez besoin de plusieurs boutons de soumission, représentant par
exemple l'action à effectuer après l'envoi du formulaire comme un bouton
"prévisualiser" et un autre "sauvegarder". Dans ce cas, vous utiliserez comme
pour les autres contrôles de type liste, un dao ou les balises @@E@<item>@@ :

<code xml>
  <submit ref="valider">
    <label>Veuillez valider</label>
    <item value="preview">Prévisualiser</item>
    <item value="svg">Sauvegarder</item>
  </submit>
</code>

Dans la variable de formulaire "valider", vous aurez alors la valeur "preview"
ou "svg", et vous pourrez agir en fonction de ces valeurs dans le contrôleur. Au
niveau du formulaire HTML, cela affichera deux boutons avec leurs libellés
respectifs "Prévisualiser" et "Sauvegarder".

A noter : le code généré n'est pas compatible avec IE (voir
[[http://jelix.org/forums/forum/5-jelix-utilisation-et-developpement/posts/1844-1844-resolu-tag-formsubmit]]).

==== Bouton reset ====

Pour afficher un bouton reset avec jForms, il faut utiliser la balise @@E@<reset>@@ :

<code xml>
  <reset ref="reinit">
    <label>Réinitialiser</label>
  </reset>
</code>

==== Bouton simple ====

Vous pouvez afficher un bouton tout simple, avec la balise @@E@<button>@@ :
<code xml>
  <button ref="calc">
    <label>Calculer</label>
  </button>
</code>

Ce sera à vous d'integrer le javascript qu'il faut dans votre page pour
lancer une action sur le click du bouton.

==== Affichage de valeurs ====

La balise @@E@<output>@@ ne sert qu'à afficher une valeur. Cette dernière ne
sera donc pas éditable. Cela peut être utile pour afficher un formulaire de tout
un enregistrement sans pour autant éditer tous les champs. Vous devez y mettre
l'attribut @@A@ref@@, et vous pouvez utiliser les balises @@E@<label>@@,
@@E@<hint>@@, @@E@<alert>@@, @@E@<help>@@ (mais pas les attributs @@A@readonly@@
ni @@A@required@@).

<code xml>
  <output ref="categorie">
    <label>Catégorie</label>
  </output>
</code>

==== Champs cachés ====

Si vous voulez inclure des champs cachés dans votre formulaire, utilisez la
balise @@E@<hidden>@@. Vous devez y mettre l'attribut @@A@ref@@, et vous pouvez
utiliser l'attribut @@A@defaultvalue@@. Tout autre balise ou attribut ne sera
pas pris en compte.

<code xml>
   <hidden ref="product_id" />
</code>

===== Source de données =====

Les contrôles tels que @@E@menulist@@, @@E@listbox@@ et @@E@radiobuttons@@,
@@E@checkboxes@@ contiennent plusieurs choix de valeurs pour l'utilisateur. Il
convient donc d'indiquer dans ces contrôles la manière dont jForms va récupérer
les valeurs et libellés de ces choix.

Il y a pour le moment trois façons de faire :
  - indiquer ces choix en dur dans le fichier jForms (données statiques)
  - indiquer un DAO qui permettra de les récupérer.
  - indiquer une classe qui fournit ces données.  

==== Données statiques ====

Elles doivent être indiquées au moyen d'une ou plusieurs balises @@E@<item>@@.
La valeur du choix doit être mis dans un attribut @@A@value@@. Le libellé du
choix doit être mis en tant que contenu de la balise @@E@<item>@@, ou dans un
fichier de locale et alors vous indiquez la locale au moyen de l'attribut
@@A@locale@@. Si aucun label est indiqué, le label sera la valeur. Exemple :

<code xml>
   <checkboxes ref="objets">
      <label>Vous avez </label>
      <item value="maison">Une maison</item>
      <item value="voiture" locale="mymodule~myform.item.car.label" />
      <item value="bateau"/>
  </checkboxes>
</code>

==== Données dynamiques avec un DAO ====

Le contenu d'une liste peut être rempli grâce à un DAO. Vous devez alors mettre
une balise @@E@<datasource>@@ qui doit avoir au moins 3 attributs :

   - @@A@dao@@, indiquant le sélecteur de la DAO à utiliser
   - @@A@method@@, indiquant la méthode de la DAO qui génère la liste des choix
   - @@A@labelproperty@@, indiquant quelle est la propriété de la DAO qui contient le libellé du choix. 


Vous pouvez indiquer un profil jDb (optionnel) à travers l'attribut @@A@profile@@.

La valeur de chaque choix sera la valeur de la clé primaire de la DAO.
Cependant, si vous voulez indiquer une autre propriété de la DAO, vous pouvez
l'indiquer dans l'attribut @@A@valueproperty@@.

Exemple :

<code xml>
  <menulist ref="conf">
      <label>Sélectionnez l'élément de configuration à éditer</label>
      <datasource dao="testapp~config" method="findAll"
                  labelproperty="cvalue" valueproperty="ckey"/>
  </menulist>
</code>

=== Indiquer une méthode dao qui attend un argument ===

Si la méthode que vous indiquez demande un paramètre en argument, vous devez indiquer celui-ci. 

Si ce paramètre est une valeur statique, ajoutez l'attribut @@A@criteria@@ :

<code xml>
      <datasource dao="testapp~config" method="findByCat" criteria="admin"
                  labelproperty="cvalue" valueproperty="ckey"/>
</code>

La méthode @@M@findByCat()@@ sera appelée avec la valeur @@L@"admin"@@ en paramètre.


== Dépendance avec un autre champs de saisie ==

Bien souvent, on veut pouvoir indiquer cette valeur de manière dynamique, et
souvent, provenant d'un autre champs de saisie. Un exemple : une liste de ville
qui dépend du choix dans une liste de département.

Plutôt que d'utiliser @@A@criteria@@, vous utiliserez l'attribut
@@A@criteriafrom@@, où vous indiquerez l'identifiant (attribut @@A@ref@@) de ce
champ de saisie pour lequel il faut récupérer la valeur :

<code xml>
  <menulist ref="catlist">
     ...
  </menulist>

  <menulist ref="conf">
      <datasource dao="testapp~config" method="findByCat" criteriafrom="catlist"
                  labelproperty="cvalue" valueproperty="ckey"/>
  </menulist>
</code>

Dans cet exemple, on a une liste dont les valeurs sont en fonction d'une autre
liste.

Note : depuis Jelix 1.2, la liste est mise à jour quand l'utilisateur change la
valeur du contrôle dont dépend la liste. Ce n'était pas le cas dans Jelix 1.1.


=== Pour l'affichage des valeurs ===

Lorsque le formulaire est affiché via les plugins @@{formdata}@@ et
@@{formdatafull}@@, où seules donc sont affichés les valeurs sélectionnées (ou
plutôt les libellés correspondants), jForms ne fait pas appel à la méthode
indiquée dans @@A@method@@ puisqu'elle est censée renvoyer une liste. Par
défaut, c'est la méthode @@M@get@@ de la factory dao qui est appelée, avec la
valeur sélectionnée. Si il y a des critères (statique ou dynamique), ces valeurs
seront aussi passées. Ce qui signifie que //la valeur sélectionnée et les
éventuels critères doivent correspondre à la clé primaire// de l'enregistrement
correspondant à ce qui a été sélectionné.

Or ce n'est pas toujours le cas. La valeur sélectionnée ou les critères peuvent
correspondre à d'autres champs que la clé primaire. Il faut donc indiquer une
autre méthode du dao, qui permettra de récupérer l'enregistrement correspondant,
et qui devra prendre en paramètre à la fois la clé et tous les critères
indiqués. Pour ce faire, indiquez dans l'attribut @@A@labelmethod@@ la méthode
du dao à utiliser (de type @@selectfirst@@).

=== attributs et valeurs multiples ===

Les attributs suivants supportent la présence de valeurs multiples séparées par
des virgules. Ainsi, il est possible de spécifier plusieurs valeurs pour:

   - @@A@labelproperty@@
   - @@A@criteria@@
   - @@A@criteriaFrom@@

@@A@labelproperty@@ définissant les propriétés daos utilisées pour l'affichage,
il est nécessaire de pouvoir utiliser un séparateur dans le cas de valeurs
multiples. Pour cela, il suffit d'ajouter l'attribut @@A@labelseparator@@ à
l'élément datasource.

Pour reprendre l'exemple précédent, si vous voulez afficher une liste d'éléments
de configuration selon une catégorie et une date, et l'afficher sous la forme de
couples @@L@"nom = valeur"@@:

<code xml>
  <input ref="date">
     ...
  </input>
  <menulist ref="catlist">
     ...
  </menulist>

  <menulist ref="conf">
      <datasource dao="testapp~config" method="findByCatAndDate" criteriafrom="catlist,date"
                  labelproperty="cname,cvalue"  labelseparator=" = " valueproperty="ckey"/>
  </menulist>
</code>


==== Données dynamiques avec une classe ====

Si vous voulez fournir les données dynamiquement d'une autre manière que par un
dao, vous pouvez créer une classe, qui devra implémenter l'interface
@@C@jIFormsDatasource@@. Elle sera stockée dans un répertoire @@F@classes/@@
d'un module, et vous l'indiquerez via l'élément @@E@<datasource>@@ avec un
attribut @@A@class@@.

Exemple de classe :
<code php>
require_once (JELIX_LIB_PATH.'forms/jFormsDatasource.class.php');

class listData implements jIFormsDatasource
{
  protected $formId = 0;

  protected $data = array();

  function __construct($id)
  {
    $this->formId = $id;
    $this->data = array(0 => 'test',
                         1 => 'test 2',
                         2 => 'Id = '. $id);
  }

  public function getData($form)
  {
    return ($this->data);
  }

  public function getLabel($key)
  {
    if(isset($this->data[$key]))
      return $this->data[$key];
    else
      return null;
  }

}
</code>

Et dans le fichier jforms
<code xml>
  <menulist ref="icone">
        <label locale="elements.crud.label.icone" />
        <datasource class="monmodule~listData" />
  </menulist>
</code>

==== Autre source de données ====

Si l'utilisation d'un DAO, d'une classe ou de données statiques n'est pas
suffisante pour vous, regardez la section "Définir les choix d'un champ à
multiple choix" dans la page [[utilisation|Utilisation de jforms]].

Dans ce cas là, vous ne devez pas indiquer de balises @@E@<item>@@ ou de balises
@@E@<datasource>@@.



==== Données groupées ====

Pour les éléments @@E@<menulist>@@ ou @@E@listbox@@, vous pouvez grouper les
valeurs. Cela générera des éléments @@E@optgroup@@ en HTML.

Pour les sources de données statiques, utiliser l'élément @@E@<itemsgroup>@@
avec un attribut @@A@label@@ ou @@A@locale@@.

<code xml>
   <menulist ref="country">
      <label>Countries </label>
      <itemsgroup label="Europe">
        <item value="fr">France</item>
        <item value="gb">Great Britain</item>
      </itemsgroup>
      <itemsgroup label="Asia">
        <item value="zh">China</item>
        <item value="in">India</item>
      </itemsgroup> 
  </menulist>
</code>

Pour les sources de données de type dao ou class, vous devez utiliser l'attribut
@@A@groupby@@ sur la balise @@E@<datasource>@@. Pour une source de donnée dao,
@@A@groupby@@ indique la propriété du dao qui contient le libellé du groupe
auquel appartient l'enregistrement. Pour une source de donnée de type class, la
signification de @@A@groupby@@ dépend de l'implémentation de la source de
donnée.


==== Présélection de valeurs ====

Dans une liste de choix, il est possible d'indiquer des valeurs par défaut qui
seront sélectionnées. Vous avez trois façons de le faire :

   - soit indiquer un attribut @@A@selected="true"@@ sur chaque balise
     @@E@item@@ voulue si vous utilisez celles-ci. Plusieurs items peuvent avoir
     un attribut @@A@selected@@ seulement sur les listes de case à cocher
     (checkboxes), soit sur une listbox "multiple". Dans les autres cas, un seul
     item doit avoir l'attribut @@A@selected@@.
   - soit indiquer un attribut @@A@selectedvalue@@ sur la balise du contrôle, en
     y stockant la valeur sélectionnée. Cependant vous ne pouvez indiquer qu'une
     valeur, donc un seul choix ne sera sélectionné par défaut
   - soit indiquer un élément @@E@<selectedvalues>@@ contenant des éléments
     @@E@<value>@@. Cette manière de faire est toute indiquée pour
     @@E@checkboxes@@ et listbox en multiple, et quand la source de données est
     une dao.

Exemples :

<code xml>
  <radiobuttons ref="home">
      <label>Vous habitez</label>
      <item value="pa" selected="true">Paris</item>
      <item value="ma">Marseille</item>
      <item value="ly">Lyon</item>
      <item value="br">Brest</item>
      <item value="li">Lille</item>
      <item value="bo">Bordeaux</item>
  </radiobuttons>

  <menulist ref="conf" selectedvalue="foo.bar">
      <label>Sélectionnez l'élément de configuration à éditer</label>
      <datasource dao="testapp~config" method="findAll"
                  labelproperty="cvalue" valueproperty="ckey">
  </menulist>

  <listbox ref="objets" required="true" multiple="true">
      <label>Vous avez </label>
      <item value="maison">Une maison</item>
      <item value="voiture">Une voiture</item>
      <item value="bateau">Un bateau</item>
      <item value="assiette">Une assiette</item>
      <selectedvalues>
           <value>maison</value>
           <value>bateau</value>
      </selectedvalues>
  </listbox>
</code>