Changes between Initial Version and Version 1 of Grails Plugins

Feb 28, 2011, 12:32:07 PM (10 years ago)



  • Grails Plugins

    v1 v1  
     1== Intro ==
     2A 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'').
     4This page is mainly about creating internal plug-ins to modularize a project.
     6Throughout 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.
     8=== Reasons ===
     9Reasons to modularize a project using plug-ins include:
     10* Promotes code re-use
     11* Create structure thereby increasing readability of a project
     12* One can work on specific aspect without needing to run whole application
     13* Faster testing
     15=== Good Uses for a Plug-in ===
     17=== Things to look out for ===
     18* 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).
     19* Changing standard behavior can be confusing
     20* Too much dependency on host application
     22== Anatomy of a plug-in ==
     23A plug-in is almost identical to a grails application, except for the file <tt>''PLUGIN_NAME''GrailsPlugin.groovy</tt> in the plug-in's root directory, the ''plug-in descriptor''.
     25The Grails plug-in class inside this descriptor has the following properties.
     27*<tt>version</tt> specifies the version of the plug-in, be sure to increment this before you package the plug-in.
     28*<tt>grailsVersion</tt> the version of Grails this plug-in depends on.
     29*<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.
     30*<tt>pluginExcludes</tt> a list of strings specifying which files to exclude from plug-in packaging.
     31*<tt>author</tt> you
     32*<tt>authorEmail</tt> your email
     33*<tt>title</tt> summary of plug-in's function
     34*<tt>description</tt> brief description
     35*<tt>documentation</tt> URL to documentation page
     36=== Plug-in Hooks ===
     37==== doWithSpring ====
     38==== doWithWebDescriptor ====
     39==== doWithApplicationContext ====
     40==== doWithDynamicMethods ====
     42== Plug-in Development ==
     44=== Creating a plug-in ===
     45Creating 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).
     47=== Deploying a plug-in ===
     49==== Automatic Deployment to Maven Repository ====
     50*In your plug-in project install the maven-publisher plugin: <tt>grails install-plugin maven-publisher</tt>
     51*Add the following lines (adjusted to your situation) to <tt>BuildConfig.groovy</tt> of your plug-in:
     52<pre>grails.project.dependency.distribution = {
     53    remoteRepository(id: "releases", url: "") {
     54        authentication username: "deployment", password: "PASSWORD"
     55    }
     57*<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.
     59==== Nexus Server Manual Deployment====
     60There is a [ Sonatype Nexus] repository at [] for the nmcdsp project. The release repository can be viewed by clicking on ''Repositories'' and then ''Releases''.
     62To 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)''.
     64==== Official Grails Repository ====
     65Should be as simple as doing <tt>grails release-plugin</tt> once you have a correct account.
     67== Running your plug-in standalone ==
     68A 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_NAME''GrailsPlugin.groovy</tt>) you can choose to exclude those files from packaging if you wish.
     69If 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''.
     71== In-place plug-ins ==
     72Add <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.
     73Also, comment out the plug-in dependency in the host application's <tt></tt> file. When running the application, Grails will ask to uninstall the plug-in if it was installed before; confirm with <tt>'y'</tt>.
     75To switch back to the normal plug-in situation, just comment out the plug-in location line and uncomment the plug-in dependency.
     77== Testing your plug-in ==
     78Running unit and integration tests for a plug-in is identical to running those tests for an application.
     80=== Development cycle ===
     81Once 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.
     83# Make changes
     84# Run your plug-in as an application
     85# Run plug-in tests
     86# Repeat steps 1 to 3 if necessary
     87# Adapt documentation/description
     88# Increment version number (in plug-in and host application)
     89# Package plug-in <pre>grails package-plugin</pre>
     90# Deploy
     91# Commit your changes
     93If 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:
     95# Set up your plug-in as an in-place plug-in
     96# Make changes
     97# Run the host application (answer 'y' when grails asks to uninstall the plug-in, since you're using the in-place code now)
     98# Run tests
     99# Repeat steps 2 to 4
     100# Revert in-place plug-in settings
     102== IDE Integration ==
     104=== IntelliJ ===
     105* Import module to view plug-in code alongside main application
     106* Add special run configurations for running plug-in standalone, and packaging
     108== External Links ==
     109[ ]
     113[[Category:Metabolomics / Tools]]