This document is for an older version of

Freeform

.

View latest version →
Freeform Freeform for ExpressionEngine
2.x Retired
Add-ons Store

Freeform_Next:Form tag

The Freeform_Next:Form template tag displays your form contents. You can either loop through automated rendering of form pages/rows/columns/fields (based on what is in Composer), or manually enter each field if you need full control for complex forms.

If you're wanting to simply render a complete form based on Composer layout and the assigned formatting template, you can just use the Freeform_Next:Render template tag (all of the same parameters below are available for it).

Form

Parameters

  • form #
    • Specify the handle of the form you'd like to be displayed.
  • form_id #
    • Specify the ID of the form you'd like to be displayed.
  • submission_token # Pro
    • Specify the token of the submission you'd like to be edited.
    • You can feed the submission token into the URL with the {submission:token} variable from a template that includes the Freeform_Next:Submissions template tag, or in email notification templates, etc.
  • input_class #
    • Overrides the class name of all input elements.
  • submit_class #
    • Overrides the class name of all submit elements.
  • row_class #
    • Overrides the class name of all row <div> elements.
  • column_class #
    • Overrides the class name of all field column <div> elements.
  • label_class #
    • Overrides the class name of all <label> elements.
  • error_class #
    • Overrides the class name of all error <ul> elements.
  • instructions_class #
    • Overrides the class name of all instruction <div> elements.
  • instructions_below_field #
    • If set to yes - will render field instructions below the <input> element.
  • class #
    • Overrides the <form> class name.
  • id #
    • Overrides the <form> ID attribute.
  • return_url or return #
    • Overrides the return URL (set inside Composer) for the form.
    • Use SUBMISSION_ID to generate the future submission ID in the return URL.
    • Use SUBMISSION_TOKEN to generate the future submission token in the return URL (great for more securely displaying submission details on return page).
  • method #
    • Overrides the <form> method attribute. POST by default.
  • name #
    • Overrides the <form> name attribute.
  • action #
    • Overrides the <form> action attribute.
  • use_action_url="yes" #
    • Available as a workaround when loading a form with AJAX and submitting normally, etc.
  • override_values #
    • Allows overriding the default values for any field:
      • Specify the field handle and provide the custom value override as its value.
      • E.g. override_values:location="{segment_3}".
      • If a field uses an override_value attribute, it will take precedence over the value specified in this attribute.
  • form_attributes #
    • Attributes which will be added to the form.
    • E.g. form_attributes:novalidate="true", form_attributes:data-form-id="test"
    • To achieve something like <form novalidate>, just specify form_attributes:novalidate instead of form_attributes:novalidate="true".
  • input_attributes #
    • Attributes which will be added to all input fields.
    • E.g. input_attributes:readonly="true", input_attributes:data-field-id="test"
  • use_required_attribute="yes" #
    • Adds required attribute to input fields that have been set to be required in Composer.
  • field_id_prefix="myform-" #
    • Adds a prefix value on field outputs. Helpful if you have more than 1 form on the same template and are sharing fields.
  • dynamic_notification_recipients #
    • Allows using a dynamic template level notification for a more fine-grained control.
    • Hard code values or pass a value from a channel entry, etc, e.g. dynamic_notification_recipients="admin@example.com|support@example.com"
    • REQUIRED: Use with dynamic_notification_template="test.html" parameter to specify the notification template to be used.
      • For Database entry based templates, specify the handle name.
      • For HTML file based templates, specify the full file name including .html.
  • no_form_tags #
    • Specify a value of yes to prevent the <form> tags from rendering.
    • Helpful in some scenarios where you might be using the Freeform_Next:Form template tag to render some field data, such as a table header for Submissions list (see demo templates).

