Skip to Content

Version 18.2 by Vincent Massol on 2020/11/22
Show last authors
1 {{box cssClass="floatinginfobox" title="**Content**"}}
2 {{toc/}}
3 {{/box}}
4
5 XWiki Forms (##xform## / ##xformInline##) are general usage purpose CSS classes, that need to be used in order to have a consistent view of forms across XWiki.
6
7 * Forms Layout Type:
8 ** **Vertical Layout** (##xform##): uses a dl-dt-dd structure
9 ** [[Inline Layout>>platform:DevGuide.InlineForms]] (##xformInline##)
10
11 This classes implementation has been voted at [[[Vote] [Standards] Forms: Usage + Documentation page to XWiki.org>>http://markmail.org/thread/5zrnncdukmc7wmer]] and implemented in [[XSCOLIBRI-260>>https://jira.xwiki.org/browse/XSCOLIBRI-260]].
12
13 = Usage =
14
15 * Obs: The CSS classes have as parent the ##.xform## class. This is supposed to be used on the form tag, but if the styling is done inside dynamically generated structures it can be used on other elements, like divs, as long as the element remains the parent for the other form components. For instance, a common use case is when you design a form that is to be used in inline edit mode, you have to wrap the form content in a div element and use ##class='xform'## on the div instead of the form. This is needed because in inline edit mode the entire page content is put inside a form element to which we don't have access as it is generated in a velocity template, and generating a form element inside the page content will produce invalid HTML since nested form elements are not allowed (the inner form element will probably be removed either by the rendering engine or by the browser).
16
17 (% summary="Table containg classes for different form components" %)
18 |=(% rowspan="2" %) Tag |=(% rowspan="2" %)Type |=(% rowspan="2" %)Size |=(% colspan="3" %)Classes|=(% rowspan="2" %)Usage\\
19 |=Required |=Optional |=Container \\
20 |form | | |##.xform## |##.half##, ##.third##| |Container for the form controls\\
21 |label | | | | |dt |Descriptive label for the control\\
22 |span | | |##.xRequired## | |dt label |Displays the required status of a control\\
23 |a | | |##.xHelp## | |dt |Attach a link to external documentation about a control\\
24 |span | | |##.xHint## | |dt |Attach hint information to a control\\
25 |span | | |##.xErrorMsg## | |dt |Alert or error information for the control\\
26 |input | hidden | | | | |\\
27 |(% rowspan="2" %)input |(% rowspan="2" %)(((text\\Since 12.10: color, date, datetime-local, email, number, search, tel, time)))|(% rowspan="2" %)size=60 |(% rowspan="2" %) |##.disabled## |dd |\\
28 |##.xErrorField##|dd |Alert or error triggering control\\
29 |(% rowspan="2" %)input |(% rowspan="2" %)password |(% rowspan="2" %)size=60 |(% rowspan="2" %) |##.disabled## |dd |\\
30 |##.xErrorField##|dd |Alert or error triggering control\\
31 |input | radio | | | | |\\
32 |input | checkbox | | | | |\\
33 |input | submit | |##.button## |##.secondary## ##.disabled##|span##.buttonwrapper##|Button controls\\
34 |input | button | |##.button## |##.secondary## ##.disabled##|span##.buttonwrapper##|Button controls\\
35 |a | | |##.button## |##.secondary## ##.disabled##|span##.buttonwrapper##|Button controls\\
36 |(% rowspan="2" %)textarea |(% rowspan="2" %) |(% rowspan="2" %)rows=7 cols=45 |(% rowspan="2" %) | | |\\
37 |##.xErrorField##|dd |Alert or error triggering control\\
38 |select | |size=1 | | | |\\
39 |fieldset | | | | | |\\
40 |legend | | | | | |\\
41
42 = Components =
43
44 == 1. Labels ==
45
46 * This element provides a descriptive label for the containing form control.
47 * **Obs.1**: Use uppercase ('UPPERCASE') bold fonts for input field labels [ title case ('Title Case') in the translation keys]
48 * **Obs.2**: Do __not__ use colons(:) at the end of labels
49
50 === [preview] ===
51
52 image:label.png
53
54 === [html] ===
55
56 {{code language="html"}}
57 <form action="." class="xform" method="post" name="form_name1">
58 <dl>
59 <dt>
60 <label for="input_id1">Label</label>
61 </dt>
62 <dd>
63 <input id="input_id1" name="input_name1" type="text" size="60" value=""/>
64 </dd>
65 </dl>
66 <p>
67 <span class="buttonwrapper">
68 <input class="button" type="submit" value="Button"/>
69 </span>
70 </p>
71 </form>
72 {{/code}}
73
74 === [demo] ===
75
76 {{html clean="false"}}
77 <form action="." class="xform" method="post" name="form_name9">
78 <dl>
79 <dt>
80 <label for="input_id1">Label</label>
81 </dt>
82 <dd>
83 <input id="input_id1" name="input_name1" type="text" size="60" value=""/>
84 </dd>
85 </dl>
86 <p>
87 <span class="buttonwrapper">
88 <input class="button" type="submit" value="Button"/>
89 </span>
90 </p>
91 </form>
92 {{/html}}
93
94 === [css] ===
95
96 {{code language="css"}}
97 .xform input[type="text" size="60"], .xform input[type="password"],
98 .xform select, .xform textarea{
99 width: 99%;
100 }
101
102 .xform dt {
103 margin-top: 1.2em;
104 }
105
106 .xform label {
107 color: $theme.textColor;
108 display: block;
109 font-size: .85em;
110 font-weight: 700;
111 margin-bottom: .3em;
112 text-transform: uppercase;
113 }
114 {{/code}}
115
116 == 2. Required ==
117
118 * This element displays the required status of a form control.
119
120 === [preview] ===
121
122 image:required.png
123
124 === [html] ===
125
126 {{code language="html"}}
127 <label for="input_id2">Label <span class="xRequired">(Required)</span></label>
128 {{/code}}
129
130 === [demo] ===
131
132 {{html clean="false"}}
133 <form action="." class="xform" method="post" name="form_name2">
134 <dl>
135 <dt>
136 <label for="input_id2">Label <span class="xRequired">(Required)</span></label>
137 </dt>
138 <dd>
139 <input id="input_id2" name="input_name2" type="text" size="60" value=""/>
140 </dd>
141 </dl>
142 <p>
143 <span class="buttonwrapper">
144 <input class="button" type="submit" value="Button"/>
145 </span>
146 </p>
147 </form>
148 {{/html}}
149
150 === [css] ===
151
152 {{code language="css"}}
153 .xform .xRequired {
154 color: $theme.textSecondaryColor;
155 font-size: .9em;
156 font-style: italic;
157 font-weight: normal;
158 margin-left: 1ex;
159 text-transform: none;
160 }
161 {{/code}}
162
163 === [translation] ===
164
165 core.validation.required=(Required)
166
167 == 3. Help ==
168
169 * This element displays an icon pointing to some external documentation about a specific field.
170
171 === [preview] ===
172
173 image:help.png
174
175 === [html] ===
176
177 {{code language="html"}}
178 <dt>
179 <label for="input_id3">Label</label>
180 <a class="xHelp" title="Documentation" href="#">Documentation</a>
181 </dt>
182 {{/code}}
183
184 === [demo] ===
185
186 {{html clean="false"}}
187 <form action="." class="xform" method="post" name="form_name">
188 <dl>
189 <dt>
190 <label for="input_id3a">Label</label>
191 <a class="xHelp" title="Documentation" href="#">Documentation</a>
192 </dt>
193 <dd>
194 <input id="input_id3a" name="input_name1" type="text" size="61" value=""/>
195 </dd>
196 </dl>
197 <p>
198 <span class="buttonwrapper">
199 <input class="button" type="submit" value="Button"/>
200 </span>
201 </p>
202 </form>
203 {{/html}}
204
205 === [css] ===
206
207 {{code language="css"}}
208 .xform .xHelp {
209 background: transparent url("$xwiki.getSkinFile('icons/silk/information.gif')") left top no-repeat;
210 float: right;
211 height: 16px;
212 line-height: 250px;
213 margin-right: 1px;
214 margin-top: -20px;
215 overflow: hidden;
216 text-align: left !important;
217 width: 16px;
218 }
219 {{/code}}
220
221 == 4. Hint ==
222
223 * This element provides a convenient way to attach hint information to a form control.
224
225 === [preview] ===
226
227 image:hint.png
228
229 === [html] ===
230
231 {{code language="html"}}
232 <dt>
233 <label for="input_id3">Label</label>
234 <span class="xHint">Hint</span>
235 </dt>
236 {{/code}}
237
238 === [demo] ===
239
240 {{html clean="false"}}
241 <form action="." class="xform" method="post" name="form_name3">
242 <dl>
243 <dt>
244 <label for="input_id3">Label</label>
245 <span class="xHint">Hint</span>
246 </dt>
247 <dd>
248 <input id="input_id3" name="input_name3" type="text" size="60" value=""/>
249 </dd>
250 </dl>
251 <p>
252 <span class="buttonwrapper">
253 <input class="button" type="submit" value="Button"/>
254 </span>
255 </p>
256 </form>
257 {{/html}}
258
259 === [css] ===
260
261 {{code language="css"}}
262 .xform .xHint {
263 color: $theme.textSecondaryColor;
264 display: block;
265 font-size: .8em;
266 font-style: normal;
267 font-weight: 400;
268 margin-bottom: .3em;
269 }
270 {{/code}}
271
272 == 5. Error ==
273
274 * This element provides a convenient way to attach alert or error information to a form control.
275
276 === [preview] ===
277
278 image:error.png
279
280 === [html] ===
281
282 {{code language="html"}}
283 <dl>
284 <dt>
285 <label for="input_id5">Label</label>
286 <span class="xHint">Hint</span>
287 <span class="xErrorMsg">Error</span>
288 </dt>
289 <dd>
290 <input class="xErrorField" id="input_id5" name="input_name5" type="text" size="60" value=""/>
291 </dd>
292 </dl>
293 {{/code}}
294
295 === [demo] ===
296
297 {{html clean="false"}}
298 <form action="." class="xform" method="post" name="form_name5">
299 <dl>
300 <dt>
301 <label for="input_id5">Label</label>
302 <span class="xHint">Hint</span>
303 <span class="xErrorMsg">Error</span>
304 </dt>
305 <dd>
306 <input class="xErrorField" id="input_id5" name="input_name5" type="text" size="60" value=""/>
307 </dd>
308 </dl>
309 <p>
310 <span class="buttonwrapper">
311 <input class="button" type="submit" value="Button"/>
312 </span>
313 </p>
314 </form>
315 {{/html}}
316
317 === [css] ===
318
319 {{code language="css"}}
320 .xform .xErrorMsg {
321 color: #CC3333;
322 display: block;
323 font-size: .8em;
324 font-weight: normal;
325 margin-bottom: .3em;
326 }
327
328 .xform .xErrorField {
329 border: 1px solid #CC3333;
330 }
331 {{/code}}
332
333 == 6. Buttons ==
334
335 * Group multiple buttons in a ##.buttons## div
336
337 === [preview] ===
338
339 image:buttons.png
340
341 === [html] ===
342
343 * Use an additional ##.buttonwrapper## class span container to surround button elements
344
345 {{code language="html"}}
346 <div class="buttons">
347 <span class="buttonwrapper">
348 <input class="button" type="submit" value="Button"/>
349 </span>
350 <span class="buttonwrapper">
351 <a href="." class="button">Link</a>
352 </span>
353 <span class="buttonwrapper">
354 <input class="button secondary" type="submit" value="Secondary Button"/>
355 </span>
356 <span class="buttonwrapper">
357 <a href="." class="button secondary">Secondary Link</a>
358 </span>
359 </div>
360 {{/code}}
361
362 === [demo] ===
363
364 {{html clean="false"}}
365 <form action="." class="xform" method="post" name="form_name6">
366 <dl>
367 <dt>
368 <label for="input_id6">Label</label>
369 </dt>
370 <dd>
371 <input id="input_id6" name="input_name6" type="text" size="60" value=""/>
372 </dd>
373 </dl>
374 <p class="buttons">
375 <span class="buttonwrapper">
376 <input class="button" type="submit" value="Button"/>
377 </span>
378 <span class="buttonwrapper">
379 <a href="." class="button">Link</a>
380 </span>
381 <span class="buttonwrapper">
382 <input class="button secondary" type="submit" value="Secondary Button"/>
383 </span>
384 <span class="buttonwrapper">
385 <a href="." class="button secondary">Secondary Link</a>
386 </span>
387 </p>
388 </form>
389 {{/html}}
390
391 === [css] ===
392
393 ##.buttonwrapper## and ##.button## (##.secondary##) classes are described in ##colibri.css##
394
395 == 7. Disabling ==
396
397 * Use the ##.disabled## class if you want to have disabled input elements
398
399 === [preview] ===
400
401 image:disabledElements.png
402
403 === [html] ===
404
405 {{code language="html"}}
406 <dd>
407 <input type="text" class="disabled" disabled="disabled" ... />
408 </dd>
409 ...
410 <span class="buttonwrapper">
411 <input type="submit" class="button" value="Primary" ... />
412 </span>
413 <span class="buttonwrapper">
414 <input type="submit" class="button disabled" disabled="disabled" value="Primary Disabled" ... />
415 </span>
416 <span class="buttonwrapper">
417 <input type="submit" class="button secondary" value="Secondary" ... />
418 </span>
419 <span class="buttonwrapper">
420 <input type="submit" class="button secondary disabled" disabled="disabled" value="Primary Disabled" ... />
421 </span>
422 ...
423 <span class="buttonwrapper">
424 <a href="." class="secondary button disabled" ... >Secondary Disabled</a>
425 </span>
426 {{/code}}
427
428 == 8. Grouping ==
429
430 * Grouping can be done by using fieldset/legend or other markup (like headers)
431
432 === [preview] ===
433
434 image:grouping.png
435
436 === [html] ===
437
438 {{code language="html"}}
439 <h2>Group 1</h2>
440 {{/code}}
441
442 === [demo] ===
443
444 {{html clean="false"}}
445 <form action="." class="xform" method="post" name="form_name10">
446 <h2>Group 1</h2>
447 <dl>
448 <dt>
449 <label for="input_id10">Label</label>
450 </dt>
451 <dd>
452 <input id="input_id10" name="input_name10" type="text" size="60" value=""/>
453 </dd>
454 </dl>
455 <h2>Group 2</h2>
456 <dl>
457 <dt>
458 <label for="input_id11">Label</label>
459 </dt>
460 <dd>
461 <input id="input_id11" name="input_name11" type="text" size="60" value=""/>
462 </dd>
463 </dl>
464 <p>
465 <span class="buttonwrapper">
466 <input class="button" type="submit" value="Button"/>
467 </span>
468 </p>
469 </form>
470 {{/html}}
471
472 === [css] ===
473
474 {{code language="css"}}
475 .xform h2 {
476 font-size: 1.2em;
477 font-weight: bold;
478 margin: 2em 0 0;
479 }
480 {{/code}}
481
482 = Form Examples =
483
484 == [preview] ==
485
486 image:example.png
487
488 == [demo] ==
489
490 {{html clean="false"}}
491 <form action="." class="xform" method="post" name="form_name7">
492 <dl>
493 <dt>
494 <label for="input_id7">Browser Title Bar Text <span class="xRequired">(Required)</span></label>
495 <span class="xHint">Type the text you want to be displayed in the browser's title bar</span>
496 </dt>
497 <dd>
498 <input id="input_id7" name="input_name7" type="text" size="60" value=""/>
499 </dd>
500 <dt>
501 <label for="checkbox_id1">Indexing</label>
502 <span class="xHint">Index only elements that are not already indexed</span>
503 </dt>
504 <dd>
505 <label for="checkbox_id1"><input type="checkbox" name="checkbox_id1"/> Standard Index</label>
506 </dd>
507 <dt>
508 <label for="select_id1">Show Left Panels</label>
509 </dt>
510 <dd>
511 <select id="select_id1" size="1">
512 <option value="" label="---">---</option>
513 <option value="1" label="Yes">Yes</option>
514 <option selected="selected" value="0" label="No">No</option>
515 </select>
516 </dd>
517 <dt>
518 <label>Activate annotations</label>
519 <span class="xHint">Configure if annotations are available for the current wiki</span>
520 </dt>
521 <dd>
522 <label for="radio_id1">
523 <input type="radio" value="1" name="radio_name1" id="radio_id1" checked="checked"/>
524 Yes
525 </label>
526 <label for="radio_id2">
527 <input type="radio" value="0" name="radio_name1" id="radio_id2"/>
528 No
529 </label>
530 </dd>
531 <dt>
532 <label for="textarea_id1">HTTP Meta Information</label>
533 </dt>
534 <dd>
535 <textarea id="textarea_id1" rows="7" cols="45">Text</textarea>
536 </dd>
537 </dl>
538 <p>
539 <span class="buttonwrapper">
540 <input class="button" type="submit" value="Button"/>
541 </span>
542 <span class="buttonwrapper">
543 <input class="secondary button" type="submit" value="Secondary Button"/>
544 </span>
545 </p>
546 </form>
547 {{/html}}
548
549 = Tips =
550
551 == Other useful CSS classes ==
552
553 * Read about [[Special CSS classes>>platform:DevGuide.SpecialCSSClasses]] that can be used for forms elements.
554
555 == LiveValidation ==
556
557 * [[XWIKI-4792>>https://jira.xwiki.org/browse/XWIKI-4792]]: Add javascript LiveValidation input validation library
558
559 == Captchas ==
560
561 * [[Captcha Module>>extensions:Extension.Captcha Module]]
562
563 == WCAG ==
564
565 * A form created within XWiki must be validated accordingly with the WCAG rules. There are some [[exceptions>>dev:Community.WCAGTesting]] stated for XWiki.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected