Switching from Freeform Classic to Freeform ("Next")
For the purpose of clarity in this documentation resource, any prior version of Freeform (free) and Freeform Pro 4.x, 5.x and 6.x are referred to as Freeform Classic. The new version of Freeform is referred to as Freeform Next.
Freeform has been completely rewritten from ground up. Whether you're considering switching from Freeform Classic to Freeform Next, or interesting in using Freeform Next on your next site build, this page is a resource to help you understand the differences and changes made with Freeform Next.
How to Upgrade
You must have the appropriate EE-compatible version of Freeform Classic installed and upgraded for the new Freeform "Next" to properly detect and migrate it. For example, if you moved from EE2 to EE4, but only have the EE2 version of Freeform Classic (4.x) installed, the migration won't work correctly. You'll need to update to the 5.x (EE3) or 6.x (EE4/EE5) version of Freeform Classic first. If you're switching from Classic to the new Freeform, we don't expect you to pay an upgrade fee to access the EE3 or EE4 compatible versions of Classic to only use it for 15 mins to run the migration utility, so feel free to temporarily "borrow and reuse" a newer Classic license from another site if you have, or contact us for a temporary copy.
Quick Overview
If you want to retain any of your Freeform data, you'll need to appease Freeform Next and its Migration Utility (if you don't care about this data, then feel free to uninstall Freeform Classic and fresh install Freeform Next):
Version & Compatibility
| Freeform version | Compatible EE version(s) |
|---|---|
| Freeform Classic 3.x / Freeform 3.x free | EE 1.x, 2.x |
| Freeform Classic 4.x / Freeform 4.x free / Freeform Pro 4.x | EE 2.x |
| Freeform Classic 5.x / Freeform 5.x free / Freeform Pro 5.x | EE 3.x |
| Freeform Classic 6.x | EE 4.x, 5.x |
| Freeform Next 1.x / new Freeform 1.x | EE 3.x, 4.x, 5.x |
| Freeform Next 2.x / new Freeform 2.x | EE 6.x |
Steps Needed to Migrate
| Current Setup | Upgrade Plans | Steps Needed To Take |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Changes to Composer
Freeform Next centers itself around the idea of letting admins and/or clients enjoy the experience of building and managing simple or complex forms in an intuitive interface that lets you see a live preview of the forms you're building. We call this Composer, where almost everything is at your fingertips as it aims to stay out of your way and let you do as much as possible without having to move around to other areas in the control panel. At the same time, Freeform Next is very powerful and flexible, so there is also a wide variety of other features, settings and options.
For Freeform Next, we now only include a single method for building forms. Freeform Classic used to allow EE Template and Composer methods. The very manual EE Template-based approach is no longer a choice. We strongly believe you will be so impressed with the power and flexibility of the new Composer, that you won't want to go back to EE Template approach. And even if you do, you still can build out your forms completely manually if you desire (but you'll still need to quickly assemble a form layout inside Composer).
Formatting options inside templates or Formatting Templates are so flexible, powerful, and easy to use. We carefully came up with a new, intuitive and consistent syntax for templating.
Changes to Composer Templates
Composer Templates are now referred to as Formatting Templates in Freeform Next.
While Freeform Next offers a very intuitive Composer interface to give you a live preview of the form you're building, there of course isn't exactly a magic way to do this on the front end for your templates. However, we have created an automated way for Freeform to figure out as much of this as possible for you.
As mentioned above, Formatting options inside templates or Formatting Templates are so flexible, powerful, and easy to use. We carefully came up with a new, intuitive and consistent syntax for templating.
Formatting Templates are also now stored as HTML files. The benefit here is that they can work nicely with version control and/or staging environments, etc, rather than being stored in the database.
Forms can be generated on the front end templates 2 different ways. There is no worse or better way, but here's an overview:
- With the Freeform_Next:Form template tag.
- Your form formatting code is contain directly within the template that you want the form to appear in.
- No matter what formatting template your form may have assigned to it in Composer, the form always conforms to the template formatting used in this template.
- Using Freeform_Next:Render method.
- Your form formatting code is stored in a separate template, but is very portable / DRY, and works similar to an include.
- Formatting templates are HTML files stored in the EE Templates directory (benefit is that they can work nicely with version control and/or staging environments, etc).
- Freeform includes several formatting template examples for you to start out with as well.
- In template(s) that you want your form(s) to show up in, you simply just insert 1 line of code:
{exp:freeform_next:render form="contact"}
- Your form formatting code is stored in a separate template, but is very portable / DRY, and works similar to an include.
Formatting templates are optional, and only necessary if using the Freeform_Next:Render tag method, which essentially allows you to attach a formatting template to a form so that you don't need to include formatting inside the template(s) you place the form inside.
The code and formatting in these templates looks exactly like the code in a Freeform_Next:Form tag, but excludes the opening and closing {exp:freeform_next:form} tags, as the Render tag does this for you.
Changes to Freeform Entries
Freeform Entries are now referred to as Submissions in Freeform Next. You'll now use the {exp:freeform_next:submissions} template tag to display an individual submission or list of submissions based on some or no criteria.
Freeform Next also now includes an option to NOT store submissions in the database, per form.
Freeform Next currently only supports basic CSV exporting. In the future, more exporting options will be added.
Changes to Email Notifications
Email Notification templates work generally the same way, but now include the option of storing them as HTML files. The benefit here is that they can work nicely with version control and/or staging environments, etc, rather than being stored in the database.
Changes to Multi-Page Forms
Multi-page forms still work similar to how they did with Freeform Classic, with the exception that there is no unique URI segment per page at this time, and users cannot jump ahead to different pages, only forward and backward 1 page.
Changes to Spam Protection
One of the greatest shortcomings in Freeform Classic was spam control. It used to be that you had to either live with out of control spam submissions, or purchase and install another add-on to combat the issue. This is why Freeform Next no longer has Ban Keywords feature and does NOT use EE's native CAPTCHA feature as it has always proven ineffective. Instead, it includes its own Javascript-based honeypot spam protection, which is immeasurably more effective (and we've had excellent success with it in Freeform for Craft CMS). This is enabled by default, but can be disabled in the Freeform Settings.
Changes to Permissions
Freeform Next currently does not have any module-level permissions like Freeform Classic. However, this is a feature that will likely be added back in a future version.
Addition of API Integrations
Freeform Next includes integrations with several popular Mailing List and CRM (Customer Relationship Management) API's, including MailChimp, Constant Contact, Campaign Monitor, Salesforce and HubSpot. We plan to add support for other API's in the future as well.
Migrating from Freeform Classic
Migration from Freeform Classic to the new Freeform is now available. Once you have installed the new Freeform, don't make any modifications to it, and then review the Migration utility documentation before running the migration utility. Freeform Next can be used alongside classic Freeform/Freeform Pro installations if you're wanting to try out and/or switch to Freeform Next.