Skip to Content

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