Freeform for ExpressionEngine

Classic Retired

• 3.x✓ Latest
• 2.xRetired
• 1.xRetired
• ClassicRetired

Add-ons Store

# Freeform:Form template tag

The Freeform:Form tag is what is used to generate forms in your EE templates. A wide variety of forms can be created, including contact forms, multi-page surveys, testimonials, etc. Form submissions are stored in the database and their content can be reviewed, displayed on front end templates with Freeform:Entries tag, formatted and emailed to admins and/or the user that submitted the form, etc. File Attachments can also be received, stored and included in email notifications. You must select from valid Freeform Classic custom fields that are created in the Freeform Classic control panel. Freeform Classic entries are available for editing. For editing, see the Freeform:Edit documentation.

If you have created a complete form in Composer, then you'll need to use the Freeform:Composer tag to parse your form.

{exp:freeform:form} content {/exp:freeform:form}

# Parameters

# form:ATTRIBUTE_NAME=

form:class="your_class_name"

This parameter allows you to control any form attribute for the form in your template. Simply replace ATTRIBUTE_NAME with an attribute name such as id, name, class, onsubmit, etc, and specify a value for that attribute. You can specify this parameter multiple times to control as many attributes as necessary. This would normally be done to control your form with Javascript or style it with CSS.

# form_id=

form_id="4"

Specify the ID of the form you created in the Freeform Classic control panel so that Freeform knows which form the submissions should be tied to. Alternatively, you can use the form_name parameter.

# form_name=

form_name="contact_form"

Specify the short name of the form you created in the Freeform Classic control panel so that Freeform knows which form the submissions should be tied to. Alternatively, you can use the form_id parameter.

# required=

required="name|email"

Specify the short name of each Freeform field you want to be required to be completed by the user before form submission. Separate multiple values with the pipe character. When using multipage forms, this parameter should be applied directly to the freeform:page:1 variable pairs.

# return=

return="template_group/template"

return="template_group/template/%%entry_id%%"

This parameter lets you set where to send users once they have submitted the form. If not specified, the user will be returned to the same page. If you'd like to send the user to a page with the newly created Freeform entry ID in the URI, just add %%entry_id%% to the end of the URL you've specified in the return parameter. That variable will be replaced by the Freeform entry ID of the newly submitted entry. This parameter can be overridden by the return field.

# status=

status="closed"

This parameter allows you to override the default status set for the form (in the Freeform control panel) for all entries submitted.

# ajax=

ajax="no"

By default, Freeform auto-detects if you are using AJAX for the form submission. AJAX requests will return errors and success messages in JSON. If you wish to disable this, specify a value of no.

# allow_status_edit=

allow_status_edit="yes"

This parameter let you have your users specify a status for the form and override the default status set for the form (in the Freeform control panel). Used in conjunction with the status form field and freeform:statuses variable pair.

# error_page=

error_page="path_to/template"

This parameter allows you to bypass the EE message template for displaying errors, and instead show your own regular template with the error messages. Your error template must follow guidelines mentioned in Freeform Error Page. If the inline_errors parameter is called (with a value of yes), it overrides this error_page parameter.

# inline_errors=

inline_errors="yes"

This parameter allows you to bypass the EE message template for displaying errors, and instead show inline error messages on your form. What it does is when there is any error(s) on form submission, it reloads the page with the previously entered values, but your freeform:error:FIELD_NAME conditional evaluates to true, and the variable parses out as the appropriate error message for that field. If you wish to adjust the return URL from something different that reloading the same page, refer to the inline_error_return parameter. If this parameter is called (with a value of yes), it overrides this error_page parameter.

# inline_error_return=

inline_error_return="path_to/template_name"

This parameter is used in conjunction with the inline_errors parameter, and allows you to specify your own return URL for when errors occur on form submission, instead of reloading the same page. Typically you would want to just reload the same page with the errors shown inline, but this parameter is available in the event you have a particular or complicated case for it. Simply specify the URI path you'd like the form to return to.

# matching_fields=

matching_fields="email"

This parameter allows you to use and validate confirmation/matching fields. For example, if you want a user to enter their email address a second time as a confirmation, you would enter that fields' name in this parameter. To create the extra form field, just copy and paste the field again, but append _confirm to the name of the field. If the values in the 2 fields do NOT match, an error will be shown upon submit. To specify multiples, separate with pipe character (|). The parameter would look like this:

matching_fields="email"

And your form fields would look like this:

<input type="text" name="email" />
<input type="text" name="email_confirm" />

# require_captcha=

require_captcha="yes"

Freeform respects the setting you have for the Require CAPTCHA with logged-in members? preference in the EE control panel (Admin -> CAPTCHA Preferences) to display and require a CAPTCHA for logged in members. ExpressionEngine will not allow this preference to be overridden. This parameter is only effective on logged in members if the preference in the control panel is set to YES or the config item: require_member_captcha is set to y.

# require_ip=

require_ip="yes"

By default, Freeform will verify that the user submitting has a recordable IP address based on the setting for the Require IP Address and User Agent for posting? preference in the EE control panel (Admin -> Security and Session Preferences). To override this, specify a value of yes or no.

# secure_action=

secure_action="yes"

This parameter allows you to set the action on the form to have https://. Used for securely processing forms with SSL.

# secure_return=

secure_return="yes"

This parameter allows you to set the return on the form to have https://. Used for securely processing forms with SSL.

# multipage=

multipage="yes"

This parameter is used with a value of yes if the form is to span across more than 1 page. Default is no. Used in conjunction with the freeform:page:1 variable pairs.

# multipage_page=

multipage_page="billing"

