Grails Plugin Config Plugin

(1)

Used by approximately

of Grails users

Author(s)	Daniel Henrique Alves Lima
Current Release	0.1.5 (8 months ago)
Grails Version	1.2.0 > *
Tags	config config merge configuration configuration merge plugin config plugin configuration
Dependency	compile ":plugin-config:0.1.5"

Plugin to simplify plugin configuration tasks.

Installation
Description
Faq
Screenshots

Last updated by daniel_henrique 10 months ago

grails install-plugin plugin-config

Project at GitHub is grails-plugin-config-plugin

Last updated by daniel_henrique 8 months ago

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, install plugin-config as a regular plugin

grails install-plugin plugin-config

or declare it as compile/runtime dependency

/* grails-app/conf/BuildConfig.groovy */
    plugins {
       //if ("$grailsVersion" > "1.3.7") 
       compile ':plugin-config:[0.1.4,)'
    }

Usage

Add plugin-config as a dependency of your plugin

/* BrandNewGrailsPlugin.groovy */
    // the other plugins this plugin depends on
    def dependsOn = [pluginConfig: '0.1.4 > *']

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.

Last updated by admin 10 months ago