-
Notifications
You must be signed in to change notification settings - Fork 3
/
display.gtw
341 lines (243 loc) · 11.6 KB
/
display.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
~~LANG:FR@frman:jforms/affichage~~
To display a form and its data, you could call @@M@getAllData@@ on your form
object and assign its returned array to a template. With it, you'll be able to
generate your HTML form along with its data. if you want to display input
errors, call @@M@getErrors@@ to retrieve them and again display them as you like
in your template.
However there are some template plugins in Jelix, to prevent you from doing this
long and sometimes boring task. They even do a lot more:
* display each control field as described in your XML form,
* display each control label in @@E@<label>@@ tag to improve ergonomy and accessibility,
* display error messages,
* display help messages,
* generate javascript for client-side checking before posting data,
* valid HTML generated and good support of accessibility,
* ids and classes on elements to ease styling.
===== Full automatic form display with formfull =====
For you in a hurry, this template plugin will fully display your form. Its name:
@@formfull@@. With it, you won't control how each field, labels and submits are
displayed. Still you can customize display of help and error messages (see
further).
Here are its arguments, in the order:
* your form object
* a selector specifying the target action
* optional:
* an array containing extra url parameters (other than fields data)
* the name of the builder ('html' is the only provided builder)
* an array containing options for the builder
Example in your controller :
<code php>
$form = jForms::get('myform');
$tpl = new jTpl();
$tpl->assign('form', $form);
</code>
And in your template :
<code html>
<h1>My form</h1>
<p>Fill this form :</p>
{formfull $form, 'mymodule~default:save'}
</code>
Labels and control fields will be displayed in a table, and submit buttons in a div below.
Note: because of some limitations of the plugin formfull and the template
engine, don't use the plugin inside a loop, where the variable passed to the
plugin is generated by the loop (typically, in a foreach). In this case, JS and
CSS files won't be loaded in the page. A solution is to indicate yourself all
CSS and JS files needed by your form with the meta_html plugin.
===== Customized display =====
There is not only @@formfull@@. Other plugins exist to control how your form is
displayed and precisely in which markup your form controls are wrapped.
The first one @@form@@ is the equivalent to @@formfull@@ except that its a block
plugin. It means that it has an end tag and should contains other plugins and
markup controlling the display of your form. Arguments for @@form@@ are :
* your form object
* a selector specifying the target action
* optional:
* an array containing extra url parameters (other than fields data)
* the name of the builder ('html' for example)
* an array containing options for the builder
Note: As for the formfull plugin, there are some limitations in the plugin form
and the template engine, so don't use the plugin inside a loop, where the
variable passed to the plugin is generated by the loop (typically, in a
foreach). In this case, JS and CSS files won't be loaded in the page. A solution
is to indicate yourself all CSS and JS files needed by your form with the meta_html plugin.
==== Simple display ====
@@formcontrols@@ plugins loops on form controls (neither submits nor reset). It
is a block plugin. Within it, @@ctrl_label@@ and @@ctrl_control@@ plugins will
display respectively label and field of current control. To display submit
buttons or reset, use @@formsubmit@@ and @@formreset@@.
Example:
<code html>
{form $form, 'mymodule~default:save'}
<fieldset><legend>Fill : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formreset}{formsubmit} </div>
{/form}
</code>
Note that form fields will be displayed in the order of their declaration in
your XML file. Note also that template here is totally independent of form
content and could be reused with more forms.
==== Advanced display ====
Some controls need to be displayed differently. To achieve this, you can use
@@ifctrl@@ inside @@formcontrols@@. Its argument is a list of control names. The
code below adds a class on 'name' and 'firstname' controls only:
<code html>
{form $form, 'mymodule~default:save'}
<fieldset><legend>Your identtity : </legend>
{formcontrols}
<p {ifctrl 'name', 'firstname'}class="help-needed"{/ifctrl}> {ctrl_label} : {ctrl_control} </p>
<p {ifctrl 'address'}class="address"{/ifctrl}> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
</code>
Or indicate a list of control names to @@formcontrols@@ plugin. It will loop only on those controls.
<code html>
{form $form, 'mymodule~default:save'}
<fieldset><legend>Identity : </legend>
{formcontrols array('lastname','firstname','address')}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<fieldset><legend>Other fields : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formsubmit} </div>
{/form}
</code>
Above, we display a series of controls in a first fieldset (lastname, firstname
and address) and the others in a second fieldset: @@formcontrols@@ loops over
controls not already displayed.
Note that @@ctrl_label@@ and @@ctrl_control@@ also function outside of
@@formcontrols@@. In that case, you should indicate a control name.
<code html>
{form $form, 'mymodule~default:save'}
<fieldset><legend>Identity : </legend>
<table>
<tr><td>{ctrl_label 'lastname'}</td><td>{ctrl_control 'lastname'}</td> </tr>
<tr><td>{ctrl_label 'firstname'}</td><td>{ctrl_control 'firstname'}</td></tr>
</table>
</fieldset>
<fieldset><legend>Other fields : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formsubmit} </div>
{/form}
</code>
Lastname and firstname fields are displayed precisely in a table whereas other
fields are displayed with @@formcontrols@@.
=== Custom attributes ===
You can add some html attributes on the HTML element generated with
@@ctrl_control@@. To do it, add a second parameter to the @@ctrl_control@@ tag:
it should be an array @@('attribute name'=>'attribute value')@@. Give @@L@""@@
as first parameter when @@ctrl_control@@ is used inside a @@formcontrols@@ loop.
Note: on other generator than 'html', this array can be an array of other
type of informations.
==== Customizing display of password controls ====
Beware that if a password control defines a confirm field (@@E@<confirm>@@ tag
in XML) you should control either the display of @@password@@ field **and**
@@confirm@@ field. The confirm control name is a concatenation of password
control name + @@_confirm@@.
See example below:
<code html>
{form $form, 'mymodule~default:save'}
<fieldset><legend>Account creation : </legend>
<table>
<tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
<tr><td>{ctrl_label 'password'}</td><td>{ctrl_control 'password'}</td></tr>
</table>
</fieldset>
<fieldset><legend>Other infos : </legend>
{formcontrols}
<p> {ctrl_label} : {ctrl_control} </p>
{/formcontrols}
</fieldset>
<div> {formsubmit} </div>
{/form}
</code>
Confirm field will appear in the second fieldset and not near password field in
the example above. To do so, just display 'password_confirm' in a row below
'password' :
<code html>
<table>
<tr><td>{ctrl_label 'login'}</td><td>{ctrl_control 'login'}</td> </tr>
<tr><td>{ctrl_label 'password'}</td><td>{ctrl_control 'password'}</td></tr>
<tr><td>{ctrl_label 'password_confirm'}</td><td>{ctrl_control 'password_confirm'}</td></tr>
</table>
</code>
On the contrary, you should not take care of confirm field in @@formcontrols@@ loop.
==== Customizing display of submit buttons ====
As you may recall, @@formsubmit@@ template plugin displays a submit button
declared in your form. But if one declares more than one submit button,
@@formsubmit@@ will display only the first one. In that case, use
@@formsubmits@@ (note the ending **s**). This block template loops over submit
buttons:
<code html>
<ul>
{formsubmits}
<li>{formsubmit}</li>
{/formsubmits}
</ul>
</code>
Another way is to use @@formsubmit@@ multiple times indicating each submit name :
<code html>
<div> {formsubmit 'preview'} {formsubmit 'save'} </div>
</code>
**Beware** : @@{formsubmits}@@ loops over submit **controls**, not submit
**items**! It is not possible to loop over submit items (see [[ticket:429|ticket #429]]).
===== Adding javascript code =====
You can add behaviors to any controls with javascript, with your prefered js
library (jForms uses jQuery).
All generated fields have an id. Ids are composed names:
"jforms_module_formname_controlref". For example, for a control with the ref
"address", declared in the form "identity" provided the "users" module, the id
of the generated field is: "jforms_users_identity_address".
The form element is also generated with an id, composed with the name of the
module and the name of the jforms form: "jforms_module_formname". In our
example, the id is "jforms_users_identity".
Knowing that, you can retrieve all fields and the form element with the
@@document.getElementById()@@ function.
To know more about javascript possibilities, read documentation about the
generator you use. See for example [[display/html-generator|the HTML generator]]
provided with Jelix, and its possibilities about submit handlers for instance.
===== Choosing a generator =====
To generate HTML code, template plugins call a generator (or builder)
which is a component of jForms.
It is possible to use another generator than the default one ('html').
You would want to generate a form based on a library like ExtJS, or a form
built using XForms etc.
Generators are themselves plugins. Furthermore, since Jelix 1.5, the generator
'html' is also extensible: you can provide your own plugins to
generate HTML code of some specific controls, without redefining th whole
generator. These are "formwidget" plugins.
Each generator has a name. The default generator is, as we already say, 'html'.
It is specified in the parameter //defaultJformsBuilder// of the main configuration.
Note: since Jelix 1.5, architecture of generators has been modified. But it
is still possible to use olders generators. To use them, you should
prefix their name with "legacy.". For example, to use the deprecated
builder 'htmllight', indicate 'legacy.htmllight'. Read manual of previous
version of Jelix to know how to use them.
To specify your own generator for th whole application, modify this parameter
in the configuration:
<code ini>
[tplplugins]
defaultJformsBuilder = myformbuilder
</code>
To achieve a fine-grained control, you can even choose a generator in @@{form}@@
ou @@{formfull}@@ (as fourth argument) :
<code html>
{formfull $form, 'mymodule~default:save', array(), 'legacy.htmllight'}
</code>
Those plugins support a fifth parameter which is an array of options passed to
the generator. These options depends on the used generator. (//errorDecorator// and //method// for 'html').
Note: You can of course create a new generator as inheriting from an existing
one. That way, you can customize only some of the output or set an option
directly in its constructor. ...
More about generators the 'html' generator: [[display/html-generator|"html" generator]].
===== Mixing jForms and AJAX response =====
see [[/web-services/ajax|ajax response documentation]].