When using multipage forms, Freeform will automatically look for a page segment in the URI. If it finds none, it will show page 1. If it finds a page name or ID, it will show that page. In the event you wish to start the form at a page other than page 1, or force the current page with a segment, you can hardcode or feed a page name or ID in this parameter.

This can be useful when using multipage forms with other third party addons that transform urls.

{exp:freeform:form
    multipage="yes"
    multipage_page_names="contact_info|billing|confirm"
    multipage_page="{segment_3}"
    }

# multipage_page_names=

multipage_page_names="contact_info|billing|confirm"

This parameter allows you to create custom page names (in the URI) for your multi-page form. By default, the values are page1, page2, page3, etc. If you have a 3-page form and you want the page names to be contact_info, billing, and confirm (and in that order), you would specify those page names in this parameter in the order you want them (see given example above). The naming of the freeform:page:1 variable pairs will then match the names you have in this parameter (ex: freeform:page:contact_info, freeform:page:billing, etc).

# page_marker=

page_marker="step"

The default page marker is page. If you do not have custom page names for your multi-page form, then default is page1, page2, page3, etc. If you set this parameter to have a value of step, then your page names will become step1, step2, step3, etc

# paging_url=

paging_url="/group/template/%page%/other_segment/"

The paging_url paramter is used to allow fine tuning of where next page urls on multipage forms are sent. The default paging_url is the current URL with %page% at the end or if not on the first page, %page% is wherever the multipage page name or marker+number is found. %page% in this parameter represents where the multipage marker will be in the url after a page is submitted.

For example: If you have parameters like so:

multipage_page_names="name|address|message|finish"
paging_url="/group/template/%page%/other_segment/"

And you submit page one, you will be taken to:

http://example.com/group/template/message/other_segment/

# redirect_on_timeout=

redirect_on_timeout="no"

This parameter lets you specify whether or not the user should be redirected upon timeout of completing form. This respects the Multi-page Form Completion Timeout setting in the Preferences page in the Freeform control panel area (default is 3 hrs per page). If the form times out, all data on the current page and previous page(s) will be lost and the user will have to start over. This parameter defaults to yes. To disable this, specify no. If yes is specified, the user will be redirected to the path specified in the redirect_on_timeout_to parameter. If no is specified, the page will just reload and start at page 1.

# redirect_on_timeout_to=

redirect_on_timeout_to="path_to/error_message"

If the redirect_on_timeout parameter is set to yes, the user will be redirected to the template path specified in this parameter if the form expires.

# admin_notify=

admin_notify="name@domain.com|name2@domain.com"

This parameter is used to specify an admin email address(es) to receive an email notification upon successful submission of the form. Separate multiple values with commas or the pipe character (|). By default, Freeform will use the email(s) specified in the form itself in the Freeform control panel. If this parameter is specified, it will override that preference. Used in conjunction with the admin_notification_template parameter. NOTE: If you're having trouble receiving email notifications, please make sure the email address the notification is being sent from is valid (actually created on the server).

# admin_cc_notify=

admin_cc_notify="name@domain.com"

This parameter is used to specify an admin email address(es) to receive an email notification as a carbon copy upon successful submission of the form. Used in conjunction with the admin_notification_template parameter.

# admin_bcc_notify=

admin_bcc_notify="name@domain.com"

This parameter is used to specify an admin email address(es) to receive an email notification as a blind carbon copy upon successful submission of the form. Used in conjunction with the admin_notification_template parameter.

# admin_notification_template=

admin_notification_template="billing_enquiry"

This parameter is used to specify which notification template should be used to generate the email notification for admin notifications. Using this parameter will override the default template specified in the Freeform control panel. Used in conjunction with the notify_admin parameter, and the admin_notify, admin_cc_notify, and admin_bcc_notify parameters.

# notify_admin=

notify_admin="yes"

Override whether or not email notifications should be sent to admins. By default, Freeform will respect the settings for the form given in the Freeform control panel. Used in conjunction with the admin_notification_template parameter, and the admin_notify, admin_cc_notify, and admin_bcc_notify parameters.

# notify_user=

notify_user="yes"

Override whether or not email notifications should be sent to the user that submitted the form. By default, Freeform will respect the settings for the form given in the Freeform control panel. Used in conjunction with the user_notification_template and user_email_field parameters.

# user_email_field=

user_email_field="customer_email"

In the event you wish to have users receive an email notification of their submission, this parameter is necessary to let Freeform know which field contains the users' email address. Simply specify the short name of the custom Freeform field that contains it. Used in conjunction with the notify_user and user_notification_template parameters.

# user_notification_template=

user_notification_template="confirmation_email"

This parameter is used to specify which notification template should be used to generate the email notification for the user that fills out the form. Using this parameter will override the default template specified in the Freeform control panel. Used in conjunction with the notify_user and user_email_field parameters.

# recipients=

recipients="yes"

This parameter allows you to let your users select recipient email addresses dynamically within the form itself. So for example, you can have a dropdown select menu that allows your users to select the destination for their email (Sales, Support, Service, etc). You can have corresponding email addresses to those options and the result is that the user can direct which email the notification should go to. This form field must be named recipient_email in order to work. Please see the recipient_email form field for more information.

# recipients_limit=

recipients_limit="3"

Allows you to set a maximum amount of recipients that can be sent to at once (for spam control measures), specifically in regards to the recipient1 parameter method. Default value is 3. Used in conjunction with the recipients and recipient1 parameters.

# recipient1=

recipient1="John McCrackin|john@mccrackinandco.com" OR recipient1="john@mccrackinandco.com"

