Solspace > Documentation > Modules > Freeform > Freeform 2.7 > Freeform 2.7 Form

Freeform 2.7 Form

Freeform allows you to create a wide variety of forms on your EE site. Form submissions are stored in the database and their content can be formatted and emailed. Attachments to form submissions can also be received, stored and forwarded on in email.

Note: Form "names" (form_name="" parameter) are not something that are actually pre-defined. In other words, you do not create them in the Freeform Control Panel. When creating a Freeform form, name the form_name in the template at your discretion. This is a simple way to dynamically organize your data. The organization happens dynamically when you view your entries in the control panel, or when pulling data with the Freeform:Entries loop using the form_name="" parameter.

Note: You do not need to create a new field set for each form. All fields are available to all of your forms.

• Parameters
• Variables
• Conditionals
• Form Fields
• Examples
• Extras

Parameters

A variety of parameters are used to control the behavior of Freeform during form submissions.

{exp:freeform:form form_name="zeus" required="name|email" notify="you@yourdomain.com" template="brief_version"} content {/exp:freeform:form}

In the above example, the form postings will be organized into the 'zeus' set of submissions as long as the required fields of 'name' and 'email' are submitted by the user. The email address 'you@yourdomain.com' will receive the notification of new postings and the format of the email will be that of the 'brief_version' notification template.

• file_upload
• form_class
• form_id
• form_name
• form_title
• status
• mailinglist
• mailinglist_opt_in
• name
• notify
• onsubmit
• prevent_duplicate_on
• redirect_on_duplicate
• require_ip
• required
• return
• secure_action
• secure_return
• send_attachment
• send_user_attachment
• send_user_email
• template
• user_email_template

file_upload =

file_upload ="Main Upload Directory"

The 'file_upload' 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_class =

form_class ="my_form_class"

The 'form_class' parameter allows you to add a class attribute to the form you create.

form_id =

form_id ="my_form_id"

The 'form_id' parameter allows you to add an id attribute to the form you create.

form_name=

form_name="my_form"

The 'form_name' 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.

form_title =

form_title ="my_form_title"

The 'form_title' parameter allows you to add a title attribute to the form you create.

status=

status="closed"

The 'status' parameter allows you to override the default status of entries submitted. The standard default is 'open', but you can change that to 'closed' by using this parameter.

mailinglist=

mailinglist="my_list_name"

The 'mailinglist' parameter indicates which of your mailing lists to subscribe the user posting to Freeform. 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"

The 'mailinglist_opt_in' parameter, when set to no, overrides the default setting and immediately subscribes the user to the given mailinglists.

name =

name="nameoftheform"

The 'name' parameter allows you to specify the 'name' attribute of the form created for you by the module. Note that this parameter is different from the 'form_name' parameter. I know, confusing. Some folks had rightly pointed out that the name attribute is not XHTML Strict compliant. So it's optional now.

notify=

notify="you@yourdomain.com|another@somedomain.com"

The 'notify' parameter will cause email notifications to be sent to the list of emails you provide. This parameter works in along with the template parameter below. Separate multiple values with the pipe "|" character.

onsubmit=

onsubmit="some_javascript_function();"

The 'onsubmit' parameter allows you to indicate onsubmit actions for your Freeforms.

prevent_duplicate_on=

prevent_duplicate_on="email"

The 'prevent_duplicate_on' parameter allows you to prevent duplicate postings based on one of three tests; member_id, ip_address or email. Provide any of those three in the parameter and Freeform will test for duplicate postings. If you have provided the form_name parameter, only entries with that form_name will be checked.

redirect_on_duplicate=

redirect_on_duplicate="some_template_group/some_template"

The 'redirect_on_duplicate' parameter prevents users from submitting a given Freeform form twice. It only works if Freeform is able to recognize a logged in member or an IP address already on file.

require_ip=

require_ip="yes"

The 'require_ip' parameter will cause Freeform to verify that the user submitting has a recordable IP address.

required=

required="name|email"

The 'required' 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="my/template"

