Module Options
Static Options
Add configuration options to a module by inserting rows into module_options. A row is the option's
definition: default_value is the value until someone saves another one. Saved values live in
module_option_values, one row per scope (system, workspace or user); is_workspace and is_user
mark an option that a workspace or a user may override.
MySQL
SET @id_module_test = (SELECT `id` FROM `modules` WHERE `ident` = 'test_module');
INSERT INTO `module_options` (`id_module`, `caption`, `name`, `type`, `default_value`, `required`)
VALUES (@id_module_test, 'Test numbers', 'number', 'number', '3', 1);
Postgres
DO $$
DECLARE
id_module_test integer;
BEGIN
SELECT id INTO id_module_test FROM modules WHERE ident = 'test_module';
INSERT INTO module_options (id_module, caption, name, type, default_value, required)
VALUES (id_module_test, 'Test numbers', 'number', 'number', '3', true);
END;
$$;
Read options in your module via getOption():
use DisplayPlugin;
use plugin\Modules\IModule;
class TestModulePlugin extends DisplayPlugin implements IModule
{
public function getNumber(): int
{
return (int) $this->getOption('number');
}
}
Option Key Prefixing
ModulesManager stores workspace- and user-scope values with a scope prefix. Use the prefix when reading them back:
$apiKey = $module->getOption('workspace_api_key'); // workspace-scope
$theme = $module->getOption('user_theme'); // user-scope
$flag = $module->getOption('debug_mode'); // system/global — no prefix
Dynamic Field Options (IModuleOptionFieldPreparer)
When a static default is not enough — for example, populating a select field with live data — implement IModuleOptionFieldPreparer. ModuleOptionsStore checks each active module for this interface when preparing a field for display.
use core\store\field\IStoreField;
use plugin\Modules\domain\preparer\IModuleOptionFieldPreparer;
use plugin\Modules\domain\model\ModuleOptionValuesObject;
class SlackModulePlugin extends DisplayPlugin implements IModule, IModuleOptionFieldPreparer
{
public function prepareModuleOptionField(
ModuleOptionValuesObject $moduleOptionValuesObject,
IStoreField $storeField
): void
{
if ($moduleOptionValuesObject->getName() !== 'notification_channel') {
return;
}
$channels = $this->getFacade()->getAvailableChannels();
$storeField->set(IStoreField::OPTION_VALUES, $channels);
}
}
Workspace Records as Select Choices (IPrepareWorkSpaceModuleOptionListener)
A select option keeps its choices as static text in module_options.options (id:caption, one
per line). When the choices are records each workspace owns, leave options empty and implement
IPrepareWorkSpaceModuleOptionListener in the module's plugin. The workspace options form asks it
for the choices of each option; return null for an option it does not fill.
public function onPrepareWorkSpaceModuleOptionValuesHandler(string $optionName, IWorkSpace $workSpace): ?array
{
if ($optionName !== 'default_role') {
return null;
}
return $this->getRolesCaptionsByWorkSpaceID($workSpace->getID()); // [id => caption]
}
Confirm Before Save (BeforeSaveModuleOptionsEvent)
The system options form (/modules/manage/<id>/options/) dispatches BeforeSaveModuleOptionsEvent through the
core before it saves the values. Use it to warn the admin about a value that is valid but risky.
- Call
addConfirmation()to ask the admin to confirm the save. Give plain text that is already translated. The store escapes it for HTML. - Tell only what is risky. Do not add a question: the dialog shows one question, "Save the options anyway?", after all confirmations.
- If there is a confirmation, the store saves nothing. The form shows a dialog with all confirmations.
- On "Yes", the form sends the values again with
module_options[confirm]=1. ThenisConfirmed()istrueand the store saves the values. - On "Cancel", the store saves nothing.
The workspace options form does not dispatch this event.
use plugin\Modules\domain\event\BeforeSaveModuleOptionsEvent;
$listener = [
$plugin,
'onBeforeSaveModuleOptionsHandler',
];
$core->addEventListener(BeforeSaveModuleOptionsEvent::EVENT_TYPE, $listener);
public function onBeforeSaveModuleOptionsHandler(BeforeSaveModuleOptionsEvent &$event): void
{
if ($event->getModule()->getIdent() !== 'payments' || $event->isConfirmed()) {
return;
}
$values = $event->getValues();
$merchant = (string) ($values['wayforpay_merchant_account'] ?? '');
if ($merchant === '' || $this->isKnownMerchant($merchant)) {
return;
}
$message = __(
'WayForPay Merchant Account "%s" is not a CRM gateway merchant. The CRM invoice will have no merchant.',
$merchant
);
$event->addConfirmation($message);
}