Freeform Documentation

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

Freeform 1.x Docs

Events & Hooks

If you wish to extend the capabilities of Freeform, you can use any of the events and hooks below:

Events for Freeform Forms #

\Solspace\Freeform\Services\FormsService

  • ::EVENT_BEFORE_SUBMIT #
    • Called when a form is submitted, but before a submission element is being made
    • \Solspace\Freeform\Events\Forms\BeforeSubmitEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
  • ::EVENT_AFTER_SUBMIT #
    • Called after processing form and saving the submission element
    • \Solspace\Freeform\Events\Forms\AfterSubmitEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission
  • ::EVENT_BEFORE_SAVE #
    • Called before saving a form
    • \Solspace\Freeform\Events\Forms\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FormModel
      • isNew() - bool
  • ::EVENT_AFTER_SAVE #
    • Called after saving a form
    • \Solspace\Freeform\Events\Forms\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FormModel
      • isNew() - bool
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting a form
    • \Solspace\Freeform\Events\Forms\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FormModel
  • ::EVENT_AFTER_DELETE #
    • Called after deleting a form
    • \Solspace\Freeform\Events\Forms\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FormModel
  • ::EVENT_RENDER_OPENING_TAG #
    • Called when rendering the opening tag of a form
    • \Solspace\Freeform\Events\Forms\FormRenderEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getCompiledOutput() - returns a string of the rendered form opening tag and inputs
      • appendToOutput(string $value) - append a chunk of your string to the output
      • appendJsToOutput(string $value) - append javascript to the form opening tag. Wraps it in <script></script> tags automatically
      • appendCssToOutput(string $value) - append css to the form opening tag. Wraps it in <style></style> tags automatically
  • ::EVENT_RENDER_CLOSING_TAG #
    • Called when rendering the closing tag of a form
    • \Solspace\Freeform\Events\Forms\FormRenderEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getCompiledOutput() - returns a string of the rendered form opening tag and inputs
      • appendToOutput(string $value) - append a chunk of your string to the output
      • appendJsToOutput(string $value) - append javascript to the form opening tag. Wraps it in <script></script> tags automatically
      • appendCssToOutput(string $value) - append css to the form opening tag. Wraps it in <style></style> tags automatically
  • ::EVENT_FORM_VALIDATE #
    • Called when validating the form
    • \Solspace\Freeform\Events\Forms\FormValidateEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • isFormValid() - bool
      • addErrorToForm(string $message) - allows you to add an error message to the form

Events for Freeform Submissions #

\Solspace\Freeform\Services\SubmissionsService

  • ::EVENT_BEFORE_SUBMIT #
    • Called before saving a submission
    • \Solspace\Freeform\Events\Submissions\SubmitEvent contains these methods:
      • getElement() - returns \Solspace\Freeform\Elements\Submission
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
  • ::EVENT_AFTER_SUBMIT #
    • Called after saving a submission
    • \Solspace\Freeform\Events\Submissions\SubmitEvent contains these methods:
      • getElement() - returns \Solspace\Freeform\Elements\Submission
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting a submission
    • \Solspace\Freeform\Events\Submissions\DeleteEvent contains these methods:
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission
  • ::EVENT_AFTER_DELETE #
    • Called after deleting a submission
    • \Solspace\Freeform\Events\Submissions\DeleteEvent contains these methods:
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission

Events for Freeform Fields #

\Solspace\Freeform\Services\FieldsService

  • ::EVENT_BEFORE_SAVE #
    • Called before saving a field
    • \Solspace\Freeform\Events\Fields\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FieldModel
      • isNew() - bool
  • ::EVENT_AFTER_SAVE #
    • Called after saving a field
    • \Solspace\Freeform\Events\Fields\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FieldModel
      • isNew() - bool
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting a field
    • \Solspace\Freeform\Events\Fields\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FieldModel
  • ::EVENT_AFTER_DELETE #
    • Called after deleting a field
    • \Solspace\Freeform\Events\Fields\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\FieldModel
  • ::EVENT_BEFORE_VALIDATE #
    • Called before validating a field
    • \Solspace\Freeform\Events\Fields\ValidateEvent contains these methods:
      • getField() - returns \Solspace\Freeform\Library\Composer\Components\AbstractField
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
  • ::EVENT_AFTER_VALIDATE #
    • Called after validating a field
    • \Solspace\Freeform\Events\Fields\ValidateEvent contains these methods:
      • getField() - returns \Solspace\Freeform\Library\Composer\Components\AbstractField
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form

