Intro

A grails application typically contains multiple plug-ins (or plugins). There are publicly available plug-ins shared through the ( official Grails plug-in portal), to which you can release your own plug-ins, but you can also make project specific plug-ins (internal plug-ins or modules).

This page is mainly about creating internal plug-ins to modularize a project.

Throughout the document <tt>PLUGIN_NAME</tt> and <tt>PROJECT_NAME</tt> should be adapted according to the current project and plug-in you are working on.

Reasons

Reasons to modularize a project using plug-ins include: * Promotes code re-use * Create structure thereby increasing readability of a project * One can work on specific aspect without needing to run whole application * Faster testing

Good Uses for a Plug-in

Things to look out for

* Using plug-ins, it is easy to add 'magic' functionality to an application to the point other developers will not understand what is happening (eg. by dynamically adding functionality to controller classes). * Changing standard behavior can be confusing * Too much dependency on host application

Anatomy of a plug-in

A plug-in is almost identical to a grails application, except for the file <tt>PLUGIN_NAMEGrailsPlugin?.groovy</tt> in the plug-in's root directory, the plug-in descriptor.

The Grails plug-in class inside this descriptor has the following properties.

*<tt>version</tt> specifies the version of the plug-in, be sure to increment this before you package the plug-in. *<tt>grailsVersion</tt> the version of Grails this plug-in depends on. *<tt>dependsOn</tt> a hashMap of plug-in names and versions this plug-in depends on like so: <tt>someOtherPlugin:"0.1"</tt>. This is used both when running the plug-in standalone and after the plug-in is installed in the host application. Duplicate dependencies resulting from multiple plug-ins (or the host application) depending on the same plug-ins will be installed once. I'm not sure what happens when multiple versions are involved but usually dependencies are for the latest version of a plug-in so the problem disappears. This can be done by doing <tt>someOtherPlugin:"0.1 > *"</tt> where version 0.1 is the minimum version but the newest one will be used. *<tt>pluginExcludes</tt> a list of strings specifying which files to exclude from plug-in packaging. *<tt>author</tt> you *<tt>authorEmail</tt> your email *<tt>title</tt> summary of plug-in's function *<tt>description</tt> brief description *<tt>documentation</tt> URL to documentation page

Plug-in Hooks

doWithSpring

doWithWebDescriptor

doWithApplicationContext

doWithDynamicMethods

Plug-in Development

Creating a plug-in

Creating a grails plug-in is done by executing the command <tt>grails create-plugin PLUGIN_NAME</tt> in the directory your grails projects are located. You should then add the resulting project tree to your version control system (eg. in a folder <tt>PROJECT_NAME-grailsPlugins/PLUGIN_NAME</tt> under the root).

Deploying a plug-in

Automatic Deployment to Maven Repository

*In your plug-in project install the maven-publisher plugin: <tt>grails install-plugin maven-publisher</tt> *Add the following lines (adjusted to your situation) to <tt>BuildConfig?.groovy</tt> of your plug-in: <pre>grails.project.dependency.distribution = {

remoteRepository(id: "releases", url: " http://nexus.nmcdsp.org/nexus-webapp-1.7.2/content/repositories/releases") {

authentication username: "deployment", password: "PASSWORD"

}

}</pre> *<tt>grails maven-deploy --repository=releases</tt> or better yet, add this as a run configuration in your IDE. Packaging will be done for you.

==== Nexus Server Manual Deployment==== There is a  Sonatype Nexus repository at  http://nexus.nmcdsp.org for the nmcdsp project. The release repository can be viewed by clicking on Repositories and then Releases.

To upload a plug-in (or artifact) log in and go to the Releases repository. Click on the Artifact Upload tab, then the Select Artifact(s) to Upload... button and select your file. For GAV Definition use GAV Parameters. Enter org.grails.plugins for Group and remove the leading grails- from the Artifact text box. Finish by clicking the Add Artifact button followed by Upload Artifact(s).

Official Grails Repository

Should be as simple as doing <tt>grails release-plugin</tt> once you have a correct account.

Running your plug-in standalone

A plug-in can be run as a normal application, making it easy to test its functionality without running the whole host application. You can add whatever domain classes, controllers, or views you like (besides those that are part of the actual plug-in). In the plug-in configuration file (<tt>PLUGIN_NAMEGrailsPlugin?.groovy</tt>) you can choose to exclude those files from packaging if you wish. If your plug-in depends on the host application and running the plug-in on its own does not make sense, you can still enjoy the flexibility of not having to repackage and install the plug-in every time you make changes by using in-place plug-ins.

In-place plug-ins

Add <tt>grails.plugin.location.'PLUGIN_NAME' = '../PLUGIN_NAME'</tt> to <tt>BuildConfig?.groovy</tt>. The location is relative to the host project so in the example both the plug-in source and host application source directories are in the same project directory. Also, comment out the plug-in dependency in the host application's <tt>application.properties</tt> file. When running the application, Grails will ask to uninstall the plug-in if it was installed before; confirm with <tt>'y'</tt>.

To switch back to the normal plug-in situation, just comment out the plug-in location line and uncomment the plug-in dependency.

Testing your plug-in

Running unit and integration tests for a plug-in is identical to running those tests for an application.

Development cycle

Once you have everything set up and working will most likely want to make changes to your plug-in. A typical workflow for a plug-in that can function on its own will be as follows.

# Make changes # Run your plug-in as an application # Run plug-in tests # Repeat steps 1 to 3 if necessary # Adapt documentation/description # Increment version number (in plug-in and host application) # Package plug-in <pre>grails package-plugin</pre> # Deploy # Commit your changes

If your plug-in requires a host app or if you want to develop using the host app you will have to substitute steps 1 to 4 by:

# Set up your plug-in as an in-place plug-in # Make changes # Run the host application (answer 'y' when grails asks to uninstall the plug-in, since you're using the in-place code now) # Run tests # Repeat steps 2 to 4 # Revert in-place plug-in settings

IDE Integration

IntelliJ

* Import module to view plug-in code alongside main application * Add special run configurations for running plug-in standalone, and packaging

[ http://www.themeswiki.org/Building_Plug-in_using_Grails ]  http://www.slideshare.net/gr8conf/the-grails-plugin-system-by-graeme-rocher  http://grails.org/doc/latest/guide/12.%20Plug-ins.html

[[Category:Metabolomics / Tools]]