Skip to content

Forms

Jump to bottom Edit New page
Mo Morsi edited this page Jan 9, 2013 · 2 revisions

Forms

Latest devel preview: http://convergeui-jcoufal.rhcloud.com/form

  • Part of Alchemy library
  • Currently prepared as a fallback with pure CSS without JS (will be added later to unify the look over browsers)
  • You are expected to use HTML5 input elements (file, email, password, date, number)
  • Supports responsive webdesign
  • SimpleForm should be used which takes care of generating the whole markup

Even if SimpleForm is recommended to generate forms, this wiki page shows both way (manually constructing the markup vs. using SimpleForm) how to implement forms in Conductor.

Either way, the forms must implement the following features apart its layout (which is described below):

  • mandatory fields must be denoted
  • a summary description for the validation constraints must be displayed in the hint section if the attribute is not in error state
  • attributes in error state must be denoted and the error message must be displayed in the hint section
  • HTML5 input tag attributes should be used where it makes sense (type, min, max, etc.)

Manually constructing the form markup

IMPORTANT: It is necessary to keep order of HTML elements!

Basic structure

<form class='form'>

  <div class='control_group'>

    <div class='label'>
      <label for='input_id'>Label</label>
    </div>

    <div class='input'>
      <input id='input_id' type='input_type'>
    </div>

  </div>

  <div class='control_group'>
    ...
  </div>
</form>

Types

Inputs

         
             
#### Checboxes
     …     
         **\
**

            

            

                     

    
Checkboxes are vertical as default, if you want horizontal ones, just add class.
#### Radios
     …     
         **\
**

            

            

                     

    
Radios are vertical as default, if you want horizontal ones, just add class.
### Features

Layout

  • - force to move labels to the top of an input
  • - force to move messages to the bottom of an input
  • - force to make the narrowest version of the form (width is according to input width)

Required field

Mark all required fields which need to be filled.

     …     
             
#### Informative text

If you don’t want to display value as an input. Displays value as normal text.

*

     …     
         **…**     
#### Read-only field

Use when you have a field, which user can never edit.

     …     
             
#### Disabled field

Use when you have a field, which can be enabled in future.

     …     
             
#### Label help

Text which works as helping attribute for label. Label name can stand for some difficult to understand term (e.g. realm), that’s why user needs some short explanation of the term (e.g. Realm is…)

     **?**      Label      **** Here will be placed explanatory information about concrete label term. ****
#### Placeholder

Classic HTML5 placeholder. Used mainly as helping aid what to fill in the text input field (e.g. “YYYY/MM/DD”).

  • <input id='input' placeholder='Placeholder' type='text'>

Note

Always visible note, which is situated under the input. Will never be hidden. Use it very rarely, just in really needed occasions, when you need to tell something important to user, what he needs to keep on his mind. (e.g. “Note:”

          ****          **Note:**          This is note, which is visible all the time. Can be longer than one line. Don’t use if not necessary.      ****
#### Hint

Text, which is helping user to fill the input. Usually input restrictions are filled in there (e.g. Password must containt at least 6 characters and one non-character symbol). Will be displayed only on input focus (if messages are not at bottom of input, then hint is display all the time).

          **** Fill in your given name. Maximum allowed length is up to 30 characters. (Hint length is max 2 lines) ****
You can force hint to be always visible by adding a class. *

IMPORTANT: Length is max 2 rows of text.

Validation messages

Used for field validations. We have three types:

** used for confirmations if necessary . **
** used rarely, just if there is vulnerable place, however user can continue **
** field is not filled and is required, field is filled incorrectly

Once validation message is displayed, hint is NOT displayed anymore, so be sure, that you navigate user how to recover from error in certain validation message.

**

     …     
         …          **** Message to display. ****
*IMPORTANT: Try to get the length at maximum of 2 rows.*

Buttons

Never forget to use Cancel button. Again, default Simple Form helper will take care for this. Styling is based on converge-ui styling for buttons (not for forms!)

    
    
                      
### Combining features

IT IS NECESSARY TO KEEP THE ORDER OF HTML ELEMENTS (not classes)

Structure (content in parentheses can be opt out):

.form
  .control_group(.required)(.informative)(.disabled)(.readonly)(.success/warning/error)(.checkbox)(.radio)(.horizontal)
    .label(.help)
      (i)
      label
      (span)
    .input
      input
      (message)
      (hint)
      (note)
      (span.value)

In HTML:

<form class='form'>

  <div class='control_group required error'>

    <div class='label help'>
      <i>?</i>
      <label for='input_id'>Label text</label>
      <span>Help text.</span>
    </div>

    <div class='input'>
      <input id='input' placeholder='Placeholder' type='text'/>
      <span class='message'>Message text</span>
      <span class='hint'>Hint text</span>
      <span class='note'><strong>Note:</strong>Note text.</span>
    </div>

  </div>
</form>

Generating forms with SimpleForm

SimpleForm is a tool to generate the markup based on its configuration. Its configuration file can be found at config/initializers/simple_form.rb. It contains among other things a wapper definition which describes the basic layout of each input. This definition will be used for generating html output for each attribute.

SimpleForm takes care of the following:

  • detects required attributes based on validation and adds the appropriate CSS class
  • in error state, displays the errors message and adds the appropriate CSS class
  • adds HTML5 input tag attributes like type, min, max

Example how to use it:

= conductor_form_for @user do |f|
  = form.input :first_name
  = form.input :last_name
  = form.fields_for :quota do |quota_form|
    = quota_form.input :maximum_running_instances

  = f.button :form_buttons, :cancel => users_path

For each input, the following options can be defined:

  • as: overrides the default input type
  • disabled
  • required: overrides the detected status which is based on ActiveRecod validators
  • label
  • placeholder
  • note: (instead of this option you should use simple_form dictionary)
  • hint: (instead of this option you should use simple_form dictionary)
  • help: (instead of this option you should use simple_form dictionary)

For notes, hints and helps you can also define the appropriate key in config/locales/simple_form/en.yml and SimpleForm will automatically pick it up.

SimpleForm comes with many input types. E.g.:

  • string input
  • text input
  • password input
  • numberic input
  • boolean input
  • file input
  • select input

For a basic overview and usage please read the SimpleForm readme: https://github.com/plataformatec/simple_form

Add a custom footer
Add a custom sidebar
Clone this wiki locally