Creating an own plugin

How to create a Plugin

The GroIMP software can be extended by plugins. This page describes how to write a plugin named MyPlugin.

Firstly, a plugin has to have a special directory layout. This is described in the INSTALL file in the Build-project of GroIMP and is as follows:

• MyPlugin
  • build.xml
  • src
    • plugin.xml
    • plugin.properties
    • <java source="" files=""></java>
    • <additional non-java="" files=""></additional>
  • build
    • plugin.xml
    • plugin.properties
    • <compiled class="" files=""></compiled>
    • <additional files="" copied="" from="" the="" src-directory=""></additional>
  • lib
    • <needed jar-files=""></needed>

During Development, the MyPlugin directory has to be located in the same directory as the needed GroIMP plugins and projects (e.g., Build, XL-Core, IMP-3D, ...).

You have to set up your development environment to compile and copy files from the src directory to the build directory. The Ant-based mechanism using build.xml together with the Build-project of GroIMP is configured to do so, but you probably may want to use an IDE like Eclipse to develop your plugin. This IDE has then to be configured correctly. If you are using Eclipse you has to rename the default output folder from "bin" to "build". Because GroIMP will search for plugins in the compiled code and this is expected at a build folder.

Afterwards, you should create the build.xml file which is used by the Ant tool. Even if you use an IDE for development, a release of a plugin should be made using Ant. Assuming that MyPlugin needs two jar-libraries mylib.jar and yourlib.jar (which are located in the lib-directory as shown in the table above) and references the plugins IMP-2D and IMP-3D of GroIMP, build.xml looks as follows:

<project name="MyProject" default="compile">
    <description>
        Ant build file for the MyPlugin plugin for GroIMP
    </description>

    <import file="../Build/buildproject.xml"/>

    <target name="-libs">
        <antcall target="-addlib">
            <param name="lib" value="lib/mylib.jar"/>
        </antcall>
        <antcall target="-addlib">
            <param name="lib" value="lib/yourlib.jar"/>
        </antcall>
    </target>

    <target name="-projects">
        <antcall target="-addproject">
            <param name="proj" value="IMP-2D"/>
        </antcall>
        <antcall target="-addproject">
            <param name="proj" value="IMP-3D"/>
        </antcall>
    </target>

    <target name="src">
        <antcall target="-src-enhance"/>
    </target>
</project></pre>

The line <antcall target="-src-enhance"></antcall> is only needed if you want to define your own node classes in the plugin, see [Creating an own node class]. Then you have to create the plugin.xml file which is read by GroIMP to obtain required information about the plugin.

<?xml version = "1.0" encoding="UTF-8"?>
<plugin
    id="bar.foo.myplugin"
    version="0.0.1"
    xmlns="http://grogra.de/registry">

    <import plugin="de.grogra.imp2d"/>
    <import plugin="de.grogra.imp3d"/>

    <library file="mylib.jar" prefixes="{bar.lib.my,foo.lib.my}"/>
    <library file="yourlib.jar" prefixes="{bar.lib.your}"/>
    <library file="MyPlugin.jar" prefixes="{bar.foo.myplugin}"/>

    <registry>
    </registry>
</plugin>

The id of MyPlugin can be chosen freely, however, it is recommended to base the id on the Java naming convention for packages. Afterwards, the plugins to import have to be specified. Note that now you have to use the id, while the build.xml-file requires the name of the directory which contains the plugin (which typically differs from the id). After the imports, specify the jar-libraries to use. The registration of the libraries has to be in an order such that earlier libraries do not depend on later ones. The last library has to be a jar-file with the same name as the project, so here it is MyPlugin.jar. The library prefixes are comma-separated lists in braces, each item is the prefix of packages which are present in the jar-file. This is used as a hint for class loaders.

Within the registry-element, the actual content of the plugin is registered.