Skip to Content

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