Creating, Distributing & Installing

Creating a Plugin

You can create a Grails plugin by running the command:

grails create-plugin [PLUGIN NAME]

This will create a plugin project for the name you specify. Say for example {{grails create-plugin example}} 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 (in fact, not only is the structure the same, but a plugin is a Grails application so you can just type {{grails run-app}} from the root of the plugin directory to execute a Grails plugin as a Grails app) Following our {{example}} plugin it will look something like:

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).

_(since 0.5.5)_ You can also provide additional information about your plugin using several special properties:

'title' - short one-sentence description of your plugin
'author' - plugin author's name
'authorEmail' - plugin author's contact e-mail
'description' - full multi-line description of plugin's features
'documentation' - URL where plugin's documentation can be found

Here is an example from Quartz Grails plugin:

class QuartzGrailsPlugin {
    def version = "0.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 the example plugin you need to navigate to its root directory using cd example 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 in the above case this would be grails-example-0.1.zip.

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 was hosted on a remote HTTP server you can also run:

grails install-plugin http://myserver.com/plugins/grails-example-0.1.zip

Distributing Plugins in Grails Plugins Repository

The preferred way to distribute a plugin is to publish it under the Grails Plugins Repository. This will make your plugin available via the 'grails list-plugins' command and make the plugin's info available via 'grails plugin-info <plugin_name>'.

Before you can start releasing plugins to the main repository, you first need an account. Sign up here if you have not already done so, then register to become a member of the Grails Plugins project - you should see an "Apply to join as a developer" link at the bottom of the left navigation bar. Finally, e-mail the developer mailing list to ask for your request to be processed.

Once you have a Xircles account and become a member of the Grails Plugins project, have your codehaus SVN login credentials available and run:

grails release-plugin

This will automatically commit changes to SVN, do some tagging and make your changes available via the grails list-plugins command.

This feature (installing plugins from http://plugins.grails.org/) is available since 0.5.5. To make your plugin available for users of older versions, put the plugin's distribution zip in http://plugins.grails.org/dist/ (can be accessed via WebDAV using Codehaus Xircles username/password)

Next: Understanding Plugins