Formee

Formee eases and helps out to build html forms designs, and also validates its data from both client-side and server-side based on model validation annotations.

Features

- It has all the features of formee
- A form wraps an single model
- Automate validations from client-side based on Play model annotations by using jquery.validate plugin.
- Homogeneous error messages from both client-side and server-side, i.e., they appear in the same place.

This play! module it’s designed to work with model objects, don’t expect correct behavior if used objects that are not extends from Model.

Getting started

- Add this module to your dependecy.yml file
- This module depends on jQuery library, but play! comes with it, just ensure you don’t delete it.

Usage

Include the following files in your views containing forms:

- stylesheets:

formee/formee-structure.css
formee/formee-structure-ext.css
formee/formee-style.css

- javascripts:

formee/formee-validate.js
formee/formee-equal-height.js

The formee-validate.js script contains copies of the [jQuery Validation Plugin] and the [jQuery Metadata Plugin]

The forme-equal-height.js scripts makes all input elements, within form which class equals “formee”, have the same height.

Configure

Configuration for the convention naming case of object models (variables) passing through Controllers to Templates and vice versa.

formee.namingCase

There are two options:

camelCase
underscore_case

In case this property is not provided, then by default the naming case will be camelCase

camelCase examples:

Model Name	Variable Name
Model	model
ModelEntity	modelEntity
Model_Entity	model_Entity
Model4Entity	model4Entity
Model_4_Entity	model_4_Entity
CModelEntity	cModelEntity

underscore_case examples:

Model Name	Variable Name
Model	model
ModelEntity	model_entity
Model_Entity	model_entity
Model4Entity	model_4_entity
Model_4_Entity	model_4_entity
CModelEntity	c_model_entity

Internationalisation Messages

The Internationalisation structure is as follows:

package.Model.field

E.g.,

models.Author.age=Age

# Validation messages for @Unique is missing in Play!, so you have to include it on you own messages file.
E.g.,
validation.unique=Already exists

Fast Tags

First things first, every standard attribute that supports a html tag not listed here is optional.

formee.clear

The formee.clear tag generates a div element for breaking floating elements.

Params:

height (optional) - the div height in pixels.

Tag

#{formee.clear height:15/}

#{formee.clear /}

Html

<div class="clear" style="height:15px;"></div>

<div class="clear"></div>

formee.hbox

The formee.hbox tag generates a div element for containing more elements aligned horizontally.

grid (required) - the number of columns for the div width. See formee framework specification.

Tag

#{formee.hbox grid:6}
...
#{/formee.hbox}

Html

<div class="hbox grid-6-12>
...
</div>

formee.vbox

The formee.vbox tag generates a div element for containing more elements aligned vertically.

grid (required) - the number of columns for the div width. See formee framework specification.

Tag

#{formee.vbox grid:3}
...
#{/formee.3box}

Html

<div class="vbox grid-3-12>
...
</div>

formee.form (HTML4)

The formee.form tag is identical to the built-in Play form tag except it outputs some JavaScript that prepares the form to be validated by the jQuery validation plugin.

Keep in mind this tag only wraps a single model object, in other words, doesn’t manage multiple model objects nor simple unencapsulated values.
At any rate, you could use class composition and @Transient annotation.
So don’t say I didn’t warn you!!!

Params:

arg (the implicit required argument) - action to be invoked after submitting.
obj (required) - model object from which the form will get the values either for editing or adding (after error submitting, so that the user doesn’t have to fill every correct value again).
method (optional) - if not specified POST by default
enctype (optional) - determines how the form data is encoded. Whenever data is transmitted from one place to another, there needs to be an agreed upon means of representing that data. Music is translated into written music notation, English is written using letters and punctuation.

In most cases you will not need to use this attribute at all. The default value (i.e. if you don’t use this attribute at all) is “application/x-www-form-urlencoded”, which is sufficient for almost any kind of form data. The one exception is if you want to do file uploads. In that case you should use “multipart/form-data”.

Either for adding/creating or editing/updating, formee.tag requires and object model.

E.g.,


public MyController extends Controller {
    public static void add() {
        Model model = new Model();
        render(model);
    }
    public static void edit(Long id) {
        MyModel model = MyModel.findById(id);
        if (model == null) {
            notFound();
        } else {
            render(model);
        }
    }
}

