Raccourcis : Contenu - rubriques - sous rubriques
EN FR

Le générateur "html" de jforms génère un formulaire HTML, utilisant principalement jQuery pour gérer le comportement de certains champs de saisie.

Le générateur "html" est celui utilisé par défaut par jForms, et son nom à indiquer aux plugins {form} ou {formfull} est "html".

Options du générateur

Vous pouvez indiquer des options en cinquième argument de {form} et {formfull} :

  • errorDecorator : le nom de la fonction javascript qui s'occupera de l'affichage des erreurs
  • method : la méthode HTTP à employer ('get' ou 'post'). Par défault : 'post'.
  • plugins : la liste des plugins à utiliser pour afficher tel ou tel contrôle. C'est un tableau associatif dont les clés sont les identifiants des contrôles, et les valeurs les noms de plugins de type formwidget.
  • attributes : liste d'attributs html et leurs valeurs, à ajouter sur la balise <form>. Ex : array('attributes'=>array('class'=>'myclass'))
  • widgetsAttributes: liste d'attributs pour chaque widget. Cela peut être des attributs HTML, mais aussi des paramètres d'affichage pour le widget, spécifique au widget. Les clés de la liste sont les identifiants des contrôles et les valeurs sont un tableau associatif entre nom d'attributs et valeur d'attributs.

Personnaliser l'affichage des contrôles

Styler avec les classes CSS existantes

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.

Ajout d'attributs html

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'))
       )}

Créer et/ou utiliser un plugin de widget

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.

Personnalisation de l'affichage des messages

jForms affiche deux types de messages :

  • les messages d'erreurs affichés lors de la vérification des champs de saisies
  • Les messages d'aides

Vous pouvez changer l'apparence avec CSS, mais aussi, pour les messages d'erreurs, en indiquant, dans les options du générateur données aux plugins form ou formfull, le noms de l'objet javascript qui s'occupera d'afficher ces messages.

Par défaut, les messages d'erreurs sont affichés en haut du formulaire.

Affichage des messages d'erreurs

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

Affichage des messages d'aides

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.

Ajouter du code javascript

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), et en incluant ce code dans un fichier js que vous lierez à la page contenant le formulaire.

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(). Vous pouvez aussi utiliser l'objet jFormsJQ comme expliqué ci-dessous.

Objet JS jFormsJQ

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.

Vérification JS sur le submit

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.

jQuery et votre application

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');

Classes CSS à connaître

Pour styler les balises générées par le générateur "html", il y a quelques classes de style à connaître.

  • jforms-table : c'est la classe du tableau principal généré par le plugin formfull, et contenant tout les champs de saisie d'un formulaire.
  • jforms-hidden : la div contenant tous les champs cachés.
  • jforms-error-list : classe de la liste (ul) des messages d'erreurs.
  • jforms-label : classe placée sur toutes les balises <label>
  • jforms-required : classe placée sur toutes les balises <label> et les champs de saisie qui sont obligatoires
  • jforms-error : classe placée sur toutes les balises <label> et sur les champs de saisies qui sont en erreur
  • jforms-readonly : classe placée sur les champs de saisies qui sont en lecture seule
  • jforms-value : classe sur les éléments span contenant les valeurs des champs de type output.
  • jforms-help : classe placée sur les éléments span contenant les liens d'aide.
  • jforms-chkbox : classe placée sur le span qui entoure chaque checkbox d'un controle checkboxes.
  • jforms-radio : classe placée sur le span qui entoure boutons radio d'un contrôle radiobuttons.
  • jforms-ctl-xxx : classe placée sur chaque checkbox d'un contrôle checkboxes, ou chaque boutons radio d'un contrôle radiobuttons (xxx étant remplacé par le ref du contrôle).
  • jforms-captcha-question : classe placée sur le span qui affiche la question d'un captcha.
  • jforms-table-group : classe placée sur le tableau d'un contrôle <group>
  • jforms-choice : classe placée sur la liste des items d'un contrôle <choice>
  • jforms-item-controls : classe placée sur chaque span entourant un contrôle d'un item d'un contrôle <choice>
  • jforms-submit-buttons : c'est la classe de la div générée par le plugin formfull, contenant les boutons d'envois.
  • jforms-submit : classe sur chaque bouton submit
  • jforms-reset : classe sur chaque bouton reset

.jforms-table {}
.jforms-hidden {}
.jforms-error-list {}
.jforms-label {}
.jforms-required {}
.jforms-error {}
.jforms-readonly {}
.jforms-value {}
.jforms-help {}
.jforms-chkbox {}
.jforms-radio {}
.jforms-ctl-xxx {} /* Remplacer xxx par ref du contrôle */
.jforms-captcha-question {}
.jforms-table-group {}
.jforms-choice {}
.jforms-item-controls {}
.jforms-submit-buttons {}
.jforms-submit {}
.jforms-reset {}