(Quick Reference)

2 Usage

Version: 2.2.8

2 Usage

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 f:input tag was deprecated because the name was confusing. Use the new f:widget tag instead.

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

Localized numbers

All numbers are now rendered localized. This means that when using Locale.ENGLISH the number 1000.50 is represented as 1,000.50 but with Locale.GERMAN is represented as 1.000,50. To use the old behavior (for backwards compatibility) without localizing the numbers, configure the following in Config.groovy:

grails.plugin.fields.localizeNumbers = false