If you're using the recipients feature (allows you to let your users select recipient email addresses dynamically within the form itself), this parameter allows you to securely list available recipients. You can just specify the recipients email, OR if you wish you can also specify the recipients name before the email, separated by the pipe character. You can create as many recipients as you wish. For each recipient, add a recipient parameter to your form tag and name them recipient1, recipient2, recipient3 successively. The values in these parameters are then available to use as variables in your form. See freeform:recipient_value1 and freeform:recipient_name1 variables. Used in conjunction with the recipient_email form field and recipients_limit parameter.

# recipient_template=

recipient_template="contact_form"

Specify a notification template you created in the Notifications tab in the Freeform control panel area. This is the notification that is sent out to the email address selected in the form field. To be used in conjunction with the recipients and recipient1 parameters.

# recipient_user_input=

recipient_user_input="yes"

If you wish to allow users to enter in their own recipient emails into an input field (for example: Tell-a-Friend form), specify a value of yes for this parameter. This form field must be named recipient_email_user in order to work. Please see the recipient_email_user form field for more information. Used in conjunction with the recipient_user_limit and recipient_user_template parameters.

# recipient_user_limit=

recipient_user_limit="1"

Allows you to set a maximum amount of manually entered (or hardcoded into template) recipients that can be sent to at once (for spam control measures). Default value is 3. Used in conjunction with the recipient_user_input and recipient_user_template parameters.

# recipient_user_template=

recipient_user_template="tell_a_friend"

Specify a notification template you created in the Notifications tab in the Freeform control panel area. This is the notification that is sent out to the email address selected in the form field. To be used in conjunction with the recipient_user_input and recipient_user_limit parameters.

# duplicate_redirect=

duplicate_redirect="template_group/template"

This parameter allows for a different variation of duplicate control. When Freeform detects that the user has already submitted the form, you would use this parameter in the event you'd like a user to be completely redirected to a template instead of the native EE error page. It only works on form load if Freeform is able to recognize a logged in member or an IP address already on file, and on form submission when Freeform is able to recognize a duplicate email address. Used in combination with the prevent_duplicate_on parameter.

# prevent_duplicate_on=

prevent_duplicate_on="email"

If you'd like to enforce duplicate checking on your form submissions, you can use this parameter to do so. It allows you to base the check on one of these three options: member_id, ip_address or email (the value provided within the email form field if specified). Provide any of those three in the parameter and Freeform will test for duplicate postings WITHIN the specific form.

# prevent_duplicate_per_site=

prevent\_duplicate\_per\_site="no"

When performing duplicate checks, Freeform will check to see if the particular form was submitted by the same user before, but on a per MSM site level. If you specify a value of no, Freeform will look across all sites to see if the user has already submitted the form.

# Variables

# freeform:field:FIELD_NAME

{freeform:field:FIELD_NAME
    attr:id="my_id"
    attr:class="my_class"
    attr:onclick="myFunction();"
}

This variable parses out as a complete form field for the specified field. This is the optimal way to display fields as it auto applies settings and includes all needed HTML to display the field. Default Freeform fields can accept attributes such as attr:id, attr:class, and attr:onclick as parameters. Individual first and third party fields might have other field parameters available. Simply construct your variables like this: freeform:field: + FREEFORM_FIELD_NAME. So if you have a field with a short name of favorite_food, the variable would look like this: {freeform:field:favorite_food}.

Also available is the default_value="VALUE" parameter, which can be applied directly to the {freeform:field:FIELD_NAME} variable. For field types that contain predetermined values such as select lists and radios, this can be used to pre-select a value from that list. For field types such as text input or text area, this can be used to add sample text to the field.

For more information about each field types' output and special handling capabilities, please refer to the Default Fieldtypes documentation. For any 3rd party field types, please refer to any documentation provided by its developer.

# freeform:label :FIELD_NAME

{freeform:label:FIELD_NAME}

This variable parses out as the label for the field. Simply construct your variables like this: freeform:label: + FREEFORM_FIELD_NAME. So if you have a field with a short name of favorite_food, the variable would look like this: {freeform:label:favorite_food}.

# freeform:description:FIELD_NAME

{freeform:description:FIELD_NAME}

This variable parses out as the description for the field. Simply construct your variables like this: freeform:description: + FREEFORM_FIELD_NAME. So if you have a field with a short name of favorite_food, the variable would look like this: {freeform:description:favorite_food}.

# freeform:mp_data:FIELD_NAME

{freeform:mp_data:FIELD_NAME}

This variable is available for use in multipage forms, and parses out data for form fields that were submitted in previous pages. This allows you to display the user's previous selections/data as they continue to fill out the form, and even use the data as conditionals to determine what form fields or wording to display on the following page(s). Simply construct your variables like this: freeform:mp_data: + FREEFORM_FIELD_NAME. So if you have a field with a short name of favorite_food, the variable would look like this: {freeform:mp_data:favorite_food}.

# freeform:error:FIELD_NAME

{if freeform:error:FIELD_NAME}
    <strong>{freeform:error:FIELD_NAME}</strong>
{/if}

This variable is for serving inline errors in your form (to be used with inline_errors parameter), and parses out as the appropriate error message for each form field if there are errors in the form submission. Simply construct your variables like this: freeform:error: + FREEFORM_FIELD_NAME. So if you have a field with a short name of favorite_food, the variable would look like this: {freeform:error:favorite_food}. All other non-field errors will parse through the freeform:general_errors variable pair.

# freeform:form_id

{freeform:form_id}

