Forms Standards: Vertical Layout

Last modified by Lucas Charpentier (Sereza7) on 2024/03/26
Content

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.

  • Forms Layout Type:
    • Vertical Layout (xform): uses a dl-dt-dd structure.
    • Inline Layout  (xformInline).

This classes implementation has been voted at [Vote] [Standards] Forms: Usage + Documentation page to XWiki.org and implemented in XSCOLIBRI-260.

Usage

  • Obs: the CSS classes have as a 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).
 Tag Type Size ClassesUsage
Required      Optional       Container  
form                       .xform     .half, .third                    Container for the form controls
label                                                     dt                  Descriptive label for the control
span                       .xRequired                 dt label            Displays the required status of a control
a                          .xHelp                     dt                  Attach a link to external documentation about a control
span                       .xHint                     dt                  Attach hint information to a control
span                       .xErrorMsg                 dt                  Alert or error information for the control
input     hidden                                                               
input 

text
Since 12.10: color, date, datetime-local, email, number, search, tel, time

size=60   .disabled   dd                   
.xErrorFielddd                  Alert or error triggering control
input password size=60  .disabled   dd                   
.xErrorFielddd                  Alert or error triggering control
input     radio                                                                
input     checkbox                                                             
input     submit           .button    .secondary .disabledspan.buttonwrapperButton controls
input     button           .button    .secondary .disabledspan.buttonwrapperButton controls
a                          .button    .secondary .disabledspan.buttonwrapperButton controls
textarea  rows=7 cols=45                                       
.xErrorFielddd                  Alert or error triggering control
select             size=1                                                      
fieldset                                                                       
legend                                                                         

Components

1. Labels

  • This element provides a descriptive label for the containing form control.
  • Obs.1: Use uppercase ('UPPERCASE') bold fonts for input field labels [ title case ('Title Case') in the translation keys] 
  • Obs.2: Do not use colons(:) at the end of labels

[preview]

label.png

[html]

<form action="." class="xform" method="post" name="form_name1">
    <dl>
      <dt>
        <label for="input_id1">Label</label>
      </dt>
      <dd>
        <input id="input_id1" name="input_name1" type="text" size="60" value=""/>
      </dd>
    </dl>
    <p>
      <span class="buttonwrapper">
        <input class="button" type="submit" value="Button"/>
      </span>
    </p>
</form>

[demo]

[css]

.xform input[type="text" size="60"], .xform input[type="password"],
.xform select, .xform textarea{
 width: 99%;
}

.xform dt {
 margin-top: 1.2em;
}

.xform label {
 color: $theme.textColor;
 display: block;
 font-size: .85em;
 font-weight: 700;
 margin-bottom: .3em;
 text-transform: uppercase;
}

2. Required

  • This element displays the required status of a form control. 

[preview]

required.png

[html]

<label for="input_id2">Label <span class="xRequired">(Required)</span></label>

[demo]

[css]

.xform .xRequired {
 color: $theme.textSecondaryColor;
 font-size: .9em;
 font-style: italic;
 font-weight: normal;
 margin-left: 1ex;
 text-transform: none;
}

[translation]

core.validation.required=(Required)

3. Help

  • This element displays an icon pointing to some external documentation about a specific field.

[preview]

help.png

[html]

<dt>
  <label for="input_id3">Label</label>
  <a class="xHelp" title="Documentation" href="#">Documentation</a>
</dt>

[demo]

Documentation

[css]

.xform .xHelp {
 background: transparent url("$xwiki.getSkinFile('icons/silk/information.gif')") left top no-repeat;
 float: right;
 height: 16px;
 line-height: 250px;
 margin-right: 1px;
 margin-top: -20px;
 overflow: hidden;
 text-align: left !important;
 width: 16px;
}

4. Hint

  • This element provides a convenient way to attach hint information to a form control. 

[preview]

hint.png

[html]

<dt>
  <label for="input_id3">Label</label>
  <span class="xHint">Hint</span>
</dt>

[demo]

Hint

[css]

.xform .xHint {
 color: $theme.textSecondaryColor;
 display: block;
 font-size: .8em;
 font-style: normal;
 font-weight: 400;
 margin-bottom: .3em;
}

5. Error

  • This element provides a convenient way to attach alert or error information to a form control.

[preview]

error.png

[html]

    <dl>
      <dt>
        <label for="input_id5">Label</label>
        <span class="xHint">Hint</span>
        <span class="xErrorMsg">Error</span>
      </dt>
      <dd>
        <input class="xErrorField" id="input_id5" name="input_name5" type="text" size="60" value=""/>
      </dd>
    </dl>

[demo]

Hint Error

[css]

.xform .xErrorMsg {
 color: #CC3333;
 display: block;
 font-size: .8em;
 font-weight: normal;
 margin-bottom: .3em;
}

.xform .xErrorField {
 border: 1px solid #CC3333;
}

6. Buttons

  • Group multiple buttons in a .buttons div

[preview]

buttons.png

[html]

  • Use an additional .buttonwrapper class span container to surround button elements 
   <div class="buttons">
      <span class="buttonwrapper">
        <input class="button" type="submit" value="Button"/>
      </span>
      <span class="buttonwrapper">
        <a href="." class="button">Link</a>
      </span>
      <span class="buttonwrapper">
        <input class="button secondary" type="submit" value="Secondary Button"/>
      </span>
       <span class="buttonwrapper">
        <a href="." class="button secondary">Secondary Link</a>
      </span>
   </div>

[demo]

Link Secondary Link

[css]

.buttonwrapper and .button (.secondary) classes are described in colibri.css

7. Disabling

  • Use the .disabled class if you want to have disabled input elements

[preview]

disabledElements.png

[html]

  <dd>
    <input type="text" class="disabled" disabled="disabled" ... />
  </dd>
...
  <span class="buttonwrapper">
    <input type="submit" class="button" value="Primary" ... />
  </span>
  <span class="buttonwrapper">
    <input type="submit" class="button disabled" disabled="disabled" value="Primary Disabled" ... />
  </span>
  <span class="buttonwrapper">
    <input type="submit" class="button secondary" value="Secondary" ... />
  </span>
  <span class="buttonwrapper">
    <input type="submit" class="button secondary disabled" disabled="disabled" value="Primary Disabled" ... />
  </span>
...
  <span class="buttonwrapper">
    <a href="." class="secondary button disabled" ... >Secondary Disabled</a>
  </span>

8. Grouping

  • Grouping can be done by using fieldset/legend or other markup (like headers)

[preview]

grouping.png

[html]

 <h2>Group 1</h2>

[demo]

Group 1

Group 2

[css]

.xform h2 {
 font-size: 1.2em;
 font-weight: bold;
 margin: 2em 0 0;
}

Form Examples

[preview]

example.png

[demo]

Type the text you want to be displayed in the browser's title bar
Index only elements that are not already indexed
Configure if annotations are available for the current wiki

Tips

Other useful CSS classes

LiveValidation

  • XWIKI-4792: Add javascript LiveValidation input validation library 

Captchas

WCAG

  • A form created within XWiki must be validated accordingly with the WCAG rules. There are some exceptions 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