Freeform 3.x

Legacy documentation for Freeform 3.x.

The Freeform:Form tag allows your users to submit all types of forms on your site. This could be anything you wish including contact forms, surveys, testimonials, etc. Form submissions are stored in the database and their content can be formatted and emailed to an admin and a copy can be sent to the user that submitted the form. File Attachments can also be received, stored and forwarded on in email.

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

Parameters

The following parameters are available for use:

collection=

collection="Cheese Survey" 

This parameter is used by Freeform to organize postings across your various forms. The organization happens dynamically when you view your entries in the control panel. Formerly known as form_name in previous versions of Freeform.

allowed_file_types=

allowed_file_types="jpg|pdf|doc" 

This parameter lets you bypass a File Upload Preference's allowed file types setting, and let's you specifically set the types of file extensions you wish to have your form receive. Use in conjunction with the file_upload parameter.

file_upload=

file_upload="Main Upload Directory" 

This parameter tells Freeform where to store attachments submitted in a given form. The upload preference provided refers to the file upload preferences you create in EE for weblog file uploads. Freeform respects all of the settings you establish for a given upload preference.

form:attribute=

form:class="your_class_name" 

This parameter allows you to control any form attribute for the form in your template. Simply replace attribute with an attribute name such as id, name, class, 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.

mailinglist=

mailinglist="list_name|another_list" 

If you'd like your users to be subscribed to mailing list(s) when they submit the form, use this parameter and specify the mailing list(s) you'd like them to be subscribed to. Separate multiple values with the pipe character. By default, users will be sent a notification email which will preserve double opt-in functionality. The notification is formatted in accord with your Mailing List Activation instructions template found in the main CP of EE.

mailinglist_opt_in=

mailinglist_opt_in="no" 

When used in conjunction with the mailinglist parameter or mailinglist form field, when this parameter is set to no, it overrides the default EE double opt-in setting and immediately subscribes the user to the given mailinglist(s). When using this parameter, be sure that the user's email is placed within the default form field named email.

notify=

notify="you@site.com|another@site.com" 

This parameter allows you to generate email notifications to the specified email addresses when a user submits the form. Separate multiple values with the pipe character. This parameter is to be used in conjunction with the template parameter, which controls the content and formatting of the notification.

NOTE: If you're having trouble receiving email notifications, please make sure the email address it's being sent from is valid (actually created on the server).

onsubmit=

onsubmit="some_javascript();" 

This parameter allows you to execute Javascript functions at form submission.

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 dynamic collection name (see collection parameter).

redirect_on_duplicate=

redirect_on_duplicate="template_group/template" 

This parameter allows for a different variation of duplicate control. You would use this parameter in the event you'd like a user to be completely redirected to a different page upon LOADING the Freeform form if they've already submitted the form. It only works if Freeform is able to recognize a logged in member or an IP address already on file. Note: the user will be redirected upon loading the template that contains the Freeform form (NOT when submitting it).

require_ip=

require_ip="yes" 

Using this parameter will cause Freeform to verify that the user submitting has a recordable IP address.

required=

required="name|email" 

This parameter tells Freeform which fields to verify as having been completed by the user before form submission. Separate multiple values with the pipe character.

return=

return="template_group/template" 

This parameter determines where to send users once they have submitted your 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. Ex:

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

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.

send_attachment=

send_attachment="yes" 

In the event you're accepting file attachments to your form and sending email notifications to admins, this parameter will tell Freeform to include the attached files to the notification email. This parameter is to be used in conjunction with the notify and template parameter.

send_user_attachment=

send_user_attachment="yes" 

In the event you're accepting file attachments to your form and sending an email notifications to the user that submitted the form, this parameter will tell Freeform to include the attached files to the notification email to them. This parameter is to be used in conjunction with the send_user_email and user_email_template parameter.

send_user_email=

send_user_email="yes" 

This parameter allows you to generate email notifications to the user that submits the form. When using this parameter, be sure that the user's email is placed within the default form field named email. If you attempt to use any other field name it will not work. This parameter is to be used in conjunction with the user_email_template parameter, which controls the content and formatting of the notification.

status=

status="closed" 

This parameter allows you to override the default status of entries submitted. By default, all entries are submitted as open. Specify closed if you wish to change the status.

template=

template="default_template" 

This parameter allows you to specify a notification template you created in the Freeform CP area in the ExpressionEngine control panel. This is the notification that is sent out to the specified admins emails. To be used in conjunction with the notify parameter.

NOTE: If you're having trouble receiving email notifications, please make sure the email address it's being sent from is valid (actually created on the server).

user_email_template=