This variable parses out as the unique ID of the Freeform form. This variable is also available for use OUTSIDE of the Freeform:Form tag (similar to how a global variable works). When using outside of the Freeform:Form tag, if you have more than 1 Freeform form in the same template, this will parse as the first forms' value.

# freeform:form_label

{freeform:form_label}

This variable parses out as the label for the Freeform form, as set in creation of form in Freeform control panel. This variable is also available for use OUTSIDE of the Freeform:Form tag (similar to how a global variable works). When using outside of the Freeform:Form tag, if you have more than 1 Freeform form in the same template, this will parse as the first forms' value.

# freeform:form_name

{freeform:form_name}

This variable parses out as the short name for the Freeform form, as set in creation of form in Freeform control panel. This variable is also available for use OUTSIDE of the Freeform:Form tag (similar to how a global variable works). When using outside of the Freeform:Form tag, if you have more than 1 Freeform form in the same template, this will parse as the first forms' value.

# freeform:form_description

{freeform:form_description}

This variable parses out as the description for the Freeform form, as set in creation of form in Freeform control panel.

# freeform:submit

{freeform:submit}

This variable parses out as a simple submit button for the form.

# freeform:submit_previous

{freeform:submit_previous}

This variable is meant for multi-page forms and parses out as a submit button and submits data from the current page of the form, but returns the user to the previous page. Used in conjunction with the multipage parameter.

# freeform:captcha

{freeform:captcha}

Captcha is available for use in your Freeform forms. This variable will be replaced by a unique captcha image. The text in this image must be submitted into the captcha form field by the user in order for the form to post. Freeform will call in the Captcha requirement under the following circumstances:

1. The Captcha code is present in the form, and the user is a Guest (not logged in).
2. The Captcha code is present in the form, the Require captcha with logged-in members? setting in the CP is set to Yes, AND the user is logged in.

# freeform:recipient_value1

<select name="recipient_email" />
    <option value="{freeform:recipient_value1}">Sales</option>
    <option value="{freeform:recipient_value2}">Technical Support</option>
    <option value="{freeform:recipient_value3}">Service</option>
</select>

When using the recipient1 parameter, this variable will parse out as a hash value to protect your email addresses. For each recipient1 parameter you've specified, use the freeform_recipient_value variable and add the corresponding number to it (ex: {freeform:recipient_value1}, {freeform:recipient_value2}, {freeform:recipient_value3} successively.

# freeform:recipient_name1

<select name="recipient_email" />
    <option value="{freeform:recipient_value1}">{freeform:recipient_name1}</option>
    <option value="{freeform:recipient_value2}">{freeform:recipient_name2}</option>
    <option value="{freeform:recipient_value3}">{freeform:recipient_name3}</option>
</select>

When using the recipient1 parameter and specifying a name value as well, this variable will parse out as the name value. For each recipient1 parameter you've specified, use the freeform:recipient_name variable and add the corresponding number to it (ex: {freeform:recipient_name1}, {freeform:recipient_name2}, {freeform:recipient_name3} successively.

# freeform:form_page

{freeform:form_page}

In multipage forms, this variable will parse the page number the user is currently on. You would likely use this in conjunction with the freeform:form_page_total variable to show progress of form completion. Used in conjunction with the multipage parameter.

This variable is also available for use OUTSIDE of the Freeform:Form tag (similar to how a global variable works). When using outside of the Freeform:Form tag, if you have more than 1 Freeform form in the same template, this will parse as the first forms' value.

# freeform:form_page_total

{freeform:form_page_total}

In multipage forms, this variable will parse the total amount of pages for a given multi-page form. You would likely use this in conjunction with the freeform:form_page variable to show progress of form completion. Used in conjunction with the multipage parameter.

This variable is also available for use OUTSIDE of the Freeform:Form tag (similar to how a global variable works). When using outside of the Freeform:Form tag, if you have more than 1 Freeform form in the same template, this will parse as the first forms' value.

# Variable Pairs

# freeform:all_form_fields

{freeform:all_form_fields}
<p>
    <label>{freeform:field_label}</label>
    {freeform:field_output}
    {if freeform:field_type == 'text'}hello!{/if}
</p>
{/freeform:all_form_fields}

In the event you wish to have Freeform just populate your form fields automatically for you, this variable pair, along with other variables are available to use. Just apply the formatting of your choice and wrap that around the variables and Freeform will do the rest. This will output all fields except a submit button. The following variables are available for use within this variable pair:

• {freeform:field_id} -## the unique ID of the field {freeform:field_data} - previously saved data for the field (when editing)
• {freeform:field_name} -## the short name of the field {freeform:field_label} -## the label for the field {freeform:field_type} - the type of field the form field is (most likely used for creating conditionals on what kind of formatting to use around certain field types)
• {freeform:field_output} -## parses as complete HTML code for the form field {freeform:field_description} - the field's description

# freeform:page:1

{freeform:page:1}
     // content
{/freeform:page:1}

When creating multipage forms, this variable pair lets you tell Freeform which content applies for each page/section of the form. Just wrap these variable pairs with successive numbers, around your content to differentiate the pages. For example, page 1 should be wrapped with freeform:page:1, page 2 should be wrapped with freeform:page:2, page 3 should be wrapped with freeform:page:3 ,etc. If you wish to have custom names for each page (and the URI segment), call the multipage_page_names parameter, and just have your variable pairs match those specified names.

For example, if you have:

multipage_page_names="contact_info|billing|confirm"

then your variable pair names should be freeform:page:contact_info, freeform:page:billing, and freeform:page:confirm.

You can also specify which Freeform fields are required on a per page basis. Simply add the required parameter directly to the page variable pair (instead of to the Freeform:Form loop), and specify which fields per page to be required to be filled out. Example:

