Skip to main content

Getting Started

​Introduction to Freeform

This page provides you with an overview of how Freeform works without going into to much detail about each feature so it's easy to digest. You can of course click the links to learn more about each feature. Be sure to check out the Getting Started documentation after reading this page.

Freeform 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 is very powerful and flexible, so there is also a wide variety of other features, settings and options.

​Forms

When creating forms, you sometimes need to look at things backwards. It often helps to prepare fields, email notification templates and other things BEFORE beginning to create your form. However, you don't have to do it this way. Freeform Composer allows you to do this directly inside the Composer form interface as well (but limited approach for it). Freeform also comes with several common fields preinstalled for you, so that should get you started.

Be sure to review the settings in the Form Settings area to adjust things such as form name and handle, formatting template, default status and return URL.

Freeform also allows for multi-page forms, and has its own built in spam protection service (it does not currently work with EE's native CAPTCHA feature as it has always proven ineffective).

​Fields

Freeform uses its own set of fields and field types. Fields are global and available to all forms, but they can also be overwritten per form. This allows you to save time reusing existing fields when making other forms, but also gives you flexibility to make adjustments to them when needed. So to clarify, you can create fields with labels and options that are common to all forms, but also override those on each form.

Fields can be created and managed in the main field creation area (Freeform > Fields > New Field) and can also be created directly within the Composer interface as well.

The following field types are available:

  • Text - a simple input field.
  • Textarea - a simple multi-line input field.
  • Email - an input field that is flagged in Freeform to expect an email address value as well as possibility for receiving email notifications.
  • Hidden - a hidden field.
  • Select - a select dropdown menu field.
  • Checkbox - a single checkbox field.
  • Checkbox Group - a group of checkboxes.
  • Radio Group - a group of radio options.
  • File Upload - a single file upload field, using EE's File Manager.
  • Dynamic Recipients - a select dropdown menu field that contains protected email addresses and labels for each.

Additionally, you may also insert HTML areas into your form for you to type or paste your code into. The HTML will also be live parsed in the Composer layout area.

​Email Notifications

Email notifications are global and can be reused for multiple forms, saving you time when you are managing many forms. Email notification templates can be managed within EE control panel (saved to database), or as HTML template files. Database entry templates are created and customized at Freeform > Notifications. They can also be created directly at form level within Composer. Email notification templates that are created within Composer will contain basic default content, and should be checked and updated once finished building your form.

Freeform allows you to send email notifications upon submittal of a form 5 different ways, each with their own content/template:

  • To admin email address(es) for the form.
  • To a predefined select menu/radios of email addresses (and labels) for the user to choose (Dynamic Recipients field type).
  • To the user submitting the form, with the email addresses specified/selected in the Email field type.
  • To a user-defined email address (e.g Tell-a-Friend form), with the email addresses specified/selected in the Email field type.
  • To template-defined email address with Dynamic Notification feature.

​Formatting Templates

Freeform attempts to do all the heavy lifting when it comes to templating. Our looping templating approach allows you to automate all or almost all of your form formatting. This can be achieved by building formatting templates for your forms.

Forms can be generated on the front end templates 2 different ways:

  1. By coding the formatting directly within the template that you want the form to appear in, using the Freeform_Next:Form template tag.
  2. By assigning one of an unlimited number of predefined formatting templates (stored as a regular HTML template file in EE Templates directory) inside Composer and using the Freeform_Next:Render method. This approach is very portable / DRY, and works similar to an include. Then simply just insert 1 line of code: {exp:freeform_next:render form="contact"} in the template you want your form to load in.

​Mailing List API Integrations

Freeform supports some popular Mailing List API integrations. The following mailing list integrations are currently available:

​CRM API Integrations

Freeform supports some popular CRM (Customer Relationship Management) API integrations. The following CRM integrations are currently available:

​Templating

As for templating, we strived to make things as flexible as possible, while also coming up with templating that can automate much of the handling of parsing of your forms. Freeform is capable of figuring out as much of this as possible for you. This can be achieved by building formatting templates for your forms, or simply building forms directly within the page template(s) you're placing your forms into:

Freeform also includes a complete set of demo templates. These demo templates let you have a fully functioning area on your website with just a couple clicks! Further to this, it allows you to see real world examples of the template code in action, which will help you get acquainted with Freeform quicker.

​Submissions

Similar to Channel Entries, every time a user submits a form, we refer to those as submissions. Currently, submissions can be viewed and edited in the control panel, and displayed on the front end in templates as a list and individually. Within the control panel, you can view submissions by form, adjust which field columns are shown, click into any of the submissions to edit them, and export the full set of submissions.

​Getting Started

This page provides you with instructions to get started quickly with Freeform. It's not exhaustive by any means, but it will get your feet wet if you're new to Freeform, and help you understand a typical flow for creating forms.

First things first, Freeform 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 is very powerful and flexible, so there is also a wide variety of other features, settings and approaches to building forms as well.

​Step 1: Fields

Freeform uses its own set of fields and field types. Fields are global and available to all forms, but they can also be overwritten per form. This allows you to save time reusing existing fields when making other forms, but also gives you flexibility to make adjustments to them when needed. So to clarify, you can create fields with labels and options that are common to all forms, but also override those on each form.

Go to the Fields area inside Freeform. By default, it comes with a handful of common fields you might use. If there's any other fields you think you might need, you can add them here. If you need to add some later, you can always come back to this area, or create fields directly inside your form too.

​Step 2: Form

  1. Go to the Forms area inside Freeform. Click on the New Form button at the top right.
  2. You'll now see a form building interface we call Composer, where you can begin creating and configuring your form. Composer is a workspace divided into 3 columns:
    • Fields: the left column, where you can see the fields available (and create new ones).
    • Layout: the middle column, where you can drag and drop fields (from left column) into, and can rearrange each field however you please.
    • Property Editor: the right column, which is where you are able to configure the form, email notifications, API integrations, and properties for each field and page, etc.
  3. Begin creating your first form by changing the name and handle of the form from "Composer form" to something else. The Form Settings will load in the Property Editor by default when the form is first created, but you can get to it by clicking the Form Settings button at top right area. Let's call the form Contact with handle of contact. Once that's done, click Save button at top (you don't have to right away, but good practice, like when you're working on a Word document, etc).
  4. In the left column, look for some fields you need. You can add them to your form by clicking and holding, and then dragging them onto the middle Layout column and let go. You can rearrange the fields however you please. They can even be placed side-by-side, and Freeform will automatically create columns for the field layout.
  5. Once you have a handful of fields placed and arranged, click on some of the fields (one by one) and view the properties for them in the right Property Editor column. Here is where you can set a field to be required, set placeholder values, etc. If you're working with a more complex field such as the Date & Time fieldtype, be sure to scroll down in the Property Editor column to see more available options. Once done all that, click the Save button at top.

​Step 3: Email Notifications

A variety of email notification options are available with Freeform. For the purpose of this example, we'll keep it simple and create an email notification for Admin(s) and an email notification for the user submitting the form.

  1. To add an email notifications for Admin(s), click on the Notify button at the top right.
  2. Assuming you don't yet have any email notification templates created, you can quickly create one here by clicking the Add New Template button. Let's name it Admin and click the Save button below. In the Admin Recipients field that appears underneath, enter the email address(es) here. Separate multiples on new lines. Then click the Save button at top.
  3. To set an email notification for the user submitting the form, find your Email field in the middle Layout column and click on it.
  4. In the Property Editor column on the right, you'll see an Email Template field. You can quickly create another email notification template by clicking the Add New Template button. Let's name it Submitter and click the Save button below.

To customize the email notification templates you quickly created in Composer, visit the Email Notifications page in the Freeform control panel later.

​Step 4: Formatting Templates

Freeform attempts to do all the heavy lifting when it comes to templating. Our looping templating approach allows you to automate all or almost all of your form formatting. This can be achieved by using ready-made available options, or custom building your own formatting templates for your forms.

Form rendering can be done two different ways - through a formatting template that can be reused by multiple forms, or entering all of the formatting code directly inside your page template. For the purpose of this example, we'll use a ready-made example formatting template.

  1. Click on the Form Settings button at top right area of Composer.
  2. In the Property Editor column on right, look for Formatting Template field. Select any one of the several formatting template examples and click the Save button at top. If you select one such as Bootstrap, be sure you call the necessary Bootstrap CSS and JS files in your page template.

​Step 5: Templating

Your form should now be ready to go. Before you hit the templates, take note of the handle name of the form you just created (you can view it in the Form Settings area of Property Editor in the right column). If you followed our example, it will be contact.

  1. Create a new template or open up an existing one.
  2. Paste the following code into your template:
{exp:freeform_next:render form="contact"}

That's it!

​Demo Templates

Be sure to check out your form in the demo templates that come with Freeform if you want to quickly see your forms in action. These demo templates let you have a fully functioning area on your website with just a couple clicks!

​Customizing Rendering of Form

If you choose to use the Render approach as used in the example above in step 5, you can customize the rendering of your form by applying overrides.

For example, instead of calling your form like this:

{exp:freeform_next:render form="contact"}

You can customize your form by applying some overrides:

{exp:freeform_next:render
    form="contact"
    label_class="my-label-class"
    input_class="my-input-class"
    submit_class="my-button-class"
    instructions_below_field="yes"
    override_values:location="{segment_3}"
}
    {if form:no_results}Sorry, no form was found.{/if}
{/exp:freeform_next:render}

In the example above, all of the field labels will globally be given the CSS class of my-label-class, and inputs given the CSS class of my-input-class, but your submit button(s) will be given the class of my-button-class. If using instructions for fields, Freeform will place them below the input instead of above. And finally, your hidden field with a handle of location will be given a value from the third segment in the URL (if supplied).

Be sure to check out the Form template tag documentation for more information.

Page Feedback