Skip to Content

Version 5.1 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 label |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 ==== [css] ====
187
188 {{code language="css"}}
189 .xform .xHelp {
190 background: transparent url("$xwiki.getSkinFile('icons/silk/information.gif')") center no-repeat;
191 float: right;
192 height: 16px;
193 line-height: 250px;
194 overflow: hidden;
195 width: 16px;
196 }
197 {{/code}}
198
199 === 4. Hint ===
200
201 * This element provides a convenient way to attach hint information to a form control.
202
203 ==== [preview] ====
204
205 [[image:hint.png]]
206
207 ==== [html] ====
208
209 {{code language="html"}}
210 <dt>
211 <label for="input_id3">Label</label>
212 <span class="xHint">Hint</span>
213 </dt>
214 {{/code}}
215
216 ==== [demo] ====
217
218 {{html clean="false"}}
219 <form action="." class="xform" method="post" name="form_name3">
220 <dl>
221 <dt>
222 <label for="input_id3">Label</label>
223 <span class="xHint">Hint</span>
224 </dt>
225 <dd>
226 <input id="input_id3" name="input_name3" type="text" size="60" value=""/>
227 </dd>
228 </dl>
229 <p>
230 <span class="buttonwrapper">
231 <input class="button" type="submit" value="Button"/>
232 </span>
233 </p>
234 </form>
235 {{/html}}
236
237 ==== [css] ====
238
239 {{code language="css"}}
240 .xform .xHint {
241 color: $theme.textSecondaryColor;
242 display: block;
243 font-size: .8em;
244 font-style: normal;
245 font-weight: 400;
246 margin-bottom: .3em;
247 }
248 {{/code}}
249
250 === 5. Error ===
251
252 * This element provides a convenient way to attach alert or error information to a form control.
253
254 ==== [preview] ====
255
256 [[image:error.png]]
257
258 ==== [html] ====
259
260 {{code language="html"}}
261 <dl>
262 <dt>
263 <label for="input_id5">Label</label>
264 <span class="xHint">Hint</span>
265 <span class="xErrorMsg">Error</span>
266 </dt>
267 <dd>
268 <input class="xErrorField" id="input_id5" name="input_name5" type="text" size="60" value=""/>
269 </dd>
270 </dl>
271 {{/code}}
272
273 ==== [demo] ====
274
275 {{html clean="false"}}
276 <form action="." class="xform" method="post" name="form_name5">
277 <dl>
278 <dt>
279 <label for="input_id5">Label</label>
280 <span class="xHint">Hint</span>
281 <span class="xErrorMsg">Error</span>
282 </dt>
283 <dd>
284 <input class="xErrorField" id="input_id5" name="input_name5" type="text" size="60" value=""/>
285 </dd>
286 </dl>
287 <p>
288 <span class="buttonwrapper">
289 <input class="button" type="submit" value="Button"/>
290 </span>
291 </p>
292 </form>
293 {{/html}}
294
295 ==== [css] ====
296
297 {{code language="css"}}
298 .xform .xErrorMsg {
299 color: #CC3333;
300 display: block;
301 font-size: .8em;
302 font-weight: normal;
303 margin-bottom: .3em;
304 }
305
306 .xform .xErrorField {
307 border: 1px solid #CC3333;
308 }
309 {{/code}}
310
311 === 6. Buttons ===
312
313 * Group multiple buttons in a ##.buttons## div
314
315 ==== [preview] ====
316
317 [[image:buttons.png]]
318
319 ==== [html] ====
320
321 * Use an additional ##.buttonwrapper## class span container to surround button elements
322
323 {{code language="html"}}
324 <div class="buttons">
325 <span class="buttonwrapper">
326 <input class="button" type="submit" value="Button"/>
327 </span>
328 <span class="buttonwrapper">
329 <a href="." class="button">Link</a>
330 </span>
331 <span class="buttonwrapper">
332 <input class="button secondary" type="submit" value="Secondary Button"/>
333 </span>
334 <span class="buttonwrapper">
335 <a href="." class="button secondary">Secondary Link</a>
336 </span>
337 </div>
338 {{/code}}
339
340 ==== [demo] ====
341
342 {{html clean="false"}}
343 <form action="." class="xform" method="post" name="form_name6">
344 <dl>
345 <dt>
346 <label for="input_id6">Label</label>
347 </dt>
348 <dd>
349 <input id="input_id6" name="input_name6" type="text" size="60" value=""/>
350 </dd>
351 </dl>
352 <p class="buttons">
353 <span class="buttonwrapper">
354 <input class="button" type="submit" value="Button"/>
355 </span>
356 <span class="buttonwrapper">
357 <a href="." class="button">Link</a>
358 </span>
359 <span class="buttonwrapper">
360 <input class="button secondary" type="submit" value="Secondary Button"/>
361 </span>
362 <span class="buttonwrapper">
363 <a href="." class="button secondary">Secondary Link</a>
364 </span>
365 </p>
366 </form>
367 {{/html}}
368
369 ==== [css] ====
370
371 .buttonwrapper and .button classes are described in colibri.css
372
373 {{code language="css"}}
374 .buttonwrapper input.secondary, .buttonwrapper a.secondary {
375 background-color: $theme.buttonSecondaryBackgroundColor;
376 color: $theme.buttonSecondaryTextColor;
377 }
378 {{/code}}
379
380 === 7. Grouping ===
381
382 * Grouping can be done by using fieldset/legend or other markup (like headers)
383
384 ==== [preview] ====
385
386 [[image:grouping.png]]
387
388 ==== [html] ====
389
390 {{code language="html"}}
391 <h2>Group 1</h2>
392 {{/code}}
393
394 ==== [demo] ====
395
396 {{html clean="false"}}
397 <form action="." class="xform" method="post" name="form_name10">
398 <h2>Group 1</h2>
399 <dl>
400 <dt>
401 <label for="input_id10">Label</label>
402 </dt>
403 <dd>
404 <input id="input_id10" name="input_name10" type="text" size="60" value=""/>
405 </dd>
406 </dl>
407 <h2>Group 2</h2>
408 <dl>
409 <dt>
410 <label for="input_id11">Label</label>
411 </dt>
412 <dd>
413 <input id="input_id11" name="input_name11" type="text" size="60" value=""/>
414 </dd>
415 </dl>
416 <p>
417 <span class="buttonwrapper">
418 <input class="button" type="submit" value="Button"/>
419 </span>
420 </p>
421 </form>
422 {{/html}}
423
424 ==== [css] ====
425
426 {{code language="css"}}
427 .xform h2 {
428 font-size: 1.2em;
429 font-weight: bold;
430 margin: 2em 0 0;
431 }
432 {{/code}}
433
434 == C. Form Examples ==
435
436 === [preview] ===
437
438 [[image:example.png]]
439
440 === [demo] ===
441
442 {{html clean="false"}}
443 <form action="." class="xform" method="post" name="form_name7">
444 <dl>
445 <dt>
446 <label for="input_id7">Browser Title Bar Text <span class="xRequired">(Required)</span></label>
447 <span class="xHint">Type the text you want to be displayed in the browser's title bar</span>
448 </dt>
449 <dd>
450 <input id="input_id7" name="input_name7" type="text" size="60" value=""/>
451 </dd>
452 <dt>
453 <label for="checkbox_id1"><input type="checkbox" name="checkbox_id1"/> Standard Index</label>
454 <span class="xHint">Index only elements that are not already indexed</span>
455 </dt>
456 <dt>
457 <label for="select_id1">Show Left Panels</label>
458 </dt>
459 <dd>
460 <select id="select_id1" size="1">
461 <option value="" label="---">---</option>
462 <option value="1" label="Yes">Yes</option>
463 <option selected="selected" value="0" label="No">No</option>
464 </select>
465 </dd>
466 <dt>
467 <label>Activate annotations</label>
468 <span class="xHint">Configure if annotations are available for the current wiki</span>
469 </dt>
470 <dd>
471 <label for="radio_id1">
472 <input type="radio" value="1" name="radio_name1" id="radio_id1" checked="checked"/>
473 Yes
474 </label>
475 <label for="radio_id2">
476 <input type="radio" value="0" name="radio_name1" id="radio_id2"/>
477 No
478 </label>
479 </dd>
480 <dt>
481 <label for="textarea_id1">HTTP Meta Information</label>
482 </dt>
483 <dd>
484 <textarea id="textarea_id1" rows="7" cols="45">Text</textarea>
485 </dd>
486 </dl>
487 <p>
488 <span class="buttonwrapper">
489 <input class="button" type="submit" value="Button"/>
490 </span>
491 <span class="buttonwrapper">
492 <input class="secondary button" type="submit" value="Secondary Button"/>
493 </span>
494 </p>
495 </form>
496 {{/html}}
497
498 == D. Tips ==
499
500 === D1. Other useful CSS classes ===
501
502 * Read about [[Special CSS classes>>DevGuide.SpecialCSSClasses]] that can be used for forms elements.
503
504 === D2. LiveValidation ===
505
506 * [[XWIKI-4792>>http://jira.xwiki.org/jira/browse/XWIKI-4792]]: Add javascript LiveValidation input validation library
507
508 === D3. Captchas ===
509
510 * http://code.xwiki.org/xwiki/bin/view/Modules/CaptchaModule
511
512 === D4. WCAG ===
513
514 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