Brouillon des spécifications de jForms
Page obsolète. Pour archive seulement. jForms est opérationnel depuis la beta 3 et les informations de cette page ne sont pas à jour.
Objectif de jForms : Faciliter la manipulation de formulaires.
Utilisation
Le développeur devra pour gérer un formulaire web :
- définir un fichier xml décrivant le formulaire : liste des contrôles, et le type de stockage (un dao par exemple). Pour éviter un minimum d'apprentissage, la grammaire ressemble à celle de XForms.
- déclarer les actions, et implementer les actions permettant d'initialiser, afficher, sauver un formulaire (un controleur "générique" pourra être proposer, il n'y aura donc juste à hériter de ce controleur, et à spécifier quelques propriétés).
- réaliser les templates, en utilisant les plugins jtpl dédiés à jForms
Une commande jelix-scripts sera proposée afin de générer un controleur, un template et un formulaire à partir d'un dao.
le fichier xml
Sa grammaire ressemble beaucoup à XForms. Il y a cependant quelques différences : toute la grammaire XForms n'est pas reprise, et des attributs/balises supplémentaires font leur apparition, notament pour lier le formulaire à un dao.
<jforms xmlns="http://jelix.org/ns/forms/1.0"> à specifier </jforms>
dans les actions
L'utilisation d'un formulaire ressemble à cela dans un controleur :
// créer un formulaire vierge
$form= jForms::create('selecteur_du_form');
// créer un formulaire avec un identifiant
// dont la valeur se situe dans un parametre de requete 'param_id'
// ce formulaire va devoir être initialisé avec des données
$form= jForms::create('selecteur_du_form', 'param_id');
// récupération d'un formulaire précedement crée, dont l'id se situe
// dans le parametre de requete param_id
$form= jForms::get('selecteur_du_form', 'param_id');
// affichage
$response->body->assign('formulaire',$form);
// affichage des données d'un formulaire (récapitulatif par ex)
$form= jForms::get('selecteur_du_form', 'param_id');
$form->setReadOnly(true);
$response->body->assign('formulaire',$form);
// aprés un submit, récuperation du formulaire et remplissage
// avec les données saisies
$form = jForms::fill('selecteur_du_form', 'param_id');
// sauvegarde
// par défaut, utilise le stockage indiqué dans le fichier xml
$form->save();
// $retour = false si ok, ou array() des erreurs.
template
Des plugins jtpl sont à disposition pour afficher le formulaire. Il y a des plugins pour créer le formulaire, dans le langage que l'on souhaite (HTML, XUL, XFORMS etc..), et d'autres pour créer les champs de saisie.
exemple
{jformhtml $formulaire,"selecteur~action_sauvegarde","post"}
<table>
{jform_foreach $champs}
<tr>
<td> {jform_label "attributs html"}</td>
<td> {jform_field "attributs html"}</td>
</tr>
{/jform_foreach}
</table>
<p>{jform_submit}</p>
{/jformhtml}
jformhtml génère la balise <form> html, les scripts javascript de validation, et les éventuels champs cachés. jformxul génère un formulaire en XUL, jformx en XForms...
jform_foreach effectue une boucle sur les champs de saisie déclaré dans le fichier xml. jform_label et jform_field affiche le label et le champs de saisie. jform_foreach n'est pas obligatoire. On peut afficher chaque champs séparément. Ce qui permet d'afficher le formulaire dans une présentation complexe.
{jformhtml $formulaire,"selecteur~action_sauvegarde","post"}
<div> {jform_label "idchamps1","attributs html"} : {jform_field "idchamps1","attributs html"}</div>
...
<div> {jform_label "idchamps2","attributs html"} : {jform_field "idchamps2","attributs html"}</div>
<p>{jform_submit}</p>
{/jformhtml}
Loic Mathaud :
{jformhtml $formulaire,"selecteur~action_sauvegarde","post"}
Y a t'il un intérêt à passer le formulaire en paramètre ?
LJ : comment alors le plugin récupère les infos du formulaire ??
{/jformhtml}
Comment implémenter cette syntaxe ? En effet jTpl accepte des plugins mais les {/foo} sont codés en dur dans le moteur.
LJ :Il faut créer un nouveau type de plugin, les "block", comme dans smarty
{jform_foreach $champs} et {/jform_foreach}
Comment implémenter ceci aussi sans toucher au moteur lui-même ?
LJ: idem, plugin de type block
{jform_label "attributs html"}
et
{jform_label "idchamps1","attributs html"}
Comment savoir si on ne passe qu'un paramètre à cette fonction, si ce sont des attributs html ou l'identifiant du champ ?
LJ: en testant le deuxième paramètre (qui aurait une valeur par défaut à null) ?
On a aussi un plugin qui génère un formulaire entier, dans un simple tableau (HTML, XUL ou autre selon le type de la réponse)
{jformhtml_smart $formulaire,"selecteur~action_sauvegarde","post"}
