getBeanSuperclasses() @return all superclasses and interfaces of `beanType` excluding `Object`, `Serializable`, `Comparable` and `Cloneable`.
+
+
+
+
+
java.lang.Class
+
getBeanType() @return the type of the object that owns the property at the end of the path, e.g. for a `address.home.street` then the type of `home` is returned.
the GORM persistent property descriptor for the property at the end of the path, e.g. for `address.home.street` then the descriptor of `street` is returned.
the resolved messages for any validation errors present on the property at the end of the path.
+
+
+
+
+
java.util.List<java.lang.String>
+
getLabelKeys() @return the i18n keys used to resolve a label for the property at the end of the path in order of preference.
+
+
+
+
+
java.lang.String
+
getPathFromRoot() @return the full path from the root bean to the requested property.
+
+
+
+
+
java.lang.String
+
getPropertyName() @return the name of the property at the end of the path, e.g. for `address.home.street`, `street` is returned.
+
+
+
+
+
java.lang.Class
+
getPropertyType() @return the type of the property at the end of the path, e.g. for `address.home.street` then the type of `street` is returned.
+
+
+
+
+
java.util.List<java.lang.Class>
+
getPropertyTypeSuperclasses() @return all superclasses and interfaces of `propertyType` excluding `Object`, `Serializable`, `Comparable` and `Cloneable`.
+
+
+
+
+
java.lang.Object
+
getRootBean() @return the object at the root of a path expression, e.g. for a `person` bean and `address.street` then `person` is returned.
+
+
+
+
+
java.lang.Class
+
getRootBeanType() @return the type of the object at the root of a path expression, e.g. for a `person` bean and `address.street` then the type of `person` is returned.
+
+
+
+
+
java.lang.Object
+
getValue() @return the value of the property at the end of the path, e.g. for `address.home.street` then the value of `street` is returned.
the constraints of the property at the end of the path, e.g. for `address.home.street` then the constraints of `street` are returned. This will be null for non-domain properties.
+
+
+
+
+
+
+
java.lang.String getDefaultLabel()
+
+
Returns:
default label text for the property at the end of the path.
the GORM persistent property descriptor for the property at the end of the path, e.g. for `address.home.street` then the descriptor of `street` is returned. This will be null for non-domain properties.
the resolved messages for any validation errors present on the property at the end of the path. This will be an empty list if there are no errors or the property is not a validateable type.
+
+
+
+
+
+
+
java.util.List<java.lang.String> getLabelKeys()
+
+
Returns:
the i18n keys used to resolve a label for the property at the end of the path in order of preference.
+
+
+
+
+
+
+
java.lang.String getPathFromRoot()
+
+
Returns:
the full path from the root bean to the requested property.
+
+
+
+
+
+
+
java.lang.String getPropertyName()
+
+
Returns:
the name of the property at the end of the path, e.g. for `address.home.street`, `street` is returned.
+
+
+
+
+
+
+
java.lang.Class getPropertyType()
+
+
Returns:
the type of the property at the end of the path, e.g. for `address.home.street` then the type of `street` is returned.
all superclasses and interfaces of `propertyType` excluding `Object`, `Serializable`, `Comparable` and `Cloneable`.
+
+
+
+
+
+
+
java.lang.Object getRootBean()
+
+
Returns:
the object at the root of a path expression, e.g. for a `person` bean and `address.street` then `person` is returned.
+
+
+
+
+
+
+
java.lang.Class getRootBeanType()
+
+
Returns:
the type of the object at the root of a path expression, e.g. for a `person` bean and `address.street` then the type of `person` is returned.
+
+
+
+
+
+
+
java.lang.Object getValue()
+
+
Returns:
the value of the property at the end of the path, e.g. for `address.home.street` then the value of `street` is returned.
+
+
+
+
+
+
+
boolean isInvalid()
+
+
Returns:
whether or not the property has any validation errors (i.e. `getErrors` will return a non-empty list). This will always be false for non-validateable types.
+
+
+
+
+
+
+
boolean isRequired()
+
+
Returns:
whether or not the property is required as determined by constraints. This will always be false for non-validateable types.
property REQUIRED The name of the property to display. This is resolved
+ against the specified bean or the bean in the current scope.
attr:
value Specifies the initial value to display in the field. The default is
+ the current value of the property.
attr:
default A default initial value to display if the actual property value
+ evaluates to false.
attr:
required Specifies whether the user is required to enter a value for this
+ property. By default, this is determined by the constraints of the property.
attr:
invalid Specifies whether this property is invalid or not. By default, this
+ is determined by whether there are any errors associated with it.
attr:
label Overrides the default label displayed next to the input field.
attr:
prefix Prefix to add to input element names.
attr:
wrapper Specify the folder inside _fields where to look up for the wrapper template.
attr:
widget Specify the folder inside _fields where to look up for the widget template.
attr:
templates Specify the folder inside _fields where to look up for the wrapper and widget template.
collection REQUIRED The collection of beans to render
attr:
domainClass The FQN of the domain class of the elements in the collection.
+ Defaults to the class of the first element in the collection.
attr:
properties OPTIONAL The list of properties to be shown (table columns).
attr:
maxProperties OPTIONAL The number of properties displayed when no explicit properties are given, defaults to 7.
attr:
displayStyle OPTIONAL Determines the display template used for the bean's properties.
+ Defaults to 'table', meaning that 'display-table' templates will be used when available.
attr:
order A comma-separated list of properties to include in provided order
attr:
except A comma-separated list of properties to exclude
attr:
theme Theme name
attr:
template OPTIONAL The template used when rendering the collection
+
+
+
+
+
+
+
+
java.lang.Object widget
+
attr:
bean Name of the source bean in the GSP model.
attr:
property REQUIRED The name of the property to display. This is resolved
+ against the specified bean or the bean in the current scope.
attr:
theme Theme name
+
+
+
+
+
+
+
+
java.lang.Object with
+
attr:
bean REQUIRED Name of the source bean in the GSP model.
This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.
+
+
+
+
+
Overview
+
The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.
+
+
+
Package
+
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
+
+
Interfaces (italic)
+
Classes
+
Enums
+
Exceptions
+
Errors
+
Annotation Types
+
+
+
+
Class/Interface
+
Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
+
+
Class inheritance diagram
+
Direct Subclasses
+
All Known Subinterfaces
+
All Known Implementing Classes
+
Class/interface declaration
+
Class/interface description
+
+
+
Nested Class Summary
+
Field Summary
+
Constructor Summary
+
Method Summary
+
+
+
Field Detail
+
Constructor Detail
+
Method Detail
+
+
Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
+
+
+
Annotation Type
+
Each annotation type has its own separate page with the following sections:
+
+
Annotation Type declaration
+
Annotation Type description
+
Required Element Summary
+
Optional Element Summary
+
Element Detail
+
+
+
+
Enum
+
Each enum has its own separate page with the following sections:
+
+
Enum declaration
+
Enum description
+
Enum Constant Summary
+
Enum Constant Detail
+
+
+
+
+
Deprecated API
+
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
+
+
+
Index
+
The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
+
+
+
Frames/No Frames
+
These links show and hide the HTML frames. All pages are available with or without frames.
+
+
+
All Classes
+
The All Classes link shows all classes and interfaces except non-static nested types.
+
+
+
Serialized Form
+
Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
the GORM persistent property descriptor for the property at the end of the path, e.g. for `address.home.street` then the descriptor of `street` is returned.
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.
BugFix: The fix for #257 did not work as described, but now it does.
+
+
+
Improvement: Documentation has been improved with more examples for the various tags.
+GitHub diff
+
+
+
+
+
+
Version 2.2.6
+
+
+
+
Improvement: Documentation of maxProperties on <f:table/>
+
+
+
Improvement: <f:table\> can now show id, lastUpdated and dateCreated (see f:table doc). Injecting DomainModelService instead of instantiating DomainModelServiceImpl in FormsFieldTagLib (Issue #257)
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.
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:
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.
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
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
+
+
+
+
+
+
+
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
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:
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 becomes string, and com.project.HomeAddress becomes 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:
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.
+
+
+
+
See Template Seach Path
+
+
The plugin logs which locations it is checking for templates as debug log. You can enable this by defining a logger in logback.groovy
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.
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.
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:
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:
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.
+
+
+
+
+
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.
+
+
+
+
+
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.
+
+
+
+
+
+
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).
+
+
+
+
+
Performance
+
+
+
For template development, the following configuration attribute should be placed in the development environment section of your application’s Config.groovy:
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.
+
+
+
+
+
Reference
+
+
+
Tags
+
+
all
+
+
+
+
f:all
+
+
Purpose
+
+
Renders fields for all properties of an object by using f:field for each property.
+
+
+
The id, version, dateCreated and lastUpdated properties are skipped on domain classes. Additionally any property with a display: false constraint set will be skipped.
+
+
+
+
Attributes
+
+
Table 5. Attributes for f:all
+
+
+
+
+
+
+
+
Name
+
Required
+
Description
+
+
+
+
+
bean
+
if not inside f:with
+
The bean whose property is being rendered. This can be the object itself or the name of a page-scope variable.
+
+
+
except
+
N/A
+
A comma-separated list of properties that should be skipped (in addition to the defaults).
+
+
+
order
+
N/A
+
A comma-separated list of properties which represents the order in which the tag should generate fields.
+
+
+
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.
+
+
+
theme
+
String
+
Theme to use if available.
+
+
+
+
+
+
Extra attributes (Since version 2.1.4)
+
+
You can pass extra attributes to the all tag that will be propagated to the inner fields.
+
+
+
+
Example
+
+
+
<f:all bean="person" wrapper="someWrapper"/>
+
+
+
+
In that way all the fields are going to be executed as if they were executed with the extra attribute on them.
+
+
+
+
+
+
+
+
+Remember that if you want to use some of those attributes in the widget templates you need to prefix them with the widget- word (unless you have configured another prefix)
+
+
+
+
+
+
+
+
display
+
+
+
+
f:display
+
+
Purpose
+
+
f:display renders a property for display. If there is no _displayWrapper template in scope the tag will simply render the property value.
+
+
+
f:display template will look for a _displayWrapper for the wrapper itself and a _displayWidget for the widget used inside the wrapper template.
+
+
+
If the f:display tag has a body its output is used as the value passed as the value model to the _display template. If there is no body then the raw property value is passed to g:fieldValue, g:formatDate or g:formatBoolean depending on its type and the result is passed as the value model to the _display template.
+
+
+
+
+
+
+
+
+In version 1.5 new attributes were added:
+Since then you can specify the folders where the templates are located. You can do this for the wrapper folder, the widget folder ot both (if they are located on the same folder).
+
The bean whose property is being rendered. This can be the object itself or the name of a page-scope variable.
+
+
+
property
+
No
+
The path to the property. This can include any level of nesting and numeric or string indexes. For example employees[0].address[home].street is a valid path. If absent, all properties will be displayed via the grails-app/views/templates/_fields/_list.gsp (see the template code below).
+
+
+
value
+
No
+
Overrides the actual value of the property.
+
+
+
default
+
No
+
A default value for the property that will be used if the actual property value is false.
+
+
+
label
+
No
+
Overrides the field label passed to the template. This value may either be an i18n key or a literal string.
+
+
+
displayStyle
+
No
+
When specified and different from the string default, this tag will try to use a _display-${displayStyle} template with a _display template as fallback. `displayStyle="table" will render embedded components by default with toString() instead of rendering all nested properties.
+
+
+
except
+
No
+
A comma-separated list of properties that should be skipped.
+
+
+
order
+
No
+
A comma-separated list of properties which represents the order in which the tag should display them.
+
+
+
theme
+
No
+
Theme to use if available. The theme can define a new directory structure in /_fields/_themes/<themename> which will take priority over templates, wrapper and widget if they are specified, as it is injecting the search path first in the list.
+
+
+
templates
+
No
+
Specify the folder inside _fields where to look up for the wrapper and widget template.
+
+
+
widget
+
No
+
Specify the folder inside _fields where to look up for the widget template.
+
+
+
wrapper
+
No
+
Specify the folder inside _fields where to look up for the wrapper template.
+
+
+
+
+
Any additional attributes are passed to the rendered template.
+
+
+
+
+
Special case for rendering all properties of a bean
+
+
When f:display is used without a property then all bean properties are rendered. This is done with the grails-app/views/templates/_fields/_list.gsp template. The default template can be found on GitHub
+
+
+
+
displayWidget
+
+
+
+
f:displayWidget
+
+
Purpose
+
+
f:displayWidget renders an appropriate widget for a display property, for example an <span>${value}</span> element for a String property.
+
+
+
+
+
+
+
+
+Using f:displayWidget directly will only be necessary for very specialized cases, usually it will be invoked via f:display.
+
+
+
+
+
+
+
Attributes
+
+
f:displayWidget accepts exactly the same attributes as the f:display tag (except for wrapper and templates attributes).
+
+
+
+
Example of a _displayWidget.gsp
+
+
If you have a domain class with a java.time.LocalDate you might want to format it specially:
f:field renders the widget using either f:widget or the tag body accompanied by any surrounding markup, typically a container, a label tag and any validation messages.
+
+
+
By default the f:field tag will output:
+
+
+
+
<div class="fieldcontain">
+ <labelfor="foo">Foo</label>
+ <!-- the widget as generated by f:widget or the tag body -->
+</div>
+
+
+
+
The intention is that f:field should typically be used without a tag body. For example:
+
+
+
+
<f:field bean="person" property="name"/>
+
+
+
+
In which case the tag will use f:widget to generate an appropriate input. Alternatively in more specialized cases you can give f:field a tag body. For example:
Since version 1.5 you can specify which specific templates are going to be used on the view.
+You can accomplish this using new attributes: wrapper, widget and templates. (See attributes section)
+
+
+
Since version 2.1.4 you can specify the theme to be used.
The f:field tag handles embedded domain properties in a special way. See Embedded Properties for details.
+
+
+
+
Attributes
+
+
Table 7. Attributes for f:field
+
+
+
+
+
+
+
+
Name
+
Required
+
Description
+
+
+
+
+
bean
+
yes for f:widget if not inside f:with, optional for f:field
+
The bean whose property is being rendered. This can be the object itself or the name of a page-scope variable.
+
+
+
property
+
yes
+
The path to the property. This can include any level of nesting and numeric or string indexes. For example employees[0].address[home].street is a valid path. If absent, all properties will be displayed.
+
+
+
value
+
No
+
Overrides the actual value of the property.
+
+
+
default
+
No
+
A default value for the property that will be used if the actual property value is false.
+
+
+
required
+
No
+
Overrides the required status of the property. By default this is worked out based on the property’s constraints.
+
+
+
invalid
+
No
+
Overrides the validity of the property. By default this is worked out using the bean’s errors property for domain and command objects.
+
+
+
label
+
No
+
Overrides the field label passed to the template. This value may either be an i18n key or a literal string.
+
+
+
prefix
+
No
+
A string (including the trailing period) that should be appended before the input name such as name="${prefix}propertyName". The label is also modified.
+
+
+
wrapper
+
No
+
Specifies the name of the folder inside _fields where the _wrapper.gsp template is located.
+
+
+
widget
+
No
+
Specifies the name of the folder inside \_fields where the \_widget.gsp template is located.
+
+
+
templates
+
No
+
Specifies the name of the folder inside _fields where the _wrapper.gsp and _widget.gsp templates are located. It is a shorthand for specifying both (wrapper and widget).
+
+
+
theme
+
String
+
Theme to use if available.
+
+
+
+
+
Any additional attributes are passed to the rendered template. Any additional attributes prefixed with widget- are instead passed to the widget template or rendered on the default input.
+
+
+
+
Example of overriding a _wrapper.gsp
+
+
If you want to override a f:wrapper to be used for all widgets then create a file with content like this:
<f:table/> renders some or all properties of a collection of beans in a table using the f:display widget for each property type. If there is no \_display template in scope the tag will simply render the property values.
+
+
+
+
Examples
+
+
+
<f:table collection="personList"/>
+
+<f:table collection="personList" properties="firstName, lastName"/>
+
+<f:table collection="personList" properties="['firstName', 'lastName']"/>
+
+<f:table collection="catsAndDogsList" domainClass="org.zoo.Animal"/>
+
+<f:table collection="catsAndDogsList" domainClass="org.zoo.Animal" theme="bs-horizontal"/>
+
+// List first three properties in Person
+<f:table collection="personList" maxProperties="3"/>
+
+// Include id, lastUpdated, dateCreated
+<f:table collection="personList" except="[]]"/>
+
+
+
+
The template for <f:table/> should be in
+
+
+
+
grails-app/views/templates/_fields/_table.gsp
+
+
+
+
but you can have multiple table templated, if you specify the template property.
+All templates should still be located in view/templates/_fields/, the example below uses 4 different templates for table.
When theme is specified, the \_display template will be searched first in theme, but the theme property does not directly apply to table.
+
+
+
+
Attributes
+
+
+
+
+
+
+
+
+
+
Name
+
Required?
+
Default
+
Description
+
+
+
+
+
collection
+
yes
+
+
The collection of beans to be displayed
+
+
+
domainClass
+
+
Class of first element in collection
+
The FQN of the domain class of the elements in the collection.
+
+
+
properties
+
+
First 7 (or less)
+
Comma-separated String or List of properties to be shown (table columns). Defaults to the first 7 (or less) properties of the domain class ordered by the domain class' constraints, unless maxProperties is set below
+
+
+
displayStyle
+
+
+
Determines the display template used for the bean’s properties. Defaults to table meaning that \_display-table templates will be used when available.
+
+
+
except
+
+
['id', 'lastUpdated', 'dateCreated']
+
A comma-separated String or List of properties that should be skipped. Use the empty list to include id, lastUpdated and dateCreated
+
+
+
order
+
+
+
Comma-separated String or List of properties which represents the order in which the tag should display them.
+
+
+
theme
+
String
+
+
Theme to use if available.
+
+
+
maxProperties
+
Number
+
7
+
The maximum number of properties to display when rendering the table. If zero is specified all columns are shown, otherwise properties[0..<maxProperties] are shown. maxProperties can be negative.
+
+
+
template
+
String
+
table
+
Alternative template for table rendering. Templates should be in the grails-app/views/templates/_fields/ folder.
+
+
+
+
+
+
Any additional attributes are passed to the rendered template.
+
+
+
+
+
Modifying the _table.gsp template.
+
+
To make you own version of a f:table template, the file should be located in grails-app/views/templates/_fields/_table.gsp
+unless a different location is specified with the template property.
+You can find a starting point for a new file on GitHub
+
+
+
Model in the template
+
+
The following model is passed to the _table.gsp template:
+
+
+
+
+
+
+
+
+
Name
+
Content
+
+
+
+
+
domainClass
+
The type of the persistent instance. Either type of the first row in the collection or the domainClass passed as argument to f:table
+
+
+
columnProperties
+
Contains a list of Map describing each table column. See table below for the map content
+
+
+
domainProperties
+
deprecated: see columnProperties
+
+
+
collection
+
Rows with data
+
+
+
displayStyle
+
The attribute displayStyle passed to the model unmodified
+
+
+
theme
+
The attribute theme passed to the model unmodified
+
+
+
+
+
The column model:
+
+
+
+
+
+
+
+
+
Name
+
Content
+
+
+
+
+
bean
+
Empty instance of a domainClass bean
+
+
+
property
+
The property name
+
+
+
name
+
Deprecated, see property
+
+
+
type
+
The property type
+
+
+
defaultLabel
+
Translated label (deprecated)
+
+
+
label
+
Translated label
+
+
+
constraints
+
If the property has constraints
+
+
+
required
+
Is the property required
+
+
+
+
+
(This is a simplified version of a wrapper model)
+
+
+
+
+
+
widget
+
+
+
+
f:widget
+
+
Purpose
+
+
f:widget renders an appropriate widget for a property, for example an <input type="text"> element for a String property or a <select> for an enum.
+
+
+
+
+
+
+
+
+Using f:widget directly will only be necessary for very specialized cases, usually it will be invoked via f:field.
+
+
+
+
+
+
+
Attributes
+
+
f:widget accepts exactly the same attributes as the f:field tag (except for wrapper and templates attributes).
+
+
+
+
Default rendering
+
+
The <f:widget/> tag will will by default use sensible defaults when rendering String, Number, Boolean, URL, Enum, Date and associations like oneToOne, oneToMany, manyToOne and manyToMany.
+
+
+
In a few cases it is possible to control which default widget to use, by specifying it in the beans constraints.
+
+
+
The following happens with these types:
+
+
+
String
+
+
By default, properties instance of String renders a <g:field type="text"> type field, but the constraints in the bean will alter this in these cases:
+
+
+
+
+
+
+
+
+
constraint
+
Rendered Widget type
+
+
+
inList
+
<g:select/>. If the field is not required, a noSelection is added to the select
+
+
+
password: true
+
<g:field type="password"/>
+
+
+
email: true
+
<g:field type="email"/>
+
+
+
url: true
+
<g:field type="url"/>
+
+
+
widget: 'textarea'
+
<g:textArea/>
+
+
+
+
+
+
Numeric and primitive types
+
+
By default, properties instance of Number renders a <g:field type="number"> or <:field type="number decimal"/> type field, but the constraints in the bean will alter this in these cases:
+
+
+
+
+
+
+
+
+
constraint
+
Affects the rendered widget
+
+
+
scale
+
Sets the step attribute on the input field
+
+
+
min
+
Set the min attribute on the input field
+
+
+
max
+
Set the max attribute on the input field
+
+
+
+
+
By default, the value is formatted with the default numberFormatter based on the request locale.
+
+
+
This behavior can be turned off in the configuration by setting:
The bean whose property is being rendered. This can be the object itself or the name of a page-scope variable.
+
+
+
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.
+
+
+
+
+
+
Extra attributes (Since version 2.1.4)
+
+
You can pass any number of extra attributes to the with tag that will be propagated to the inner fields and displays.
+Remember that if you want to use some of those attributes in the widget or displayWidget templates you need to prefix them with the widget- word (unless you have configured another prefix)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/4.0.x/api/deprecated-list.html b/4.0.x/api/deprecated-list.html
index d7ff8bca..f0f8fa4c 100644
--- a/4.0.x/api/deprecated-list.html
+++ b/4.0.x/api/deprecated-list.html
@@ -23,7 +23,7 @@
-
+
Deprecated API (fields "${RELEASE_VERSION}" API)
diff --git a/4.0.x/api/grails/plugin/formfields/Application.html b/4.0.x/api/grails/plugin/formfields/Application.html
index fde3bea2..92b0c518 100644
--- a/4.0.x/api/grails/plugin/formfields/Application.html
+++ b/4.0.x/api/grails/plugin/formfields/Application.html
@@ -26,7 +26,7 @@
-
+
Application (fields "${RELEASE_VERSION}" API)
@@ -179,7 +179,7 @@