// binds request parameters to a target object
bindData(target, params)
// exclude firstName and lastName
bindData(target, params, [exclude: ['firstName', 'lastName']])
// only use parameters starting with "author." e.g. author.email
bindData(target, params, "author")
bindData(target, params, [exclude: ['firstName', 'lastName']], "author")
// using inclusive map
bindData(target, params, [include: ['firstName', 'lastName']], "author")
// clear included properties omitted from the source
bindData(target, params, [include: ['firstName', 'lastName'], clearMissing: true])bindData
Purpose
Allows fine-grained control of binding request parameters from strings onto objects and the necessary types (data binding).
Examples
Description
Usage: bindData(target, params, includesExcludes*, prefix*)
Arguments:
-
target- The target object to bind to -
params- AMapof source parameters, often the params object when used in a controller -
includesExcludes- (Optional) A map with 'include' and/or 'exclude' lists containing the names of properties to either include or exclude. SetclearMissing: truewith anincludelist to clear included properties that are omitted from the binding source. -
prefix- (Optional) A string representing a prefix to use to filter parameters. The method will automatically append a '.' when matching the prefix to parameters, so you can use 'author' to filter for parameters such as 'author.name'.
If no include list is supplied, bindData uses the target class default binding behavior. By default, statically typed instance properties bind for compatibility unless they are marked bindable: false. Existing bindable: true declarations and explicit include lists continue to bind exactly the properties they name without configuration changes. An empty include list binds no properties.
In compatibility mode, supplying only exclude binds all other eligible properties without intersecting them with the generated allowlist. In secure mode, the generated allowlist is still applied when only exclude is supplied.
For typed Map properties, each value is converted to the declared generic value type. Conversion failures are recorded as binding errors and binding listeners are notified.
Use include to allow only the properties needed for a request:
bindData(target, params, [include: ['firstName', 'lastName']])Include entries may use wildcard suffixes for nested properties. address. includes all
properties nested under address, while address_ is the corresponding underscore-form
used for nested binding paths and generated binding allowlists:
bindData(target, params, [include: ['address.*']])
bindData(target, params, [include: ['address_*']])When clearMissing: true is used, omitted properties matched by either wildcard form are
cleared, subject to the normal exclude and bindability rules.
For controller action command object parameters, use grails.web.databinding.BindAllowed to allow request binding for only the listed properties:
import grails.web.databinding.BindAllowed
class PersonController {
def save(@BindAllowed(['firstName', 'lastName']) PersonCommand command) {
// command.email, command.admin, etc. are not bound by this action
}
}See the bindable constraint documentation for more information on controlling default bindability. Applications may set grails.databinding.denyByDefault=true to opt into deny-by-default binding allowlists. In secure mode, permit a property with bindable: true, an explicit include list, or @BindAllowed on a controller action command object parameter.
clearMissing is opt-in and only applies when an include list is provided. This is useful for update forms where an omitted allowed field should clear an existing value instead of leaving stale persisted data. Excluded properties are not cleared.
Only boolean values and the strings 'true' and 'false' are recognised for grails.databinding.denyByDefault. String matching ignores case and surrounding whitespace. An unrecognised value logs a warning and enables secure binding.
The underlying implementation uses Spring’s Data Binding framework. If the target is a domain class, type conversion errors are stored in the errors property of the domain class.
Refer to the section on data binding in the user guide for more information.