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:

grails run-app

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:

Here is an example from Quartz Grails plugin

class 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:

grails package-plugin

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:

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.