Events

If you wish to extend the capabilities of Freeform, you can use any of the events 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 #
    • 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

Element Connections

\Solspace\Freeform\Services\ConnectionsService

  • ::EVENT_BEFORE_VALIDATE
    • Called before a connection gets validated, letting you do your own checks and/or changes.
    • \Solspace\Freeform\Events\Connections\ValidateEvent contains these methods
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getConnection() - returns the Connection object which implements the \Solspace\Freeform\Library\Connections\ConnectionInterface
      • getElement() - returns the associated Element
      • getTransformers() - returns an array of value transformers which implement \Solspace\Freeform\Library\Connections\Transformers\TransformerInterface and manages the correct data transformations between freeform fields and craft elements.
      • addTransformer(TransformerInterface $transformer) - lets you add your own transformers. Check \Solspace\Freeform\Library\Connections\Transformers\AbstractFieldTransformer for reference.
      • setTransformers(array $transformers) - override all of the transformers in the event
  • ::EVENT_AFTER_VALIDATE
    • Called after a connection is validated.
    • \Solspace\Freeform\Events\Connections\ValidateEvent contains these methods
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getConnection() - returns the Connection object which implements the \Solspace\Freeform\Library\Connections\ConnectionInterface
      • getElement() - returns the associated Element
  • ::EVENT_BEFORE_CONNECT
    • Called before actually saving the connection Element.
    • \Solspace\Freeform\Events\Connections\ConnectEvent contains these methods
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getConnection() - returns the Connection object which implements the \Solspace\Freeform\Library\Connections\ConnectionInterface
      • getElement() - returns the associated Element
  • ::EVENT_AFTER_CONNECT
    • Called after successfully saving the connection Element.
    • \Solspace\Freeform\Events\Connections\ConnectEvent contains these methods
      • getForm() - returns \Solspace\Freeform\Library\Composer\Components\Form
      • getConnection() - returns the Connection object which implements the \Solspace\Freeform\Library\Connections\ConnectionInterface
      • getElement() - returns the associated Element

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
      • 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 #
    • 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 #
    • 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 #
    • 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
      }
    );

		// Element Connections
		Event::on(Entries::class, Entries::EVENT_AFTER_CONNECT, function (ConnectEvent $event) {
				$element = $event->getElement();
				$form = $event->getForm();

				/** @var Asset $asset */
				$asset = $element->fileUploader->one();
				if ($asset) {
						$asset->firstName = $form->get('firstName')->getValue();
						$asset->lastName = $form->get('lastName')->getValue();
						\Craft::$app->elements->saveElement($asset);
				}
		});

    // 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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
Last Updated: 6/11/2019, 9:05:28 AM