In case of editing, don’t forget to put the model id into a hidden element.
#{formee.hidden for:“package.Model.id” /}

Tag

#{formee.form @Controller.action(), obj:model}
    ...
#{/formee.form}

Html

<form action="/route/to/action" method="post" accept-charset="utf-8" enctype="application/x-www-form-urlencoded" class="formee" >
    <input type="hidden" name="authenticityToken" value="...">
    ...
</form>

formee.field

The formee.field tag is identical to the built-in Play field tag except it puts two extra properties on the field:

field.validationData You need to put this data in an HTML5 data attribute called data-validate on your input, select, or textarea element.
field.for The full qualified name of a field, i.e. package.Model.field

Params:

arg (implicit optional argument) - name of the model object
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.field for:'package.Model.field'}
    <label>&{field.name}</label>
    <input type="text" data-validate="${field.validationData}" id="${field.id}" name="${field.name}" value="${field.value}" class="${field.errorClass}">
    <span class="error">${field.error}</span>
#{/formee.field}

Html

<label>...</label>
<input type="text" data-validate={...} id="model_object_field_name" name="model_object.field_name" value="..." class="..."/>
<span class="error">...</span>

formee.label (HTML4)

The formee.label tag simplifies the creation of label element...

Params:

arg (the implicit optional argument) - name of the model object.
msg (optional) - label text.
for (optional) - full qualified name of a field, i.e. package.Model.field
required (optional) - boolean value to indicate, visually, if it’s required.

See notes.

Tag

#{formee.label for:'package.Model.field', required:true /}

Html

<label>First name<em class='formee-req'>*</em></label>

formee.error (HTML4)

The formee.error tag is very similar to the built-in Play error tag except it wraps the error message into a span element and outputs some JavaScript that prepares the element to be used by the jQuery validation plugin.
It’s highly recommended to use it in conjunction with built-in Play error tag.

Params:
for (required) - full qualified name of a field, i.e. package.Model.field

Tag

#{formee.error for:'package.Model.field' }#{error 'object.field' /}#{/formee.error}

Html

<span for='input_element_id' class='error' generated='true'>...</span>

formee.input (HTML4)

The formee.input tag generates any input type: text, textarea, password, hidden, checkbox, radio, "checkbool":#checkbool.

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field
type (optional) - input type, if not provided or is not valid, then ‘text’ is used.

See notes.

Tag

#{formee.input for:'package.Model.field', type:'text' /}

Html

<input type="text" data-validate="{...}" class id="model_field" name="model.field" value/>

formee.text (HTML4)

The formee.text tag generates an input element of type text

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.text for:'package.Model.field' /}

Html

<input type="text" data-validate="{...}" class id="model_field" name="model.field" value/>

formee.textarea (HTML4)

The formee.textarea tag generates an input element of type text

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.textarea for:'package.Model.field' /}

Html

<textarea data-validate="{...}" class id="model_field" name="model.field">...</textarea>

formee.password (HTML4)

The formee.password tag generates an input element of type password

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.password for:'package.Model.field' /}

Html

<input type="password" data-validate="{...}" class id="model_field" name="model.field" value/>

formee.hidden (HTML4)

The formee.hidden tag generates an input element of type hidden

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.hidden for:"package.Model.field" /}

Html

<input type="hidden" name="model.field" value/>

formee.checkbool (HTML4)

The formee.checkbool tag is useful for representing a boolean value as a checkbox.

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.checkbool for:"package.Model.field" /}

Html

<input type='checkbox' data-validate='{}' class='' id='model_field' name='author.mastermind' value='true' />
<input type='hidden' name='author.mastermind' value='false'/>

formee.timestamp (HTML4)

The formee.timestamp tag is useful just for formatting @Temporal (DATE, TIME & TIMESTAMP) fields when editing a record.
The pattern date is gotten from @As(value=“...”) annotation, if there’s no such annotation, then the pattern is gotten from date.format from application.conf

If pattern date fails to be obtained, then the default pattern is: yyyy-MM-dd

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field

See notes.

Tag

#{formee.timestamp for:"package.Model.field" /}

Html

<input type="text" data-validate="{...}" class id="model_field" name="model.field" value/>

