Section: Générateur "html"
| ^ Affichage d'un formulaire | Générateur "htmllight" » |
− Table des matières
Le générateur "html" de jforms génère un formulaire HTML, utilisant principalement jQuery pour le comportement de certains champs de saisie. Par conséquent, ce genre de formulaire peuvent être assez lourd.
Le générateur "html" est celui utilisé par défaut par jForms, et son nom à indiquer aux plugins {form} ou {formfull} est "html".
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 {}
Personnalisation de l'affichage des messages ¶
Les messages d'erreurs, qui peuvent survenir lors de la vérification du formulaire avant l'envoi des données, et les messages d'aides qui apparaissent quand on clique sur le point d'interrogation, sont affichés dans une boîte de dialogue de type alert.
Vous pouvez changer ça, en indiquant, dans les options du générateurs données aux plugins form ou formfull, les noms des objets javascript qui s'occuperont d'afficher ces messages.
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 htmllight :
{form $formulaire, 'monmodule~default:sauver', array(), 'htmllight', 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
Affichage des messages d'aides ¶
Pour les messages d'aide, c'est le même principe que pour les messages d'erreur, mais l'objet ne doit contenir qu'une méthode, show qui est appelée avec en paramètre le message affiché.
function MyHelpDecorator(){ }
MyHelpDecorator.prototype = {
show : function(message){
document.getElementById("help").firstChild = document.createTextNode(message);
}
}
Ensuite il faut indiquer cet objet dans les options du builder 'htmllight' de form ou formfull :
{form $formulaire, 'monmodule~default:sauver', array(), "htmllight", array("helpDecorator"=>"MyHelpDecorator")}
...
{/form}
Notez ici que l'on a indiqué "" pour l'affichage des erreurs : jforms utilisera alors l'afficheur par défaut. Mais vous pouvez aussi indiquer un autre, en même temps que l'afficheur d'aide.
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'incluerez 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($GLOBALS['gJConfig']->urlengine['jelixWWWPath'].'jquery/jquery.js');