Events for Freeform Notifications #

\Solspace\Freeform\Services\NotificationsService

  • ::EVENT_BEFORE_SAVE #
    • Called before saving a notification
    • \Solspace\Freeform\Events\Notifications\SaveEvent contains these methods:
      • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord
      • isNew() - bool
  • ::EVENT_AFTER_SAVE #
    • Called after saving a notification
    • \Solspace\Freeform\Events\Notifications\SaveEvent contains these methods:
      • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord
      • isNew() - bool
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting a notification
    • \Solspace\Freeform\Events\Notifications\DeleteEvent contains these methods:
      • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord
  • ::EVENT_AFTER_DELETE #
    • Called after deleting a notification
    • \Solspace\Freeform\Events\Notifications\DeleteEvent contains these methods:
      • getRecord() - returns \Solspace\Freeform\Records\NotificationRecord

Events for Freeform Statuses #

\Solspace\Freeform\Services\StatusesService

  • ::EVENT_BEFORE_SAVE #
    • Called before saving a status
    • \Solspace\Freeform\Events\Statuses\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\StatusModel
      • isNew() - bool
  • ::EVENT_AFTER_SAVE #
    • Called after saving a status
    • \Solspace\Freeform\Events\Statuses\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\StatusModel
      • isNew() - bool
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting a status
    • \Solspace\Freeform\Events\Statuses\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\StatusModel
  • ::EVENT_AFTER_DELETE #
    • Called after deleting a status
    • \Solspace\Freeform\Events\Statuses\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\StatusModel

Events for Freeform File Uploads #

\Solspace\Freeform\Services\FilesService

  • ::EVENT_BEFORE_UPLOAD #
    • Called before uploading a file
    • \Solspace\Freeform\Events\Files\UploadEvent contains these methods:
      • getField() - returns \Solspace\Freeform\Library\Composer\Components\Fields\FileUploadField
  • ::EVENT_AFTER_UPLOAD #
    • Called after uploading a file
    • \Solspace\Freeform\Events\Files\UploadEvent contains these methods:
      • getField() - returns \Solspace\Freeform\Library\Composer\Components\Fields\FileUploadField

Events for Freeform Mailing #

\Solspace\Freeform\Services\MailerService

  • ::EVENT_BEFORE_SEND #
    • Called before sending an email
    • \Solspace\Freeform\Events\Mailer\SendEmailEvent contains these methods:
      • getMessage() - returns \craft\mail\Message
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getNotification() - returns \Solspace\Freeform\Library\Mailing\NotificationInterface
      • getFieldValues() - array of key-value pairs of fields and their values
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission if the form is set to store data
  • ::EVENT_AFTER_SEND #
    • Called after sending an email
    • \Solspace\Freeform\Events\Mailer\SendEmailEvent contains these methods:
      • getMessage() - returns \craft\mail\Message
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getNotification() - returns \Solspace\Freeform\Library\Mailing\NotificationInterface
      • getFieldValues() - array of key-value pairs of fields and their values
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission if the form is set to store data
  • ::EVENT_BEFORE_RENDER #
    • Called before rendering the email message body and subject, etc
    • \Solspace\Freeform\Events\Mailer\RenderEmailEvent::__construct contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getNotification() - returns \Solspace\Freeform\Library\Mailing\NotificationInterface
      • getFieldValues() - array of key-value pairs of fields and their values
      • setFieldValues(array $fieldValues) - allows you to update the field values that are passed to the email body and subject twig templates
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission if the form is set to store data

Events for Freeform CRM Integrations #