Variables

  • {form:name} #
    • Outputs the name of the form.
  • {form:handle} #
    • Outputs the handle of the form.
  • {form:id} #
    • Outputs the unique ID of the form.
  • {form:description} #
    • Outputs the description of the form.
  • {form:return_url} #
    • Outputs the return URL of the form.
  • {current_page:label} #
    • Returns the current page label.
  • {current_page:index} #
    • Returns the current page index, e.g. 0, 1, etc.
  • Custom Attributes #
    • The following variables are available to help with formatting, based on what you have specified in Composer or the corresponding parameters:
      • {form:id_attribute} #
        • The ID attribute of the HTML form tag.
      • {form:class} #
        • The CLASS attribute of the HTML form tag.
      • {form:method} #
        • The METHOD attribute for the form tag.
      • {form:action} #
        • The ACTION attribute for the form tag.
      • {form:row_class} #
        • The CLASS attribute of all HTML row tags.
      • {form:column_class} #
        • The CLASS attribute of all HTML column tags.
  • {column:grid_width} #
    • Outputs the grid width (out of 12) for the column that contains the field. Aids with setting up responsive template.
  • {column:count} #
    • Outputs the total number of columns (fields) for the row.
  • {column:index} #
    • Outputs the column number for specific column (field) of that row, e.g. 0, 1, 2, 3.
  • Manual Fields #
    • You can manually construct forms with any Freeform field variable, using the proper syntax:
      • {field:field_name:label} - displays the label (name) of the field.
      • {field:field_name:value} - displays the option label(s) submitted (for form reloading upon submit error).
      • {field:field_name:handle} - displays the handle of the field.
      • {field:field_name:placeholder} - displays the placeholder of the field (when applicable).
      • {field:field_name:options}{/field:field_name:options} - variable pair that helps render fields with multiple options like select fields, etc.
        • {option:value} - the option value for the field option.
        • {option:label} - the option label for the field option.
        • {if option:checked}selected{/if} - check if the field option is selected/checked.
        • Example code would look something like this:
<select name="{field:state:handle}">
	{field:state:options}
	<option value="{option:value}" {if option:checked}selected{/if}>
		{option:label}
	</option>
	{/field:state:options}
</select>
1
2
3
4
5
6
7
  • Also available are automated rendering options for manually constructed forms:
    • {field:field_name:render} - renders complete field (label, input, etc). The following override parameters are available:
      • id - overrides ID for input(s)
      • class - overrides class for input(s)
      • label_class - overrides class for label
      • error_class - adds class to ul generated for error(s)
      • instructions_class - adds class to div generated for instructions
      • instructions_below_field="yes" - loads instructions below input rather than above
      • input_attributes
        • Attributes to be added to the input field, e.g. input_attributes:readonly="true", input_attributes:data-field-id="test"
      • override_value
        • Override the value for the input field, e.g. override_value="test"
      • Manually rendering reCAPTCHA (Pro) fields need to be called like this (using the Hash value for reCAPTCHA field in Property Editor of Composer, e.g. MD1KzPw68):
        • {field:grecaptcha_MD1KzPw68:render}
    • {field:field_name:render_label} - renders the complete label. The following override parameters are available:
      • label_class
    • {field:field_name:render_input} - renders the complete input. The following override parameters are available:
      • class
      • input_attributes
        • Attributes to be added to the input field, e.g. input_attributes:readonly="true", input_attributes:data-field-id="test"
      • override_value
        • Override the value for the input field, e.g. override_value="test"
    • {field:field_name:render_instructions} - renders the instructions. The following override parameters are available:
      • instructions_class
    • {field:field_name:render_errors} - renders the errors. The following override parameters are available:
      • errors_class
  • For a more robust automated rendering of fields, see the {fields}{/fields} variable pair.

