////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

==== f:field

===== Description

`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:

[source,groovy]
----
<div class="fieldcontain">
    <label for="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:

[source,groovy]
----
<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:

[source,groovy]
----
<f:field bean="person" property="name">
    <g:textField name="${property}" value="${value}"/>
</f:field>
----

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.

----
<f:field bean="person" property="name" theme="bs-horizontal"/>
----

[source,groovy]
----
// renders _fields/bootstrap3/_wrapper.gsp:
<f:field bean="person" property="name" wrapper="bootstrap3"/>

// renders _fields/maskedInput/_widget.gsp:
<f:field bean="person" property="name" widget="maskedInput"/>

// renders _fields/maskedInput/_wrapper.gsp and _fields/maskedInput/_widget.gsp:
<f:field bean="person" property="name" templates="maskedInput"/>
----

See link:#customizingFieldRendering[Customizing Field Rendering] for details of the parameters passed to the tag body.

The `f:field` tag handles embedded domain properties in a special way. See link:#embeddedProperties[Embedded Properties] for details.


===== Attributes


.Attributes for `f:field`

[options="header",cols="1,1,3"]
|===
|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:

.grails-app/views/_fields/default/_wrapper.gsp
----
<div class="form-group ${invalid ? 'has-error' : ''}">
    <label for="${property}">${label} ${required ? '*' : ''}</label>

    <div>
        <f:widget property="${property}"/>
        <g:if test="${errors}">
            <g:each in="${errors}" var="error">
                <span class="help-block"><g:message error="${error}"/></span>
            </g:each>
        </g:if>
    </div>
</div>
----
