Editable system settings

Overview

Editable system settings are settings that effect the working of your entire system and that are editable through the CMS admin GUI.

They are stored against a single data object, system_config, and are organised into categories.

Screenshot showing system settings with two categories,

Multiple sites & custom tenancy

As of Preside 10.7.0, if you have multiple sites, each configuration form can now be configured globally and then per-site if you wish to override global defaults in a particular site.

As of Preside 10.13.0, this behaviour can be overwritten in two ways:

Disable site tenancy altogether
Specify an alternative tenant (see Configuring data tenancy)

Disabling site tenancy for a category

Disabling site tenancy for a system configuration category can be done by adding a noTenancy="true" attribute to the configuration form xml:

<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.my_category:" noTenancy="true">
    <tab id="default">
        <fieldset id="default" sortorder="10">
            <field name="my_setting" />
        </fieldset>
    </tab>
</form>

Using a custom tenancy

Custom tenancy (see Configuring data tenancy) allows automatic filtering of data based on some configured current request record. As of 10.13.0, you can specify a custom tenant for any configuration form by adding a tenancy="my_custom_tenant" attribute to your setting category's xml form.

For example, if you had defined a special account tenancy, you could add this to your settings form:

<?xml version="1.0" encoding="UTF-8"?>
<form i18nBaseUri="system-config.my_category:" tenancy="account">
    <tab id="default">
        <fieldset id="default" sortorder="10">
            <field  />
        </fieldset>
    </tab>
</form>

This would result in admin users being able to supply a global set of default settings for your category and then being able to override the settings for each account tenant.

Retrieving settings

From handlers and views

Settings can be retrieved from within your handlers and views with the getSystemSetting() method. For example:

function myHandler( event, rc, prc ) {
    prc.hipchatApiKey = getSystemSetting(
          category = "hipchat-integration"
        , setting  = "hipchat_api_key"
        , default  = "someDefaultApiKey"
    );
}

From within your service layer

Preside Super Class

The preferred method of retrieving settings through the service layer is through use of the $getPresideSetting() and $getPresideCategorySettings() methods that can be injected into your service as part of the Preside Super Class (see Using the super class). For example:

/**
 * presideService
 *
 */
component {

    public void function doSomething() {
        var settings    = $getPresideCategorySettings( category="email" );
        var emailServer = $getPresideSetting( category="email", setting="server", default="127.0.0.1" );
    }

}

Wirebox

Settings can alternatively be injected into your service layer components using the Preside custom WireBox DSL. For example:

component {
    property name="hipchatApiKey" inject="presidecms:systemsetting:hipchat-integration.hipchat_api_key";

    ...
}

Warning

If you inject settings this way into a singleton, any changes to the settings through the admin will not be reflected in your service object until it is reinstantiated (i.e. a full application reload). In this case, you may wish to use the method described below.

You can also inject the System configuration service object itself into your services and use its getSetting() method directly. For example:

component {
    property name="systemConfigurationService" inject="systemConfigurationService";

    ...

    private string function _getApiKey() {
        return systemConfigurationService.getSetting(
              category = "hipchat-integration"
            , setting  = "hipchat_api_key"
            , default  = "nokeyselected"
        );
    }
}

Interceptors and custom validation

When you save the settings through the admin UI, two interception points are raised, preSaveSystemConfig and postSaveSystemConfig. These events allow your systems to perform custom validation and any other logic your need to perform once a category's settings have been saved.

Tip

See the ColdBox Interceptors documentation for in depth instructions on setting up interceptors.

Both interception points receive category and configuration arguments in the interceptData struct and, in addition, the preSaveSystemConfig interception point receives a validationResult object with which to record any custom validation (see Validation result).

For example, the core email settings form uses an interceptor to validate the email server configuration:

component extends="coldbox.system.Interceptor" {

    property name="emailService" inject="delayedInjector:emailService";

// PUBLIC
    public void function configure() {}

    public void function preSaveSystemConfig( event, interceptData ) {
        // interception point data
        var category         = interceptData.category         ?: "";
        var configuration    = interceptData.configuration    ?: {};
        var validationResult = interceptData.validationResult ?: "";

        // check that we are the email category and that the
        // form contains all the server configuration variables
        // we need to check
        if ( category == "email" && configuration.keyExists( "server" ) && configuration.keyExists( "port" ) && configuration.keyExists( "username" ) && configuration.keyExists( "password" ) && !IsSimpleValue( validationResult ) ) {

            var errorMessage = emailService.validateConnectionSettings(
                  host     = configuration.server
                , port     = configuration.port
                , username = configuration.username
                , password = configuration.password
            );

            if ( Len( Trim( errorMessage ) ) ) {
                if ( errorMessage == "authentication failure" ) {
                    // adding an error to the validation result with a
                    // translatable error message
                    validationResult.addError( "username", "system-config.email:validation.server.authentication.failure" );
                } else {
                    // adding an error to the validation result with a
                    // translatable error message
                    validationResult.addError( "server", "system-config.email:validation.server.details.invalid", [ errorMessage ] );
                }
            }
        }
    }
}