{freeform:page:1 required="name|phone|address"}
    // content
{/freeform:page:1}

{freeform:page:2 required="favorite_food|favorite_sports"}
    // content
{/freeform:page:2}

# freeform:recipients

<label>Choose Recipients</label>
<select name="recipient_email" />
    {freeform:recipients}
    <option value="{freeform:recipient_value}"
    {if freeform:recipient_selected}selected="selected"{/if}>
        {freeform:recipient_name}
    </option>
    {/freeform:recipients}
</select>

This variable pair will provide the formatting for parsing out all available contacts you've specified in the recipient1 parameters. Used in conjunction with the recipients parameter. Within this variable pair is the following variables and conditionals:

• freeform:recipient_value variable - pulls email value from recipient1 parameter.
• freeform:recipient_name variable - pulls name value if present, from recipient1 parameter.
• if freeform:recipient_selected conditional - available for use when editing an entry.

# freeform:statuses

<select name="status" id="status">
    <option value="">Select:</option>
    {freeform:statuses status="not closed|testing"}
        <option value="{status_name}"
            {if freeform:edit_data:status == "{status_name}"} selected="selected"{/if}>
        {status_label}
    </option>
    {/freeform:statuses}
</select>

This variable pair is available to help with parsing a list of available statuses. You can filter the list of statuses by specifying specific ones, or exclude specific statuses by prepending the status name(s) with not. Separate multiple status names with the pipe character (|). Used in conjunction with the Used in conjunction with the status form field and allow_status_edit parameter.

# freeform:general_errors

{if freeform:general_errors}
    <h2>There were some error(s) with your submission:</h2>
    <ul>
    {freeform:general_errors}
        <li>{freeform:error_message}</li>
    {/freeform:general_errors}
    </ul>
{/if}

This variable pair is available for parsing all general errors such as incorrect CAPTCHA, user banned, login required, spam keyword ban, secure form timeout, invalid form, etc, inside of the form. It is used in conjunction with the inline_errors parameter. When a user submits the form and any general, non-field error is triggered, it will parse through this variable pair. Field-specific errors will parse through the freeform:error:FIELD_NAME variable.

# Conditionals

# freeform:captcha

{if freeform:captcha}
    <p>
        Please enter the word you see in the image below:
        {freeform:captcha}
    </p>
    <p><input type="text" name="captcha" /></p>
{/if}

Freeform respects the global Captcha preferences that you set in ExpressionEngine. Currently, you can indicate in EE that logged in members need not submit captchas. This conditional allows you to evaluate so that you do not show your captcha field when it is not necessary. Freeform will call in the Captcha requirement under the following circumstances:

1. The Captcha code is present in the form, and the user is a Guest (not logged in).
2. The Captcha code is present in the form, the Require captcha with logged-in members? setting in the CP is set to Yes, AND the user is logged in.

# freeform:duplicate

{if freeform:duplicate}You've already submitted this form.{/if}

If the user has already submitted the form, this conditional will show its contents. This will be determined by their member ID if logged in, or by their IP address if logged out/guest.

# freeform:not_duplicate

{if freeform:not_duplicate}You may submit the form.{/if}

If the user has NOT yet submitted the form, this conditional will show its contents. This will be determined by their member ID if logged in, or by their IP address if logged out/guest.

# freeform:no_results

{if freeform:no_results}Form not found.{/if}

This conditional will show its contents if there is an invalid form name or ID selected.

# freeform:field_errors

{if freeform:field_errors}
    <h2>There were some error(s) with your submission:</h2>
    <ul>
    {if freeform:error:first_name}
        <li><b>First Name</b> is required.</li>
    {/if}
    {if freeform:error:last_name}
        <li><b>Last Name</b> is required.</li>
    {/if}
    {if freeform:error:email}
        <li><b>Email</b> is required.</li>
    {/if}
    </ul>
{/if}

This conditional is available if you wish to parse all field errors inside one area of the form. It is used in conjunction with the inline_errors parameter. When a user submits the form and fields contain errors, this conditional will show its contents. Used in conjunction with the freeform:error:FIELD_NAME variable.

# Form Fields

# captcha

<input type="text" name="captcha" />

When using Captchas in your forms, this field is necessary for users to submit the text of the Captcha image they see. Used in conjunction with the freeform:captcha variable. Freeform will call in the Captcha requirement under the following circumstances:

1. The Captcha code is present in the form, and the user is a Guest (not logged in).
2. The Captcha code is present in the form, the Require captcha with logged-in members? setting in the CP is set to Yes, AND the user is logged in.

# recipient_email

<label>Choose Recipients</label>
<select name="recipient_email">
{freeform:recipients}
    <option
        value="{freeform:recipient_value}"
        {if freeform:recipient_selected}selected="selected"{/if}>
        {freeform:recipient_name}
    </option>
{/freeform:recipients}
</select>

This form field allows you to have your users dynamically select the recipient of the form submission they're sending to. This could typically be used for displaying a list of departments or contacts a user can send the form submission to. To help prevent spam, refer to the recipients_limit parameter. Used in conjunction with the recipients parameter and/or freeform:recipient_value1 variables.

NOTE: If you wish to have the data value(s) entered/selected for this field available to view in control panel and for use in Freeform:Entries or notification templates, simply create a Freeform field with the short name of recipient_email.

# recipient_email_user

<input type="text" name="recipient_email_user" />

This form field allows you to have your users dynamically specify the recipient of the form submission they're sending to. This would typically be used for a Tell-a-Friend type form on your site, where a user can specify their friend's email address to submit an email notification to. To help prevent spam, refer to the recipient_user_limit parameter. Used in conjunction with the recipient_user_input and recipient_user_template parameters.

