Griffon: Your first plugin/addon

Here's another quick Griffon howto. In the last two posts I showed a brand new feature found in Griffon 0.9.2, the ability to handle uncaught exceptions, and building a custom MVC group to handle error dialogs. I mentioned at the end that perhaps it would be a good idea to group several dialogs in a plugin, so that they could be reused in several applications. And that's precisely what we're going to do.

The plugin workflow is very similar to Grails

create a plugin project
configure dependencies as needed
add relevant source code and artifacts
package the plugin

However there's a small but important difference in Griffon: plugins can only affect an application during build time. That is, they can provide new dependencies, new command targets (scripts) or create artifacts. For anything else that must be executed at runtime you must create an Addon. Addons are then the runtime counterpart of plugins. An addon is nothing more than a bunch of classes and a very special class that describes the Addon's capabilities. But will see that in a moment, first we must create a plugin project.

$ griffon create-plugin dialogs
$ cd dialogs

A Griffon plugin project has pretty much the same structure as an application but you can't run it as one (another difference with Grails where you can actually perform this action). The project also includes a very special filed called the plugin descriptor, which in our case is named DialogsGriffonPlugin.groovy. This file describes what the plugin requires in order to be installed in an application (like Griffon version, dependencies, UI toolkit, OS platform) and pointers to additional documentation. Open the file in your favorite editor and make the following changes

DialogsGriffonPlugin.groov

class DialogsGriffonPlugin {
    // the plugin version
    def version = "0.1"
    // the version or versions of Griffon the plugin is designed for
    def griffonVersion = '0.9.2 > *'
    // the other plugins this plugin depends on
    def dependsOn = [nuvolaicons: 0.2]
    // resources that are included in plugin packaging
    def pluginIncludes = []
    // the plugin license
    def license = 'Apache Software License 2.0'
    // Toolkit compatibility. No value means compatible with all
    // Valid values are: swing, javafx, swt, pivot, gtk
    def toolkits = ['swing']
    // Platform compatibility. No value means compatible with all
    // Valid values are:
    // linux, linux64, windows, windows64, macosx, macosx64, solaris
    def platforms = []

def author = 'Your name'
    def authorEmail = ''
    def title = 'Plugin summary/headline'
    def description = '''
Brief description of the plugin.
'''

// URL to the plugin's documentation
    def documentation = 'http://griffon.codehaus.org/Dialogs+Plugin'
}

The dialog built in the last post requires that the NuvolaIcons plugin be installed too. We can force the installation of the plugin by setting a dependency on it. Now, every time a developer installs the dialogs plugin the nuvolaicons plugin will follow if it's not installed already.

Step #2 is creating the addon descriptor. This task can be done by invoking the following command

$ griffon create-addon dialogs

The convention is that the addon's name follows the plugin's but it's not enforced, you can pick any name you want. This command will perform the following tasks for you

create the addon descriptor file named DialogsGriffonAddon.groovy
add addon install instructions to scripts/_Install.groovy
addd addon removal instructions to scripts/_Uninstall.groovy
addd compile dependency on the addon's jar to scripts/_Events.groovy

Addons provide new behavior at runtime, which means the application should be aware of them in the first place. That's precisely what the install hook does. In the same vein, you must remove any hooks if the plugin is uninstalled. Now, an addon can provide many things at runtime. For example, it can add new nodes to the builder (that's precisely how the nuvolaIcon() node is added by the NuvolaIcons addon). It can also add new methods and properties, builder delegates (like those described here), application event handlers, and react to the application's life cycle. All these things are hinted in the Addon descriptor as commented out code. What you don't see however is the hint for MVC groups to be delivered by an Addon. Don't be fooled though, addons can deliver any Griffon artifact, even MVC groups, as we'll see in just a bit.

Step #3. Remember how we created the MVC group before? Right, by means of a griffon command

$ griffon create-mvc griffon.plugins.dialogs.ErrorDialog

This time we have chosen a name with a package. The command should create the following files

griffon-app/models/griffon/plugins/dialogs/ErrorDialogModel.groovy
griffon-app/views/griffon/plugins/dialogs/ErrorDialogView.groovy
griffon-app/controllers/griffon/plugins/dialogs/ErrorDialogController.groovy

If you look inside the addon descriptor class you'll find that the code has been updated too
There's a definition for the MVC group we just created. Awesome! Recall that addons can deliver application event handlers. Also recall from the previous post that we registered an application event handler in order to listen to uncaught exception events. What follows is that we can add the event handler to the addon, making it an integral part of it, thus the application developer no longer has to write a custom handler in griffon-app/conf/Events.groovy. WIN! The following snippet shows the final code for the addon descriptor

