slider

Defining Site Settings

Site settings work a lot like plugin settings do - you define them by creating fields in an admin box, and you can check their values by calling a function. However rather than just applying to one plugin, they apply to the entire site.

Defining a Group of Site Settings

Rather than have every single site setting squeezed into one Admin Box, site settings are split up across different groups.

To create a new group, you will need to define it in the Organizer panel that contains the setting groups, for example from the Newsletters module:

zenario__administration:
    panels:
        site_settings:
            items:
                zenario_newsletter__site_settings_group:
                    name: Newsletters
                    desc: Settings for Newsletters

Adding fields to the correct Site Settings Admin Box

As with plugin settings, when defining new fields in your Admin Box you will need to need to specify which settings group these fields should appear in.

The syntax that you need to use is similar, except the property is called setting_group:

You must use the site_settings tag path.
Your site_settings element must have a property called setting_group set to the name of the setting group.

Here's another example from the Newsletter module:

site_settings:
    setting_group: zenario_newsletter__site_settings_group
    title: Editing settings for newsletters
    tabs:
        zenario_newsletter__site_settings:
            edit_mode:
                enabled: Yes
                priv: _PRIV_EDIT_SITE_SETTING
                on: Yes
            label: Details
            fields:
                zenario_newsletter__default_from_name:
                    label: 'Default "From" name:'
                    site_setting:
                        name: zenario_newsletter__default_from_name
                    type: text
                    validation:
                        required: Please enter default "From" name.
                zenario_newsletter__default_from_email_address:
                    label: 'Default "From" address:'
                    site_setting:
                        name: zenario_newsletter__default_from_email_address
                    type: text
                    validation:
                        required: Please enter default "From" email address.
                        email: Please enter valid "From" email address.

Loading and Saving Site 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 site setting and enter it into the name property.

The code-name must be unique, so we recommend that you prefix it (e.g. with your company name or module's name) to avoid clashing with any other developer.

Formatting and Validating Site 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 'site_settings':
            switch ($settingGroup) {
                case 'zenario_newsletter__site_settings':
                    //...
                    
                    break;
            }
        
        break;
    }
}