formee.selectList (HTML4)

The formee.selectList generates a select element containing a set of option elements.

This tag is more useful for a field that requires a value from a Catalog, therefore the binding must be single object/primitive.
The annotation validation that makes more sense for this tag is @Required

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field
items (required) - a Collection of Objects (not necessarily Models), each item will be an option.
valueProperty (required) - the Item field from which the value will be retrieved.
labelProperty (required) - the Item field from which the label will be named.
supplementaryLabelProperty (optional) - the Item field from which a supplementary label will be named.

In case supplementaryLabelProperty is used, the option element will be formed as follows:
<option>label - supplementaryLabel</option>

See notes.

Tag

#{formee.selectList for:“package.Model.field”, items:collection, valueProperty:“id”, labelProperty:“name”/}

Html

<select data-validate="..." class="" id="model_field_id" name="model.field">
    <option></option>
    <option value="1">Option1</option>
    <option value="2">Option2</option>
    ...
    <option value="n">OptionN</option>
</select>

formee.checkboxList (HTML4)

The formee.checkboxList generates a group of checkbox elements organized in an ul element.

This tag is more useful for a field that requires one or mores values from a Catalog, therefore the binding must be collection/array of objects/primitives.

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field
items (required) - a Collection of Objects (not necessarily Models), each item will be a checkbox.
valueProperty (required) - the Item field from which the value will be retrieved.
labelProperty (required) - the Item field from which the label will be named.

See notes.

Tag

#{formee.checkboxList for:“package.Model.field”, items:collection, valueProperty:“id”, labelProperty:“name”/}

Html

<ul class="formee-list">
    <li><input type="checkbox" data-validate="..." name="model.field" id="model.field.0" value="0"><label for="model.field.0">Option1</label></li>
    <li><input type="checkbox" name="model.field" id="model.field.1" value="1"><label for="model.field.1">Option1</label></li>
    ...
    <li><input type="checkbox" name="model.field" id="model.field.n" value="n"><label for="model.field.n">OptionN</label></li>
</ul>

formee.radioList (HTML4)

The formee.radioList generates a group of radio elements organized in an ul element.

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field
items (required) - a Collection of Objects (not necessarily Models), each item will be a radio.
valueProperty (required) - the Item field from which the value will be retrieved.
labelProperty (required) - the Item field from which the label will be named.

See notes.

Tag

#{formee.radioList for:“package.Model.field”, items:collection, valueProperty:“id”, labelProperty:“name”/}

Html

<ul class="formee-list">
    <li><input type="radio" data-validate="..." name="model.field" id="model.field.0" value="0"><label for="model.field.0">Option1</label></li>
    <li><input type="radio" name="model.field" id="model.field.1" value="1"><label for="model.field.1">Option1</label></li>
    ...
    <li><input type="radio" name="model.field" id="model.field.n" value="n"><label for="model.field.n">OptionN</label></li>
</ul>

formee.submit (HTML4)

The formee.submit generates an input element of type submit.

Params:

value (optional) - visual name of the input. If not provided, the web browser creates a default value.

This tag will try to get an internationalized message based on the value provided and the messages file.

Tag

#{formee.submit value:"Create" /}

#{formee.submit value:"views.model.create.submit" /}

Html

<input type="submit" value="Create">

formee.reset (HTML4)

The formee.reset generates an input element of type reset.

Params:

value (optional) - visual name of the input. If not provided, the web browser creates a default value.

This tag will try to get an internationalized message based on the value provided and the messages file.

Tag

#{formee.reset value:"Clear" /}

#{formee.reset value:"views.model.reset" /}

Html

<input type="reset" value="Clear">

Notes

If for is not provided, an exception is thrown.

If arg is not provided, then, by convention, the name of the model object will be the model name converted to underscore_case

Provide arg if the name of model object being passed to a template doesn’t follow the underscore_case convention.

Slow Tags

formee.h_box

The formee.h_box tag generates label, an input and a span (for error messages) aligned horizontally and wrapped by a div element.

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field
type (optional) - input type, if this is not provided or is not valid, then ‘text’ is used.
value (optional) - field value, if this is not provided, then the default value from model is used. When creating a record, it’s useful as a suggested value.
label_grid (required) - the number of columns for placing the label. See formee framework specification.
input_grid (required) - the number of columns for placing the input. See formee framework specification.
required (optional) - boolean value to indicate, visually, if it’s required.

