Utility Events
TipTap Events
The registerExtensions Event
The event that registers matching TipTap nodes, marks, extensions, and safe TextStyle definitions before Formie's rich-text editors are created.
use verbb\formie\events\RegisterTiptapExtensionsEvent;
use verbb\formie\services\TiptapExtensions;
use yii\base\Event;
Event::on(TiptapExtensions::class, TiptapExtensions::EVENT_REGISTER_EXTENSIONS, function(RegisterTiptapExtensionsEvent $event) {
$event->registerExtension('acme/abbreviation', new AbbreviationMark());
});Persisted extensions also require a matching browser registration. See TipTap extensions for the complete PHP, JavaScript, toolbar, TextStyle, and asset-loading contract.
Stencil Events
The beforeSaveStencil Event
The event that is triggered before a stencil is saved.
use verbb\formie\events\StencilEvent;
use verbb\formie\services\Stencils;
use yii\base\Event;
Event::on(Stencils::class, Stencils::EVENT_BEFORE_SAVE_STENCIL, function(StencilEvent $event) {
$stencil = $event->stencil;
$isNew = $event->isNew;
// ...
});The afterSaveStencil Event
The event that is triggered after a stencil is saved.
use verbb\formie\events\StencilEvent;
use verbb\formie\services\Stencils;
use yii\base\Event;
Event::on(Stencils::class, Stencils::EVENT_AFTER_SAVE_STENCIL, function(StencilEvent $event) {
$stencil = $event->stencil;
$isNew = $event->isNew;
// ...
});The beforeDeleteStencil Event
The event that is triggered before a stencil is deleted.
use verbb\formie\events\StencilEvent;
use verbb\formie\services\Stencils;
use yii\base\Event;
Event::on(Stencils::class, Stencils::EVENT_BEFORE_DELETE_STENCIL, function(StencilEvent $event) {
$stencil = $event->stencil;
// ...
});The beforeApplyStencilDelete Event
The event that is triggered before a stencil is deleted.
use verbb\formie\events\StencilEvent;
use verbb\formie\services\Stencils;
use yii\base\Event;
Event::on(Stencils::class, Stencils::EVENT_BEFORE_APPLY_STENCIL_DELETE, function(StencilEvent $event) {
$stencil = $event->stencil;
// ...
});The afterDeleteStencil Event
The event that is triggered after a stencil is deleted.
use verbb\formie\events\StencilEvent;
use verbb\formie\services\Stencils;
use yii\base\Event;
Event::on(Stencils::class, Stencils::EVENT_AFTER_DELETE_STENCIL, function(StencilEvent $event) {
$stencil = $event->stencil;
// ...
});Migration Events
The modifyField Event
The event that is triggered during a migration (from Sprout Forms or Freeform), trying to map the respective third-party field to a Formie field. The field variable represents the Sprout Forms or Freeform field, and newField represents the Formie equivalent field.
You can use this event to map a custom Sprout Forms or Freeform field to a field Formie can understand.
use verbb\formie\events\ModifyMigrationFieldEvent;
use verbb\formie\migrations\plugins\MigrateFreeform4;
use yii\base\Event;
Event::on(MigrateFreeform4::class, MigrateFreeform4::EVENT_MODIFY_FIELD, function(ModifyMigrationFieldEvent $event) {
$field = $event->field;
$newField = $event->newField;
// ...
});
use verbb\formie\events\ModifyMigrationFieldEvent;
use verbb\formie\migrations\plugins\MigrateSproutForms;
use yii\base\Event;
Event::on(MigrateSproutForms::class, MigrateSproutForms::EVENT_MODIFY_FIELD, function(ModifyMigrationFieldEvent $event) {
$field = $event->field;
$newField = $event->newField;
// ...
});The modifyForm Event
The event that is triggered during a migration when a third-party form is mapped to a Formie form.
use verbb\formie\events\ModifyMigrationFormEvent;
use verbb\formie\migrations\plugins\MigrateFreeform5;
use yii\base\Event;
Event::on(MigrateFreeform5::class, MigrateFreeform5::EVENT_MODIFY_FORM, function(ModifyMigrationFormEvent $event) {
$form = $event->form;
$newForm = $event->newForm;
// ...
});The modifyNotification Event
The event that is triggered during a migration when a third-party notification is mapped to a Formie notification.
use verbb\formie\events\ModifyMigrationNotificationEvent;
use verbb\formie\migrations\plugins\MigrateFreeform5;
use yii\base\Event;
Event::on(MigrateFreeform5::class, MigrateFreeform5::EVENT_MODIFY_NOTIFICATION, function(ModifyMigrationNotificationEvent $event) {
$form = $event->form;
$notification = $event->notification;
$newNotification = $event->newNotification;
// ...
});The modifySubmission Event
The event that is triggered during a migration when a third-party submission is mapped to a Formie submission.
use verbb\formie\events\ModifyMigrationSubmissionEvent;
use verbb\formie\migrations\plugins\MigrateFreeform5;
use yii\base\Event;
Event::on(MigrateFreeform5::class, MigrateFreeform5::EVENT_MODIFY_SUBMISSION, function(ModifyMigrationSubmissionEvent $event) {
$form = $event->form;
$submission = $event->submission;
// ...
});Variable Events
The registerReferences Event
The event that is triggered when Formie builds its reference catalogue. Add typed, namespaced source and transform definitions to the event. Metadata construction never evaluates source values.
use verbb\formie\events\RegisterReferencesEvent;
use verbb\formie\fields\definitions\FieldValueType;
use verbb\formie\references\ReferenceCatalogue;
use verbb\formie\references\ReferenceDefinition;
use verbb\formie\references\ReferenceSource;
use verbb\formie\references\ReferenceType;
use yii\base\Event;
Event::on(ReferenceCatalogue::class, ReferenceCatalogue::EVENT_REGISTER, function(RegisterReferencesEvent $event) {
$event->sources[] = new ReferenceSource(
new ReferenceDefinition(
id: 'acme/campaign',
label: 'Campaign Code',
category: 'custom',
valueType: FieldValueType::string(),
types: [ReferenceType::Text],
),
static fn() => 'spring-sale',
);
});See Custom Variable Sources for context, availability and transform registration.
The registerClientEventTemplates Event
The event that is triggered to register client event templates for the form builder Tracking tab.
use Craft;
use verbb\formie\events\RegisterClientEventTemplatesEvent;
use verbb\formie\services\ClientEventTemplates;
use yii\base\Event;
Event::on(ClientEventTemplates::class, ClientEventTemplates::EVENT_REGISTER_CLIENT_EVENT_TEMPLATES, function(RegisterClientEventTemplatesEvent $event) {
$event->templates[] = [
'handle' => 'acme_demo_request',
'label' => Craft::t('site', 'Acme — Demo request'),
'description' => Craft::t('site', 'Push a demo-request event after the final page submits.'),
'category' => 'acme',
'categoryLabel' => Craft::t('site', 'Acme Analytics'),
'event' => 'demo_request',
'pageContexts' => ['last-page', 'single-page'],
'payload' => [
['key' => 'form_id', 'value' => '{form:handle}', 'kind' => 'static'],
],
];
});See Custom client event templates for template properties, payload rows, page contexts, and troubleshooting.
Email Domain Events
The modifyFreeEmailDomains Event
The event that is triggered when Formie prepares the list of free email domains.
use verbb\formie\events\ModifyEmailDomainsEvent;
use verbb\formie\services\EmailDomains;
use yii\base\Event;
Event::on(EmailDomains::class, EmailDomains::EVENT_MODIFY_FREE_EMAIL_DOMAINS, function(ModifyEmailDomainsEvent $event) {
$event->domains[] = 'example.com';
});The modifyTwigEnvironment Event
The event that is triggered to modify the allowed items in the Twig Sandbox used to parse some content like Email Notifications.
Formie uses a Twig Sandbox with a limited set of allowed Tags, Filter and Functions. This also extends to the allowed Methods and Properties. This is a security measure to prevent Twig injections into the fields that support Twig.
use verbb\formie\Formie;
use verbb\formie\events\ModifyTwigEnvironmentEvent;
use yii\base\Event;
Event::on(Formie::class, Formie::EVENT_MODIFY_TWIG_ENVIRONMENT, function(ModifyTwigEnvironmentEvent $event) {
// Add allowed Twig Tags
$event->allowedTags[] = [
'tag',
];
// Add allowed Twig Filters
$event->allowedFilters[] = [
'format',
'format_number',
];
// Add allowed Twig Functions
$event->allowedFunctions[] = [
'alias',
];
// Add allowed methods
// i.e. to allow `craft.entries.one()`
$event->allowedMethods[\craft\web\twig\variables\CraftVariable::class] = 'entries';
$event->allowedMethods[\craft\elements\db\ElementQuery::class] = 'one';
// Add allowed properties
$event->allowedProperties[\craft\base\Element::class] = 'title';
});The defineHiddenDefaultTemplateContext Event
Triggered when resolving a Hidden field Template default value. Use this to inject project-specific variables (for example an event entry) without opening arbitrary craft.entries() access in CP-authored templates.
use craft\elements\Entry;
use verbb\formie\events\DefineHiddenDefaultTemplateContextEvent;
use verbb\formie\helpers\HiddenDefaultTemplateResolver;
use yii\base\Event;
Event::on(HiddenDefaultTemplateResolver::class, HiddenDefaultTemplateResolver::EVENT_DEFINE_CONTEXT, function(DefineHiddenDefaultTemplateContextEvent $event) {
$slug = Craft::$app->getRequest()->getParam('event');
if (!$slug) {
return;
}
$event->variables['event'] = Entry::find()
->slug($slug)
->one();
});Template defaults are resolved server-side only. Posted hidden values are ignored when Default Value is set to Template.