Variable Pairs

  • {pages}{/pages} #
    • Handles formatting options for displaying list of pages for multi-page forms.
      • {page:index} - page number
      • {page:label} - name of the page (set in Composer)
      • {current_page:index} - page number of currently viewed page
      • {form:page_count} - total number of pages for the form
    • Typical usage looks something like this:
{if form:page_count > 1}
	<ul class="nav nav-tabs">
	{pages}
		<li class="{if page:index == current_page:index}active{if:else}disabled{/if}">
			<a href="javascript:;">{page:label}</a>
		</li>
	{/pages}
	</ul>
{/if}
1
2
3
4
5
6
7
8
9
  • {rows}{/rows} #
    • Handles formatting options for displaying rows of fields in layout (set by Composer).
  • {fields}{/fields} #
    • Handles formatting options for displaying columns of fields in layout (set by Composer).
    • Not required if rendering a form manually.
    • The following variables and variable pairs are available for use when rendering your form:
      • {field:label} - label of field, e.g. First Name
      • {field:handle} - handle for field, e.g. first_name
      • {field:instructions} - instructions for field, e.g. Please select from the following
      • {field:placeholder} - placeholder for field (where applicable), e.g. you@yourdomain.com
      • {field:type} - type of field:
        • text
        • textarea
        • hidden
        • select
        • checkbox
        • checkbox_group
        • radio_group
        • email
        • dynamic_recipients
        • file
        • mailing_list
        • html
        • submit
        • confirmation (Pro)
        • datetime (Pro)
        • phone (Pro)
        • rating (Pro)
        • regex (Pro)
        • website (Pro)
      • {field:required} - renders as 1 if field is set to be required. Used as a conditional.
      • {field:options}{/field:options} - variable pair for formatting options for multi-option fields.
        • {option:label} - label of option, e.g. California
        • {option:value} - value of the option, e.g. CA
        • {option:checked} - renders as 1 if the option should be checked. Used as a conditional.
        • {option:index} - the order number of the option, e.g. 4
      • {field:show_as_radio} - specific to Dynamic Recipients fieldtype.
      • {field:position} - positioning of field (submit fields), e.g. submit-align-left
    • Also available are automated rendering options:
      • {field:render} - renders complete field (label, input, etc). The following override parameters are available:
        • id
        • class
        • label_class
        • error_class
        • instructions_class
        • instructions_below_field="yes"
        • input_attributes
          • Attributes to be added to the input field, e.g. input_attributes:readonly="true", input_attributes:data-field-id="test"
        • override_value
          • Override the value for the input field, e.g. override_value="test"
      • {field:render_label} - renders the complete label. The following override parameters are available:
        • label_class
      • {field:render_input} - renders the complete input. The following override parameters are available:
        • input_class
        • input_attributes
          • Attributes to be added to the input field, e.g. input_attributes:readonly="true", input_attributes:data-field-id="test"
        • override_value
          • Override the value for the input field, e.g. override_value="test"
      • {field:render_instructions} - renders the instructions. The following override parameters are available:
        • instructions_class
      • {field:render_errors} - renders the errors. The following override parameters are available:
        • errors_class

Conditionals

  • {if form:no_results}{/if} #
    • Displays its contents when there are no results found for this template tag with the given set of parameters.
  • {if form:has_errors}{/if} #
    • Displays its contents when there are errors after attempting to submit the form.
  • {if form:is_submitted_successfully}{/if} #
    • Session success flash message.
    • Displays only once after a form is successfully submitted.

Examples

Below shows a variety of approaches available to render your forms. For more complete examples for use with front-end frameworks like Bootstrap, see the Formatting Template Examples documentation.

Render Examples

Render the form using its formatting template with the Render template tag:

{exp:freeform_next:render form="contact_form"}
1

Render the form using its formatting template, but overriding some classes with the Render template tag:

{exp:freeform_next:render
	form="contact_form"
	label_class="form-label"
	input_class="form-control"
	instructions_below_field="yes"
	submit_class="btn btn-success"
	override_values:location="{segment_3}"
}
	{if form:no_results}Sorry, no form was found.{/if}
{/exp:freeform_next:render}
1
2
3
4
5
6
7
8
9
10

Render a form automatically with some control on formatting:

{exp:freeform_next:form
	form="contact_form"
	return_url="{path='about/contact'}"
	id="myform"
	class="form-class"
	row_class="sample-row-class"
	submit_class="button"
}

	{if form:page_count > 1}
		<ul class="freeform-pages">
		{pages}
			<li>
			{if page:index == current_page:index}
				<a href="javascript:;">{page:label}</a>
			{if:else}
				{page:label}
			{/if}
			</li>
		{/pages}
		</ul>
	{/if}

	{if form:has_errors}
		<div class="freeform-form-has-errors">
			There was an error submitting this form
		</div>
	{/if}

	{rows}
		<div class="freeform-row {form:row_class}">
		{fields}
			<div class="freeform-column {form:column_class}{if field:type == 'submit'} freeform-column-content-align-{field:position}{/if}">
				{field:render
					class="{if field:type != 'submit'}freeform-input{/if}"
					label_class="freeform-label{if field:required} freeform-required{/if}{if field:input_only} freeform-input-only-label{/if}"
					error_class="freeform-errors"
					instructions_class="freeform-instructions"
				}
			</div>
		{/fields}
		</div>
	{/rows}

