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 inputsappendToOutput(string $value)
- append a chunk of your string to the outputappendJsToOutput(string $value)
- append javascript to the form opening tag. Wraps it in<script></script>
tags automaticallyappendCssToOutput(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 inputsappendToOutput(string $value)
- append a chunk of your string to the outputappendJsToOutput(string $value)
- append javascript to the form opening tag. Wraps it in<script></script>
tags automaticallyappendCssToOutput(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 formattachAttribute(string $name, mixed $value)
- attach an attribute to the formremoveAttribute(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()
- booladdErrorToForm(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 setReturn URL
setReturnUrl(string $returnUrl)
- allows you to set a customReturn 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 valuesgetSubmission()
- 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 valuesgetSubmission()
- 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 valuessetFieldValues(array $fieldValues)
- allows you to update the field values that are passed to the email body and subject twig templatesgetSubmission()
- 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 integrationsetValues(array $values)
- override all of the values with a new key-value arrayaddValue(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
instancegetResponse()
- returns\Psr\Http\Message\ResponseInterface
getResponseBodyAsString()
- returns theResponseInterface
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
instancegetResponse()
- returns\Psr\Http\Message\ResponseInterface
getResponseBodyAsString()
- returns theResponseInterface
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
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