Freeform:Form
- Home
- Documentation
- Modules
- Freeform
- Tags
- Form
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
- file_upload
- form:attribute
- mailinglist
- mailinglist_opt_in
- notify
- onsubmit
- prevent_duplicate_on
- redirect_on_duplicate
- require_ip
- required
- return
- secure_action
- secure_return
- send_attachment
- send_user_attachment
- send_user_email
- status
- template
- user_email_template
- recipients
- recipient1
- recipient_limit
- recipient_template
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.
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.
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.
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.
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}
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.
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.
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.
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}