NOTE: If you wish to have the data value(s) entered/selected for this field available to view in control panel and for use in Freeform:Entries or notification templates, simply create a Freeform field with the short name of recipient_email_user.

# return

<select name="return">
    <option value="application-form/thank-you">
        I will pay at the door
    </option>
    <option value="application-form/payment">
        I will pay now
    </option>
</select>

This field (actual Freeform field or not), will override the return parameter and allows you to control the return path, dependent on a users selection. If you'd like to send the user to a page with the newly created Freeform entry ID in the URI, just add %%entry_id%% to the end of the URL you've specified in the return field. That variable will be replaced by the Freeform entry ID of the newly submitted entry.

# status

<select name="status" id="status">
    <option value="">Select:</option>
    {freeform:statuses status="not closed|testing"}
        <option value="{status_name}"
        {if freeform:edit_data:status == "{status_name}"}
            selected="selected"
        {/if}>
        {status_label}
    </option>
    {/freeform:statuses}
</select>

This field is available to let you have your users specify a status for the form and override the default status set for the form (in the Freeform control panel). Used in conjunction with the Used in conjunction with the freeform:statuses variable pair and allow_status_edit parameter.

# FREEFORM_FIELD_NAME

<input type="text" name="FREEFORM_FIELD_NAME">
<input type="checkbox" name="FREEFORM_FIELD_NAME[]" value="pie">
<textarea name="FREEFORM_FIELD_NAME"></textarea>

All Freeform fields you created for a given form are available for use as form fields here to collect data. Just specify the short_name of the field (ex: subject) as the field name. For fields that are to be accepting multiple values (or single and multiple file upload fields), be sure to include brackets ([]) after the name of the field in the name attribute (ex: name="FREEFORM_FIELD_NAME[]"). If you wish to use a more automated form of populating these fields, check out the freeform:all_form_fields variable pair, or the freeform🏷FIELD_NAME and freeform:field:FIELD_NAME variables.

# Examples

• Simple Contact Form
• Advanced Contact Form
• Inline Errors Form
• Multi-page Surveys
• Simple Voting / Polls
• Tell-A-Friend Form
• AJAX Validation

# Simple Contact Form

The following example will display a simple contact form for site visitors to contact you. It will not send any notifications but the data will be posted to the database and be available for viewing in the Freeform control panel area or within the Freeform:Entries tag.

<h3>Contact Us</h3>
<p>
    To send us a message, please fill out the form below.
    We’ll get back to you shortly!
</p>

{exp:freeform:form
    form_name="contact"
    return="contact_us/thank_you"
}
    <dl>
    {freeform:all_form_fields}
        <dt><label>{freeform:field_label}</label></dt>
        <dd>{freeform:field_output}</dd>
    {/freeform:all_form_fields}
    </dl>
    {if freeform:captcha}
        <p>Please enter the word you see in the image below:</p>
        <p>
            {freeform:captcha}
            <input type="text" name="captcha" />
        </p>
    {/if}
    <p>{freeform:submit}</p>
{if freeform:no_results}
    <p>
        Specified form was not found. Please make sure you have specified the
        correct short name of the form in the <b>form_name</b> parameter.
    </p>
{/if}
{/exp:freeform:form}

# Advanced Contact Form

The following example will create a more elaborate contact form for site visitors to contact you. This is dependent on you setting notification preferences for a given form in the Freeform control panel, and creating new fields as named in the form below. The form will send an email notification to the specified email the submitter selects in addition to posting the data to the database. It will also send out a notification to the user that submitted the form (good for sending a message like "We received your submission and we'll be right with you..."). It uses 8 Freeform fields (name, email, home_phone, cell_phone, urgent, subject, question, and attach_file) that will need to be created in the Freeform control panel.

<h3>Contact Us</h3>
<p>
    To send us a message, please fill out the form below. We’ll get back to you shortly!
</p>

{exp:freeform:form
    form_id="1"
    required="name|email"
    return="contact_us/thank_you"
    recipients="yes"
    recipient1="Happy Harry|h_harry@somemail.com"
    recipient2="Lazy Larry|lazyl63@somemail.com"
    recipient_template="contact_form"
    notify_user="yes"
    user_email_field="user_email"
}

    <p><label>Choose Recipients</label><br/>
        <select name="recipient_email" />
            {freeform:recipients}
            <option value="{freeform:recipient_value}">
                {freeform:recipient_name}
            </option>
            {/freeform:recipients}
        </select></p>

    <p>
        <label>{freeform:label:name}</label>
        {freeform:field:name}
    </p>
    <p>
        <label>{freeform:label:email}</label>
        {freeform:field:email}
    </p>
    <p>
        <label>{freeform:label:home_phone}</label>
        {freeform:field:home_phone}
    </p>
    <p>
        <label>{freeform:label:cell_phone}</label>
        {freeform:field:cell_phone}
    </p>

    <!--
        This is the long form of a radio button. The Radio
        Button fieldtype makes this as easy as {freeform:field:my_radio}
    -->
    <p>
        Is This Urgent?:
        <input type="radio" name="urgent" id="urgent_yes" value="yes" />
        <label for="urgent_yes">Yes</label>

        <input type="radio" name="urgent" id="urgent_no" value="no" />
        <label for="urgent_no">No</label>
    </p>

    <p>
        <label>{freeform:label:subject}</label>
        {freeform:field:subject}
    </p>

    <p>
        <label>{freeform:label:question}</label>
        {freeform:field:question}
    </p>

    <p>
        <label>{freeform:label:attach_file}</label>
        {freeform:field:attach_file show="2"}
    </p>

    {if freeform:captcha}
        <p>Please enter the word you see in the image below:</p>
        <p>
            {freeform:captcha}
            <input type="text" name="captcha" />
        </p>
    {/if}

    <p>{freeform:submit}</p>

