3 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
• Automatic merging of legacy Config settings into the new plugin namespace

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

3.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.

{docx} 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 = config.p.q == 'something' ? true : false } } {docx}

See doWithConfig for more details.

3.2 Declaring Configuration Options

This allows the platform to warn users when they mistype a config name or supply and invalid value - and to formalise 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:

{docx} 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)') } {docx}

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

You can also supply a custom validator:

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

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

When implementing this config in your plugins, you may want to use the legacyPrefix value so that applications that use your existing Config settings will continue to work, and users will be warned to update their Config.

See doWithConfigOptions for more details.

3.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:

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