Configuration #

Create an formie.php file under your /config directory with the following options available to you. You can also use multi-environment options to change these per environment.

The below shows the defaults already used by Formie, so you don't need to add these options unless you want to modify the values.

<?php

return [
    '*' => [
        'pluginName' => 'Formie',
        'defaultPage' => 'forms',

        // Forms
        'defaultFormTemplate' => '',
        'defaultEmailTemplate' => '',
        'enableUnloadWarning' => true,
        'ajaxTimeout' => 10,

        // General Fields
        'defaultLabelPosition' => 'above-input',
        'defaultInstructionsPosition' => 'below-input',

        // Fields
        'defaultFileUploadVolume' => '',
        'defaultDateDisplayType' => '',
        'defaultDateValueOption' => '',
        'defaultDateTime' => '',

        // Submissions
        'maxIncompleteSubmissionAge' => 30,
        'enableCsrfValidationForGuests' => true,
        'useQueueForNotifications' => true,
        'useQueueForIntegrations' => true,

        // Sent Notifications
        'maxSentNotificationsAge' => 30,

        // Spam
        'saveSpam' => true,
        'spamLimit' => 500,
        'spamEmailNotifications' => false,
        'spamBehaviour' => 'showSuccess',
        'spamKeywords' => '',
        'spamBehaviourMessage' => '',

        // Alerts
        'sendEmailAlerts' => false,
        'alertEmails' => [],
    ]
];

Configuration options #

• pluginName - Set a custom name for the plugin.
• defaultPage - Set the default sub-page navigated to when clicking "Formie" in the main menu.

Forms #

• defaultFormTemplate - The handle for the default form template used for new forms. Formie‘s defaults will be used if not specified.
• defaultEmailTemplate - The handle for the default email template used for new forms. Formie's defaults will be used if not specified.
• enableUnloadWarning - Whether front-end forms should trigger an "unload" warning when a form‘s content has changed and the user tries to navigate away without submitting.
• ajaxTimeout - Set the timeout in seconds for Ajax/XHR requests when using the front-end JS. Default to 10 seconds.

General Fields #

• defaultLabelPosition - The default label position for new forms and fields.
• defaultInstructionsPosition - The default instruction position for new forms and fields.

Fields #

• defaultFileUploadVolume - The asset volume to be used as the default for all new file upload fields. Must be in the format folder:uid.
• defaultDateDisplayType - The display type to be used as the default for all new date fields. Can be calendar, dropdowns, inputs.
• defaultDateValueOption - The default value option to be used as the default for all new date fields. Can be today, date.
• defaultDateTime - When defaultDateValueOption is set to date, this date will be used as the default value. Must be a valid datetime.

Submissions #

• maxIncompleteSubmissionAge - The maximum age of an incomplete submission in days before it is deleted in garbage collection. Set to 0 to disable automatic deletion.
• enableCsrfValidationForGuests - Whether to enable Craft‘s CSRF validation checks for anonymous form submissions.
• useQueueForNotifications - Whether to use Craft‘s queue system to trigger emails. This is highly, highly recommended to prevent slow submissions for your users. This may be useful to disable for local development.
• useQueueForIntegrations - Whether to use Craft‘s queue system to trigger integrations. This is highly, highly recommended to prevent slow submissions for your users. This may be useful to disable for local development.

Sent Notifications #

• maxSentNotificationsAge - The number of days to keep sent notifications before they are deleted permanently. Set to 0 to disable automatic deletion.

Spam #

• saveSpam - Whether to save spam submissions to the database.
• spamLimit - If saving spam, set a suitable limit for how many to keep. Spam submissions past this limit will be deleted.
• spamEmailNotifications - Whether submissions marked as spam should still trigger email notifications.
• spamBehaviour - Set to either showSuccess or showMessage to set the submission behaviour when a spam submission is detected.
• spamKeywords - Set keywords that if matched in the submission, will be marked as spam.
• spamBehaviourMessage - This text will be shown as an error after submission. HTML and Markdown is supported.

Alerts #

• sendEmailAlerts - Whether an email alert should be sent to a nominated email when an email notification fails to send.
• alertEmails - A collection of emails that alerts should be sent to. See below for an example.

Control Panel #

You can also manage configuration settings through the Control Panel by visiting Settings → Formie.

Alerts Configuration #

Supply a nested array for the name and email of each contact to receive alert notifications. The first index should contain the name, with the second index the email address.

'alertEmails' => [
    ['Primary Name', 'admin@site.com'],
    ['Secondary Admin Name', 'admin-alt@site.com'],
],

Rich Text Configuration #

Formie uses a Rich Text field for numerous settings for forms, notifications and more. This field is powered by TipTap. You have control over the configuration of these Rich Text fields, by providing a .json file with its configurations, very similar to how the Redactor plugin works.

For example, create a formie folder in your /config directory, and inside that, create a rich-text.json file. Place the following content into that file:

{
    "forms": {
        "errorMessage": {
            "buttons": ["bold"],
            "rows": 3
        }
    }
}

Here, we're setting the forms.errorMessage field config to provide a single button for Bold, and the number of rows the field should show. There are a number of available fields to configure, shown by the default config below:

{
    "forms": {
        "submitActionMessage": {
            "buttons": ["bold", "italic"],
            "rows": 3
        },
        "errorMessage": {
            "buttons": ["bold", "italic"],
            "rows": 3
        }
    },
    "notifications": {
        "content": {
            "buttons": ["bold", "italic", "variableTag"]
        }
    }
}

Available Buttons #

As shown above, your config can provide an array of button configs to include or exclude certain buttons from the Rich Text field interface. It's a good idea to only allow the types of formatting and functionality you want users to have access to.