(Quick Reference)

14.6 Addons - Reference Documentation

Authors: Andres Almiray

Version: 1.2.0

14.6 Addons

Understanding Addons

Addons are a plugin's best friend. While plugins can only contribute build-time artifacts (such as scripts) and participate on build events, addons may contribute runtime artifacts (such as MVC Groups or services) and participate on application events.

Often times whenever you'd like to package a reusable runtime artifact you'd have to create an Addon as well.

Addon responsibilities

Addons may contribute any of the following to your application: MVC Groups and application event handlers. They can also contribute the following to the CompositeBuilder: factories, methods, properties and FactoryBuilderSupport delegates (attribute, preInstantiate, postInstantiate, postNodeCompletion).

Addons are created using a template that suggests all of the properties and methods you can use configure. The complete list follows:

  • addonInit - called right after the addon has been loaded but before contributions are taken into account
  • addonPostInit - called after all contributions haven been made
  • addonBuilderInit - called before contributions to the CompositeBuilder are taken into account
  • addonBuilderPostInit - called after all CompositeBuilder contributions haven been made
  • events - Map of additional application event handlers
  • factories - Map of additional node factories, added to CompositeBuilder
  • methods - Map of additional methods, added to CompositeBuilder
  • props - Map of additional methods, added to CompositeBuilder
  • attributeDelegates - List of attributeDelegates (as Closures), added to CompositeBuilder
  • preInstantiateDelegates - List of preInstantiateDelegates (as Closures), added to CompositeBuilder
  • postInstantiateDelegates - List of postInstantiateDelegates (as Closures), added to CompositeBuilder
  • postNodeCompletionDelegates - List of postNodeCompletionDelegates (as Closures), added to CompositeBuilder

You may also contribute MVC groups inside an addon (by calling the create-mvc command line for example) however you must define first a dependency on any UI toolkit plugin from this list.

Configuring Addons

This task is done automatically for you when you package an addon inside a plugin. The plugin's _Install and _Uninstall scripts will make sure that griffon-app/conf/Builder.groovy stays up to date. When you install a plugin that contains an addon you'll notice that Builder.groovy may get updated with a line similar to the next one

root.'CustomGriffonAddon'.addon=true

This means that all factories, methods and props defined on the Addon will be available to View scripts. However you need to explicitly specify which contributions should be made to other MVC members. You can list them one by one, or use a special group qualified by '*'. In recent releases of Griffon the default configuration is assumed meaning you won't see any changes in the Builder.groovy file. You can still apply modifications as explained below.

The following snippet shows how to configure an Addon to contribute all of its methods to Controllers, and all of its contributions to Models.

root.'CustomGriffonAddon'.controller='*:methods'
root.'CustomGriffonAddon'.model='*'

The special groups are: '*', '*:factories', '*:methods', '*:props'

Should you encounter a problem with duplicate node names you can change the default prefix (root) of the addon to something more suitable to your needs. All nodes contributed by the addon will now be accessible using that prefix. Here's an example

nx.'CustomGriffonAddon'.addon=true

Assuming CustomGriffonAddon is defined as follows

class CustomGriffonAddon {
    def factories = [
        button: com.acme.CustomButton
    ]
}

Then instances of CustomButtom can be obtained by using nxbutton, whereas regular instances of JButton will be accessible with button.