18.1 Creating and Installing Plugins - Reference Documentation
Authors: Graeme Rocher, Peter Ledbrook, Marc Palmer, Jeff Brown, Luke Daley, Burt Beckwith, Lari Hotari
Version: 3.1.6
18.1 Creating and Installing Plugins
Creating Plugins
Creating a Grails plugin is a simple matter of running the command:grails create-plugin [PLUGIN NAME]
grails create-plugin example
would create a new plugin project called example
.In Grails 3.0 you should consider whether the plugin you create requires a web environment or whether the plugin can be used with other profiles. If your plugin does not require a web environment then use the "plugin" profile instead of the "web-plugin" profile:grails create-plugin [PLUGIN NAME] --profile=plugin
src/main/groovy
directory under the plugin package structure you will find a plugin descriptor class (a class that ends in "GrailsPlugin").Being a regular Grails project has a number of benefits in that you can immediately test your plugin by running (if the plugin targets the "web" profile):grails run-app
Plugin projects don't provide an index.gsp by default since most plugins don't need it. So, if you try to view the plugin running in a browser right after creating it, you will receive a page not found error. You can easily create a grails-app/views/index.gsp
for your plugin if you'd like.
The plugin descriptor name ends with the convention GrailsPlugin
and is found in the root of the plugin project. For example:class ExampleGrailsPlugin { … }
src/main/groovy
directory, otherwise they are not regarded as a plugin. The plugin class defines metadata about 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 plugingrailsVersion
- The version range of Grails that the plugin supports. eg. "1.2 > *" (indicating 1.2 or higher)author
- plugin author's nameauthorEmail
- plugin author's contact e-maildescription
- full multi-line description of plugin's featuresdocumentation
- URL of the plugin's documentationlicense
- License of the pluginissueManagement
- Issue Tracker of the pluginscm
- Source code management location of the plugin
class QuartzGrailsPlugin { def grailsVersion = "1.1 > *" def author = "Sergey Nebolsin" def authorEmail = "nebolsin@gmail.com" def title = "Quartz Plugin" def description = '''\ The 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/plugin/quartz" … }
Installing Local Plugins
To make your plugin available for use in a Grails application run theinstall
command:grails install
build.gradle
file:compile "org.grails.plugins:quartz:0.1"
In Grails 2.x plugins were packaged as ZIP files, however in Grails 3.x plugins are simple JAR files that can be added to the classpath of the IDE.
Plugins and Multi-Project Builds
If you wish to setup a plugin as part of a multi project build then follow these steps.Step 1: Create the application and the pluginUsing thegrails
command create an application and a plugin:$ grails create-app myapp $ grails create-plugin myplugin
settings.gradle
file with the following contents:include "myapp", "myplugin"
PROJECT_DIR - settings.gradle - myapp - build.gradle - myplugin - build.gradle
build.gradle
of the application declare a dependency on the plugin within the plugins
block:grails { plugins { compile project(':myplugin') } }
You can also declare the dependency within the dependencies
block, however you will not get subproject reloading if you do this!
Step 4: Run the applicationNow run the application using the grails run-app
command from the root of the application directory, you can use the verbose
flag to see the Gradle output:$ cd myapp $ grails run-app -verbose
:myplugin:compileAstJava UP-TO-DATE :myplugin:compileAstGroovy UP-TO-DATE :myplugin:processAstResources UP-TO-DATE :myplugin:astClasses UP-TO-DATE :myplugin:compileJava UP-TO-DATE :myplugin:configScript UP-TO-DATE :myplugin:compileGroovy :myplugin:copyAssets UP-TO-DATE :myplugin:copyCommands UP-TO-DATE :myplugin:copyTemplates UP-TO-DATE :myplugin:processResources :myapp:compileJava UP-TO-DATE :myapp:compileGroovy :myapp:processResources UP-TO-DATE :myapp:classes :myapp:findMainClass :myapp:bootRun Grails application running at http://localhost:8080 in environment: development
Notes on excluded Artefacts
Although the create-plugin command creates certain files for you so that the plugin can be run as a Grails application, not all of these files are included when packaging a plugin. The following is a list of artefacts created, but not included by package-plugin:grails-app/build.gradle
(although it is used to generatedependencies.groovy
)grails-app/conf/application.yml
(renamed to plugin.yml)grails-app/conf/spring/resources.groovy
grails-app/conf/logback.groovy
- Everything within
/src/test/**
- SCM management files within
**/.svn/**
and**/CVS/**
Customizing the plugin contents
When developing a plugin you may create test classes and sources that are used during the development and testing of the plugin but should not be exported to the application.To exclude test sources you need to modify thepluginExcludes
property of the plugin descriptor AND exclude the resources inside your build.gradle
file. For example say you have some classes under the com.demo
package that are in your plugin source tree but should not be packaged in the application. In your plugin descriptor you should exclude these:// resources that should be loaded by the plugin once installed in the application def pluginExcludes = [ '**/com/demo/**' ]
build.gradle
you should exclude the compiled classes from the JAR file:jar {
exclude "com/demo/**/**"
}
Inline Plugins in Grails 3.0
In Grails 2.x it was possible to specify inline plugins inBuildConfig
, in Grails 3.x this functionality has been replaced by Gradle's multi-project build feature.To set up a multi project build create an appliation and a plugin in a parent directory:$ grails create-app myapp $ grails create-plugin myplugin
settings.gradle
file in the parent directory specifying the location of your application and plugin:include 'myapp', 'myplugin'
build.gradle
on the plugin:compile project(':myplugin')