Freeform Documentation

Learn the basics, and get to know Freeform inside and out.

Freeform 1.x Docs

Plugin Settings

Solspace Freeform includes several settings that allow you to customize your form management experience. To adjust your settings, click the Settings menu item while in the Freeform plugin, or go to Settings > Plugins > Freeform and click the settings link.

If you wish to override these settings with a config file, please see the Config Overrides documentation.

General Settings

The settings allow you to adjust:

General #

  • General Settings #

    • Custom Plugin Name #
      • Override the plugin name by specifying your own here.
    • Show Composer Tutorial #
      • Enable this to show the interactive tutorial again in Composer. This setting disables again when the tutorial is completed or skipped.
    • Default view #
      • This setting allows you to specify which Freeform page should be loaded by default when clicking the Freeform navigation link.
    • Display Order of Fields in Composer #
      • The display order for the list of available fields in Composer:
        • Field type, Field name (alphabetical)
        • Field name (alphabetical)
    • Include Default Freeform Formatting Templates #
      • Disable this to hide the default Freeform formatting templates in the Formatting Template options list inside Composer.
    • Remove Newlines from Textareas for Exporting #
      • Enable this to have newlines removed from Textarea fields in submissions when exporting.
    • Disable Submit Button on Form Submit? #
      • Enable this to automatically disable the form's submit button when the user submits the form. This will prevent the form from double-submitting.
    • Freeform Javascript Insertion Location #
      • The location of where you want Freeform to insert it's scripts for form and field functionality (such as spam protection and advanced field types). This setting should be set to Inside Form to work with AJAX.
        • Page Footer
        • Inside Form
    • Automatically Purge Submission Data #
      • If you wish to have Freeform automatically purge submission data after a specified number of days, enable this setting and specify the number of days after submission date it should purge submissions.
        • WARNING: Enabling this and saving this settings page will result in purging beginning.
        • Days After Submission Date to Purge
          • Select the number of days after submissions have been submitted for Freeform to begin automatically purging. This process will only run every hour, and only when Freeform is accessed on the front end in templates or in the control panel.
  • Formatting Templates #

    • Directory Path #
      • When using custom formatting templates for your forms, you'll need to specify where your Twig-based templates are stored.
      • Provide a relative path to craft root to your custom form templates directory.
        • Ex: templates/freeform
      • To add a starter example template, click the "Add a sample template" button, and then edit the template after.

Formatting Templates

  • Email Templates #
    • This area is for users that wish to use Twig-based HTML template files for email notifications. See Email Notifications documentation for more information about implementation.
    • Directory Path #
      • Provide a relative path to craft root to your custom form templates directory.
        • Ex: templates/freeform_emails
      • To add a starter example template, click the "Add a sample template" button, and then edit the template after.
    • Default Email Notification Creation Method #
      • Select which storage method to use when creating new email notifications with Add New Notification option in Composer.
        • Database Entry - Use CP-based database template editor.
        • Template File - Use Twig-based HTML template files.

Email Templates

  • Statuses #
    • This area allows you to manage and create new statuses for your forms.
      • You can set the default status to be set for all forms here.

Statuses

Create a Status

  • Demo Templates #
    • Allows you to install the Demo Templates to get Freeform up and running on the front end with just a couple clicks!

Spam #

  • Spam Settings #
    • Freeform Honeypot / Javascript detection #
      • Freeform includes its own Javascript-based honeypot spam protection. This is enabled by default, but can be disabled here.
      • For more information, visit the Spam Protection documentation.
    • Spam Protection Behavior #
      • Select the behavior you'd like Freeform to take when it detects a submission as being spam:
        • Simulate successful submission (recommended)
        • Display error messages (not recommended)
        • Reload form
    • Use Spam Folder #
      • When enabled, all submissions caught by the honeypot or blocked email addresses, keywords and IP addresses will be flagged as spam and stored in the database, but available to manage in a separate menu inside Freeform.
      • Automatically Purge Spam Submissions #
        • If you wish to have Freeform automatically purge submissions flagged as spam after a specified number of days, enable this setting and specify the number of days after submission date it should purge spammy submissions.
          • WARNING: Enabling this and saving this settings page will begin the purging of submissions flagged as spam, and cannot be undone.
          • Days After Submission Date to Purge
            • Select the number of days after spammy submissions have been submitted for Freeform to begin automatically purging. This process will only run every hour, and only when Freeform is accessed on the front end in templates or in the control panel.
    • Block Email addresses #
      • Enter email addresses you would like blacklisted from being used in Email fields. Use * for wildcard, and separate multiples on new lines.
      • Display errors about blocked email(s) under each email field?
        • Enable this if you'd like field-based errors to display under the email field(s) that the user has entered blocked emails for. Not recommended for regular use, but helpful if trying to troubleshoot submission issues.
    • Block Keywords #
      • Enter keywords you would like blacklisted from being used in all text and textarea fields. Use * for wildcard, and separate multiples on new lines.
      • Display errors about blocked keyword(s) under each text/textarea field?
        • Enable this if you'd like field-based errors to display under the field(s) that the user has entered blocked keywords for. Not recommended for regular use, but helpful if trying to troubleshoot submission issues.
    • Block IP addresses #
      • Enter IP addresses you would like blacklisted. Separate multiples on new lines.
    • Form Submission Throttling #
      • Globally (affecting all users) prevent spam or attacks by limiting the number of times all forms can be submitted within a given timeframe.

Spam Settings

  • reCAPTCHA (Pro only) #
    • Enable reCAPTCHA #
      • Enable this setting and fill in the reCAPTCHA Site Key and Secret Key to enable reCAPTCHA for Freeform. Then, to add reCAPTCHA to your forms, open up and edit each form and drag over the reCAPTCHA special field anywhere you like into your form layout.
      • Visit Google reCAPTCHA site to register your site and get your Site Key and Secret Key.

reCAPTCHA Settings

API Integrations #

  • Mailing Lists (Pro only) #
    • The Mailing Lists area allows you to manage your mailing list API integrations.
    • Mailing list integrations are set up here and are globally available to all forms, but are configured per form inside the Composer interface.
    • Included with Lite edition is access to connecting to the Craft Campaign plugin.
    • To connect to a mailing list API, click the New Mailing List Integration at the top right.

Connect Mailing List

  • CRM (Pro only) #
    • The CRM area allows you to manage your CRM (Customer Relationship Management) API integrations.
    • CRM integrations are set up here and are globally available to all forms, but are configured per form inside the Composer interface.
    • To connect to a CRM API, click the New CRM Integration at the top right.
      • View the CRM API Integration documentation for more information about setting up and configuring.

Connect CRM