class DialogsGriffonAddon {
    def mvcGroups = [
        // MVC Group for "griffon.plugin.dialogs.ErrorDialog"
        'ErrorDialog' : [
            model : 'griffon.plugin.dialogs.ErrorDialogModel',
            view : 'griffon.plugin.dialogs.ErrorDialogView',
            controller : 'griffon.plugin.dialogs.ErrorDialogController'
        ]
    ]

def events = [
        UncaughtExceptionThrown: { x ->
            withMvcGroup('ErrorDialog') { m, v, c ->
                m.title = 'Somebody setup us the bomb!'
                m.message = """
                    Oops! An unexpected error occurred and we do not
                    know what to do with it. However instead of
                    crashing we thought you would like to know that
                    the problem was caused by a

Also, look at the logging information printed in
                    your console.

For great justice!
                """.stripIndent(12)
                c.show()
            }
        }
    ]

private withMvcGroup = { String type, Closure callback ->
        try {
            callback(*app.createMVCGroup(type))
        } finally {
            app.destroyMVCGroup(type)
        }
    }
}

Pay close attention to the name of the event we choose this time: UncaughtExceptionThrown. The addon cannot know in advance the type of exception it should handle, so we declare our intention to handle any exception that might have been caught by GriffonExceptionHandler.

The next step (#4 if you're keeping count) is to fill in the details of the ErrorDialog group. You can copy the snippets from the previous post into their respective new places taking into account the changes in the package and class names.

The last step is to package the plugin and test it on an application. Packaging plugins in Griffon is done in the same way as in Grails, with one additional change: specify a -nodoc if you want a speedy build and avoid javadoc construction

$ griffon package-plugin -nodoc

The command should have created a file named griffon-dialogs-0.1.zip. You can then go an install this plugin in an application, like this

$ griffon create-app sample
$ cd sample
$ griffon install-plugin /path/to/griffon-dialogs-0.1.zip

The output of the last command should result in something similar to this

Welcome to Griffon 0.9.2 - http://griffon.codehaus.org/
Licensed under Apache Standard License 2.0
Griffon home is set to: /usr/local/griffon

Base Directory: /private/tmp/sample
Resolving dependencies...
Dependencies resolved in 569ms.
Running script /usr/local/griffon/scripts/InstallPlugin.groovy
Environment set to development
Installing zip /private/tmp/dialogs/griffon-dialogs-0.1.zip... ...
    [mkdir] Created dir: /Users/aalmiray/.griffon/0.9.2/projects/sample/plugins/dialogs-0.1
    [unzip] Expanding: /private/tmp/dialogs/griffon-dialogs-0.1.zip into /Users/aalmiray/.griffon/0.9.2/projects/sample/plugins/dialogs-0.1
Installed plugin dialogs-0.1 to location /Users/aalmiray/.griffon/0.9.2/projects/sample/plugins/dialogs-0.1. ...
Plugin dependency [nuvolaicons] not found. Attempting to resolve... ...
Resolving plugin nuvolaicons. Please wait...

Installing zip /Users/aalmiray/.ivy2/cache/org.codehaus.griffon.plugins/nuvolaicons/zips/nuvolaicons-0.2-jar.zip... ...
    [mkdir] Created dir: /Users/aalmiray/.griffon/0.9.2/projects/sample/plugins/nuvolaicons-0.2
    [unzip] Expanding: /Users/aalmiray/.ivy2/cache/org.codehaus.griffon.plugins/nuvolaicons/zips/nuvolaicons-0.2-jar.zip into /Users/aalmiray/.griffon/0.9.2/projects/sample/plugins/nuvolaicons-0.2
Installed plugin nuvolaicons-0.2 to location /Users/aalmiray/.griffon/0.9.2/projects/sample/plugins/nuvolaicons-0.2. ...
Resolving plugin JAR dependencies ...
Plugin license for nuvolaicons-0.2 is 'GNU LGPL 2.1'
Executing nuvolaicons-0.2 plugin post-install script ...
Adding NuvolaiconsGriffonAddon to Builder.groovy
Plugin nuvolaicons-0.2 installed
Plugin provides the following new scripts:
------------------------------------------
griffon nuvola-icon-selector
Resolving plugin JAR dependencies ...
Plugin license for dialogs-0.1 is 'Apache Software License 2.0'
Executing dialogs-0.1 plugin post-install script ...
Adding DialogsGriffonAddon to Builder.groovy
Plugin dialogs-0.1 installed

Now, edit the application by adding a few conditions that will make it fail. Run the application and trigger those failing conditions. You should see the ErrorDialog appear as soon as an exception reaches GriffonExceptionHandler. That concludes today's Griffon howto.

Keep on Groovying!

Posted by: Andres Almiray on March 24, 2011

About Andres Almiray

Why Attend the NFJS Tour?

Current Topics: