12.1 Creating and Installing Plug-ins

#### Creating Plug-ins

Creating a Griffon plugin is a simple matter of running the command:

    griffon create-plugin [PLUGIN NAME]

This will create a plugin project for the name you specify. Say for example you run `griffon create-plugin example`. This would create a new plugin project called `example`.

The structure of a Griffon plugin is exactly the same as a regular Griffon project's directory structure, except that in the root of the plugin directory you will find a plugin Groovy file called the "plugin descriptor".

The plugin descriptor itself ends with the convention `GriffonPlugin` and is found in the root of the plugin project. For example:

    class ExampleGriffonPlugin {
       def version = 0.1   …
    }

All plugins must have this class in the root of their directory structure to be valid. The plugin class defines the version of 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 plugin
- `version` - the version of your plugin. Valid versions are for example "0.1", "0.2-SNAPSHOT", "0.1.4" etc.
- `griffonVersion` - The version of version range of Griffon that the plugin supports. eg. "1.1 > *"
- `license` - the plugin's license name in one sentence
- `pluginIncludes` - additional resources that should be included in the plugin zip
- `toolkits` - a list of supported toolkits [swing, javafx, swt, pivot, gtk]
- `platforms` - a list of supported platforms [linux, linux64, windows, windows64, macosx, macosx64, solaris, solaris64]
- `authosr` - a list of plugin author names/emails
- `description` - full multi-line description of plugin's features
- `documentation` - URL where plugin's documentation can be found
- `source` - URL where plugin's source can be found

Here is an example from Swing plugin :

    class SwingGriffonPlugin {
        String version = '0.9.5'
        String griffonVersion = '0.9.5 > *'
        Map dependsOn = [:]
        List pluginIncludes = []
        String license = 'Apache Software License 2.0'
        List toolkits = ['swing']
        List platforms = []
        String documentation = ''
        String source = 'https://github.com/griffon/griffon-swing-plugin'    List authors = [
            [
                name: 'Andres Almiray',
                email: 'aalmiray@yahoo.com'
            ]
        ]
        String title = 'Enables Swing support'
        String description = '''
    Enables the usage of Swing based components in Views.Usage
    ----
    This plugin enables the usage of the following nodes inside a View....Configuration
    -------------
    There's no special configuration for this plugin.[1]: http://groovy.codehaus.org/Swing+Builder
    '''
    }

#### Installing & Distributing Plugins

To distribute a plugin you need to navigate to its root directory in a terminal window and then type:

    griffon package-plugin

This will create a zip file of the plugin starting with `griffon-` then the plugin name and version. For example with the example plugin created earlier this would be `griffon-example-0.1.zip`. The `package-plugin` command will also generate `plugin.json` file which contains machine-readable information about plugin's name, version, author, and so on.

Once you have a plugin distribution file you can navigate to a Griffon project and type:

    griffon install-plugin /path/to/plugin/griffon-example-0.1.zip

If the plugin is hosted on a remote HTTP server you can also do:

    griffon install-plugin http://myserver.com/plugins/griffon-example-0.1.zip

#### Releasing Plugins into a Griffon Artifact Repository

To release a plugin call the `release-plugin` command while inside the plugin project. If no `repository` flag is specified then the default artifact repository (`griffon-central`) will be used. For quick testing purposes you can publish a release to `griffon-local` (which is always available) by issuing the following command

    griffon install-plugin --repository=griffon-local

The aforementioned steps can be applied to archetypes too, you just need to change the command names from `package-plugin` to `package-archetype`; from `install-plugin` to `install-archetype`; from `release-plugin` to `release-archetype`.

Should you decide to become a plugin/archetype author and wish to publish your artifacts to the Griffon Central repository then you must follow these steps:

- Create an account at http://artifacts.griffon-framework.org
- After confirming your email, log into your profile and click the button for membership request.
- Ping us at the developer mailing list or at @theaviary
- Once approved configure your credentials in `$USER_HOME/.griffon/settings.groovy` like this

    griffon.artifact.repositories = [
        'griffon-central': [
            username: 'yourUsername',
            password: 'yourPassword'
        ]
    ]