(Quick Reference)

3 Customizing Field Rendering - Reference Documentation

Authors: Rob Fletcher

Version: 1.4

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 _field.gsp, the f:input tag looks for a template called _input.gsp and the f:display tag looks for a template called _display.gsp. All the tags will look in the following locations in decreasing order of preference:
  1. grails-app/views/controllerName/actionName/propertyName/
  2. grails-app/views/controllerName/actionName/propertyType/
  3. grails-app/views/controllerName/actionName/
  4. grails-app/views/controllerName/propertyName/
  5. grails-app/views/controllerName/propertyType/
  6. grails-app/views/controllerName/
  7. grails-app/views/_fields/class/propertyName/
  8. grails-app/views/_fields/superclass/propertyName/
  9. grails-app/views/_fields/associationType/
  10. grails-app/views/_fields/propertyType/
  11. grails-app/views/_fields/propertySuperclass/
  12. grails-app/views/_fields/default/

The variables referenced in these paths are:

controllerNameThe name of the current controller (if any).
actionNameThe name of the current action (if any).
classThe bean class. For simple properties this is the class of the object passed to the bean attribute of the f:field or f:input 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 .
superclassAny superclass or interface of class excluding Object , GroovyObject , Serializable , Comparable and Cloneable .
propertyNameThe property name at the end of the chain passed to the property attribute of the f:field or f:input tag. For example, if the property path was employees[0].address.street then this will be street .
propertyTypeThe type of the property at the end of the chain passed to the property attribute of the f:field or f:input tag. For example, for a java.lang.String property this would be string .
propertySuperclassAny superclass or interface of propertyType excluding Object , GroovyObject , Serializable , Comparable and Cloneable .
associationTypeOne 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/_input.gsp the same template in your application will override it but if the plugin provides grails-app/views/_fields/person/name/_input.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.


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

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

  1. grails-app/views/controllerName/actionName/name/_field.gsp
  2. grails-app/views/controllerName/actionName/string/_field.gsp
  3. grails-app/views/controllerName/actionName/_field.gsp
  4. grails-app/views/controllerName/name/_field.gsp
  5. grails-app/views/controllerName/string/_field.gsp
  6. grails-app/views/controllerName/_field.gsp
  7. grails-app/views/_fields/employee/name/_field.gsp
  8. grails-app/views/_fields/person/name/_field.gsp
  9. grails-app/views/_fields/string/_field.gsp
  10. grails-app/views/_fields/default/_field.gsp

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

  1. grails-app/views/controllerName/actionName/name/_input.gsp
  2. grails-app/views/controllerName/actionName/string/_input.gsp
  3. grails-app/views/controllerName/actionName/_input.gsp
  4. grails-app/views/controllerName/name/_input.gsp
  5. grails-app/views/controllerName/string/_input.gsp
  6. grails-app/views/controllerName/_input.gsp
  7. grails-app/views/_fields/employee/name/_input.gsp
  8. grails-app/views/_fields/person/name/_input.gsp
  9. grails-app/views/_fields/string/_input.gsp
  10. grails-app/views/_fields/default/_input.gsp

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

  1. grails-app/views/controllerName/actionName/name/_display.gsp
  2. grails-app/views/controllerName/actionName/string/_display.gsp
  3. grails-app/views/controllerName/actionName/_display.gsp
  4. grails-app/views/controllerName/name/_display.gsp
  5. grails-app/views/controllerName/string/_display.gsp
  6. grails-app/views/controllerName/_display.gsp
  7. grails-app/views/_fields/employee/name/_display.gsp
  8. grails-app/views/_fields/person/name/_display.gsp
  9. grails-app/views/_fields/string/_display.gsp
  10. grails-app/views/_fields/default/_display.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 Input 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 input-, e.g.

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

Template parameters

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

beanObjectThe bean attribute as passed to the f:field or f:input tag.
propertyStringThe property attribute as passed to the f:field or f:input tag. This would generally be useful for the name attribute of a form input.
typeClassThe property type.
labelStringThe field label text. This is based on the label attribute passed to the f:field or f:input tag. If no label attribute was used the label is resolved by convention - see below.
valueObjectthe property value. This can also be overridden or defaulted if the value or default attribute was passed to f:field or f:input .
constraintsConstrainedPropertyThe constraints for the property if the bean is a domain or command object.
persistentPropertyGrailsDomainClassPropertyThe persistent property object if the bean is a domain object.
errorsList<String>The error messages for any field errors present on the property. If there are no errors this will be an empty List .
requiredboolean true if the field is required, i.e. has a nullable: false or blank: false constraint.
invalidboolean true if the property has any field errors.
prefixStringA 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:

widgetStringThe output of f:input 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:

  1. 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="books0.title"/> would use the key author.books.title.label.
  2. 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.
  3. The natural property name. For example when using <f:field bean="personInstance" property="dateOfBirth"/> the plugin will use the label "Date Of Birth".