Pour les développeurs pressés, il existe un plugin de template qui affiche tout tout seul : formfull. Vous ne pouvez pas contrôler la façon dont sont affichés les champs de saisie, leur libellés et les boutons de validation. La seule chose que vous pouvez personnaliser c'est l'affichage des messages d'erreurs et d'aide (voir plus loin).

Vous devez passer à ce plugin, les paramètres suivant, dans l'ordre :

• l'objet formulaire
• le sélecteur de l'action où le contenu du formulaire sera envoyé
• facultatif :
  • un tableau des paramètres de l'url de cette action (autre que les champs de saisie)
  • le nom du générateur à utiliser (entre autre 'html' ou 'htmllight')
  • un tableau contenant des options pour le générateur

Voici un exemple dans le contrôleur :

    $form = jForms::get('monform');
    $tpl = new jTpl();
    $tpl->assign('formulaire', $form);

Et dans le template :

   <h1>Le formulaire</h1>
   <p>Remplissez le formulaire suivant :</p>

   {formfull $formulaire, 'monmodule~default:sauver'}

Les libellés et les champs de saisies s'affichent dans un tableau, et les boutons de validation dans une div en dessous du tableau.

Note : n'utilisez pas ce plugin dans une boucle avec une variable générée par cette boucle (typiquement dans un foreach). À cause d'une limitation du moteur de template et du plugin, les fichiers JS et CSS pour le formulaire ne seront pas chargés dans ce cas. Ou alors il faut les indiquer vous même avec le plugin meta_html.

D'autres plugins que formfull existent permettant de mieux contrôler l'affichage des champs de saisie, en particulier, de pouvoir définir les endroits où les champs seront placés.

Le premier plugin à connaitre, est le plugin form. Il a les même paramètres que formfull. C'est un plugin de type bloc, c'est à dire qu'il y a une balise de fin, et qu'entre les deux balises form, on placera les autres plugins.

Le plugin form a les même paramètres que formfull, à savoir, dans l'ordre :

• l'objet formulaire
• le sélecteur de l'action où le contenu du formulaire sera envoyé
• facultatif :
  • un tableau des paramètres de l'url de cette action (autre que les champs de saisie)
  • le nom du générateur à utiliser (entre autre 'html' ou 'htmllight')
  • un tableau contenant des options pour le générateur

Note : n'utilisez pas ce plugin dans une boucle avec une variable générée par cette boucle (typiquement dans un foreach). À cause d'une limitation du moteur de template et du plugin, les fichiers JS et CSS pour le formulaire ne seront pas chargés dans ce cas. Ou alors il faut les indiquer vous même avec le plugin meta_html.

Affichage contrôlé simple ¶

  {form $formulaire, 'monmodule~default:sauver'}

   <fieldset><legend>Saisissez : </legend>

      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>

   <div> {formreset}{formsubmit} </div>

  {/form}

Aller plus loin dans le contrôle de l'affichage ¶

  {form $formulaire, 'monmodule~default:sauver'}

   <fieldset><legend>Votre identité : </legend>

      {formcontrols}            
         <p {ifctrl 'nom', 'prenom'}class="help-needed"{/ifctrl}> {ctrl_label} : {ctrl_control} </p>
         <p {ifctrl 'adresse'}class="address"{/ifctrl}> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>

  {form $formulaire, 'monmodule~default:sauver'}

   <fieldset><legend>Votre identité : </legend>

      {formcontrols array('nom','prenom','adresse')}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>
   <fieldset><legend>Autres renseignements : </legend>

      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}

   </fieldset>

   <div> {formsubmit} </div>
  {/form}

  {form $formulaire, 'monmodule~default:sauver'}
   <fieldset><legend>Votre identité : </legend>
        <table>
          <tr><td>{ctrl_label 'nom'}</td><td>{ctrl_control 'nom'}</td> </tr>
          <tr><td>{ctrl_label 'prenom'}</td><td>{ctrl_control 'prenom'}</td></tr>
        </table>
   </fieldset>
   <fieldset><legend>Autres renseignements : </legend>
      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}
   </fieldset>
   <div> {formsubmit} </div>
  {/form}

Pour les champs de saisie de mot de passe pour lesquels il y a un champ de confirmation (balise <confirm>), si vous indiquez explicitement leur affichage, il faut aussi indiquer spécifiquement l'affichage du champ de confirmation, sachant que celui-ci a le nom du champ de saisie principale avec un suffixe _confirm.

Par exemple, vous indiquez explicitement d'afficher le champ "motdepasse" qui est un mot de passe :

  {form $formulaire, 'monmodule~default:sauver'}
   <fieldset><legend>Créer votre compte : </legend>
        <table>
          <tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
          <tr><td>{ctrl_label 'motdepasse'}</td><td>{ctrl_control 'motdepasse'}</td></tr>
        </table>
   </fieldset>
   <fieldset><legend>Autres renseignements : </legend>
      {formcontrols}
         <p> {ctrl_label} : {ctrl_control} </p>
      {/formcontrols}
   </fieldset>
   <div> {formsubmit} </div>
  {/form}

