Grails Fields Plugin

Customizable form-field rendering based on overrideable GSP template

Version: 2.2.3

1 Introduction

The Fields plugin allows you to customize the rendering of input fields for properties of domain objects, command beans and POGOs based on their type, name, etc. The plugin aims to:

  • Use good defaults for fields.

  • Make it very easy to override the field rendering for particular properties or property types without having to replace entire form templates.

  • Not require you to copy and paste markup for containers, labels and error messages just because you need a different input type.

  • Support inputs for property paths of arbitrary depth and with indexing.

  • Enable other plugins to provide field rendering for special property types that gets picked up automatically (e.g. the Joda Time plugin can provide templates for the various date/time types).

  • Support embedded properties of GORM domain classes.

Changelog

Version 2.2.0

  • Conversion to the Mapping Context API. Usages of the GrailsDomainClass and GrailsDomainClassProperty classes have been removed. If you extend a template that relies on those classes, they have been replaced with PersistentEntity and DomainProperty respectively.

  • Conversion of constraints to a common implementation between grails.validation and grails.gorm.validation. See Constrained.

Version 2.1.4

  • Upgrade to Grails 3.2.8

  • Convert documentation to Asciidoc

Version 2.0

  • Redesign for Grails 3.0

Version 1.5

2015_04_26

See Usage and Customizing Field Rendering for breaking changes.

