Plugin Basics

<- Understanding a Plugin's Structure Top: Plugin Dev Guide Hooking into Build Script Events ->

Post-install configuration and participating in application upgrade process

A plugin can do post-install configuration and participate in application upgrade process ('grails upgrade' command). There are two special scripts under scripts directory of the plugin - _Install.groovy and _Upgrade.groovy. _Install.groovy is executed after the plugin has been installed and _Upgrade.groovy is executed each time the user upgrades his application with 'grails upgrade' command.

These scripts are Gant scripts so you can use the full power of Gant. An addition to the standard Gant variables is the pluginBasedir variable which points at the plugin installation basedir.

Here is s simple example of such script if plugin wants to create jobs dir under application's 'grails-app' and copy sample configuration from plugin basedir application's conf directory:

Ant.mkdir(dir:"${basedir}/grails-app/jobs")
Ant.copy(file:"${pluginBasedir}/src/samples/SamplePluginConfiguration.groovy",
         todir:"${basedir}/grails-app/conf")
// To access Grails home you can use following code:
// Ant.property(environment:"env")
// grailsHome = Ant.antProject.properties."env.GRAILS_HOME"

Adding a new Script

A plugin can add a new script simply by providing the relevant Gant script within the scripts directory of the plugin:

+ MyPlugin.groovy
   + scripts     <-- additional scripts here
   + grails-app
        + controllers
        + services
        + etc.
    + lib

Adding a new Controller, Tag Library or Service

A plugin can add a new controller, taglib, service etc. by simply creating the relevant file within the grails-app tree. Note that when the plugin is installed it will be loaded from where it is installed and not copied into the main dir tree.

+ ExamplePlugin.groovy
   + scripts
   + grails-app
        + controllers  <-- additional controllers here
        + services <-- additional services here
        + etc.  <-- additional XXX here
    + lib

<- Understanding a Plugin's Structure Top: Plugin Dev Guide Hooking into Build Script Events ->