WARNING
The Express Forms plugin has been discontinued. Please see the Freeform migration guide for more information.
Settings Events
If you wish to extend the capabilities of Settings CP pages in Express Forms, feel free to use any of the events listed below:
Rendering Sidebar Navigation
The EVENT_REGISTER_SETTING_SIDEBAR_ITEMS event is called when the settings sidebar is being rendered. Use this event to register new sidebar items.
TIP
Express Forms uses this event to register all of the Settings' sidebar items.
use Solspace\ExpressForms\services\Settings;
use Solspace\ExpressForms\events\settings\RegisterSettingSidebarItemsEvent;
Event::on(
Settings::class,
Settings::EVENT_REGISTER_SETTING_SIDEBAR_ITEMS,
function (RegisterSettingSidebarItemsEvent $event) {
// You can even specify the URL handle and the specific order number
// Otherwise the URL handle will be generated from the name
// And it will be attached to the end of the list
$event->addItem('General');
}
);
2
3
4
5
6
7
8
9
10
11
12
13
Rendering the Settings page
The EVENT_RENDER_SETTINGS event is called when a settings page should be rendered. You can attach content to the page based on the currently selected setting navigation item, as well as modify the page title and change the action buttons.
TIP
Express Forms uses this event to render all settings pages. Here's an example of how the Spam Settings page is being rendered.
use Solspace\ExpressForms\services\Settings;
use Solspace\ExpressForms\events\settings\RenderSettingsEvent;
Event::on(
Settings::class,
Settings::EVENT_RENDER_SETTINGS,
function (RenderSettingsEvent $event) {
// Check if the currently selected page should have the specific content added or not
if ($event->getSelectedItem() !== 'spam') {
return;
}
// Change the title of the page and add some content
$event
->setTitle('Spam')
->addContent(
// Render a template with input fields that get their values from the Settings model
Craft::$app->getView()->renderTemplate(
'express-forms/settings/_components/spam/honeypot',
['settings' => $event->getSettings()]
)
);
}
);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
Before Saving Settings
The EVENT_BEFORE_SAVE_SETTINGS event is called before the settings are being saved. Use this event to check the $_POST data for your items (we recommend prefixing the input names for convenience), then do with the data what you want. If you want to add data directly to the Settings model, you can use the convenience method on the event $event->addData(string $name, $value).
TIP
Express Forms uses this event to store all of the posted settings. Below is an example of how the Honeypot settings are saved.
use Solspace\ExpressForms\services\Settings;
use Solspace\ExpressForms\services\Honeypot;
use Solspace\ExpressForms\events\settings\SaveSettingsEvent;
use craft\helpers\StringHelper;
Event::on(
Settings::class,
Settings::EVENT_BEFORE_SAVE_SETTINGS,
function (SaveSettingsEvent $event) {
// Try to fetch the prefixed POST data
$post = Craft::$app->getRequest()->post('honeypot');
// Do the saving only the data was posted at all
if (!empty($post) && is_array($post)) {
$name = $post['name'] ?? Honeypot::DEFAULT_NAME;
$name = StringHelper::toKebabCase($name, '_');
$name = StringHelper::toAscii($name);
$event->addData('honeypotEnabled', $post['enabled'] ?? false);
$event->addData('honeypotBehaviour', $post['behaviour'] ?? Honeypot::BEHAVIOUR_SIMULATE_SUCCESS);
$event->addData('honeypotInputName', $name);
}
}
);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
After Saving Settings
The EVENT_AFTER_SAVE_SETTINGS event is called right after saving the Settings model data. You might use it to flush some of your own plugin caches, etc.
use Solspace\ExpressForms\services\Settings;
use yii\base\Event;
Event::on(
Settings::class,
Settings::EVENT_AFTER_SAVE_SETTINGS,
function (Event $event) {
// Do something here.
}
);
2
3
4
5
6
7
8
9
10