/
affichage.gtw
389 lines (286 loc) · 14.5 KB
/
affichage.gtw
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
~~LANG:EN@enman:jforms/display~~
Pour afficher les données d'un formulaire jforms, vous pouvez appeler la méthode
@@M@getAllData()@@ d'un objet formulaire, et vous obtiendrez un tableau
contenant toutes les données. Vous pouvez passer ensuite ce tableau à un
template pour afficher votre formulaire HTML avec les données. Vous pouvez aussi
récupérer les erreurs avec @@M@getErrors()@@ et ainsi afficher les éventuelles
erreurs.
Cependant des plugins de templates vous permettent d'éviter de faire ce travail
répétitif, et surtout font bien plus qu'afficher les valeurs :
* affichage de chaque champ de saisie, en accord avec ce qui est décrit dans
le fichier XML du formulaire,
* affichage des libellés de chaque champ dans des balises @@E@<label>@@ pour
une meilleure ergonomie/accessibilité,
* affichage automatique des messages d'erreurs,
* affichage des messages d'aide,
* intégration du code javascript qui vérifiera le bon contenu des données
saisies avant validation du formulaire,
* code HTML généré valide, avec un effort sur l'accessibilité,
* des classes sur les balises générés pour pouvoir les styler facilement.
===== Affichage sans personnalisation =====
Pour les développeurs pressés, il existe un plugin de template qui affiche tout
tout seul : @@formfull@@. Vous ne pouvez pas contrôler la façon dont sont
affichés les champs de saisie, leur libellés et les boutons de validation. La
seule chose que vous pouvez personnaliser c'est l'affichage des messages
d'erreurs et d'aide (voir plus loin).
Vous devez passer à ce plugin, les paramètres suivant, dans l'ordre :
* l'objet formulaire
* le sélecteur de l'action où le contenu du formulaire sera envoyé
* facultatif :
* un tableau des paramètres de l'url de cette action (autre que les champs
de saisie)
* le nom du générateur à utiliser (entre autre 'html' ou 'htmllight')
* un tableau contenant des options pour le générateur
Voici un exemple dans le contrôleur :
<code php>
$form = jForms::get('monform');
$tpl = new jTpl();
$tpl->assign('formulaire', $form);
</code>
Et dans le template :
<code html>
<h1>Le formulaire</h1>
<p>Remplissez le formulaire suivant :</p>
{formfull $formulaire, 'monmodule~default:sauver'}
</code>
Les libellés et les champs de saisies s'affichent dans un tableau, et les
boutons de validation dans une div en dessous du tableau.
Note : n'utilisez pas ce plugin dans une boucle avec une variable générée par
cette boucle (typiquement dans un foreach). À cause d'une limitation du moteur
de template et du plugin, les fichiers JS et CSS pour le formulaire ne seront
pas chargés dans ce cas. Ou alors il faut les indiquer vous même avec le plugin
meta_html.
===== Affichage contrôlé =====
D'autres plugins que @@formfull@@ existent permettant de mieux contrôler
l'affichage des champs de saisie, en particulier, de pouvoir définir les
endroits où les champs seront placés.
Le premier plugin à connaitre, est le plugin @@form@@. Il a les même paramètres
que @@formfull@@. C'est un plugin de type bloc, c'est à dire qu'il y a une
balise de fin, et qu'entre les deux balises @@form@@, on placera les autres
plugins.
Le plugin @@form@@ a les même paramètres que @@formfull@@, à savoir, dans
l'ordre :
* l'objet formulaire
* le sélecteur de l'action où le contenu du formulaire sera envoyé
* facultatif :
* un tableau des paramètres de l'url de cette action (autre que les champs de saisie)
* le nom du générateur à utiliser (entre autre 'html' ou 'htmllight')
* un tableau contenant des options pour le générateur
Note : n'utilisez pas ce plugin dans une boucle avec une variable générée par
cette boucle (typiquement dans un foreach). À cause d'une limitation du moteur
de template et du plugin, les fichiers JS et CSS pour le formulaire ne seront
pas chargés dans ce cas. Ou alors il faut les indiquer vous même avec le plugin
meta_html.
==== Affichage contrôlé simple ====
Le plugin @@formcontrols@@ permet de faire une boucle sur la liste des champs de
saisie. C'est aussi un bloc dans lequel on utilisera les plugins @@ctrl_label@@
et @@ctrl_control@@ pour afficher respectivement le libellé et le champ de
saisie. Et on utilise le plugin @@formsubmit@@ pour afficher le bouton de
validation déclaré dans le fichier xml, ainsi que @@formreset@@ pour afficher le
bouton reset si il est déclaré lui aussi dans le fichier xml.
Exemple :
<code html>
{form $formulaire, 'monmodule~default:sauver'}
<fieldset><legend>Saisissez : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formreset}{formsubmit} </div>
{/form}
</code>
Notez que les champs seront affichés dans le même ordre que leur déclaration
dans le fichier XML. Notez également qu'ici le template est **totalement indépendant**
du contenu du formulaire. Il pourrait être réutilisé avec plusieurs formulaires.
==== Aller plus loin dans le contrôle de l'affichage ====
Il arrive que l'on ne veuille pas présenter tous les champs de saisie de la même
façon.
Vous pouvez utiliser le plugin @@ifctrl@@ à l'intérieur du bloc
@@formcontrols@@. Il suffit de lui indiquer une liste de noms de champs à
tester.
Par exemple, le code ci-dessous ajoute la classe //help-needed// pour les champs
'nom' et 'prenom' et la classe //address// pour le champ adresse.
<code html>
{form $formulaire, 'monmodule~default:sauver'}
<fieldset><legend>Votre identité : </legend>
{formcontrols}
<p {ifctrl 'nom', 'prenom'}class="help-needed"{/ifctrl}> {ctrl_label} : {ctrl_control} </p>
<p {ifctrl 'adresse'}class="address"{/ifctrl}> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
</code>
Vous pouvez aussi indiquer une liste des noms des champs à afficher au plugin
@@formcontrols@@. Par exemple si on souhaite encadrer par un @@E@<fieldset>@@
différents groupes de champs.
<code html>
{form $formulaire, 'monmodule~default:sauver'}
<fieldset><legend>Votre identité : </legend>
{formcontrols array('nom','prenom','adresse')}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<fieldset><legend>Autres renseignements : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formsubmit} </div>
{/form}
</code>
Dans cet exemple, on affiche une première série de champs de saisie (les champs
nom, prenom et adresse). Et une deuxième série dont on ne précise pas la liste
de champs : @@formcontrols@@ bouclera alors uniquement sur les champs qui n'ont
pas encore été affiché.
Vous pouvez aussi utiliser @@ctrl_label@@ et @@ctrl_control@@ en dehors d'une
boucle @@formcontrols@@. Vous devez alors leur indiquer un nom de champs.
<code html>
{form $formulaire, 'monmodule~default:sauver'}
<fieldset><legend>Votre identité : </legend>
<table>
<tr><td>{ctrl_label 'nom'}</td><td>{ctrl_control 'nom'}</td> </tr>
<tr><td>{ctrl_label 'prenom'}</td><td>{ctrl_control 'prenom'}</td></tr>
</table>
</fieldset>
<fieldset><legend>Autres renseignements : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formsubmit} </div>
{/form}
</code>
Ici on affiche les champs noms et prenoms à des endroits précis, et le reste
sera affiché par le plugin formcontrols qui suit.
=== Ajout d'attributs personnalisés ===
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 @@L@""@@ comme premier paramètre quand @@ctrl_control@@
est utilisé à l'intérieur d'une boucle @@formcontrols@@
Note : pour les générateurs autre que HTML, ce tableau d'attribut peut être
d'autres options.
==== Contrôle de l'affichage des champs de type password ====
Pour les champs de saisie de mot de passe pour lesquels il y a un champ de
confirmation (balise @@E@<confirm>@@), si vous indiquez explicitement leur
affichage, il faut aussi indiquer spécifiquement l'affichage du champ de
confirmation, sachant que celui-ci a le nom du champ de saisie principale avec
un suffixe **_confirm**.
Par exemple, vous indiquez explicitement d'afficher le champ "motdepasse" qui
est un mot de passe :
<code html>
{form $formulaire, 'monmodule~default:sauver'}
<fieldset><legend>Créer votre compte : </legend>
<table>
<tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
<tr><td>{ctrl_label 'motdepasse'}</td><td>{ctrl_control 'motdepasse'}</td></tr>
</table>
</fieldset>
<fieldset><legend>Autres renseignements : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formsubmit} </div>
{/form}
</code>
Ici, si le champ de confirmation ne s'affiche pas près du champ de mot de passe,
il faut ajouter le champ "motdepasse_confirm" :
<code html>
<table>
<tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
<tr><td>{ctrl_label 'motdepasse'}</td><td>{ctrl_control 'motdepasse'}</td></tr>
<tr><td>{ctrl_label 'motdepasse_confirm'}</td><td>{ctrl_control 'motdepasse_confirm'}</td></tr>
</table>
</code>
Par contre, il n'est pas besoin de préciser le champ de confirmation quand on
afficher le champ de saisie de mot de passe dans une boucle @@formcontrols@@.
==== Contrôle de l'affichage des boutons d'envoi ====
On a vu que l'on pouvait utiliser le plugin @@formsubmit@@ pour afficher le
bouton d'envoi déclaré dans votre formulaire. Mais utilisé comme cela, si vous
avez déclaré plusieurs balises @@E@<submit>@@, seul le premier bouton sera
affiché. Dans ce cas là il faut utiliser le plugin @@formsubmits@@ (avec un s),
qui est une boucle sur les boutons d'envoi :
<code html>
<ul>
{formsubmits}
<li>{formsubmit}</li>
{/formsubmits}
</ul>
</code>
Ou encore, vous pouvez utiliser plusieurs plugins @@formsubmit@@, sans
@@formsubmits@@, en indiquant le nom du bouton :
<code html>
<div> {formsubmit 'preview'} {formsubmit 'save'} </div>
</code>
**Attention** : @@{formsubmits}@@ boucle sur la liste des contrôles
@@E@<submit>@@, pas sur les item d'un submit ! Il n'est pas possible pour le
moment de boucler sur les items d'un submit (voir [[ticket:429|ticket #429]]).
===== 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).
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()@@.
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
@@M@addSubmitHandler@@ de l'objet javascript jforms.
Voici un exemple pour ajouter un message de confirmation:
<code javascript>
jQuery(document).ready(function(){
jFormsJQ.getForm("the_id_of_formelement").addSubmitHandler(function(ev){
return window.confirm("Voulez vous vraiment envoyer ces données ?");
});
});
</code>
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 @@M@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.
===== Choisir un générateur =====
Les plugins de templates de jForms reposent sur d'autres plugins spécifiques à
jForms, s'occupant de générer le formulaire proprement dit. Deux générateurs
sont fournis : "html" et "htmllight". [[/plugins/jforms|Vous pouvez en créer d'autres]]
si la façon dont sont générés les formulaires ne vous plaît pas. Par
exemple, un générateur qui génère un formulaire en se reposant une bibliothèque
javascript comme Extjs, un formulaire qui utilise Ajax, ou encore un formulaire
en XUL, en XForms etc...
Le générateur par défaut de Jelix est 'html'. Il est spécifié par la variable
//defaultJformsBuilder// du fichier de configuration.
Pour spécifier son propre choix de générateur pour l'ensemble d'une application,
il vous suffit de modifier cette variable dans le fichier de configuration:
<code ini>
[tplplugins]
defaultJformsBuilder = myformbuilder
</code>
Ponctuellement, vous pouvez aussi indiquer le générateur de votre choix en
passant son nom aux plugins de template @@{form}@@ ou @@{formfull}@@ (4ième
paramètre) :
<code html>
{formfull $formulaire, 'monmodule~default:sauver', array(), 'htmllight'}
</code>
Comme indiqué plus haut, ces plugins acceptent un cinquième paramètre, un
tableau, contenant des options pour le générateur. Ces options dépendent du
générateur utilisé (//errorDecorator// et //method// par exemple pour 'html' et
htmllight').
Remarque : si vous souhaitez passer la même option dans tous vos formulaires,
créez le générateur de votre choix en dérivant un générateur existant et
affectez-lui directement ces options dans son code...
Pour en savoir plus sur chaque générateur :
* [[affichage/generateur-html|Générateur "html"]]
* [[affichage/generateur-htmllight|Générateur "htmllight"]]
===== Utilisation de jforms dans des réponses Ajax =====
Voir [[/services-web/ajax|la note sur la page des réponses ajax]]