Version 1.4

  • Upgraded plugin to work with Grails 2.3.x (Issue #122)

  • Fixed missing property exception (Issue #134)

  • Fixed encoding in tag libraries (Issue #137)

  • Configuring caching in dev mode (Issue #139)

  • byte[] and Byte[] arrays types now look for files in byteArray folders (general for all array types) (Issue #144)

Version 1.3

2012-07-31

  • Adds the f:display tag.

  • Supports overriding templates by property type or by default in individual controllers and actions.

Browse issues Thanks to https://github.com/cdeszaq,[Rick Jensen] https://github.com/delight,[Konstantinos Kostarellis] Gus Power and Eliot Sykes for their contributions.

Version 1.2

2012-03-16

  • Pass attributes from f:field to the rendered input using input- prefix.

  • Optionally use entire property path for label key.

Browse issues Thanks to Brian Saville and OverZealous for contributions.

Version 1.1

2012-03-11

  • Adds the prefix attribute.

  • Support widget:'textarea' constraint.

Browse issues Thanks to Brian Saville for contributions.

Version 1.0.4

2012-02-13: Bugfix release.

Version 1.0.3

2012-02-09: Bugfix release.

Version 1.0.2

2012-02-07: Bugfix release.

Version 1.0.1

2012-02-03: Bugfix release.

Version 1

2012-02-01: Initial release.

2 Usage

The plugin provides a set of tags you can use to render the fields in a form.

In the simplest case you can use f:all to render a field for every property of a bean (the domain object or command the form will bind to):

<g:form>
    <f:all bean="person"/>
</g:form>

To render individual fields you use the f:field tag:

<g:form>
    <f:field bean="person" property="name"/>
    <f:field bean="person" property="address"/>
    <f:field bean="person" property="dateOfBirth"/>
</g:form>

The f:field tag will automatically handle embedded domain properties recursively:

<f:field bean="person" property="address"/>

If there is no bean object backing a form but you still want to render the surrounding field markup you can give f:field a body:

<f:field property="password">
    <g:password name="password"/>
</f:field>

It should be an unusual case but to render just the widget without its surrounding container you can use the f:widget tag:

<f:widget bean="person" property="name"/>

To make it more convenient when rendering lots of properties of the same bean you can use the f:with tag to avoid having to specify bean on any tags nested inside:

<g:form>
    <f:with bean="person">
        <f:field property="name"/>
        <f:field property="address"/>
        <f:field property="dateOfBirth"/>
    </f:with>
</g:form>

If you need to render a property for display purposes you can use f:display. It will internally use g:fieldValue, g:formatBoolean or g:formatDate to format the value.

<f:display bean="person" property="name"/>

If you need to render the value in a different way you can give f:display a body instead.

<f:display bean="person" property="dateOfBirth">
    <g:formatDate format="dd MMM yyyy" date="${value}"/>
</f:display>

By default f:display simply renders the property value but if you supply a \_display.gsp template you can render the value in some structured markup, e.g. a table cell or list item. See the Customizing Field Rendering section for how to override templates. For example to render values in a definition list you could use a template like this:

<dt>${label}</dt>
<dd>${value}</dd>

Extra attributes (Since version 2.1.4)

You can pass any number of extra attributes to the f:with and f:all tags that will be propagated to the inner fields and displays. See their individual tags sections for more information.

Breaking changes

Templates

The names of the templates were changed for more adequate ones: * _field to _wrapper * _input to _widget * _display to _displayWrapper * _displayWidget was added

To use the old names (for backwards compatibility), configure the following in Config.groovy

grails.plugin.fields.wrapper = "field"
grails.plugin.fields.displayWrapper = "display"
grails.plugin.fields.widget = "input"

Widget attributes

To pass additional attributes to widgets, prefix them with 'widget-'.

Example:

<f:field property="birthDate" widget-format="dd/MM/yyyy"/>

To use the old prefix (for backwards compatibility), configure the following in Config.groovy:

grails.plugin.fields.widgetPrefix = "input-"

Changes in tags

  • The input tag was deprecated because the name was confusing. Use the new widget tag instead.

  • The displayWidget tag was added. It outputs the widget for display purposes, without the wrapper (similar to the widget tag).

3 Customizing Field Rendering

The plugin resolves the GSP template used for each property according to conventions. You can override the rendering based on the class and property name or the property type. The f:field tag looks for a template called _wrapper.gsp, the f:widget tag looks for a template called _widget.gsp, the f:display tag looks for a template called _displayWrapper.gsp.

Breaking changes in version 1.5

In version 1.5 a new template was introduced _displayWidget.gsp. This is the corollary of _widget.gsp for fields that are read-only, i.e. it is responsible for rendering just the markup for the field itself. Furthermore, the default names of all the templates were changed in this version, in the interest of clarity and consistency. The changes to the template names are summarized below:

Table 1. Template Name Changes
Old Template Name (before v.1.5) New Template Name (v.1.5 onwards)

_field.gsp

_wrapper.gsp

_display.gsp

_displayWrapper.gsp

N/A

_displayWidget.gsp

Users upgrading to 1.5 from a previous version should either rename their templates (recommended) or add the following to grails-app/conf/application.yml to change the default templates names to the old names

grails:
    plugin:
        fields:
            wrapper: field
            displayWrapper: display
            widget: input
            displayWidget: displayWidget

Locating Field Templates by Convention

The template for a field is chosen by a convention using the names of the controller, action, bean class, bean property, theme, etc. All the tags will look for templates in the following directories in decreasing order of preference:

  • grails-app/views/controllerNamespace/controllerName/actionName/propertyName/_themes/themeName/

  • grails-app/views/controllerNamespace/controllerName/actionName/_themes/themeName/propertyType/

  • grails-app/views/controllerNamespace/controllerName/actionName/_themes/themeName/

  • grails-app/views/controllerNamespace/controllerName/propertyName/_themes/themeName/

  • grails-app/views/controllerNamespace/controllerName/_themes/themeName/propertyType/

  • grails-app/views/controllerNamespace/controllerName/_themes/themeName/

  • grails-app/views/controllerName/actionName/propertyName/_themes/themeName/

  • grails-app/views/controllerName/actionName/_themes/themeName/propertyType/

  • grails-app/views/controllerName/actionName/_themes/themeName/

  • grails-app/views/controllerName/propertyName/_themes/themeName/

  • grails-app/views/controllerName/_themes/themeName/propertyType/

  • grails-app/views/controllerName/_themes/themeName/

  • grails-app/views/_fields/_themes/themeName/class/propertyName/

  • grails-app/views/_fields/_themes/themeName/superclass/propertyName/

  • grails-app/views/_fields/_themes/themeName/associationType/

  • grails-app/views/_fields/_themes/themeName/propertyType/

  • grails-app/views/_fields/_themes/themeName/propertySuperclass/

  • grails-app/views/_fields/_themes/themeName/default/

  • grails-app/views/controllerNamespace/controllerName/actionName/propertyName/

  • grails-app/views/controllerNamespace/controllerName/actionName/propertyType/

  • grails-app/views/controllerNamespace/controllerName/actionName/

  • grails-app/views/controllerNamespace/controllerName/propertyName/

  • grails-app/views/controllerNamespace/controllerName/propertyType/

  • grails-app/views/controllerNamespace/controllerName/

  • grails-app/views/controllerName/actionName/propertyName/

  • grails-app/views/controllerName/actionName/propertyType/

  • grails-app/views/controllerName/actionName/

  • grails-app/views/controllerName/propertyName/

  • grails-app/views/controllerName/propertyType/

  • grails-app/views/controllerName/

  • grails-app/views/_fields/class/propertyName/

  • grails-app/views/_fields/superclass/propertyName/

  • grails-app/views/_fields/associationType/

  • grails-app/views/_fields/propertyType/

  • grails-app/views/_fields/propertySuperclass/

  • grails-app/views/_fields/default/

The variables referenced in these paths are:

Table 2. Referenced Variables
Name Description

controllerName

The name of the current controller (if any).

actionName

The name of the current action (if any).

themeName

Theme name specified as value of theme attribute (Optional).

class

The bean class. For simple properties this is the class of the object passed to the bean attribute of the f:field or f:widget tag but when the property attribute was nested this is the class at the end of the chain. For example, if the property path was employees[0].address.street this will be the class of address.

superclass

Any superclass or interface of class excluding Object, GroovyObject, Serializable, Comparable and Cloneable and those from GORM.

propertyName

The property name at the end of the chain passed to the property attribute of the f:field or f:widget tag. For example, if the property path was employees[0].address.street then this will be street.

propertyType

The type of the property at the end of the chain passed to the property attribute of the f:field or f:widget tag. For example, for a java.lang.String property this would be string.

propertySuperclass

Any superclass or interface of propertyType excluding Object, GroovyObject, Serializable, Comparable and Cloneable.

associationType

One of 'oneToOne', 'oneToMany', 'manyToMany' or 'manyToOne'. Only relevant if the property is a domain class association.

All class names are camel-cased simple forms. For example java.lang.String = string, com.project.HomeAddress = homeAddress.

Templates are resolved in this order so that you can override in the more specific circumstance and fall back to successively more general defaults. For example, you can define a field template for all java.lang.String properties but override a specific property of a particular class to use more specialized rendering.

Templates in plugins are resolved as well. This means plugins such as Joda Time can provide default rendering for special property types. A template in your application will take precedence over a template in a plugin at the same 'level'. For example if a plugin provides a grails-app/views/_fields/string/_widget.gsp the same template in your application will override it but if the plugin provides grails-app/views/_fields/person/name/_widget.gsp it would be used in preference to the more general template in your application.

For most properties the out-of-the-box defaults should provide a good starting point.

Locating Templates Conventionally Example

Imagine an object of class Employee that extends the class Person and has a String name property.

You can override the template f:field uses with any of these:

  • grails-app/views/controllerName/actionName/name/_themes/themeName/_wrapper.gsp

  • grails-app/views/controllerName/actionName/name/_wrapper.gsp

  • grails-app/views/controllerName/actionName/string/_wrapper.gsp

  • grails-app/views/controllerName/actionName/_wrapper.gsp

  • grails-app/views/controllerName/name/_wrapper.gsp

  • grails-app/views/controllerName/string/_wrapper.gsp

  • grails-app/views/controllerName/_wrapper.gsp

  • grails-app/views/_fields/employee/name/_wrapper.gsp

  • grails-app/views/_fields/person/name/_wrapper.gsp

  • grails-app/views/_fields/string/_wrapper.gsp

  • grails-app/views/_fields/default/_wrapper.gsp

override the template f:widget uses with any of these:

  • grails-app/views/controllerName/actionName/name/_themes/themeName/_widget.gsp

  • grails-app/views/controllerName/actionName/name/_widget.gsp

  • grails-app/views/controllerName/actionName/string/_widget.gsp

  • grails-app/views/controllerName/actionName/_widget.gsp

  • grails-app/views/controllerName/name/_widget.gsp

  • grails-app/views/controllerName/string/_widget.gsp

  • grails-app/views/controllerName/_widget.gsp

  • grails-app/views/_fields/employee/name/_widget.gsp

  • grails-app/views/_fields/person/name/_widget.gsp

  • grails-app/views/_fields/string/_widget.gsp

  • grails-app/views/_fields/default/_widget.gsp

And override the template f:display uses with any of these:

  • grails-app/views/controllerName/actionName/name/_themes/themeName/_displayWrapper.gsp

  • grails-app/views/controllerName/actionName/name/_displayWrapper.gsp

  • grails-app/views/controllerName/actionName/string/_displayWrapper.gsp

  • grails-app/views/controllerName/actionName/_displayWrapper.gsp

  • grails-app/views/controllerName/name/_displayWrapper.gsp

  • grails-app/views/controllerName/string/_displayWrapper.gsp

  • grails-app/views/controllerName/_displayWrapper.gsp

  • grails-app/views/_fields/employee/name/_displayWrapper.gsp

  • grails-app/views/_fields/person/name/_displayWrapper.gsp

  • grails-app/views/_fields/string/_displayWrapper.gsp

  • grails-app/views/_fields/default/_displayWrapper.gsp

During template development it is usually recommended to disable template caching in order to allow the plugin to recognize new/renamed/moved templates without restarting the application. See the "Performance" section of the guide for the exact settings.

Default Behaviour - Using Grails Widget Tags

If no template override is found the plugin will use the standard grails input tags (e.g. g:select, g:checkbox, g:field) for rendering input controls. Using f:field you can pass extra arguments (e.g. optionKey, optionValue) through to these tags by prefixing them with widget-, e.g.

<f:field bean="person" property="gender" widget-optionValue="name"/>

Template parameters

The f:field and f:widget tags will pass the following parameters to your templates or to the body of f:field if you use one:

Table 3. Template Parameters
Name Type Description

bean

Object

The bean attribute as passed to the f:field or f:widget tag.

property

String

The property attribute as passed to the f:field or f:widget tag. This would generally be useful for the name attribute of a form input.

type

Class

The property type.

label

String

The field label text. This is based on the label attribute passed to the f:field or f:widget tag. If no label attribute was used the label is resolved by convention - see below.

value

Object

the property value. This can also be overridden or defaulted if the value or default attribute was passed to f:field or f:widget.

constraints

ConstrainedProperty

The constraints for the property if the bean is a domain or command object.

persistentProperty

DomainProperty

The persistent property object if the bean is a domain object.

errors

List<String>

The error messages for any field errors present on the property. If there are no errors this will be an empty List.

required

boolean

true if the field is required, i.e. has a nullable: false or blank: false constraint.

invalid

boolean

true if the property has any field errors.

prefix

String

A string (including the trailing period) that should be appended before the input name such as name="${prefix}propertyName". The label is also modified.

In addition f:field passes the following parameters:

Table 4. Parameter Names from f:field

Name

Type

Description

widget

String

The output of f:widget for the current bean and property if f:field was used without a tag body, otherwise the output of the tag body.

If the bean attribute was not supplied to f:field then bean, type, value and persistentProperty will all be null.

Field labels

If the label attribute is not supplied to the f:field tag then the label string passed to the field template is resolved by convention. The plugin uses the following order of preference for the label:

  • An i18n message using the key 'beanClass.path`.label’. For example when using <f:field bean="personInstance" property="address.city"/> the plugin will try the i18n key person.address.city.label. If the property path contains any index it is removed so <f:field bean="authorInstance" property="books[0].title"/> would use the key author.books.title.label.

  • An i18n message using the key 'objectType.propertyName`.label’. For example when using <f:field bean="personInstance" property="address.city"/> the plugin will try the i18n key address.city.label.

  • The natural property name. For example when using <f:field bean="personInstance" property="dateOfBirth"/> the plugin will use the label "Date Of Birth".

Locating Field Templates Directly

Rather than relying on the convention described previously to locate the template(s) to be used for a particular field, it is instead possible to directly specify the directory containing the templates. This feature was introduced in version 1.5.

  • The wrapper attribute can be used with the f:field or f:display tags to specify the directory containing the _wrapper.gsp or _displayWrapper.gsp template to be used

  • The widget attribute can be used with the f:field or f:display tags to specify the directory containing the _widget.gsp or _displayWidget.gsp template to be used

  • If the wrapper and widget templates both have the same value, the templates attribute can be used instead as a shorthand. For example:

<f:field property="startDate" templates="bootstrap3" />

is equivalent to:

<f:field property="startDate" wrapper="bootstrap3" widget="bootstrap3" />

if theme is specified, theme will be searched first to find the templates For example

<f:field property="startDate" templates="custom" theme="bs-horizontal"/>

Will search the templates first in \_fields/_themes/bs-horizontal/custom and then \_fields/custom

If a direct location is specified, and the templates cannot be found therein, the plugin will fall back to locating templates by convention.

Locating Templates Directly Example

// renders _fields/\_themes/bs-horizontal/custom/_wrapper.gsp:
<f:field property="startDate" wrapper="custom" theme="bs-horizontal"/>

// renders _fields/bootstrap3/_wrapper.gsp:
<f:field property="startDate" wrapper="bootstrap3"/>

// renders _fields/time/_widget.gsp:
<f:field property="startDate" widget="time"/>

// renders _fields/time/_wrapper.gsp and _fields/time/_widget.gsp:
<f:field property="startDate" templates="time"/>

// renders _fields/\_themes/bs-horizontal/custom/_displayWrapper.gsp:
<f:display property="startDate" wrapper="custom" theme="bs-horizontal"/>


// renders _fields/bootstrap3/_displayWrapper.gsp:
<f:display property="startDate" wrapper="bootstrap3"/>

// renders _fields/time/_displayWidget.gsp:
<f:display property="startDate" widget="time"/>

// renders _fields/time/_displayWrapper.gsp and _fields/time/_displayWidget.gsp:
<f:display property="startDate" templates="time"/>

4 Embedded Properties

Embedded properties are handled in a special way by the f:field and f:all tags. If the property attribute you pass to f:field is an embedded property then the tag recursively renders each individual property of the embedded class with a surrounding fieldset. For example if you have a Person class with a name property and an Address embedded class with street, city and country properties <f:field bean="person" property="address"> will effectively do this:

<fieldset class="embedded address">
    <legend>Address</legend>
    <f:field bean="person" property="address.street"/>
    <f:field bean="person" property="address.city"/>
    <f:field bean="person" property="address.country"/>
</fieldset>

You can customize how embedded properties are surrounded by providing a layout at grails-app/views/layouts/_fields/embedded.gsp which will override the default layout provided by the plugin.

When you use the f:all tag it will automatically handle embedded properties in this way.

5 Scaffolding

Scaffolding templates based on the Fields plugin are quite powerful as they will pick up field and input rendering templates from your application and any plugins that provide them. This means that the useful life of scaffolding templates should be much longer as you do not need to replace the entire create.gsp and/or edit.gsp template just because you want to do something different with a certain property of one particular class.

The plugin makes the renderEditor.template file used by standard Grails scaffolding redundant. This template was very limited because it could not be extended by plugins or applications (only replaced) and was unable to support embedded properties of domain classes.

The Fields plugin includes scaffolding templates you can use in your application by running:

grails install-form-fields-templates

This will overwrite any create.gsp and edit.gsp files you have in src/templates/scaffolding.

Alternatively, it’s very easy to modify your existing scaffolding templates to use the f:all tag or multiple f:field tags.

6 Themes

Since version 2.1.4 It is possible to create themes to provide set of templates for different css frameworks or form layouts. For example, a bootstrap-fields plugin can provide different themes (eg bs-horizontal, bs-vertical) to support horizontal and vertical form layouts. And another plugin can provide theme for purecss framework.

Themes are put under directory _fields/themes/themeName/.

All of the field tags supports theme attribute which accepts the name of the theme. When a theme name is specified, widget, wrapper, and display templates will be searched in theme directory first as described in Customizing Field Rendering.

7 Including Templates in Plugins

Plugins can include field and/or input level templates to support special UI rendering or non-standard property types. Just include the templates in the plugin’s grails-app/views directory as described in the Customizing Field Rendering section.

If you supply templates in a plugin you should consider declaring a <%@page defaultCodec="html" %> directive so that any HTML unsafe property values are escaped properly regardless of the default codec used by client apps.

8 Performance

In order to be performant, the Fields plugin caches field template lookup results by default. This makes it possible to perform the time-consuming template path resolutions only once during the runtime of the application.

When template caching is active, only the first page renderings are slow, subsequent ones are fast.

Due to the flexibility needed during template development, this feature can be disabled so it would be possible to recognize newly added field templates without restarting the application. As a result, with bigger webpages, containing a lot of fields, rendering may be fairly slow in development (depending on the number of fields on the page).

For template development, the following configuration attribute should be placed in the development environment section of your application’s Config.groovy:

grails.plugin.fields.disableLookupCache = true

After the template development has finished, it is recommended to re-enable the template lookup cache in order to have a performant page rendering even during development.