Form object
The Form object contains its metadata and field objects. You can either render the form using the pre-selected formatting template by calling form.render() or achieve a more fine-grained control over it by iterating over its rows and fields and using form.renderTag and form.renderClosingTag methods.
Freeform will automatically insert javascript in the footer of the page for features such as Spam Protection, Submit disable on click, and other special fieldtypes. If you prefer to have this load inside the <form></form> tags, you can adjust the Script Insert Location Location setting.
Properties
name
Outputs the name of the form.
handle
Outputs the handle of the form.
id
Outputs the unique ID of the form.
description
Outputs the description of the form.
submissionTitleFormat
Outputs the submission title format used when creating new submissions based on this form.
returnUrl
Outputs the return URL of the form.
successMessage
Outputs the custom success message configured in the Validation tab for your form inside the form builder.
errorMessage
Outputs the custom error message configured in the Validation tab for your form inside the form builder.
hasErrors
A bool variable, which will be true if there are any errors in any of the fields or the form. It might be true even if form.errors list is empty, (e.g. if one or more fields have an error). This can be used in conjunction with the Errors object for displaying special and general errors.
pages
Returns a list of Page objects each containing its label and index.
currentPage
Returns the current Page object containing its label and index.
duplicate Renamed and Revised in 5.0+
A bool variable, which will be true if the form has the Duplicate Check setting enabled (duplicate submission check) and the user has already submitted the form.
isIntegrationEnabled New in 5.6+
Allows you to check if an integration is enabled for a form. Use the integration handle you created for each integration.
For Singles, the handles are:
- Honeypot:
honeypot - Javascript Test:
javascript-test - Google Tag Manager:
gtm - Post Forwarding:
post-forwarding
<ul>
{% if form.isIntegrationEnabled("mailchimp") %}
<li>Mailchimp is enabled</li>
{% endif %}
{% if form.isIntegrationEnabled("honeypot") %}
<li>Honeypot is enabled</li>
{% endif %}
{% if form.isIntegrationEnabled("recaptchaV3") %}
<li>reCAPTCHA v3 is enabled</li>
{% endif %}
</ul>
Template OverridesNew in 5.0+
The form and each field have the ability to control attributes, values and more at the template level. Each one of them is entirely optional. There are several namespaces:
attributes- whatever you specify here will be set as an attribute on the form.buttons- controls the output of the Submit button(s).fields- controls the output of all Fields.captchas- add attributes to the main Captcha wrapper automatically inserted by Freeform when using reCAPTCHA or hCaptcha.
Please see the Template Overrides documentation for detailed instructions.
Usage in Templates
Simple Render
A basic implementation might look like this:
{% set form = freeform.form("myFormHandle") %}
{{ form.render() }}
Override Classes & Values
Once Template Overrides have been implemented, your code might look something like this:
{% set form = freeform.form("myFormHandle") %}
{{ form.render({
attributes: {
novalidate: true,
class: "my-form-class",
},
buttons: {
attributes: {
submit: { class: "form-field-button blue" },
back: { class: "form-field-button gray" },
},
},
fields: {
"@global": {
attributes: {
input: {
class: "form-field-input",
},
label: {
class: "form-field-label",
},
},
},
":required": {
attributes: {
label: { "+class": "form-field-required" },
},
},
":errors": {
attributes: {
input: { "+class": "form-field-is-invalid" },
},
},
"@dropdown": {
attributes: {
container: {
"data-select-container": true,
},
input: {
"+class": "form-field-select fullwidth",
},
},
},
"@checkboxes, @radios" : {
attributes: {
input: {
"+class": "form-field-options",
},
},
},
"myFieldHandle": {
value: entry.id,
},
},
}) }}
Manually Iterate
Manually iterate through form fields inside your regular template:
{# Set the form #}
{% set form = freeform.form("myFormHandle") %}
{# Render the opening form tag #}
{{ form.renderTag({
attributes: {
row: { class: "freeform-row" },
success: { class: "freeform-form-success" },
errors: { class: "freeform-form-errors" },
novalidate: true,
},
buttons: {
attributes: {
container: { class: "freeform-button-container" },
column: { class: "freeform-button-column" },
buttonWrapper: { class: "freeform-button-wrapper" },
submit: { class: "freeform-button-submit" },
back: { class: "freeform-button-back" },
save: { class: "freeform-button-save" },
},
},
fields: {
"@global": {
attributes: {
container: { class: "freeform-column" },
input: {
"data-field": true,
class: "freeform-input",
},
label: { class: "freeform-label" },
instructions: { class: "freeform-instructions" },
error: { class: "freeform-errors" },
},
},
":required": {
attributes: {
label: { "+class": "freeform-required" },
},
},
":errors": {
attributes: {
input: { "+class": "is-invalid has-validation" },
},
},
"@group": {
attributes: {
label: { "+class": "group-label" },
},
},
"@signature": {
attributes: {
input: { "-class": "freeform-input" },
},
}
},
}) }}
{# Success and error message handling for non-AJAX forms #}
{% if not form.settings.ajax %}
{% if form.submittedSuccessfully %}
<div{{ form.attributes.success|raw }}>
<p>{{ form.settings.successMessage | t('freeform') }}</p>
</div>
{% endif %}
{% if form.hasErrors %}
<div{{ form.attributes.errors|raw }}>
<p>{{ form.settings.errorMessage | t('freeform') }}</p>
{% if form.errors|length %}
<ul>
{% for error in form.errors %}
<li>{{ error }}</li>
{% endfor %}
</ul>
{% endif %}
</div>
{% endif %}
{% endif %}
{# Render page tabs if multi-page #}
{% if form.pages|length > 1 %}
<ul class="freeform-pages">
{% for page in form.pages %}
<li {% if form.currentPage.index == page.index %}class="active"{% endif %}>
{% if form.currentPage.index == page.index %}
<b>{{ page.label }}</b>
{% else %}
{{ page.label }}
{% endif %}
</li>
{% endfor %}
</ul>
{% endif %}
{# Build form rows and fields #}
{% macro renderRows(form, rows) %}
{% for row in rows %}
{% set width = (12 / (row|length)) %}
<div{{ form.attributes.row|raw }}>
{% for field in row %}
{% do field.setParameters({
attributes: {
container: { class: [
"freeform-column-" ~ width,
"freeform-fieldtype-" ~ field.type,
]},
},
}) %}
{% if field.type == "group" %}
<div class="freeform-group">
<label{{ field.attributes.label }}>
{{ field.label }}
</label>
<div>
{{ _self.renderRows(form, field.layout) }}
</div>
</div>
{% else %}
{{ field.render }}
{% endif %}
{% endfor %}
</div>
{% endfor %}
{% endmacro %}
{# Display form field rows and columns #}
{{ _self.renderRows(form, form.rows) }}
{# Render the closing form tag #}
{{ form.renderClosingTag }}
Success Flash
When not using AJAX, the session success flash message (displays only once) when the form is successfully submitted:
{% set form = freeform.form("myForm") %}
{% if form.submittedSuccessfully %}
<div>You've successfully submitted this form!</div>
{% endif %}
{{ form.render }}
Error when Duplicate
Display a message when the submission is a duplicate:
{% set form = freeform.form("myForm") %}
{% if form.duplicate %}
<div class="alert alert-warning duplicate">
You've already submitted this form!
</div>
{% else %}
{{ form.render }}
{% endif %}