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".
Options ¶
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 erreursmethod: la méthode HTTP à employer ('get' ou 'post'). Par défault : 'post'.
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 ¶
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
Affichage des messages d'aides ¶
Dans les versions précédentes, les messages d'aides étaient affichés par un mécanisme similaire à celui des messages d'erreurs. Ce n'est plus le cas depuis la version 1.2, où ils 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.
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($GLOBALS['gJConfig']->urlengine['jelixWWWPath'].'jquery/jquery.js');
