Skip to Content

Version 7.16 by Sergiu Dumitriu on 2011/03/10
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.
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 | | |dd |\\
30 | | | | |##.xErrorField##|dd |Alert or error triggering control\\
31 |input | password |size=60 | | |dd |\\
32 | | | | |##.xErrorField##|dd |Alert or error triggering control\\
33 |input | radio | | | | |\\
34 |input | checkbox | | | | |\\
35 |input | submit | |##.button## |##.secondary## |span##.buttonwrapper##|Button controls\\
36 |input | button | |##.button## |##.secondary## |span##.buttonwrapper##|Button controls\\
37 |a | | |##.button## |##.secondary## |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_name">
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 classes are described in colibri.css
396
397 {{code language="css"}}
398 .buttonwrapper input.secondary, .buttonwrapper a.secondary {
399 background-color: $theme.buttonSecondaryBackgroundColor;
400 color: $theme.buttonSecondaryTextColor;
401 }
402 {{/code}}
403
404 === 7. Grouping ===
405
406 * Grouping can be done by using fieldset/legend or other markup (like headers)
407
408 ==== [preview] ====
409
410 [[image:grouping.png]]
411
412 ==== [html] ====
413
414 {{code language="html"}}
415 <h2>Group 1</h2>
416 {{/code}}
417
418 ==== [demo] ====
419
420 {{html clean="false"}}
421 <form action="." class="xform" method="post" name="form_name10">
422 <h2>Group 1</h2>
423 <dl>
424 <dt>
425 <label for="input_id10">Label</label>
426 </dt>
427 <dd>
428 <input id="input_id10" name="input_name10" type="text" size="60" value=""/>
429 </dd>
430 </dl>
431 <h2>Group 2</h2>
432 <dl>
433 <dt>
434 <label for="input_id11">Label</label>
435 </dt>
436 <dd>
437 <input id="input_id11" name="input_name11" type="text" size="60" value=""/>
438 </dd>
439 </dl>
440 <p>
441 <span class="buttonwrapper">
442 <input class="button" type="submit" value="Button"/>
443 </span>
444 </p>
445 </form>
446 {{/html}}
447
448 ==== [css] ====
449
450 {{code language="css"}}
451 .xform h2 {
452 font-size: 1.2em;
453 font-weight: bold;
454 margin: 2em 0 0;
455 }
456 {{/code}}
457
458 == C. Form Examples ==
459
460 === [preview] ===
461
462 [[image:example.png]]
463
464 === [demo] ===
465
466 {{html clean="false"}}
467 <form action="." class="xform" method="post" name="form_name7">
468 <dl>
469 <dt>
470 <label for="input_id7">Browser Title Bar Text <span class="xRequired">(Required)</span></label>
471 <span class="xHint">Type the text you want to be displayed in the browser's title bar</span>
472 </dt>
473 <dd>
474 <input id="input_id7" name="input_name7" type="text" size="60" value=""/>
475 </dd>
476 <dt>
477 <label for="checkbox_id1"><input type="checkbox" name="checkbox_id1"/> Standard Index</label>
478 <span class="xHint">Index only elements that are not already indexed</span>
479 </dt>
480 <dt>
481 <label for="select_id1">Show Left Panels</label>
482 </dt>
483 <dd>
484 <select id="select_id1" size="1">
485 <option value="" label="---">---</option>
486 <option value="1" label="Yes">Yes</option>
487 <option selected="selected" value="0" label="No">No</option>
488 </select>
489 </dd>
490 <dt>
491 <label>Activate annotations</label>
492 <span class="xHint">Configure if annotations are available for the current wiki</span>
493 </dt>
494 <dd>
495 <label for="radio_id1">
496 <input type="radio" value="1" name="radio_name1" id="radio_id1" checked="checked"/>
497 Yes
498 </label>
499 <label for="radio_id2">
500 <input type="radio" value="0" name="radio_name1" id="radio_id2"/>
501 No
502 </label>
503 </dd>
504 <dt>
505 <label for="textarea_id1">HTTP Meta Information</label>
506 </dt>
507 <dd>
508 <textarea id="textarea_id1" rows="7" cols="45">Text</textarea>
509 </dd>
510 </dl>
511 <p>
512 <span class="buttonwrapper">
513 <input class="button" type="submit" value="Button"/>
514 </span>
515 <span class="buttonwrapper">
516 <input class="secondary button" type="submit" value="Secondary Button"/>
517 </span>
518 </p>
519 </form>
520 {{/html}}
521
522 == D. Tips ==
523
524 === D1. Other useful CSS classes ===
525
526 * Read about [[Special CSS classes>>DevGuide.SpecialCSSClasses]] that can be used for forms elements.
527
528 === D2. LiveValidation ===
529
530 * [[XWIKI-4792>>http://jira.xwiki.org/jira/browse/XWIKI-4792]]: Add javascript LiveValidation input validation library
531
532 === D3. Captchas ===
533
534 * http://code.xwiki.org/xwiki/bin/view/Modules/CaptchaModule
535
536 === D4. WCAG ===
537
538 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