From 8ca6cc32b2c789a3149861159ad258f2cb9491e3 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 14:39:39 +0200 Subject: Adding upstream version 2.11.4. Signed-off-by: Daniel Baumann --- doc/60-Hooks.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 doc/60-Hooks.md (limited to 'doc/60-Hooks.md') diff --git a/doc/60-Hooks.md b/doc/60-Hooks.md new file mode 100644 index 0000000..2dc645d --- /dev/null +++ b/doc/60-Hooks.md @@ -0,0 +1,49 @@ +# Hooks + +## ConfigFormEventsHook + +The `ConfigFormEventsHook` allows developers to hook into the handling of configuration forms. It provides three methods: + +* `appliesTo()` +* `isValid()` +* `onSuccess()` + +`appliesTo()` determines whether the hook should run for a given configuration form. +Developers should use `instanceof` checks in order to decide whether the hook should run or not. +If `appliesTo()` returns `false`, `isValid()` and `onSuccess()` won't get called for this hook. + +`isValid()` is called after the configuration form has been validated successfully. +An exception thrown here indicates form errors and prevents the config from being stored. +The exception's error message is shown in the frontend automatically. +If there are multiple hooks indicating errors, every error will be displayed. + +`onSuccess()` is called after the configuration has been stored successfully. +Form handling can't be interrupted here. Any exception will be caught, logged and notified. + +Hook example: + +```php +namespace Icinga\Module\Acme\ProvidedHook; + +use Icinga\Application\Hook\ConfigFormEventsHook; +use Icinga\Forms\ConfigForm; +use Icinga\Forms\Security\RoleForm; + +class ConfigFormEvents extends ConfigFormEventsHook +{ + public function appliesTo(ConfigForm $form) + { + return $form instanceof RoleForm; + } + + public function onSuccess(ConfigForm $form) + { + $this->updateMyModuleConfig(); + } + + protected function updateMyModuleConfig() + { + // ... + } +} +``` -- cgit v1.2.3