Skip to main content

ElementsProRevised in 5.0+

Freeform allows you to connect and map Freeform submission data to other Craft Elements.

Hire Us

Freeform includes the ability to map the Freeform submission ID, submission token, submission title, form ID, form handle and form name to other element fields as well. You can choose these as options in the mapping table in the Integrations tab.

​Craft Entries

If you'd like to map Freeform submission data to Craft Entries, while in the form builder for an existing form, do the following:

  1. Click on the chain icon button in the Property Editor column at the top right.
  2. For the Type dropdown, select Entries.
  3. For the Section dropdown, select the section you'd like to map to.
  4. For the Entry Type dropdown, select the section entry type you'd like to map to.
  5. If you'd like new entries created from Freeform submissions to be disabled when submitted, check the Disable entries? checkbox.
  6. Map compatible Craft fields to Freeform fields in the Field mapping table.

In addition to most custom Craft fields, Freeform can also map to the Post Date and Expiry Date.4.0.23+

​Important Notes

  • Freeform submissions can map to sections with autogenerated titles. Just make sure to set the fields you're using to map to Craft fields that populate the title field to be required on Freeform's end, otherwise the submission likely won't generate the Craft Entry if data for the title is missing.
  • Freeform attempts to route Entry-based errors to the mapped fields. In some cases you might see more than 1 error for a Freeform field because of this. The field that is mapped to the Entry Title field will mention that "a title is required", etc. Entry Slug errors are suppressed for Freeform errors as not to confuse users.
  • While multipage forms do appear to map correctly to entries, you may see some slightly unusual behavior. For example, if you have your Title field placed in the second page, when submitting from the first page to the second page, the second page will highlight the field mapped to the Title field highlighted with an error. The whole process still works, but there's that visual issue.
  • If the submission is blocked or flagged as spam, there's currently no way to retroactively map submission data to Entries. The best option for avoiding this would be using Captchas.

​Craft Users

This feature requires a Craft Pro license in order to work, as Users are a Craft Pro feature.

If you'd like to map Freeform submission data to Craft User, essentially creating a User Registration form, while in the form builder for an existing form, do the following:

  1. Click on the chain icon button in the Property Editor column at the top right.
  2. For the Type dropdown, select Users.
  3. For the User Group checkboxes, select the user group(s) you'd like to map to.
    • All user groups (including ones with access to CP) will show here. Exercise extreme caution if allowing users to self-register for accounts that can access the Craft CP!
  4. If you'd like new users created from Freeform submissions to not yet be activated (and receive the Craft User Activation email) when submitted, check the Activate users? checkbox. If you'd like to manually approve registrations (please see warning below) and suppress the email notification to users, uncheck the Send activation email? checkbox.

    When using a manual Admin approving approach, it's still possible for a Pending user to circumvent this process if a Forgot Password form is available to them, as Craft currently does not have a concept of Admin approval only, and allows users to verify their account either through an email notification or using a Forgot Password form.

  5. Map compatible Craft fields to Freeform fields in the Field mapping table.
    • See Field Mapping Guidelines for more info.
    • You will need to use the special Password field for mapping passwords to User passwords. The Freeform Password field will NOT save any password data in the Freeform database tables.

Check out our guide for a specialized look at creating User registration forms.

​Important Notes

  • Freeform submissions can map to sections with autogenerated titles. Just make sure to set the fields you're using to map to Craft fields that populate the title field to be required on Freeform's end, otherwise the submission likely won't generate the Craft Entry if data for the title is missing.
  • Freeform attempts to route User-based errors to the mapped fields. In some cases you might see more than 1 error for a Freeform field because of this. The fields that are mapped to essential fields like username, email and password will mention that "Email cannot be blank", etc.
  • While multipage forms do appear to map correctly to users, you may see some slightly unusual behavior. For example, if you have your Password field placed in the second page, when submitting from the first page to the second page, the second page will highlight the field mapped to the Password field highlighted with an error. The whole process still works, but there's that visual issue.
  • If the submission is blocked or flagged as spam, there's currently no way to retroactively map submission data to Users. The best option for avoiding this would be using Captchas.

​Solspace Calendar Events

Freeform's Element Connections feature supports mapping to Solspace Calendar Events, providing you have the Calendar plugin installed of course. If you'd like to map Freeform submission data to Calendar Events, while in the form builder for an existing form, do the following:

​Setup Instructions

  1. Click on the chain icon button in the Property Editor column at the top right.
  2. For the Type dropdown, select Calendar Events.
  3. For the Calendar dropdown, select the calendar you'd like to map to.
  4. If you'd like new events created from Freeform submissions to be disabled when submitted, check the Disable events? checkbox.
  5. If you'd like all new events created through Freeform to be considered "all day" events, check the All day? checkbox.
    • When checked, this will allow you to have users just choose a Start date and End date for events and not worry about time, but you will not be able to allow any users at all to specify a time for some events.
    • If you wish to have users specify times in addition to dates of their events, leave this unchecked. If you wish to offer the ability for users to set that an event is "all day", you can map a Freeform checkbox field to the All Day field in the field mapping table.
  6. Map compatible Craft fields to Freeform fields in the Field mapping table.