The 'return' parameter determines where to send users once they have submitted your form. You can add a variable to the parameter that will be replaced by the entry id of the newly submitted entry, like this: return="my/template/%%entry_id%%"

secure_action=

secure_action="yes"

The 'secure_action' parameter allows you to set the action on the form to have https://. Use for processing forms with SSL.

secure_return=

secure_return="yes"

The 'secure_return' parameter allows you to set the return on the form to have https://. Use for processing forms with SSL.

send_attachment=

send_attachment="yes"

The 'send_attachment' parameter tells Freeform to include the attachments that a user uploaded along with the notification that will be sent to those people indicated in the 'notification' parameter.

send_user_attachment=

send_user_attachment="yes"

The 'send_user_attachment' parameter tells Freeform to include the attachments that a user uploaded with the notification they will receive upon successful upload. If you are not sending user notifications, this parameter will be ignored.

send_user_email=

send_user_email="yes"

The 'send_user_email' parameter tells Freeform to send a message to the person who submitted your form. This can be used in conjunction with a Freeform notification template to send customized messages by supplying a template name in the 'user_email_template' parameter. See below.

template=

template="your_notification_template"

The 'template' parameter will call one of your Freeform notification templates to be used during the notification routine. Notification templates can be created in the Freeform CP.

Any of the variables and conditionals available in the freeform:entries function should be available in the notification templates.

user_email_template=

user_email_template="some_template"

The 'user_email_template' parameter, when used in conjunction with the 'send_user_email' parameter above, indicates which Freeform notification template to use for messages sent back to the user who submits a form.

Any of the variables and conditionals available in the freeform:entries function should be available in the notification templates.

Variables

The following variables are available with the {exp:freeform:form} tag.

• name
• email
• url
• location
• captcha
• custom_member_field

name

{name}

The 'name' variable will be replaced by the screen name of the logged in user. If they have no screen name, their username will be used.

email

{email}

The 'email' variable will be replaced by the email address of the logged in user.

url

{url}

The 'url' variable will be replaced by the url of the logged in user.

location

{location}

The 'location' variable will be replaced by the location of the logged in user.

captcha

{captcha}

The 'captcha' variable will be replaced by a unique captcha image. The text in this image must be submitted by the user in order for the form to post. Note that when using the captcha you need to provide users with a field in which to submit the captcha word. See below.

custom_member_field

{custom_member_field}

You can call in any of the custom member fields for the logged in user.

Conditionals

The following conditionals are available with the {exp:freeform:form} tag.

• if duplicate
• if not_duplicate
• if captcha

if duplicate

{if duplicate}{/if}

In the event that a user is either logged in or their IP address is available and if they have already submitted your form, the contents of this conditional will be shown.

if not_duplicate

{if not_duplicate}{/if}

In the event that a user is either logged in or their IP address is available and if they have not already submitted your form, the contents of this conditional will be shown.

if captcha

{if captcha}{/if}

Freeform respects the global captcha preferences that you set in EE. 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

• file1
• captcha
• mailinglist

file1

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

You can allow users to submit attachments with their Freeform submissions. You can accept as many attachments as you like. For each attachment you want to receive, add a field of type 'file' to your form and name it 'file1', 'file2', 'file3' successively.

captcha

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

When using captchas in your forms, this field allows users to submit the text of the captcha image they see.

mailinglist

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

The 'mailinglist' 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.

Note: You must specify and require the 'email' field in your form for this to correctly work.

Examples

Example 1

This example will post straight into Freeform with no form name. No fields are required. No notifications are sent to email addresses.

The field named ‘question’ must have been created in Freeform prior to any use of the form.

{exp:freeform:form form_name="your_form"}
 
<p>Name<br />
<input type="text" name="name" value="" />
</p>
 
<p>Email<br />
<input type="text" name="email" value="" />
</p>
 
<p>Question<br />
<textarea name="question" /></textarea>
</p>
 
<p>
<input type="submit" name="submit" value="submit" />
</p>
 
{/exp:freeform:form}

Example 2

This example will prevent duplicate postings by the same user. Users who have already posted to this form will be redirected to the template group and template ‘weblog/already_posted’. The form_name parameter, ‘party_sign_up’ specifies which form to check for previous postings. If you leave the form_name parameter out, all forms will be checked.

