12.1 Creating and Installing Plug-ins.gdoc

h4. Creating Plugins

Creating a Grails plugin is a simple matter of running the command:

{code:java}
grails create-plugin [PLUGIN NAME]
{code}

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:

{code:java}
grails run-app
{code}

The plugin descriptor itself ends with the convention @GrailsPlugin@ and is found in the root of the plugin project. For example:

{code:java}
class ExampleGrailsPlugin {
   def version = 0.1

   ...
}
{code}

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 plugin":http://grails.org/Quartz+plugin:

{code:java}
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"

   ...
}
{code}

h4. Installing & Distributing Plugins

To distribute a plugin you need to navigate to its root directory in a terminal window and then type:

{code:java}
grails package-plugin
{code}

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:

{code:java}
grails install-plugin /path/to/plugin/grails-example-0.1.zip
{code}

If the plugin is hosted on a remote HTTP server you can also do:

{code:java}
grails install-plugin http://myserver.com/plugins/grails-example-0.1.zip
{code}

h4. Notes on excluded Artefacts

Although the [create-plugin|commandLine] 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|commandLine]:

* @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@.

h4. 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:

{code:java}
// 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"
{code}

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.