{/exp:freeform_next:form}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

Advanced Forms

Here is a more complex form (made to work with Bootstrap):

<style>label.required:after {content:"\*";color:#d00;margin-left:5px;}.submit-align-left{text-align:left}.submit-align-right{text-align:right}.submit-align-center{text-align:center}.submit-align-center button:not(:first-of-type),.submit-align-left button:not(:first-of-type),.submit-align-right button:not(:first-of-type){margin-left:5px}.submit-align-spread button:first-child{float:left}.submit-align-spread button:last-child{float:right}</style>

{exp:freeform_next:form
	form="contact_form"
	return_url="{path='about/contact'}"
}

	{if form:page_count > 1}
		<ul class="nav nav-tabs">
		{pages}
			<li class="{if page:index == current_page:index}active{if:else}disabled{/if}">
				<a href="javascript:;">{page:label}</a>
			</li>
		{/pages}
		</ul>
	{/if}

	{if form:has_errors}
		<div class="alert alert-danger">
			There was an error submitting this form
		</div>
	{/if}

	{rows}
		<div class="row {form:row_class}">
		{fields}
			<div class="{form:column_class} col-xs-12 col-lg-{column:grid_width} {if field:type == 'checkbox' OR field:type == 'mailing_list'}checkbox{if:else}form-group{/if}{if field:has_errors} has-error{/if}{if field:type == 'submit'} submit-align-{field:position}{/if}">
			{if field:type == 'checkbox_group'}

				{field:render_label label_class="{if field:required}required{/if}"}

				{field:options}
					<div class="checkbox">
						<label>
							<input type="checkbox"
								name="{field:handle}[]"
								value="{option:value}"
								{if option:checked}checked{/if}
							/>
							{option:label}
						</label>
					</div>
				{/field:options}

				{field:render_instructions instructions_class="help-block"}
				{field:render_errors error_class="help-block"}

			{if:elseif field:type == 'radio_group' OR (field:type == 'dynamic_recipients' AND field:show_as_radio)}

				{field:render_label label_class="{if field:required}required{/if}"}

				{field:options}
					<div class="radio">
						<label>
							<input type="radio"
								name="{field:handle}"
								value="{option:value}"
								{if option:checked}checked{/if}
							/>
							{option:label}
						</label>
					</div>
				{/field:options}

				{field:render_instructions instructions_class="help-block"}
				{field:render_errors error_class="help-block"}

			{if:elseif field:type == 'submit'}

				{field:render}

			{if:else}

				{field:render
					class="{if field:type == 'checkbox' OR field:type == 'mailing_list'}checkbox{if:else}form-control{/if}"
					label_class="{if field:required}required{/if}"
					error_class="help-block"
					instructions_class="help-block"
					instructions_below_field="yes"
				}

			{/if}
			</div>
		{/fields}
		</div>
	{/rows}

{/exp:freeform_next:form}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

Manual Forms

Form formatting can also be very manual or semi manual, if that is something you prefer. Here's an example of different levels of manual you can use:

{exp:freeform_next:form
	form="contact_form"
	return_url="{path='about/contact'}"
}

	{if form:is_submitted_successfully}
		{!-- Session success flash message - displays only once after a form is successfully submitted --}
		<div class="success">Form submitted successfully!</div>
	{/if}

	{if form:has_errors}
		<div class="error">There was an error submitting this form.</div>
	{/if}

	<h3>{form:name}</h3>

	<ul>
		<li>
			<label for="first_name">Name (required)</label>
			<input type="text" name="first_name" value="{field:first_name:value}" />
			<input type="text" name="last_name" value="{field:last_name:value}" />
			{field:first_name:render_errors error_class="field-error"}
			{field:last_name:render_errors error_class="field-error"}
		</li>
		<li>
			{field:email:render
				class="email-field"
				placeholder="you@youremail.com"
			}
		</li>
		<li>
			<label for="city">City</label>
			<input type="text" name="city" value="{field:city:value}" />
			{if field:city:render_errors}
				<div class="field-error">This field is required!</div>
			{/if}
		</li>
		<li>
			{field:state:label}
			{field:last_name:render_instructions instructions_class="field-instructions"}
	 		<select name="{field:state:handle}">
				{field:state:options}
				<option value="{option:value}" {if option:checked}selected{/if}>
					{option:label}
				</option>
				{/field:state:options}
			</select>
			{field:last_name:render_errors error_class="field-error"}
		</li>
		<li>
			{field:how_you_found_us:render}
		</li>
		<li>
			{field:department:label}
			<select name="{field:department:handle}" type="dynamic_recipients">
			{field:department:options}
				<option value="{option:index}" {if option:checked}selected{/if}>
					{option:label}
				</option>
			{/field:department:options}
			</select>
		</li>
		<li>
			<button type="submit">Submit</button>
		</li>
	</ul>

	{if form:no_results}
		<div class="error">This form does not exist.</div>
	{/if}

{/exp:freeform_next:form}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

Manual Multi-page Forms

Building multi-page forms manually can get a bit tricky. For this, we do recommend using the automated flow for multi-page forms. However, if you must, what you need to do is perform a conditional check on {current_page:index}, where page one is 0, page two is 1, page three is 2, etc, and place your fields within those conditionals. If you wish to include a Previous page button, be sure that it is given a name of form_previous_page_button and Freeform will take care of the rest. So something like this:

{exp:freeform_next:form
	form="my-multipage-form"
	return_url="{path='freeform_next_demo/manual_multipage'}"
}

	{if form:is_submitted_successfully}
		{!-- Session success flash message - displays only once after a form is successfully submitted --}
		<div class="success">Form submitted successfully!</div>
	{/if}

	{if form:has_errors}
		<div class="error">There was an error submitting this form.</div>
	{/if}

	<h3>{form:name}</h3>

	<ul class="page-tabs">
	{pages}
		<li class="{if page:index == current_page:index}active{if:else}disabled{/if}">
			{page:label}
		</li>
	{/pages}
	</ul>

	<ul>
	{if current_page:index == 0} {!-- SHOW PAGE 1 --}
		<li>
			<label for="first_name">Name (required)</label>
			<input type="text" name="first_name" value="{field:first_name:value}" />
			<input type="text" name="last_name" value="{field:last_name:value}" />
			{field:first_name:render_errors error_class="field-error"}
			{field:last_name:render_errors error_class="field-error"}
		</li>
		<li>
			{field:email:render
				class="email-field"
				placeholder="you@youremail.com"
			}
		</li>
		<li>
			<button type="submit" name="form_page_submit">Continue</button>
		</li>
	{/if}
	{if current_page:index == 1} {!-- SHOW PAGE 2 --}
		<li>
			<label for="city">City</label>
			<input type="text" name="city" value="{field:city:value}" />
			{if field:city:render_errors}
				<div class="field-error">This field is required!</div>
			{/if}
		</li>
		<li>
			{field:state:label}
			{field:last_name:render_instructions instructions_class="field-instructions"}
	 		<select name="{field:state:handle}">
				{field:state:options}
				<option value="{option:value}" {if option:checked}selected{/if}>
					{option:label}
				</option>
				{/field:state:options}
			</select>
			{field:last_name:render_errors error_class="field-error"}
		</li>
		<li>
			<button type="submit" name="form_previous_page_button">Previous</button>
			<button type="submit" name="form_page_submit">Continue</button>
		</li>
	{/if}
	{if current_page:index == 2} {!-- SHOW PAGE 3 --}
		<li>
			{field:how_you_found_us:render}
		</li>
		<li>
			{field:department:label}
			<select name="{field:department:handle}" type="dynamic_recipients">
			{field:department:options}
				<option value="{option:index}" {if option:checked}selected{/if}>
					{option:label}
				</option>
			{/field:department:options}
			</select>
		</li>
		<li>
			<button type="submit" name="form_previous_page_button">Previous</button>
			<button type="submit" name="form_page_submit">Finish</button>
		</li>
	{/if}
	</ul>

	{if form:no_results}
		<div class="error">This form does not exist.</div>
	{/if}

{/exp:freeform_next:form}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

© 2024 Solspace, Inc.

Icons created by Smashicons from Flaticon.

Solspace is not just a plugin company. We also build and maintain websites. In fact, we often help other developers with their website builds. Learn more about our second chair development services today.