​Important Notes

  • Currently the Calendar integration only allows you to specify Start Date (and Time), End Date (and Time) and if the event is All Day or not. Advanced settings like repeat rules are currently not available.
  • Freeform attempts to route Calendar-based errors to the mapped fields. In some cases you might see more than 1 error for a Freeform field because of this. The field that is mapped to the Event Title field will mention that "a title is required", etc. Event Slug errors are suppressed for Freeform errors as not to confuse users.
  • While multipage forms do appear to map correctly to entries, you may see some slightly unusual behavior. For example, if you have your Title field placed in the second page, when submitting from the first page to the second page, the second page will highlight the field mapped to the Title field highlighted with an error. The whole process still works, but there's that visual issue.
  • If the submission is blocked or flagged as spam, there's currently no way to retroactively map submission data to Calendar Events. The best option for avoiding this would be using Captchas.

​Field Mapping Guidelines

There are some obvious limitations with field mapping, as Freeform does not have anything like a Matrix or Table field, etc. Most traditional fields that are similar to each other should be able to correctly map to each other however. This list is a work in progress, and we'll continue to update it as we make improvements:

  • Freeform Checkbox fields can be mapped to Craft's Checkbox field (with just 1 option) as well as the Lightswitch field. Just make sure the value and casing in Freeform matches.
  • Craft Date/Time fields should be mapped to with the following format: Y-m-d H:i:s (aka YYYY-MM-DD HH:MM:SS or just YYYY-MM-DD for Freeform Date & Time fields using Date only).
  • Freeform File Upload fields can be mapped to regular Craft Assets fields, as well as the Users Photo field.

​Email Notification Templates

When using the Element Connections feature, you can use the element object to display data from the newly created Craft Element such as ID, title, username, etc.

For example (but not limited to):

  • element.id will return the ID of the newly created Element
  • element.title will return the title of the newly created Craft Entry
  • element.username will return the username of the newly created Craft User

If you have more than 1 element connection for the form, you can use either:

  • {% for item in element %}
  • {{ element[0].id }}, {{ element[1].id }}, etc

​Editing Elements

Please be aware that the Element Editing feature opens up a wide variety of possibilities, including ones that could pose a risk to your data and User accounts. When used cautiously and correctly, this feature is secure and is of no risk. Completely read the documentation below, and always carefully think through your flow and test it thoroughly. When in doubt, do not hesitate to contact Solspace support for clarity about the approach you're taking and if there may be any issues or risks with it.

Freeform allows you to edit/update existing Craft elements (Entries, Users and Calendar Events currently) by including the elementId parameter in your form. It works by feeding a Freeform form an element ID. If you already have a Freeform form to handle creating Craft elements (e.g. User Registration), it's very likely you'll need to create a new form (or duplicate an existing form as a starting point) for form to update Craft elements (e.g. Edit Profile). When you create a new form, be sure to to set up the Element Connections feature and field mapping, and then in your template, a basic call to it would look something like this:

{{ craft.freeform.form("editCraftUsers").render({
	elementId: craft.app.request.segment(3)
}) }}

​Important Notes

  • Element editing does not offer any user or author authentication for Craft Entries and Calendar Events. We urge you to always wrap these forms in a check to make sure the user is a logged in Admin only (or specific checks on certain user groups).
  • User account element editing is restricted to the following logic:
    • Logged in users can only modify their own account.
    • Logged in Admins can modify any account.
    • Logged in users / groups with the Edit users Craft permission may modify other user accounts.
  • There are currently some limitations with User account editing: _ Users cannot be asked to enter their current password to update their profile. _ Users currently can update their email address, but there will currently be no additional validation from Craft (such as having the user verify their email address, etc). A future version may address this. _ Users may see redundant error messages for fields like Email Address, as some of Craft's validation will be show up in addition to Freeform validation. _ If you have users / groups with the Edit users Craft permission but do not want them editing users on the front end, you'll need to use template conditionals to prevent it (in the event you provide a dynamic way of doing so for Admins, e.g. URI segments). _ For self-serve "profile update" forms, you should be using something like elementId: currentUser.id (see docs example below). _ Users currently cannot have their user group(s) changed when they are updated through a Freeform form with Element Connections. A future version may address extra settings and handling to accomodate user group changes.

Here are some examples of what this might look like for you...

​Allow the currently logged in user to update their own User profile

{% if currentUser %}
	<h2>Update Your Profile</h2>
	{{ craft.freeform.form("editCraftUsers").render({
		elementId: currentUser.id
	}) }}
{% endif %}
{% set segment2 = craft.app.request.segment(2) %}

{# SAFETY FIRST - LOGGED IN ADMINS ONLY #}
{% if (currentUser) and (currentUser.admin) %}

	<h2>Craft Entries</h2>
	{% set entries = craft.entries()
		.section('mySection')
		.limit(4)
	%}
	<ul>
	{% for entry in entries.all() %}
		<li>
			<a href="{{ siteUrl }}edit-entry/{{ entry.id }}/">{{ entry.title }}</a>
		</li>
	{% endfor %}
	</ul>

	{% if segment2 %}
		<hr />
		{{ craft.freeform.form("editCraftEntries").render({
			elementId: segment2
		}) }}
	{% endif %}

{% endif %}

You could also use a conditional like this to perform a check on users assigned to a specific group:

{% if currentUser.isInGroup('editors') %}{% endif %}
Page Feedback