Creating Plugins
Creating a Grails plugin is a simple matter of running the command:
grails create-plugin [PLUGIN NAME]
This will create a plugin project for the name you specify. Say for example you run
grails create-plugin example
. This would create a new plugin project called
example
.
The structure of a Grails plugin is exactly the same as a regular Grails project's directory structure, except that in the root of the plugin directory you will find a plugin Groovy file called the "plugin descriptor".
Being a regular Grails project has a number of benefits in that you can immediately get going testing your plugin by running:
The plugin descriptor itself ends with the convention
GrailsPlugin
and is found in the root of the plugin project. For example:
class ExampleGrailsPlugin {
def version = 0.1 …
}
All plugins must have this class in the root of their directory structure to be valid. The plugin class defines the version of the plugin and optionally various hooks into plugin extension points (covered shortly).
You can also provide additional information about your plugin using several special properties:
title
- short one sentence description of your plugin
version
- The version of your problem. Valid versions are for example "0.1", "0.2-SNAPSHOT", "0.1.4" etc.
grailsVersion
- The version of version range of Grails that the plugin supports. eg. "1.1 > *"
author
- plug-in author's name
authorEmail
- plug-in author's contact e-mail
description
- full multi-line description of plug-in's features
documentation
- URL where plug-in's documentation can be found
Here is an example from
Quartz Grails pluginclass QuartzGrailsPlugin {
def version = "0.1"
def grailsVersion = "1.1 > *"
def author = "Sergey Nebolsin"
def authorEmail = "nebolsin@gmail.com"
def title = "This plugin adds Quartz job scheduling features to Grails application."
def description = '''
Quartz plugin allows your Grails application to schedule jobs to be
executed using a specified interval or cron expression. The underlying
system uses the Quartz Enterprise Job Scheduler configured via Spring,
but is made simpler by the coding by convention paradigm.
'''
def documentation = "http://grails.org/Quartz+plugin" …
}
Installing & Distributing Plugins
To distribute a plugin you need to navigate to its root directory in a terminal window and then type:
This will create a zip file of the plugin starting with
grails-
then the plugin name and version. For example with the example plug-in created earlier this would be
grails-example-0.1.zip
. The
package-plugin
command will also generate
plugin.xml
file which contains machine-readable information about plugin's name, version, author, and so on.
Once you have a plugin distribution file you can navigate to a Grails project and type:
grails install-plugin /path/to/plugin/grails-example-0.1.zip
If the plugin is hosted on a remote HTTP server you can also do:
grails install-plugin http://myserver.com/plugins/grails-example-0.1.zip
Notes on excluded Artefacts
Although the
create-plugin command creates certain files for you so that the plug-in can be run as a Grails application, not all of these files are included when packaging a plug-in. The following is a list of artefacts created, but not included by
package-plugin:
grails-app/conf/DataSource.groovy
grails-app/conf/UrlMappings.groovy
build.xml
- Everything within
/web-app/WEB-INF
If you need artefacts within
WEB-INF
it is recommended you use the
_Install.groovy
script (covered later), which is executed when a plug-in is installed, to provide such artefacts. In addition, although
UrlMappings.groovy
is excluded you are allowed to include a
UrlMappings
definition with a different name, such as
FooUrlMappings.groovy
.
Specifying Plugin Locations
An application can load plugins from anywhere on the file system, even if they have not been installed. Simply add the location of the (unpacked) plugin to the application's
grails-app/conf/BuildConfig.groovy
file:
// Useful to test plugins you are developing.
grails.plugin.location.jsecurity = "/home/dilbert/dev/plugins/grails-jsecurity"// Useful for modular applications where all plugins and
// applications are in the same directory.
grails.plugin.location.'grails-ui' = "../grails-grails-ui"
This is particularly useful in two cases:
- You are developing a plugin and want to test it in a real application without packaging and installing it first.
- You have split an application into a set of plugins and an application, all in the same "super-project" directory.