Grails - Understanding Plugins

Working with Plugins

Previous: Creating Plugins Top: Plugin Dev Guide Next: Basic Artifacts

Understanding a Plugin's structure

So as mentioned previously, a plugin is merely a regular Grails application with this special file; however when installed, the structure of a plugin differs slightly. For example, take a look at this plugin directory structure:

+ grails-app
     + controllers
     + domain
     + taglib
     etc.
 + lib
 + src
     + java
     + groovy
 + web-app
     + js
     + css

Basically when a plugin is installed into a project, the stuff within the grails-app directory will go into a directory like $PROJECT_HOME/plugins/example-1.0/grails-app . They will NOT be copied into the main source tree. A plugin NEVER messes with a project's primary source tree.

However, static resources such as those inside the web-app directory will be copied into the project's web-app directory under a special "plugins" directory for example web-app/plugins/example-1.0/js . It is therefore the responsibility of the plugin to make sure that it references static resources from the correct place. For example if you were

<g:createLinkTo dir="/plugins/example/js" file="mycode.js" />

To make this easier there is a special pluginContextPath variable available that changes whether you're executing the plugin standalone or whether you've installed it into an application:

<g:createLinkTo dir="${pluginContextPath}" file="js/mycode.js" />

At runtime this will either evaluate to /js or /plugins/example/js depending on whether the plugin is running standalone or has been installed in an application

Java & Groovy code that the plugin provides within the lib and src/java and src/groovy directories will be compiled into the main project's web-app/WEB-INF/classes directory so that they are made available at runtime.

What a Plugin can and can't do

A plugin can do just about anything, but a good plugin should be as unintrusive as possible. It should use convention over configuration where possible, otherwise provide an artifact in a project's grails-app/conf directory where configuration can be done.

One thing a plugin cannot do though is modify the web-app/WEB-INF/web.xml or web-app/WEB-INF/applicationContext.xml files. A plugin can participate in web.xml generation, but not modify the file or provide a replacement. A plugin can NEVER change the applicationContext.xml file, but can provide runtime bean definitions as seen shortly.

Previous: Creating Plugins Top: Plugin Dev Guide Next: Basic Artifacts