\Solspace\Freeform\Services\CrmService

  • ::EVENT_BEFORE_SAVE #
    • Called before saving an integration
    • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
      • isNew - bool
  • ::EVENT_AFTER_SAVE #
    • Called after saving an integration
    • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
      • isNew - bool
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting an integration
    • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
  • ::EVENT_AFTER_DELETE #
    • Called after deleting an integration
    • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
  • ::EVENT_BEFORE_PUSH #
    • Called before pushing data to an integration
    • \Solspace\Freeform\Events\Integrations\PushEvent contains these methods:
      • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration
      • getValues() - a key-value array of all values to be pushed to the integration
  • ::EVENT_AFTER_PUSH #
    • Called after pushing data to an integration
    • \Solspace\Freeform\Events\Integrations\PushEvent contains these methods:
      • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration
      • getValues() - a key-value array of all values to be pushed to the integration

Events for Freeform Mailing List Integrations #

\Solspace\Freeform\Services\MailingListsService

  • ::EVENT_BEFORE_SAVE #
    • Called before saving an integration
    • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
      • isNew - bool
  • ::EVENT_AFTER_SAVE #
    • Called after saving an integration
    • \Solspace\Freeform\Events\Integrations\SaveEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
      • isNew - bool
  • ::EVENT_BEFORE_DELETE #
    • Called before deleting an integration
    • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel
  • ::EVENT_AFTER_DELETE #
    • Called after deleting an integration
    • \Solspace\Freeform\Events\Integrations\DeleteEvent contains these methods:
      • getModel() - returns \Solspace\Freeform\Models\IntegrationModel

Usage Examples #

In your plugin's ::init() method, subscribe to any of these events by using the Event::on() static method:

<?php

namespace Craft;

class YourPlugin extends BasePlugin
{
    public function init()
    {
        parent::init();

        // Forms
        Event::on(
            FormsService::class,
            FormsService::EVENT_BEFORE_SAVE,
            function (SaveEvent $event) {
                $form  = $event->getModel();
                $isNew = $event->isNew();
                // Do something with this data
            }
        );

        // Submissions
        Event::on(
            SubmissionsService::class,
            SubmissionsService::EVENT_AFTER_SUBMIT,
            function (SubmitEvent $event) {
                $submission = $event->getElement();
                $form       = $event->getForm();
                // Do something with this data
            }
        );

        // Fields
        Event::on(
            FieldsService::class,
            FieldsService::EVENT_BEFORE_DELETE,
            function (DeleteEvent $event) {
                $fieldModel = $event->getModel();
                // Do something with this data
            }
        );

        // Notifications
        Event::on(
            NotificationsService::class,
            NotificationsService::EVENT_AFTER_DELETE,
            function (DeleteEvent $event) {
                $notificationRecord = $event->getRecord();
                // Do something with this data
            }
        );

        // Statuses
        Event::on(
            StatusesService::class,
            StatusesService::EVENT_BEFORE_SAVE,
            function (SaveEvent $event) {
                $statusModel = $event->getModel();
                $isNew       = $event->isNew();
                // Do something with this data
            }
        );

        // File Uploads
        Event::on(
            FilesService::class,
            FilesService::EVENT_AFTER_UPLOAD,
            function (UploadEvent $event) {
                $fileUploadField = $event->getField();
                // Do something with this data
            }
        );

        // Mailing
        Event::on(
            MailerService::class,
            MailerService::EVENT_AFTER_SEND,
            function (SendEmailEvent $event) {
                $message = $event->getMessage();
                $form    = $event->getForm();
                $notification = $event->getNotification();
                $fieldValues  = $event->getFieldValues();
                $submission   = $event->getSubmission();
                // Do something with this data
            }
        );

        // CRM Integrations
        Event::on(
            CrmService::class,
            CrmService::EVENT_BEFORE_SAVE,
            function (SaveEvent $event) {
                $integrationModel = $event->getModel();
                // Do something with this data
            }
        );

        // Mailing List Integrations
        Event::on(
            MailingListsService::class,
            MailingListsService::EVENT_BEFORE_SAVE,
            function (SaveEvent $event) {
                $integrationModel = $event->getModel();
                // Do something with this data
            }
        );
    }
}