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:

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');
    }
);

1
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()]
                )
            );
    }
);

1
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);
        }
    }
);

1
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.
    }
);

1
2
3
4
5
6
7
8
9
10

# Settings Events

# Rendering Sidebar Navigation

# Rendering the Settings page

# Before Saving Settings

# After Saving Settings

Need Extra Help?

Settings Events

Rendering Sidebar Navigation

Rendering the Settings page

Before Saving Settings

After Saving Settings