This document is for an older version of

Freeform

.

View latest version →

Events & Hooks

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

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_ATTACH_FORM_ATTRIBUTES #
    • Called when attaching attributes to a form
    • \Solspace\Freeform\Events\Forms\FormRenderEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getAttributes() - returns an array of existing attributes specified for the form
      • attachAttribute(string $name, mixed $value) - attach an attribute to the form
      • removeAttribute(string $name) - removes an attribute from the attribute stack
  • ::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
  • ::EVENT_AFTER_GENERATE_RETURN_URL #
    • Called after generating a return URL, allowing you to modify the return URL of a form.
    • \Solspace\Freeform\Events\Forms\ReturnUrlEvent contains these methods:
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getSubmission() - returns \Solspace\Freeform\Elements\Submission
      • getReturnUrl() - allows you to get the currently set Return URL
      • setReturnUrl(string $returnUrl) - allows you to set a custom Return URL

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

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

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

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

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

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 2.0.4+ #
    • 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

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 2.0.1+ #
    • 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
      • setValues(array $values) - override all of the values with a new key-value array
      • addValue(string $key, mixed $value) - add or override any key/value in the set
  • ::EVENT_AFTER_PUSH 2.0.1+ #
    • 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
  • ::EVENT_AFTER_RESPONSE 2.5.6+ #
    • Called after a response is received from pushing to the integration
    • \Solspace\Freeform\Events\Integrations\IntegrationResponseEvent contains these methods:
      • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration instance
      • getResponse() - returns \Psr\Http\Message\ResponseInterface
      • getResponseBodyAsString() - returns the ResponseInterface object's body as string, which will usually contain the JSON response as string

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
  • ::EVENT_AFTER_RESPONSE 2.5.6+ #
    • Called after a response is received from pushing to the integration
    • \Solspace\Freeform\Events\Integrations\IntegrationResponseEvent contains these methods:
      • getIntegration() - returns \Solspace\Freeform\Library\Integrations\AbstractIntegration instance
      • getResponse() - returns \Psr\Http\Message\ResponseInterface
      • getResponseBodyAsString() - returns the ResponseInterface object's body as string, which will usually contain the JSON response as string

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();

        // Get a specific field value
        $value = $form->get('firstName')->getValue();

        // Iterate over all posted fields and get their values
        foreach ($form->getLayout()->getFields() as $field) {

            // Bypass fields such as HTML or Submit, etc.
            if ($field instanceof NoStorageInterface) {
                continue;
            }

            $field->getValue();
        }

        // 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
      }
    );

    Event::on(
      CrmService::class,
      CrmService::EVENT_AFTER_RESPONSE,
      function (IntegrationResponseEvent $event) {
        $integration = $event->getIntegration();
        $response  = $event->getResponse();
        $jsonString  = $event->getResponseBodyAsString();

        $object = json_decode($jsonString);

        // Do something with the response object
      }
    );

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

    Event::on(
      MailingListsService::class,
      MailingListsService::EVENT_AFTER_RESPONSE,
      function (IntegrationResponseEvent $event) {
        $integration = $event->getIntegration();
        $response  = $event->getResponse();
        $jsonString  = $event->getResponseBodyAsString();

        $object = json_decode($jsonString);

        // Do something with the response object
      }
    );
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151