Grails Plugin Config Plugin

1 vote

9% of Grails users

Dependency : 
compile ":plugin-config:0.1.8"

Documentation Source Issues

Summary

Simplifies plugin configuration tasks

Description

plugin-config helps plugin developers to deal with repetitive tasks, such as defining the default settings, merging the settings of the plugin with settings provided by the application and checking for specific values.

Installation

In your plugin, add a plugin dependency in BuildConfig.groovy:

plugins {
   compile ':plugin-config:0.1.8'
}

Usage

Create a <plugin-name>DefaultConfig.groovy file and include in it the default settings of your plugin

/* grails-app/conf/BrandNewDefaultConfig.groovy */
grails {
    plugin {
        brandnew {
             setting1 = 'test-value'
             setting2 = new java.util.Date()
        }
    }
}

Retrieving the settings

Using any instance of GrailsApplication, access the merged configuration:

println grailsApplication.mergedConfig
println grailsApplication.mergedConfig.grails.plugin.brandnew.setting1

The merged configuration contains all *DefaultConfig.groovy merged with grailsApplication.config. Settings in grailsApplication.config override settings in *DefaultConfig.groovy.

For example, if your plugin default configuration contains

/* grails-app/conf/BrandNewDefaultConfig.groovy */
grails {
    plugin {
        brandnew {
             enableDirectorySearch = true
             baseDirectory = System.properties['user.dir']
        }
    }
}

And the application configuration contains

/* grails-app/conf/Config.groovy */
grails.plugin.brandnew.baseDirectory = '/home/webadmin/rootDir'

The corresponding merged configuration will be

grails {
    plugin {
        brandnew {
             enableDirectorySearch = true
             baseDirectory = '/home/webadmin/rootDir'
        }
    }
}

In development mode, the merged configuration will be automatically reloaded if any *Config.groovy file changes, but your plugin can "force" the reloading, if necessary:

def oldCfg = grailsApplication.mergedConfig
def newCfg = grailsApplication.getMergedConfig(true) // Will reload and return the merged config
assert oldCfg != newCfg
assert newCfg == grailsApplication.mergedConfig

Because the plugin now has its default settings, there is no need of the 'on demand property creation' behavior of ConfigObject

def config = grailsApplication.mergedConfig.asMap()
println config.grails.plugin.brandnew.setting1
println config.grails.plugin.brandnew.missingSetting // Will return null instead of creating an empty ConfigObject/Map

Your plugin can also use a checked map

def config = grailsApplication.mergedConfig.asMap(true)
println config.grails.plugin.brandnew.setting1
println config.grails.plugin.brandnew.misspelledSetting // Will throw an IllegalArgumentException instead of creating an empty ConfigObject/Map

Plugin dependency and load-merge order

If the brand-new plugin depends on known-helper plugin and both use *DefaultConfig.groovy files, KnownHelperDefaultConfig.groovy will load first and its default settings will be available in BrandNewDefaultConfig.groovy:

/* grails-app/conf/KnownHelperDefaultConfig.groovy */
grails {
    plugin {
        knownhelper {
             amountOfProcesses = 3
        }
    }
}

/* grails-app/conf/BrandNewDefaultConfig.groovy */
grails {
    plugin {
        brandnew {
             amountOfProcesses = 10 * grails.plugin.knownhelper.amountOfProcesses
        }
    }
}

Validating or changing the configuration

brand-new plugin can validate and/or change the merged configuration by defining a special closure:

/* BrandNewGrailsPlugin.groovy */
    def afterConfigMerge = {config, mergeCtx ->
       /* Validate that the application has provided all the required settings. */
    }

afterConfigMerge closures will be executed following the same order as the merge.

Be very careful when changing the configuration, because you can cause malfunction of other plugins that use plugin-config and that will depend on your plugin.