Note: Duplicate postings can only be detected if a user’s IP address was previously recorded and is recognized again or if the user is logged in and has already posted.

{exp:freeform:form form_name="party_sign_up" redirect_on_duplicate="weblog/already_posted"}
 
<p>Name<br />
<input type="text" name="name" value="" />
</p>
 
<p>Email<br />
<input type="text" name="email" value="" />
</p>
 
<p>Will attend party<br />
<input type="radio" name="will_attend" value="yes" /> Yes<br />
<input type="radio" name="will_attend" value="no" /> No<br />
</p>
 
<p>
<input type="submit" name="submit" value="submit" />
</p>
 
{/exp:freeform:form}

Example 3

This example will organize postings under the form name of ‘foods_form’. When posted, the user will be returned to the template group and template ‘weblog/foods’. ‘mitchell@solspace.com’ will be notified of the posting using the notification format declared in the Freeform template ‘food_template’. The form will not post unless the required fields of ‘name’ and ‘email’ are completed.

Note the use of the post array syntax in ‘foods[]‘. This is a multi-select field that will allow the submission of multiple values for the ‘foods’ field. Because the standard naming convention of field_name[] is used, Freeform will recognize the post array and process the field appropriately. The Freeform field named ‘foods’ must have been created in Freeform prior to any use of this form.

{exp:freeform:form form_name="foods_form" return="weblog/foods" notify="mitchell@solspace.com" template="food_template" required="name|email"}
 
<p>Name<br />
<input type="text" name="name" value="" />
</p>
 
<p>Email<br />
<input type="text" name="email" value="" />
</p>
 
<p>Favorite Foods<br />
<select name="foods[]" multiple="multiple" />
<option value="Broccoli">Broccoli</option>
<option value="Sushi">Sushi</option>
<option value="Chocolate">Chocolate</option>
<option value="Bananas">Bananas</option>
</select>
</p>
 
<p>
<input type="submit" name="submit" value="submit" />
</p>
 
{/exp:freeform:form}

Extensions

The following extension hooks can be used with Freeform to increase the module's capabilities.

• freeform_module_admin_notification
• freeform_module_user_notification
• freeform_module_validate_end
• freeform_module_form_end
• freeform_module_insert_begin
• freeform_module_insert_end

freeform_module_admin_notification

This extension hook executes right before admin notification emails are sent. It allows you to modify the $msg array. This extension hook passes to you $fields, $this->entry_id, and $msg.

freeform_module_user_notification

This extension hook executes right before user notification email is sent. It allows you to modify the $msg array. This extension hook passes to you $fields, $this->entry_id, and $msg.

freeform_module_validate_end

This extension hook is called immediately after the built in form validation routine. It allows you to do further validation on a Freeform posting prior to submission. Available through the extension is the array $errors which contains the validation errors present up to the point of the hook execution. Your extension can stop the form submission by returning the error messages at that point.

freeform_module_form_end

This extension hook is called immediately before the form is returned to the template parser for display. Available through the extension is the string variable $r which contains the HTML form code. You can use regular expression replacements to alter the form.

Important: Remember to play nice. If your extension uses this hook, it needs to return the contents of the $r variable whether your extension alters its contents or not. This allows other extensions to execute on the same hook at the same time and not lose data.

freeform_module_insert_begin

This extension hook is called immediately before user submissions are inserted into the DB.

Available through this extension hook is the associative array $data which contains all of the information to be inserted as a Freeform entry.

freeform_module_insert_end

This extension hook is called immediately before users are redirected upon a successful form submission.

Available through this extension hook is the associative array $fields which contains all of the Freeform fields where the key is the name of the field and the value is the label.

Also available through this extension hook is the $entry_id of the submitted Freeform entry.

Finally, if a user email was sent on this form submission, you will have access to the $msg variable that contains the data for the email message sent.

NOTE: If no user email is sent, this array will be empty as Freeform will not have loaded the notification template.

© 2009 Copyright · Solspace · Support Forums · License Agreement