{/exp:freeform:form}

# Inline Errors Form

The following example shows the inline errors feature in use:

<h3>Contact Us</h3>
<p>
    To send us a message, please fill out the form below. We’ll get back to you shortly!
</p>

{exp:freeform:form
    form_id="1"
    required="name|email"
    return="contact_us/thank_you"
    inline_errors="yes"
}

    {if freeform:general_errors}
        <h2>There were some error(s) with your submission:</h2>
        <ul>
        {freeform:general_errors}
            <li>{freeform:error_message}</li>
        {/freeform:general_errors}
        </ul>
    {/if}

    <p>
        <label>{freeform:label:name}</label>
        {freeform:field:name}
        {if freeform:error:name}
            <span class="error">{freeform:error:name}</span>
        {/if}
    </p>

    <p>
        <label>{freeform:label:email}</label>
        {freeform:field:email}
        {if freeform:error:email}
            <span class="error">{freeform:error:email}</span>
        {/if}
    </p>

    <p>
        <label>{freeform:label:home_phone}</label>
        {freeform:field:home_phone}
        {if freeform:error:home_phone}
            <span class="error">{freeform:error:home_phone}</span>
        {/if}
    </p>

    <p>
        <label>{freeform:label:cell_phone}</label>
        {freeform:field:cell_phone}
        {if freeform:error:cell_phone}
            <span class="error">{freeform:error:cell_phone}</span>
        {/if}
    </p>

    <p>
        <label>{freeform:label:question}</label><br />
        {freeform:field:question}<br />
        {if freeform:error:question}
            <span class="error">{freeform:error:question}</span>
        {/if}
    </p>

    {if freeform:captcha}
        <p>Please enter the word you see in the image below:</p>
        <p>{freeform:captcha}<br />
        <input type="text" name="captcha" /></p>
    {/if}

    <p>{freeform:submit}</p>

{/exp:freeform:form}

# Multi-page Surveys

The following example shows you how to create a multi-page survey form. It will send an email notification to the specified admin in addition to posting the data to the database. We've also set conditionals in the code so that users are NOT allowed to submit the form more than once.

<h3>Survey</h3>
<p>We would appreciate it if you could fill out this quick survey!</p>

{exp:freeform:form
    form_name="foods_survey"
    multipage="yes"
    return="survey/thank_you"
    notify_admin="yes"
    notify="joe@yoursite.com"
    admin_template="survey_response"
}

{if freeform:duplicate}
    <p>Sorry, you’ve already submitted this survey.</p>
{/if}

{if freeform:not_duplicate}

{freeform:page:1 required="name|email"}
    <p><label>{freeform:label:name}</label> {freeform:field:name}</p>
    <p><label>{freeform:label:email}</label> {freeform:field:email}</p>

    <p><input type="submit" name="submit" value="Continue" /></p>
{/freeform:page:1}

{freeform:page:2 required="question_1"}
    <h4>Question 1</h4>
    <p>
        Do you like to eat?:
        <input
            type="radio"
            name="question_1"
            id="question_1_yes"
            value="yes" />
        <label for="question_1_yes">Yes</label>

        <input
            type="radio"
            name="question_1"
            id="question_1_no"
            value="no" />
        <label for="question_1_no">No</label>
    </p>

    <p><input type="submit" name="submit" value="Continue" /></p>
{/freeform:page:2}

{freeform:page:3 required="question_2"}
    <h4>Question 2</h4>
    <p>Which of the 4 Food Groups do you like most?:
    <select name="question_2" />
        <option value="Breads & Grains">Breads & Grains</option>
        <option value="Fruits & Vegetables">Fruits & Vegetables</option>
        <option value="Dairy Products">Dairy Products</option>
        <option value="Meats">Meats</option>
    </select></p>

    <p><input type="submit" name="submit" value="Continue" /></p>
{/freeform:page:3}

{freeform:page:4 required="question_3"}
    <h4>Question 3</h4>
    <p>
        Which meals do you eat throughout the day (check all that apply)?:

        <input type="checkbox" name="question_3[]" id="question_3_breakfast" value="Breakfast" />
        <label for="question_3_breakfast">Breakfast</label>

        <input type="checkbox" name="question_3[]" id="question_3_lunch" value="Lunch" />
        <label for="question_3_lunch">Lunch</label>

        <input type="checkbox" name="question_3[]" id="question_3_supper" value="Supper" />
        <label for="question_3_supper">Supper</label>

        <input type="checkbox" name="question_3[]" id="question_3_latenightsnack" value="Late Night Snack" />
        <label for="question_3_latenightsnack">Late Night Snack</label>
    </p>

    <p><input type="submit" name="submit" value="Submit" /></p>
{/freeform:page:4}

{/if}

{/exp:freeform:form}

# Simple Voting / Polls

The following example shows you how to create a voting form. With its current parameters set, it will not send any email notifications, but will post the data to the database. We've also set conditionals in the code so that users are NOT allowed to submit the form more than once.

<h3>Weekly Vote</h3>

{exp:freeform:form
    form_name="american_idol"
    required="name|email|vote"
    return="vote/thank_you"
}

{if freeform:duplicate}
    <p>Sorry, you’ve already voted.</p>
{/if}

