Chaque type de contrôle est généré par un plugin dédié, de type formwidget.

Les balises HTML générées par ces plugins possèdent des classes CSS (voir plus bas). Vous pouvez donc les styler à votre convenance dans une feuille de style que vous ajouterez à votre page.

Vous pouvez ajouter des attributs HTML sur les elements HTML générés par ctrl_control. Pour ce faire, ajouter un deuxième paramètre à ctrl_control. Cela doit être un tableau ('nom attribut'=>'valeur attribute'). Donnez "" comme premier paramètre quand ctrl_control est utilisé à l'intérieur d'une boucle formcontrols.

<td>{ctrl_control 'nom', array('class'=>'myclass', 'placeholder'=>'votre nom')}</td>

Note : pour les générateurs autre que HTML, ce tableau d'attribut peut être d'autres options.

Vous pouvez aussi indiquer ces attributs dans l'option widgetsAttributes du generateur. Si le contrôle en question est dans une boucle {formcontrols}, cela évite d'avoir des {if_ctrl} etc.

{form $form, 'module~action', array(), 'html', array(
      'widgetsAttributes'=> array(
          'nom' => array('class'=>'myclass', 'placeholder'=>'votre nom'))
       )}

Il est possible que le HTML généré ne vous convienne pas. La solution est alors d'utiliser un plugin formwidget différent, que vous développerez vous même ou que vous aurez récupéré. Vous indiquerez son nom dans l'option plugins de {form}.

{form $form, 'module~action', array(), 'html', array('plugins'=> array('myctrl'=>'superchamps'))}

Dans cet exemple, pour le contrôle qui a pour identifiant "myctrl", le plugin "superchamps" sera utilisé.

Un plugin formwidget implémente l'interface jelix\forms\HtmlWidget\WidgetInterface et peut hériter de la classe jelix\forms\HtmlWidget\WidgetBase.

Voyez les plugins existants et cet interface pour comprendre la création de ce type de plugins, et le chapitre expliquant la création de tels plugins.

Pour les messages d'erreurs, il faut créer un objet javascript qui contient trois méthodes :

• start, qui est appelé quand le processus de vérification commence
• addError, qui est appelé quand une erreur est trouvée. Cette méthode reçoit un objet javascript jFormsControl qui contient des données relatifs au champs de saisie en faute, et un code erreur : 1 si le champs n'est pas renseigné alors qu'il est obligatoire, et 2 si le contenu saisi est invalide.
• end, qui est appelé quand le processus de vérification est terminé

Dans ces méthodes vous faites ce que vous voulez. Par exemple, dans addError, vous pouvez insérer dans une liste html le message d'erreur, comme dans l'exemple (l'élément "errors" est une liste <ul> quelque part dans votre page html):

function MyErrorDecorator(){
}

MyErrorDecorator.prototype = {
    start : function() {
    },
    addError : function(control, messageType) {
        var message='';
        if (messageType == 1) {
            message = control.errRequired;
        }
        else if (messageType == 2) {
            message = control.errInvalid;
        }
        else {
            message = "Error on '"+control.label+"' field";
        }
        var item = document.createElement("li");
        item.appendChild(document.createTextNode(message));
        document.getElementById("errors").appendChild(item);
    },
    end : function() {
    }
}

Ensuite vous l'indiquez au plugin form ou formfull, dans la liste des options pour le builder html :

  {form $formulaire, 'monmodule~default:sauver', array(), 'html',
        array("errorDecorator"=>"MyErrorDecorator")}
   ...
  {/form}

En ce qui concerne l'objet jFormsControl que addError() reçoit en paramètre (ici control), voici les propriétés utiles qu'il contient :

• name : le nom du contrôle, du champs de saisie
• label : son libellé
• datatype : type de donnée (attribut type pour les input dans le fichier xml)
• required : booléen indiquant si il est obligatoire
• readonly : booléen indiquant si il est en lecture seule
• errInvalid : message d'erreur prédéfini quand son contenu est invalide
• errRequired : message d'erreur prédéfini quand le champs n'est pas renseigné
• help : message d'aide

Depuis Jelix 1.6.17, vous pouvez indiquer votre décorateur comme celui par défaut pour tous les formulaires. Pour cela déclarez le dans la configuration :

[tplplugins]
defaultJformsErrorDecorator = MyErrorDecorator

Les messages d'aides sont directement en dur en HTML, et par défaut affichés dans des info bulles au survol du picto du point interrogation. Vous pouvez bien sûr changer cela en modifiant les CSS, en ajoutant du javascript etc.

Le code Javascript généré par jForms dans votre page web repose sur principalement sur un objet jFormsJQ, à partir duquel vous pouvez récupérer les objets JS correspondant à chaque contrôle, et qui permettent entre autre de faire les vérifications.

Le premier objet que vous pouvez récupérer, c'est l'objet correspondant au formulaire même. Pour ce faire, vous devez appeler la fonction jFormsJQ.getForm() avec l'id du formulaire.

var f = jFormsJQ.getForm("jforms_utilisateurs_identite");

À partir de là, vous avez accès à plusieurs fonctions

  f.setErrorDecorator(new MyErrorDecorator); // voir plus haut
  f.addSubmitHandler(function(event){...}); // voir ci dessous
  f.updateDynamicList("ref_d_un_control"); // pour rafraichir une listbox
                                           // générée dynamiquement par jForms
  var c = f.getControl("ref_d_un_control"); // récupérer l'objet js d'un control

L'objet JS d'un contrôle contient un certain nombre de propriété :

    c.name; // son "ref"
    c.label; // son label
    c.required; // indique si il est obligatoire, true ou false
    c.errInvalid; // message si le contenu est invalide
    c.errRequired; // message si le contenu est requis
    c.readOnly; // indique si il est en lecture seule, true ou false.

Certains objets ont des propriétés supplémentaires en fonction de leur type.

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.

Le générateur HTML inclut le script jQuery dans toute réponse HTML contenant un formulaire jForms. Si vous utilisez jQuery pour toute votre application, vous l'inclurez sûrement dans votre réponse commune. Dans ce cas, faites attention d'inclure le même fichier que celui référencé par le générateur HTML, sinon, jQuery sera téléchargé 2 fois par vos utilisateurs.

Exemple d'inclusion dans votre réponse commune :

  $this->addJSLink(jApp::urlJelixWWWPath().'jquery/jquery.js');