4 Configuration API

• A way to declare the Config properties that a plugin supports
• Automatic namespacing of plugin Config values to avoid clashes
• Validation of Config values
• Merging of config from plugins into main Application config
• The ability for plugins to configure other plugins
• An injected "pluginConfig" variable in all artefacts containing the plugin's configuration

All of this adds up to more powerful integration and less frustration and confusion for developers.

4.1 Changing Application and Plugin Config Values

The code uses a simple DSL that is identical to normal Config except:

1. The top level nodes are plugin names or "application" to determine what scope of config you are changing
2. The closure is passed the existing config as its first and only argument

The application Config is loaded first. All the doWithConfig blocks are evaluated and the results merged in.

def doWithConfig = { config ->
    platformUi {
        ui.Bootstrap.button.cssClass = 'btn'
        ui.Bootstrap.tab.cssClass = 'tab-pane'
        ui.Bootstrap.field.cssClass = 'input'
    }
    application {
        // set something based on another config value that has already been
        // by the application
        grails.x.y = confg.p.q == 'something' ? true : false
    }
}

The plugin name scope is the camel case beanNameConventionStyle. So the above is setting config values for the "grails-platform-ui" plugin.

Any values within a plugin scoped block as in the first block above, are merged into the main Config under plugin.<pluginName>. It is therefore impossible to change global Config values within a plugin config block.

Values inside the "application" block are merged into the root level of the application Config, so you can set any normal value.

4.2 Declaring Configuration Options

This allows the platform to warn users when they mistype a config name or supply and invalid value - and to formalize definition of default values rather than a plugin merging in default values.

Do declare the options your plugin supports, add the doWithConfigOptions closure to your plugin descriptor:

def doWithConfigOptions = {
    'organization.name'(type: String, defaultValue: 'My Corp (set plugin.platformCore.organization.name)')
    'site.name'(type: String, defaultValue: 'Our App (set plugin.platformCore.site.name)')
}

This block, from the platform core, defines two configuration values of type String, with a default value.

You can also supply a custom validator:

def doWithConfigOptions = {
    'concurrentConnections'(type: Integer, defaultValue: 10, 
        validator: { v -> v < 500 ? null : 'concurrent.connections.too.big' }
}

Behaving just like constraint validators, your validator returns null for "ok" or an i18n message string for the error.

4.3 Accessing Plugin Config

The pluginConfig variable is automatically injected into all artefacts of your plugin, automatically namespace for your plugin using the plugin.<pluginName>. prefix.

So in a service you can trivially access this config inside a service or controller for example:

class MyPluginService {
    def doSomething() {
       if (pluginConfig.enabled) {
          println "It worked!"
       }
    }
}