-
Notifications
You must be signed in to change notification settings - Fork 27
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.)
IMPORTANT: It is necessary to keep order of HTML elements!
<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>
<div class='control_group'>
<div class='input'>
<input id='input_id' type='input_type'>
</div>
</div>
<div class='control_group *checkbox*'>
<div class='input'>
<div class=‘control’>
<input id='checkbox_id' type='checkbox'>
<input id='checkbox_id' type='checkbox'>
<input id='checkbox_id' type='checkbox'>
</div>
</div>
</div>
Checkboxes are vertical as default, if you want horizontal ones, just add class.
<div class='control_group checkbox *horizontal*'>
<div class='control_group *radio*'>
<div class='input'>
<divclass=‘control’>
<input id='radio_id' type='radio'>
<input id='radio_id' type='radio'>
<input id='radio_id' type='radio'>
</div>
</div>
</div>
Radios are vertical as default, if you want horizontal ones, just add class.
<div class='control_group radio *horizontal*'>
- - 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)
Mark all required fields which need to be filled.
<div class='control_group *required*'>
<div class='input'>
<input id='input_id' type='input_type' *required='required'*>
</div>
</div>
If you don’t want to display value as an input. Displays value as normal text.
<div class='control_group *informative*'>
<div class='input'>
<span class='value'></span>
</div>
</div>
Use when you have a field, which user can never edit.
<div class='control_group readonly'>
<div class='input'>
<input id='input_id' type='input_type' readonly='readonly'>
</div>
</div>
Use when you have a field, which can be enabled in future.
<div class='control_group *disabled*'>
<div class='input'>
<input id='input_id' type='input_type' *disabled='disabled'*>
</div>
</div>
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…)
<div class='label *help*'>
<i>?</i>
<label for='input_id'>Label</label>
<span> Here will be placed explanatory information about concrete label term.</span>
</div>
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'>
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:”
<div class='input'>
<input id='input' type='text'/>
<span class='note'>
<strong>Note:</strong>
This is note, which is visible all the time. Can be longer than one line. Don’t use if not necessary.
</span>
</div>
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).
<div class='input'>
<input id='input' type='text'/>
<span class='hint'> Fill in your given name. Maximum allowed length is up to 30 characters. (Hint length is max 2 lines)</span>
</div>
You can force hint to be always visible by adding a class.
IMPORTANT: Length is max 2 rows of text.
Used for field validations. We have three types:
<div class='control_group *success*'>
used for confirmations if necessary .
<div class='control_group *warning*'>
used rarely, just if there is vulnerable place, however user cancontinue
<div class='control_group *error*'>
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.
<div class='control_group *error*'>
<div class='input'>
<span class='message'>Message to display.</span>
</div>
IMPORTANT: Try to get the length at maximum of 2 rows.
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!)
<div class='control_group *buttons*'>
<div class='label'>
</div>
<div class='input'>
<input class='*btn primary*' type='submit' value='Save'>
<input class='*btn*' type='submit' value='Cancel'>
</div>
</div>
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>
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