Field object

Each field object contains the metadata specified in form builder for the specific form it resides in. It can render its label, input field, instructions and errors out of the box.

Properties

id

The ID of the field.

handle

The handle of the field.

label

The label for the field.

instructions

The instructions for the field, if specified in form builder.

required

A boolean value. true if the field has been set to required in the form builder.

errors

An array of error message strings if any are present after submitting the form.

pageIndex

A number representing the page index this field resides on.

Custom Attributes (customAttributes)

An object of customizable attributes to ease the customizability of render methods. Contains the following properties (each one is null if not set):

• id
  • The ID attribute of the HTML input field for renderInput().
  • When used on renderLabel(), it will replace the default for attribute value.
• class
  • The CLASS attribute of the HTML input field for renderInput().
• labelClass
  • The CLASS attribute of the HTML label field for renderLabel().
• errorClass
  • The CLASS attribute of the errors HTML list for renderErrors().
• instructionsClass
  • The CLASS attribute of the instructions HTML field for renderInstructions().
• instructionsBelowField
  • Set to true to render instructions below, not above the input field when using the render() method.
• overrideValue
  • An override value for the field's defaultValue in case you need a context specific default value.
• inputAttributes
  • An object of attributes which will be added to the input field. If the form has inputAttributes specified, the attributes will be merged together with field inputAttributes taking precedence over form's inputAttributes, e.g.

    inputAttributes: {
    	"readonly": true,
    	"data-field-id": "test"
    }
• useRequiredAttribute: true
  • Adds required attribute to input fields that have been set to be required in the form builder.
• idAttribute
  • The ID for the field.
  • Considers the fieldIdPrefix parameter available to the Form query.
• inputAttributes
  • An array of input attributes specified for the field input in the Field Attribute table inside the form builder at template level.
  • For example, it may look something like this when hardcoding a form field:

    {% for option in field.inputAttributes %}
    	{{ option.attribute }}="{{ option.value }}"
    {% endfor %}
• labelAttributes
  • An array of label attributes specified for the field label in the Field Attribute table inside the form builder at template level.
• errorAttributes
  • An array of error attributes specified for the field error in the Field Attribute table inside the form builder at template level.
• instructionAttributes
  • An array of instruction attributes specified for the instruction input in the Field Attribute table inside the form builder at template level.
• value
  • The default or posted value of the field.
  • Can be a string, number or array (e.g. checkbox_group fields)
• valueAsString
  • The value value cast as a string.
  • Array values get joined via a , separator.
  • Uses the selected option labels for checkbox_group and radio_group.
    • Use getValueAsString(false) to use selected option values instead.
• type
  • The type of the field:
    • text
    • textarea
    • hidden
    • select
    • checkbox
    • checkbox_group
    • radio_group
    • email
    • dynamic_recipients
    • file
    • mailing_list
    • html
    • submit
    • number
    • ratingProSurveys & Polls
    • opinion_scaleProSurveys & Polls
    • tablePro
    • signaturePro
• rulesHtmlData
  • Parses the necessary code for Conditional Rules feature.
  • Should be used in automated form rendering, placed on the div wrapper for each field inside of for field in row.

    <div class="{{ columnClass }}"{{ field.rulesHtmlData }}>
  • Will render a data-ff-rule attribute along with the necessary string to work with Freeform's inserted JS for Rules feature, e.g.

    data-ff-rule='{"show":true,"type":"any","criteria":[{"tgt":"firstName","o":"=","val":"Bob"}]}'

Field Specific Properties

Each field type has their own specific properties available to them. Some are more complex than others. To see all available properties, check out the Fields documentation.

Methods

render()

Use this method to render a predefined, minimal markup html block containing the field's label, input field, instructions and list of errors. It can receive an object of customAttributes as the first and only argument (optional).

When using with HTML blocks or Submit buttons, use the hash value provided in property editor in the form builder as the handle. Example code would look like:

{{ form.get('Ajx7jNxXL').render }}

renderLabel()

Use this method to only render the label html field with the field's label inside. The label class can be overwritten via form's custom attributes or the field's custom attributes.

renderInput()

Use this method to only render the field's html input field. The class can be overwritten via form's custom attributes or the field's custom attributes.

The single Checkbox fieldtype has an additional method: renderSingleInput() to render the checkbox input without an additional hidden input. However, this is available as a workaround for special use-cases, and could have negative consequences for most regular setups and flows.

renderInstructions()

Use this method to only render the field's html instructions field. (Renders only if there are instructions present). The instructions field class can be overwritten via form's custom attributes or the field's custom attributes.

renderErrors()

Use this method to only render the error message block. (Renders only if there are errors present). The error list class can be overwritten via form's custom attributes or the field's custom attributes.

isValid()

Returns a boolean value of true if the form has been posted and this field doesn't contain any errors.

Usage in Templates

Simple Render

Render the whole field (label, input field, instructions and errors) with a single line:

{{ field.render() }}

Render Each Part Separately

Render each part of the field separately:

{{ field.renderLabel() }}
{{ field.renderInstructions() }}
{{ field.renderInput() }}
{{ field.renderErrors() }}

Customize Output

Fully customize the output of your field:

<label data-label class="label">
	{{ field.label }}
	{% if field.instructions %}
		<span class="instructions">{{ field.instructions }}</span>
	{% endif %}
</label>
<input type="text" name="{{ field.handle }}" value="{{ field.valueAsString }}" data-some-value="my_custom_value_here" />
{% if field.errors %}
	{% for errorString in field.errors %}
		<div class="error">{{ errorString }}</div>
	{% endfor %}
{% endif %}

Override Classes & Values

Render the whole field but override some of the HTML element classes:

{{ field.render({
	class: "freeform-input",
	labelClass: "freeform-label" ~ (field.required ? " freeform-required" : ""),
	errorClass: "freeform-errors",
	instructionsClass: "freeform-instructions",
	instructionsBelowField: true,
	overrideValue: "This is now the new default value",
	inputAttributes: {
		"data-field-id": field.id,
	}
}) }}