user_email_template="some_template" 

This parameter allows you to specify a notification template you created in the Freeform CP area in the ExpressionEngine control panel. This is the notification that is sent out to the user that submits the form. To be used in conjunction with the send_user_email parameter.

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). This form field must be named recipient_email in order to work. Please see the recipient_email form field for more information.

recipient1=

recipient1="John McCrackin|john@mccrackinandco.com" 
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, seperated by the pipe character. You can create as many recipients as you wish. For each recipient, add a recipient parameter to your form and name it recipient1, recipient2, recipient3 successively. The values in these parameters are then available to use as variables in your form. See recipient_value1 and recipient_name1 variables.

recipient_limit=

recipient_limit="3" 

Allows you to set a maximum amount of recipients that can be sent to at once (for spam control measures). Default value is held in the Preferences tab in the Freeform Control Panel. Used in conjunction with the recipients parameter and recipient_email form field.

recipient_template=

recipient_template="default_template" 

This parameter allows you to specify a notification template you created in the Freeform CP area in the ExpressionEngine control panel. This is the notification that is sent out to the email address a user specifies in the recipient_email form field. To be used in conjunction with the recipients parameter.

reply_to=

reply_to="yes" 

This parameter allows you to have a "reply to" option on the notification emails that go to your admin(s) (via the notify parameter). You might want your notification emails to the admin(s) to appear from an automated email address like submissions@yoursite.com and appear from a name of YourSite.com Contact Form, but when you reply to the email, have it go to the actual name and email address of the customer/user that filled out the form. Use in conjunction with the reply_to_name_field and reply_to_email_field parameters to designate the fields you wish to collect this data. If you do not specify these additional parameters, Freeform will automatically look for and use the values provided in the name and email fields in your form.

Note: You can already set up your notification emails to appear from the customer/user's name and email by just using {name} and {email} variables in your notification template for From Name and From Email fields, but this specific option is for this advanced scenario described above.

reply_to_name_field=

reply_to_name_field="YOUR_FIELD_NAME" 

This parameter lets you specify which field to use to collect and generate the Reply to Name for the email notification. This field MUST exist as a Freeform field. If you do NOT specify this parameter, Freeform will automatically attempt to use the name field. Use in conjunction with the reply_to and reply_to_email_field parameters.

reply_to_email_field=

reply_to_email_field="YOUR_FIELD_NAME" 

This parameter lets you specify which field to use to collect and generate the Reply to Email for the email notification. This field MUST exist as a Freeform field. If you do NOT specify this parameter, Freeform will automatically attempt to use the email field. Use in conjunction with the reply_to and reply_to_name_field parameters.

output_json=

output_json="yes" 

Using this parameter with a value of yes allows for AJAX requests to return errors and success mesages in JSON. Default is no.

ajax_request=

ajax_request="no" 

Using this parameter with a value of no forces the form to do a standard redirect after a new entry is inserted, even when the request was made via AJAX.

Variables

The following variables are available for use:

name

{name} 

This variable will be replaced by the Screen Name of the logged in user.

email

{email} 

This variable will be replaced by the Email Address of the logged in user.

captcha

