A newer version of

Freeform

is available.

Try Freeform 5 now →

Developer Events

Form Events

If you wish to extend the capabilities of Forms in Freeform, feel free to use any of the events listed below:

Before Submitting

This event is triggered once a form has completed all steps and a submission is being stored.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\SubmitEvent;

Event::on(
  Form::class,
  Form::EVENT_SUBMIT,
  function (SubmitEvent $event) {
    $form = $event->getForm();
    $submission = $event->getSubmission();

    // Perform some action here
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13

After Submitting

This event is triggered once a form has completed all steps and a submission has been stored and integrations have completed.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\SubmitEvent;

Event::on(
  Form::class,
  Form::EVENT_AFTER_SUBMIT,
  function (SubmitEvent $event) {
    $form = $event->getForm();
    $submission = $event->getSubmission();

    // Perform some action here
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13

On Validating the Form

This event is called whenever a form is being validated. Use this event to attach your own validation logic to any form.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\ValidationEvent;

Event::on(
  Form::class,
  Form::EVENT_BEFORE_VALIDATE,
  function (ValidationEvent $event) {
    $form = $event->getForm();

    // Only perform our custom validation if the form is already valid so far
    if ($form->isValid()) {
      // Poor little "specificFormHandle" form, will never see the light of day
      if ($form->getHandle() === 'specificFormHandle') {
        $form->addError('Sorry, but this form is always invalid');
      }
    }

    // you can also cancel the event
    $event->isValid = false;
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

After Validating the Form

This event is called after a form has been validated. Use this event to perform some actions after form validation.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\ValidationEvent;

Event::on(
  Form::class,
  Form::EVENT_AFTER_FORM_VALIDATE,
  function (ValidationEvent $event) {
    $form = $event->getForm();

    // do something here...
  }
)
1
2
3
4
5
6
7
8
9
10
11
12

Rendering the Opening HTML tag

Use this event to attach your own HTML, CSS or JS to the output of the opening form tag. Most commonly used to attach some sort of additional hidden values or scripts.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\RenderTagEvent;

// Add output before the <form> opening tag is rendered
Event::on(
  Form::class,
  Form::EVENT_RENDER_BEFORE_OPEN_TAG,
  function (RenderTagEvent $event) {
    $form = $event->getForm();

    // Add any chunks to the output
    $event->addChunk('<h1>'.$form->getName().'</h1>');
    $event->addChunk('<input type="hidden" name="some_input_name" value="123" />');

    // Add a chunk at the beginning of the output
    $event->addChunk('<script>alert("test");</script>', RenderTagEvent::POSITION_BEGINNING);

    // Add a chunk in a specific position in the chunk list
    $event->addChunk('<style>body { backround: red; }</style>', 2);
  }
)

// Add output after the <form> opening tag is rendered
Event::on(
  Form::class,
  Form::EVENT_RENDER_AFTER_OPEN_TAG,
  function (RenderTagEvent $event) {
    $form = $event->getForm();

    // Add some hidden inputs or whatever else you like
    $event->addChunk('<input type="hidden" name="some_input_name" value="123" />');
  }
)
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

Rendering the Closing HTML tag

Use this event to attach your own HTML, CSS or JS to the output of the closing form tag. Most commonly used to attach some sort of additional hidden values or scripts.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\RenderTagEvent;

Event::on(
  Form::class,
  Form::EVENT_RENDER_BEFORE_CLOSING_TAG,
  function (RenderTagEvent $event) {
    $form = $event->getForm();

    $event->addChunk('<input type="hidden" name="some_input_name" value="123" />');
  }
)

Event::on(
  Form::class,
  Form::EVENT_RENDER_AFTER_CLOSING_TAG,
  function (RenderTagEvent $event) {
    $form = $event->getForm();

    $event->addChunk('<script>alert("form rendered");</script>');
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Attaching Attributes to Forms

This event lets you attach custom attributes to all or specific forms.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\AttachFormAttributesEvent;

Event::on(
  Form::class,
  Form::EVENT_ATTACH_TAG_ATTRIBUTES,
  function (AttachFormAttributesEvent $event) {
    $form = $event->getForm();

    // Get all existing attributes for this form
    $attributes = $event->getAttributes();

    // Only deal with our "specificFormHandle" form
    if ($form->getHandle() === 'specificFormHandle') {
      // If "data-custom" attribute is present - we remove it
      if (array_key_exists('data-custom', $attributes)) {
        $event->removeAttribute('data-custom');
      }

      // Attach a "data-other-attrib" attribute to the form
      $event->attachAttribute('data-other-attrib', true);
    }
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Attaching custom properties to Forms

This event lets you inject your own properties on forms, to expand their application.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\GetCustomPropertyEvent;

Event::on(
  Form::class,
  Form::EVENT_GET_CUSTOM_PROPERTY,
  function (GetCustomPropertyEvent $event) {
    $key = $event->getKey(); // Get the property name that was being tried to be accessed

    // Only set this return value when accessing $form->myCustomProperty
    if ($key === 'myCustomProperty') {
      $event->setValue('my custom return value');
    }
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

After Generating the Return URL

This event is called when the return URL has been generated and is ready to be used to redirect the page.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\ReturnUrlEvent;

Event::on(
  Form::class,
  Form::EVENT_GENERATE_RETURN_URL,
  function (ReturnUrlEvent $event) {
    $form = $event->getForm();
    $submission = $event->getSubmission();

    // Override all return URL's for our "specificFormHandle" forms
    if ($form->getHandle() === 'specificFormHandle') {
      $event->setReturnUrl('/some/url/' . $submission->id);
    }
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Generating JSON Output for AJAX Forms

You can attach your own info to the JSON payload that is returned when calling $form->json(). Most commonly used in twig to create an endpoint for fetching fresh form and csrf tokens when using caching in the frontend templates. (E.g. form.json|raw)

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\OutputAsJsonEvent;

Event::on(
  Form::class,
  Form::EVENT_OUTPUT_AS_JSON,
  function (OutputAsJsonEvent $event) {
    $form = $event->getForm();
    $event->add('myCustomProperty', ['anything' => 'here']);
  }
)
1
2
3
4
5
6
7
8
9
10
11
{# twig file for fetching fresh form data #}
{% set form = craft.freeform.form('myForm') %}
{% do form.registerContext %}
{{- form.json|raw -}}
1
2
3
4

Attaching extra output to AJAX response when submitting forms

You can attach extra data to the AJAX response when forms are submitted by using this event.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\PrepareAjaxResponsePayloadEvent;

Event::on(
  Form::class,
  Form::EVENT_PREPARE_AJAX_RESPONSE_PAYLOAD,
  function (PrepareAjaxResponsePayloadEvent $event) {
    $event->add('someExtraData', [
        'one' => 1,
        'two' => true,
    ]);
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13

Handling Form Submit Request

Use these events to perform actions when the submit request is being processed.

The before handle request event happens as soon as the processing starts, so you can update your form with your custom information that will be later necessary during validation, etc. Freeform uses this event to determine which session storage mechanism is used, adds additional validation based on it and populates the form values based on it.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\HandleRequestEvent;

Event::on(
  Form::class,
  Form::EVENT_BEFORE_HANDLE_REQUEST,
  function (HandleRequestEvent $event) {
    $form = $event->getForm();
    $request = $event->getRequest();

    $event->add('myCustomProperty', ['anything' => 'here']);
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13

The after handle request event happens after the form has been processed, validated and ready for generating a submission. Freeform uses this event to store the session context with the updated values from POST.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\HandleRequestEvent;

Event::on(
  Form::class,
  Form::EVENT_BEFORE_HANDLE_REQUEST,
  function (HandleRequestEvent $event) {
    $form = $event->getForm();
    $request = $event->getRequest();

    $event->add('myCustomProperty', ['anything' => 'here']);
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13

Resetting a Form Between Requests

This event is triggered once a form is submitted fully and it has to be reset and prepared for the next round. While this happens after every form finalization, this is useful only for AJAX forms, which never refresh the page. Freeform uses this to clear the stored values of previous requests for multi-page forms.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\ResetEvent;

Event::on(
  Form::class,
  Form::EVENT_BEFORE_RESET,
  function (ResetEvent $event) {
    $form = $event->getForm();
    
    // We might need to reset our custom property which might have been
    // set during the life-cycle of the form
    $form->getPropertyBag()->set('my-custom-property', '');
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14

This event is triggered after the form has been reset:

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\ResetEvent;

Event::on(
  Form::class,
  Form::EVENT_AFTER_RESET,
  function (ResetEvent $event) {
    $form = $event->getForm();
    
    // your logic here...
  }
)
1
2
3
4
5
6
7
8
9
10
11
12

Persisting Form State

This event is called after handling the request and after resetting the form. Freeform uses this event to store the session context in either the PHP's session or the database table, depending on the user settings.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\PersistStateEvent;

Event::on(
  Form::class,
  Form::EVENT_PERSIST_STATE,
  function (PersistStateEvent $event) {
    $form = $event->getForm();
    
    // your logic here...
  }
)
1
2
3
4
5
6
7
8
9
10
11
12

Hydrating the Form

This event is called when the form object is being built. It parses the form builder settings and attaches them to the form object. You can use this event to attach various default form properties in the property bag. Freeform uses this event to attach the Post Forwarding data to the property bag.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\SendNotificationsEvent;

Event::on(
  Form::class,
  Form::EVENT_HYDRATE_FORM,
  function (HydrateEvent $event) {
    $form = $event->getForm();

    // We attach a custom property which will be always present in every form
    // and be accessible via `{{ form.propertyBag.get('always-attached-to-form') }}
    $form->getPropertyBag()->set('always-attached-to-form', 'my value here');
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Sending Notifications

This event is called when the form should be sending email notifications. You can use this event to send your own emails.

use Solspace\Freeform\Library\Composer\Components\Form;
use Solspace\Freeform\Events\Forms\SendNotificationsEvent;

Event::on(
  Form::class,
  Form::EVENT_SEND_NOTIFICATIONS,
  function (SendNotificationsEvent $event) {
    $form = $event->getForm();
    $submission = $event->getSubmission();
    $fields = $event->getFields();
    $mailer = $event->getMailer();

    $mailer->sendEmail(
      $form,
      ['recipient@one.com', 'recipient@two.com'],
      'your-template-file.html',
      $fields,
      $submission
    );
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

CORS setup event

This event lets you modify the CORS headers that will be sent with the request.

use Solspace\Freeform\Events\Controllers\ConfigureCORSEvent;
use Solspace\Freeform\Controllers\SubmitController;

Event::on(
  SubmitController::class,
  SubmitController::EVENT_CONFIGURE_CORS,
  function (ConfigureCORSEvent $event) {
    // View existing headers
    $existingHeaders = $event->getHeaders();

    // Add headers via the ::add() function
    $event->add('Header-Name', 'Header Value');

    // ::remove(string $key) and ::setHeaders(array $headers) is also available
  }
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

© 2024 Solspace, Inc.

Icons created by Smashicons from Flaticon.

Solspace is not just a plugin company. We also build and maintain websites. In fact, we often help other developers with their website builds. Learn more about our second chair development services today.