Tag

#{formee.h_box for:"package.Model.field", type:'text', value:val, label_grid:3, input_grid:4, required:true /}

Html

<div class="h-block grid-12-12 ">
    <div class="grid-3-12">
        <label for='model_field' required="true" >Field name<em class='formee-req'>*</em></label>
    </div>
    <div class="grid-4-12">
        <input type='text' data-validate='{...}' class='' id='model_field' name='model.field' value=''  />
        <span class='error' for='model_field' generated='true'></span>
    </div>
</div>

formee.v_box

The formee.v_box tag generates label, an input and a span (for error messages) aligned vertically and wrapped by a div element.

Params:

arg (implicit optional argument) - name of the model object.
for (required) - full qualified name of a field, i.e. package.Model.field
type (optional) - input type, if this is not provided or is not valid, then ‘text’ is used.
value (optional) - field value, if this is not provided, then the default value from model is used. When creating a record, it’s useful as a suggested value.
grid (required) - the number of columns for placing the elements (label, input, and span). See formee framework specification.
required (optional) - boolean value to indicate, visually, if it’s required.

Tag

#{formee.v_box for:'package.Model.field', type:'text', value:val, grid:4, required:true /}

Html

<div class="v-block grid-4-12 ">
     <label for='model_field' required="true" >Field name<em class='formee-req'>*</em></label>
    <input type='text' data-validate='{...}' class='' id='model_field' name='model.field' value=''  />
    <span class='error' for='model_field' generated='true'></span>
</div>

formee.css

The formee.css tag generates three required style elements: formee-structure.css, formee-structure-ext.css and formee.stye.css

Tag

#{formee.css/}

Html

<link rel="stylesheet" type="text/css" href="/public/stylesheets/formee/formee-structure.css" charset="utf-8" ></link>
<link rel="stylesheet" type="text/css" href="/public/stylesheets/formee/formee-structure-ext.css" charset="utf-8" ></link>
<link rel="stylesheet" type="text/css" href="/public/stylesheets/formee/formee-style.css" charset="utf-8" ></link>

Supported Annotations

The module currently supports the following annotations:

Required
Email
Min
Max
Range
MinSize
MaxSize
URL
Unique, but only validated at server-side

Sample application

One sample demo is part of the distribution. Don’t forget to run play deps so that it resolves dependencies.

The demo was laid out using 52framework

TODO

Implement fast tags for HTML4 input types:

multipleSelectList

Implement validation for @As annotation from @Temporal fields

Implement a calendar input type

Implement fast tags for HTML5 input types:

search
tel
url
email
datetime
date
month
week
time
datetime-local
number
range
color

Implement validation via Ajax.

Implement secure password mechanism.

Include validation using jQuery.validationEngine plug-in.

Provide a formee-validate.js min VERSION

Credits

Author: Omar O. Román

Formee module is inpired and based on the following components:

- Formee framework by Bernard De Luna, Daniel Araujo, and Marcello Manso
- jqvalidate module by Michael Murray
- jqvalidation module by Ahmed Mahmoud Mohammed Abd El-wahab
- html5validate module by Sebastian Hoß
- jquery.validate plug-in by Jörn Zaefferer
- jquery.metadata plug-in by John Resig, Yehuda Katz, Jörn Zaefferer, Paul McLanahan
- 52framework by enavu network folks.

Community contributed extensions

Formee

Features

Getting started

Usage

Configure

Internationalisation Messages

Fast Tags

formee.clear

formee.hbox

formee.vbox

formee.form (HTML4)

formee.field

formee.label (HTML4)

formee.error (HTML4)

formee.input (HTML4)

formee.text (HTML4)

formee.textarea (HTML4)

formee.password (HTML4)

formee.hidden (HTML4)

formee.checkbool (HTML4)

formee.timestamp (HTML4)

formee.selectList (HTML4)

formee.checkboxList (HTML4)

formee.radioList (HTML4)

formee.submit (HTML4)

formee.reset (HTML4)

Notes

Slow Tags

formee.h_box

formee.v_box

formee.css

Supported Annotations

Sample application

TODO

Credits