Skip to Content

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