Ici, si le champ de confirmation ne s'affiche pas près du champ de mot de passe, il faut ajouter le champ "motdepasse_confirm" :

   <table>
      <tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
      <tr><td>{ctrl_label 'motdepasse'}</td><td>{ctrl_control 'motdepasse'}</td></tr>
      <tr><td>{ctrl_label 'motdepasse_confirm'}</td><td>{ctrl_control 'motdepasse_confirm'}</td></tr>
   </table>

Par contre, il n'est pas besoin de préciser le champ de confirmation quand on afficher le champ de saisie de mot de passe dans une boucle formcontrols.

On a vu que l'on pouvait utiliser le plugin formsubmit pour afficher le bouton d'envoi déclaré dans votre formulaire. Mais utilisé comme cela, si vous avez déclaré plusieurs balises <submit>, seul le premier bouton sera affiché. Dans ce cas là il faut utiliser le plugin formsubmits (avec un s), qui est une boucle sur les boutons d'envoi :

    <ul>
    {formsubmits}
       <li>{formsubmit}</li>
    {/formsubmits}
    </ul>

Ou encore, vous pouvez utiliser plusieurs plugins formsubmit, sans formsubmits, en indiquant le nom du bouton :

<div> {formsubmit 'preview'} {formsubmit 'save'} </div>

• *Attention** : {formsubmits} boucle sur la liste des contrôles <submit>, pas sur les item d'un submit ! Il n'est pas possible pour le moment de boucler sur les items d'un submit (voir ticket #429).

Vous pouvez ajouter des comportements sur n'importe quel contrôle avec javascript, avec votre bibliothèque JS préférée (jQuery étant celle utilisée par jForms par défaut).

Tout les champs générés par jForms ont un id. Les id sont des noms composés : "jforms_module_nomform_refcontrole". Par exemple, pour un contrôle qui a un ref="adresse", déclaré par le formulaire "identite" fournis dans le module "utilisateurs", l'id du champs sera : "jforms_utilisateurs_identite_adresse".

L'élément html <form> est aussi généré avec un id, composé du nom du module et de celui du formulaire : "jforms_module_nomform". Dans notre exemple, il vaudra "jforms_utilisateurs_identite".

Sachant ces ids, vous pouvez récupérer tout les champs de formulaire ou l'élément form, avec la fonction document.getElementById().

Pour ajouter des vérifications ou traitements additionnels durant l'évènement submit du formulaire, vous ne devez pas utiliser un listener sur l'évènement submit, mais vous devez utiliser un "submit handler" avec l'objet jforms en javascript. Un "submit handler" est une fonction qui accepte en argument un objet DOM event, et doit retourner true si le formulaire peut être envoyé, ou false sinon. Vous ajoutez ce "submit handler" avec la méthode addSubmitHandler de l'objet javascript jforms.

Voici un exemple pour ajouter un message de confirmation:

jQuery(document).ready(function(){
    jFormsJQ.getForm("the_id_of_formelement").addSubmitHandler(function(ev){
         return window.confirm("Voulez vous vraiment envoyer ces données ?");
       });
});

Par défaut, la fonction indiquée est exécutée après la vérification des données. Si vous voulez l’exécuter avant la vérification, ajouter un second paramètre true à la méthode addSubmitHandler.

Toutes les fonctions "handlers" sont exécutées, même si une des fonctions retourne false ou que la vérification des données échoue. Si vous voulez stopper l’exécution des handlers qui suivent l'un deux, générez simplement une exception dans ce dernier.

Les plugins de templates de jForms reposent sur d'autres plugins spécifiques à jForms, s'occupant de générer le formulaire proprement dit. Deux générateurs sont fournis : "html" et "htmllight". Vous pouvez en créer d'autres si la façon dont sont générés les formulaires ne vous plaît pas. Par exemple, un générateur qui génère un formulaire en se reposant une bibliothèque javascript comme Extjs, un formulaire qui utilise Ajax, ou encore un formulaire en XUL, en XForms etc...

Le générateur par défaut de Jelix est 'html'. Il est spécifié par la variable defaultJformsBuilder du fichier de configuration.

Pour spécifier son propre choix de générateur pour l'ensemble d'une application, il vous suffit de modifier cette variable dans le fichier de configuration:

[tplplugins] 
defaultJformsBuilder = myformbuilder

Ponctuellement, vous pouvez aussi indiquer le générateur de votre choix en passant son nom aux plugins de template {form} ou {formfull} (4ième paramètre) :

  {formfull $formulaire, 'monmodule~default:sauver', array(), 'htmllight'}

Comme indiqué plus haut, ces plugins acceptent un cinquième paramètre, un tableau, contenant des options pour le générateur. Ces options dépendent du générateur utilisé (errorDecorator et method par exemple pour 'html' et htmllight').

Remarque : si vous souhaitez passer la même option dans tous vos formulaires, créez le générateur de votre choix en dérivant un générateur existant et affectez-lui directement ces options dans son code...

Pour en savoir plus sur chaque générateur :

• Générateur "html"
• Générateur "htmllight"

Voir la note sur la page des réponses ajax