{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.

recipient_value1

<select name="recipient_email" />
    <option value="{recipient_value1}">Sales</option>
    <option value="{recipient_value2}">Technical Support</option>
    <option value="{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 recipient# parameter you've specified, use the recipient_value variable and add the corresponding number to it (ex: {recipient_value1}, {recipient_value2}, {recipient_value3} successively.

recipient_name1

<select name="recipient_email" />
    <option value="{recipient_value1}">{recipient_name1}</option>
    <option value="{recipient_value2}">{recipient_name2}</option>
    <option value="{recipient_value3}">{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 recipient# parameter you've specified, use the recipient_name variable and add the corresponding number to it (ex: {recipient_name1}, {recipient_name2}, {recipient_name3} successively.

Variable Pairs

The following variable pairs are available for use:

recipients

<select name="recipient_email[]" />
    {recipients}
    <option value="{recipient_value}">{recipient_name}</option>
    {/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.

Conditionals

The following conditionals are available for use:

if duplicate

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

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

if not_duplicate

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

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

if captcha

{if captcha}{/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.

Form Fields

The following form fields are available for use:

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 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.

file1

<input type="file" name="file1" /> 

Freeform is able to accept file attachments in form submissions. You can accept as many attachments as you wish. For each attachment you want to receive, add a file field type to your form and name it file1, file2, file3 successively. Used in conjunction with the file_upload parameter.

mailinglist

<input type="checkbox" name="mailinglist[]" value="default"> 

This form field enables your visitors to subscribe to a mailing list by clicking a checkbox. The value needs to be the same as the short_name of your mailing list. When using this feature, be sure that the user's email is placed within the default form field named email.

recipient_email

<select name="recipient_email" />
    <option value="{recipient_value1}">Sales</option>
    <option value="{recipient_value2}">Technical Support</option>
    <option value="{recipient_value3}">Service</option>
</select>
Your Friends Email: <input type="text" name="recipient_email" /> 

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 2 different methods: 1) displaying a list of departments a user can send the form submission to, OR 2) a Tell-a-Friend form. In this case you would just have the form field set to a regular text input field and left emtpy. To help prevent spam, refer to the recipient_limit parameter. Used in conjunction with the recipients parameter and/or recipient_value1 variables.

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 as available in the Freeform CP are available for use as form fields here to collect data. To use a Freeform field to collect data, just specify the short_name of the field (ex: subject).

Examples

Simple Contact Form

The following example will create 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 CP or with the Freeform:Entries tag. It uses two of the default Freeform fields (name and email), but requires you to create an additional field in the Freeform CP named question.

<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
    collection="Contact Form"
    required="name|email"
    return="contact_us/thank_you"
}

<p>Name: <input type="text" name="name" /></p>
<p>Email: <input type="text" name="email" /></p>
<p>Questions or Comments:<br /><textarea name="question"></textarea></p>

<p><input type="submit" name="submit" value="Submit" /></p>

{/exp:freeform:form}

Advanced Contact Form

The following example will create a more elaborate contact form for site visitors to contact you. The form contains a file upload field that allows your users to submit a file as well. It will send an email notification to the specified admin 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 “We received your submission and we’ll be right with you…” type messages). It uses four of the default Freeform fields (name, email, phone1, and phone2), but requires you to create a few additional fields in the Freeform CP named urgent, subject, and question.

<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
    collection="Contact Form"
    required="name|email"
    return="contact_us/thank_you"
    notify="joe@yoursite.com"
    template="default_template"
    send_user_email="yes"
    user_email_template="some_template"
    file_upload="Main Upload Directory"
}

<p>Name: <input type="text" name="name" /></p>
<p>Email: <input type="text" name="email" /></p>
<p>Home Phone: <input type="text" name="phone1" /></p>
<p>Cell Phone: <input type="text" name="phone2" /></p>

<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>Subject: <input type="text" name="subject" /></p>
<p>Questions or Comments:<br /><textarea name="question"></textarea></p>
<p>Attach a File: <input type="file" name="file1" /></p>

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

<p><input type="submit" name="submit" value="Submit" /></p>

{/exp:freeform:form}

Surveys

The following example shows you how to create a 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. It uses two of the default Freeform fields (name and email), but requires you to create a few additional fields in the Freeform CP named question_1, question_2, and question_3.

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

{exp:freeform:form
    collection="Foods Survey"
    required="name|email|question_1|question_2|question_3"
    return="survey/thank_you"
    notify="joe@yoursite.com"
    template="default_template"
}

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

{if not_duplicate}
    <p>Name: <input type="text" name="name" /></p>
    <p>Email: <input type="text" name="email" /></p>

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

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

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

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

    <p><input type="submit" name="submit" value="Submit" /></p>

{/if}

{/exp:freeform:form}

Simple Voting / Polls

The following example shows you how to create a survey form. 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. It uses two of the default Freeform fields (name and email), but requires you to create 1 additional field in the Freeform CP named vote.

<h3>Weekly Vote</h3>

{exp:freeform:form
    collection="American Idol"
    required="name|email|vote"
    return="vote/thank_you"
}

{if duplicate}
    <p>Sorry, you've already voted.</p>
{/if}

{if not_duplicate}
    <p>Name: <input type="text" name="name" /></p>
    <p>Email: <input type="text" name="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

The following example makes use of the “User Recipients” feature. In this example, it allows your users to send a Tell-A-Friend style a message about your site. It will send an email notification to the email address they enter, and the data will also be posted to the database and be available for viewing in the Freeform CP. It uses two of the default Freeform fields (name and email), but requires you to create additional fields in the Freeform CP named recipient_name and comments. The recipient_email field is a special field that’s recognized by Freeform.

<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
    collection="Tell-a-Friend"
    required="name|email"
    return="tell-a-friend/thank_you"
    recipients="yes"
    recipient_limit="1"
    recipient_template="tell_friend_template"
}

<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="recipient_name" /></p>
<p>Friends Email: <input type="text" name="recipient_email" /></p>

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

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

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

{/exp:freeform:form}