GroIMP wiki

First download the default empty template from the repository.

Once downloaded, you should have a directory called newplugin-maven, which contains a src folder, a pom.xml file, and some additional files for deployment (which we will not modify here). You can, and should, rename the directory with the name you want for your plugin. For the rest of this tutorial, the directory is called newplugin.

We can start editing it using a text editor/ or IDE (e.g. Eclipse) of your choice.

A plugin requires to: have a maven (pom) file working, and a groimp (plugin.xml) file working.

Let's start with the maven file:

• It needs a parent version in the following replace the x.x by the version of GroIMP you want to use. Here we can use 2.1.5,

 <parent>
    <artifactId>GroIMP</artifactId>
    <groupId>de.grogra</groupId>
    <version>x.x</version>
  </parent>

• The plugin needs a java name, this is the java identifier of the plugin. Here we can use template.tutorial.

<artifactId>template.tutorial</artifactId>

• Any additional dependencies to other java package (including GroIMP package) need to be declared,

</dependency>
    <dependency>
      <groupId>de.grogra</groupId>
      <artifactId>graph</artifactId>
      <version>x.x</version>
    </dependency>
 
    ...
 
  </dependencies>

Replace x.x by the version you want to use, 2.1.5 for instance.

Now, we need to change the GroIMP files, go in the directory src/main/resources and open plugin.xml:

• The plugin id should match the java id:

<plugin
  id="de.grogra.template.tutorial"
  ...

• The file name must match the directory name:

  <library file="newplugin" prefixes="{de.grogra.template.tutorial}"/>

• All imports must also be declared here:

  <import plugin="de.grogra.graph"/>
  ...

Now edit the plugin.properties file to update the plugin name, it needs to match the directory name:

pluginName = newplugin

Now we need to change the base java files: the module-info and the package name. First, open the src/main/java/module.info file and update the plugin name:

module template.tutorial {
	exports de.grogra.template.tutorial;
 
	requires graph;
}

• The module name needs to be the same as the <artifactId>template.tutorial</artifactId> from the pom.xml file.
• The exports de.grogra.template.tutorial; must match the java package name, i.e. the name of the sub folders from here.
• All dependencies must be declared here with requires ….

Then, the name of the package should be updated, we just called it de.grogra.template.tutorial, so open the sub folders de, then grogra, then template. You can rename the folder (or create a new one) to tutorial, and create (or copy) a java file in, Hello.java for instance. Your src directory should then, have one java file at the path: src/main/java/de/grogra/template/tutorial/Hello.java.

Open Hello.java and fill the following:

package de.grogra.template.tutorial;
 
public class Hello {
}

Now, the plugin should be entirely functional. To try it needs to be compiled. At the root of the plugin (where the pom.xml file is) run the command line: mvn compile. It should download a lot of dependencies and after some time properly compile.

The current plugin compile and can be “used” by GroIMP, but it doesn't do anything. So Let's add some features.

In the following, the directory src/main/resources will be referred as the resource directory and src/main/java/de/grogra/template/tutorial as the java directory.

This will enables GroIMP to read a new type of file (or an existing one but differently). See here for the complete explanation of how to set up a new file filter and mimetype. In this tutorial we will only do the basic steps.

In the resource directory, open the plugin.xml file and add to the registry:

<registry>
   <ref name="io">
      <ref name="filetypes">
         <ext name="example" extensions="{.example}" mimeType="text/example"/>
      </ref>
      <ref name="mimetype">
         <mimetype name="text/example">
            <filter input="freader" create="de.grogra.template.tutorial.ExampleFilter$LoadAsNode"/>
         </mimetype>
      </ref>
   </ref>
</registry>

This enables GroIMP to know on startup that a new file filter exists for files with the extension: .example. When it will try to open one, it will use the class ExampleFilter$LoadAsNode (which do not exists yet).

In the java directory create a file called ExampleFilter.java and add its content:

package de.grogra.template.tutorial;
 
import java.io.IOException;
 
import de.grogra.pf.io.FilterBase;
import de.grogra.pf.io.FilterItem;
import de.grogra.pf.io.FilterSource;
import de.grogra.pf.io.IOFlavor;
import de.grogra.pf.io.ObjectSource;
 
public class ExampleFilter {
 
	public static class LoadAsNode extends FilterBase implements ObjectSource  {
		public LoadAsNode(FilterItem item, FilterSource source) {
			super(item, source);
			setFlavor (IOFlavor.NODE);
		}
 
		@Override
		public Object getObject() throws IOException {
			// TODO Auto-generated method stub
			return null;
		}
	}
}

The project only misses the import of dependencies we used: Platform and Platform-Core. Let's add them in:

• The module.info file:

        requires platform;
	requires platform.core;

• The plugin.xml file in the resource directory, (to add before the <registry> tag):

  <import plugin="de.grogra.pf"/>

• In the pom.xml file int the root directory of the plugin:

    <dependency>
      <groupId>de.grogra</groupId>
      <artifactId>platform</artifactId>
      <version>2.1.5</version>
    </dependency>
 
    <dependency>
      <groupId>de.grogra</groupId>
      <artifactId>platform.core</artifactId>
      <version>2.1.5</version>
    </dependency>

The plugin can now be compiled AND be used in GroIMP. We can see it by creating a compiled version of it with the command : mvn package (run at the root directory of the plugin).

This command create a new directory in the parent directory of the plugin called app (relative path: ../app/). In the app directory there is a directory called plugins, in which there is a directory called newplugin. This is the compiled plugin. You can copy this directory in your GroIMP plugin directory (or in /home/.grogra.de-platform/plugins) and start GroIMP.