Defining Plugin Settings

If your module is pluggable, the CMS will automatically create a "plugin settings" Admin Box for you, which will let an administrator change the framework your plugins use.

If you wish to have more settings for your plugins, you can target this Admin Box and add more fields by writing a file called tuix/admin_boxes/plugin_settings.yaml and merging in some settings.

Adding fields to the correct Plugin Settings Admin Box

Lots of modules define plugin settings, and you will need to make sure that the fields that you define appear in the correct Admin Box!

You can do this be ensuring that your plugin_settings.yaml file starts as follows:

plugin_settings:
    module_class_name: your_modules_class_name
    tabs:
        first_tab:
            label: Label for the first tab

Please note the following three things:

• You must use the plugin_settings tag path.
• Your plugin_settings element must have a property called module_class_name set to your module's class name. This is so that the plugin settings you define in this file do not appear for other modules.
• The code-name for the left-most tab is called first_tab. (The tabs following can have any code-name.)

So, if you copy and paste the example above, you should replace your_modules_class_name with the directory name of your module, and Label for the first tab with the label that you want for the first tab.

Loading and Saving Plugin Settings

The CMS contains logic for loading and saving these fields, so you do not need to add any code to your module's fillAdminBox() or saveAdminBox() functions to make the loading and saving work. All you need to do is come up with a code-name for your plugin setting and enter it into the name property.

Formatting and Validating Plugin Settings

While not required, you can still write your module's formatAdminBox() and validateAdminBox() functions, e.g.:

public function validateAdminBox(
    $path, $settingGroup, &$box, &$fields, &$values, $changes, $saving
) {
    switch ($path) {
        case 'plugin_settings':
            switch ($settingGroup) {
                case 'your_modules_class_name':
                    if (empty($values['first_tab/your_field'])) {
                        $fields['first_tab/your_field']['error'] =
                            adminPhrase('Please enter a name');
                    } elseif (strlen($values['first_tab/your_field']) < 5) {
                        $fields['first_tab/your_field']['error'] =
                            adminPhrase('Please enter a longer name');
                    }
                    
                    break;
            }
        
        break;
    }
}

Please note the $settingGroup parameter in the example above - this is used to determine which module's plugin settings are currently being edited.

Defining the default value of Plugin Settings

You can set the value property of a field and then bump your module's revision number to give a Plugin Setting a default value.

If you ever change the default value you will need to bump your module's revision number again to have it re-read.

Inheriting Plugin Settings from other Modules

If you use the inherit_settings_from_module property in your module's description.yaml file, your module's plugin setting admin box will also contain all of the plugin settings from the module that you inherit from.

You must still set the module_class_name in your plugin_settings.yaml file to your module's directory name.

Reference for plugin_setting: