Last updated by 4 years ago

Page: Creating Plugins, Version:9

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

You can also provide additional information about your plugin using several special properties but is not require:

  • '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
or
grails install-plugin file:///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.
1.) Sign up at xircles.codehaus.org
2.) 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.
3.) E-mail the developer mailing list to summarize what you would like to contribute and ask for your request to be processed. Include your xircles user name in the request, so your account can be approved.

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.

If you are updating an existing plugin you need to be using a SVN working copy. which you can get by doing
svn checkout https://svn.codehaus.org/grails-plugins/grails-[pluginname]/trunk
You will need to manually add or remove files with something like 'svn add ...' once all that is ready then you are ready for the release-plugin command

Next: Understanding Plugins