{if freeform:not_duplicate}
    <p><label>{freeform:label:name}</label> {freeform:field:name}</p>
    <p><label>{freeform:label:email}</label> {freeform:field:email}</p>

    <p>
        Choose your favorite American Idol:
        <input type="radio" name="vote" id="vote_1" value="Kelly Clarkson" />
        <label for="vote_1">Kelly Clarkson</label>

        <input type="radio" name="vote" id="vote_2" value="Ruben Studdard" />
        <label for="vote_2">Ruben Studdard</label>

        <input type="radio" name="vote" id="vote_3" value="Fantasia Barrino" />
        <label for="vote_3">Fantasia Barrino</label>
    </p>

    <p><input type="submit" name="submit" value="Vote!" /></p>
{/if}

{/exp:freeform:form}

# Tell-A-Friend Form

In this example, your users can to send a Tell-A-Friend style message to their friends about your site. It will send an email notification to the email address they enter (in the field with the short name of recipient_email_user), and the data will also be posted to the database and be available for viewing in the Freeform CP (if you create a Freeform field with the same name for the form, otherwise it will not be stored). The recipient_user_input field is required with a value of yes.

<h3>Tell A Friend About This Site</h3>
<p>Tell your friends about this site! Just fill out the form below.</p>

{exp:freeform:form
    form_name="tell_a_friend"
    required="name|email|friend_email"
    return="tell-a-friend/thank_you"
    recipient_user_input="yes"
    recipient_user_limit="1"
    recipient_user_template="tell_a_friend"
}

    <p>Your Name: <input type="text" name="name" /></p>
    <p>Your Email: <input type="text" name="email" /></p>

    <p>Friends Name: <input type="text" name="friends_name" /></p>
    <p>Friends Email: <input type="text" name="recipient_email_user" /></p>

    <p>	Comments:<br />
        <textarea name="comments">
            Hey there! You should check out this site - it’s totally awesome!
        </textarea>
    </p>

    {if freeform:captcha}
        <p>Please enter the word you see in the image below:</p>
        <p>{freeform:captcha}<br />
        <input type="text" name="captcha" /></p>
    {/if}

    <p><input type="submit" name="submit" value="Send!" /></p>

{/exp:freeform:form}

# AJAX Validation

The following example shows you how you might implement AJAX validation on your form. Comments explaining each part are included inline with the example code.

<style type="text/css">
    .general_errors,
    .error_message {
        color:            red;
        border:            1px solid red;
        border-radius:    3px;
        padding:        0 10px;
        display:        none;
        margin-bottom:    10px;
        width:            300px;
    }
</style>

{exp:freeform:form
    form:id="ajax_form"
    {if segment_3}form_name="{segment_3}"{/if}
    {if segment_3 == ''}form_id="1"{/if}
}
    {if freeform:no_results}
        Form Not Found.
    {/if}
    <h1>{freeform:form_label}</h1>

    <!-- place holder for ajax errors-->
    <div class="general_errors"></div>

    <dl>
    {freeform:all_form_fields}
        <dt>
            <label>{freeform:field_label}</label>
        </dt>
        <dd>
            <!-- place holder for ajax errors-->
            <div class="error_message"></div>
            {freeform:field_output}
        </dd>
    {/freeform:all_form_fields}
    </dl>

    {if freeform:captcha}
        <p>Please enter the word you see in the image below:</p>
        <p>
            {freeform:captcha}<br />
            <input
                type="text"
                name="captcha"
                value=""
                size="20"
                maxlength="20"
                style="width:140px;" />
        </p>
    {/if}

    <p>{freeform:submit}</p>
{/exp:freeform:form}

<!-- example requires jquery -->
<script type="text/javascript"
        src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js">
</script>

<script type="text/javascript">
    jQuery(function($){
        var $form            = $('#ajax_form');
        var $generalErrors    = $('.general_errors');

        $form.submit(function(e){
            //hide all errors
            $('.error_message').hide().html('');
            $generalErrors.hide().html('');

            //jquery ajax shortcut
            $.post(
                //form url (Freeform autodetects ajax)
                $form.attr('action'),
                //form params
                $form.serialize(),
                //data handler
                function(data)
                {
                    // -------------------------------------
                    //   `data` is a json string that jQuery
                    //    automatically detects and converts.
                    //    data {
                    //        //posting successful?
                    //
                    //        "success" : true/false,
                    //
                    //        //object containing error messages
                    //        //if success is false
                    //        //multiple error messages are an array
                    //        //single error messages are a string
                    //
                    //        "errors"    : {
                    //            "field_name1"    : 'single error message',
                    //            "field_name2"    : [
                    //                'multiple error messages',
                    //                'for the same field'
                    //            ]
                    //        }
                    //
                    //        //the return url of return="" if set, or this current url
                    //
                    //        "return_url"    : "http://yoursite.com/return/segment/"
                    //    }
                    // -------------------------------------
                    if (data.success == false)
                    {
                        //data.errors
                        $.each(data.errors, function(i, item){

                            var $errorHolder = $('[name="' + i + '"]').
                                                    parent().find('.error_message');
                            var error         = ($.isArray(item) ? item.join('<br/>') : item);

                            //does the error holder field exist?
                            if ($errorHolder.length > 0)
                            {
                                $errorHolder.append('<p>' + error + '</p>').show();
                            }
                            //lets add it to general errors
                            else
                            {
                                $generalErrors.append('<p>' + error + '</p>').show();
                            }
                        });
                    }
                    else if (data.success)
                    {
                        window.location.href = data['return_url'];
                    }
                }
            );

            e.preventDefault();
            return false;
        });
    });
</script>