How to use and make own Plugins - Revision history

Mentaer at 10:17, 3 January 2012

2012-01-03T10:17:03Z

Mentaer at 21:22, 18 October 2009

2009-10-18T21:22:27Z

Mentaer: Created page with '== Introduction == The first part of this page will describe how one can make its own plugins for JUMP/OpenJUMP. In part B we will outline how the plugins are used. Either inter…'

2009-10-18T21:00:55Z

Created page with '== Introduction == The first part of this page will describe how one can make its own plugins for JUMP/OpenJUMP. In part B we will outline how the plugins are used. Either inter…'

New page

== Introduction ==

The first part of this page will describe how one can make its own plugins for JUMP/OpenJUMP. In part B we will outline how the plugins are used. Either internally from Eclipse using the workbench-properties.xml file or externally as jar for distributing.

== How to make your own plugin ==

'''First of all''': To make coding easier you should use a Integrated Developement Environment (IDE) like [http://www.eclipse.org Eclipse] or [http://www.netbeans.org NetBeans] (of course you can also use commercial IDEs). Such an IDE shows you errors in your code already during programming and has nice properties like proposing you ''commands'' or paths.

*Now* have a look here: [[FAQ OpenJump and Eclipse]]

*Note*: If you use Eclipse for the first time, then have a look on this very good tutorial on how to use the Eclipse IDE: "Eclipse Tutorial":http://eclipsetutorial.sourceforge.net/

*Finally* lets start.. :)

_If you have installed Eclipse see also [[How to make your plugin in ECLIPSE]]_

* create a new Java project (eg. call it "Helloi18n")
* go to the project properties, and look where you can set the Java \BuildPath. Look for an option called like "add JAR". Now use this to add the JUMP kernel file jumpxxx.jar which should be located in your Jump (\OpenJump) folder. (nota bene: xxx is used a placeholder for different names)
Further add also all the jar files which are in the JUMPxxx/lib/ folder.
* now you can start coding - preferably make a "hello world" plugin like it is described in the jump developer manual. (see also code below of \HelloWorldPlugIn.java)

** basically you have to know that a plugin has to have
the class ending "\PlugIn" and inherits methods using "extends \AbstractPlugIn"
** further it has always 2 methods which are called by Jump to interact:
**# the method _initialize()_ is necessary to register and to create a menu item (for the example it is done in the _View_ menu)
**# the method _execute()_ contains the code which should be evaluated if the menu entry/button is activated. (see below)

<pre>
<code>
/*
* created on 04.10.2005
* last modified: 05.10.2005 comments added
*
* author: sstein
*
**/

package ch.unizh.geo.degen;

import com.vividsolutions.jump.workbench.WorkbenchContext;
import com.vividsolutions.jump.workbench.plugin.AbstractPlugIn;
import com.vividsolutions.jump.workbench.plugin.EnableCheckFactory;
import com.vividsolutions.jump.workbench.plugin.MultiEnableCheck;
import com.vividsolutions.jump.workbench.plugin.PlugInContext;
import com.vividsolutions.jump.workbench.ui.plugin.FeatureInstaller;

/**
* @description:
* testplugin for jump<p>
* shows hello world - window in Jump
*
* @author sstein
*
*/
public class HelloWorldPlugIn extends AbstractPlugIn{

public HelloWorldPlugIn() {
// empty constructor
}

public void initialize(PlugInContext context) throws Exception {
FeatureInstaller featureInstaller = new FeatureInstaller(context.getWorkbenchContext());
featureInstaller.addMainMenuItem(
this, //exe
new String[] {"View"}, //menu path
this.getName(), //name methode .getName recieved by AbstractPlugIn
false, //checkbox
null, //icon
createEnableCheck(context.getWorkbenchContext())); //enable check
}

public static MultiEnableCheck createEnableCheck(WorkbenchContext workbenchContext) {
EnableCheckFactory checkFactory = new EnableCheckFactory(workbenchContext);

return new MultiEnableCheck()
.add(checkFactory.createWindowWithLayerNamePanelMustBeActiveCheck());
}

/**
* Action on menu item selection:
* creates doc to show
*/
public boolean execute(PlugInContext context) throws Exception{

context.getWorkbenchFrame().getOutputFrame().createNewDocument();
context.getWorkbenchFrame().getOutputFrame().addText("Hello, World!");
context.getWorkbenchFrame().getOutputFrame().surface();

return true;
}

}
</code>
</pre>

*Example*
=> For Eclipse i have done an example Project, which needs \OpenJump or Jumpi18n core("donwload here":http://www.geo.unizh.ch/publications/sstein/openjump/eclipsehelloi18.zip ). To use that in Eclipse:
** download it and unpack. Put it into your Eclipse workspace folder
** use the following menu entry to load "\File\Import\". Select "Existing Project into Workspace"
** After importing don't forget to set the java build path entries in the project properties.

Another example, that shows how to create buffers from features in a layer has been posted here: [[Example Plugin For Buffering Features in a Layer]]

h2. B) How to use own plugins

To load a plugin in Jump we have two options:
* either we create a library for the _Jump\lib\ext\ Folder_
* or we load our plugin by using a _workbench-properties.xml_ file

_If you have installed Eclipse see also_
* [[How to create a jar plugin in ECLIPSE]] and
* [[How to use a plugin with a properties file in ECLIPSE]]

h3. Version 1

This option is a bad choice for finding errors, but necessary to deploy our work.

# to load an external plugin on Jump start we have to create a class
\HelloWorldExtension.java (see also the downloadable example). The Extension class is necessary to register the plugin in Jump. Note: The class name must end with Extension, (see below)
# export the compiled directory/files to a jar file (it is like
zipping the project and renaming the ending to jar)
# then put the jar file in Jumpi18n/lib/ext and start jump as usual ("example myhelloi18nplugin.jar":http://www.geo.unizh.ch/publications/sstein/openjump/myhelloi18nplugin.jar )

How does such an Extension class look like:
<pre>
<code>
/*
* created on 04.10.2005
* last modified:
*
* author: sstein
*
*************************************************/
package ch.unizh.geo.degen;

import com.vividsolutions.jump.workbench.plugin.Extension;
import com.vividsolutions.jump.workbench.plugin.PlugInContext;

/**
* @description
* - this class loads the PlugIn into Jump <p>
* - class has to be called "Extension" on the end of classname
* to use the PlugIn in Jump
*
* @author sstein
*/
public class HelloWorldExtension extends Extension{

/**
* calls PlugIn using class method xplugin.initialize()
*/
public void configure(PlugInContext context) throws Exception{
new HelloWorldPlugIn().initialize(context);
}

}
</code>
</pre>

h3. Version 2

This option is a good choice for debugging errors but not for deployment.

*note:* for this version is might be good to have the original openjump sources in a project (since one can better trace errors and has good examples on programming). The Jump sources can be obtained from the Jump or \OpenJUMP %{color:black}SVN% or as zip files. If you create your own Openjump project, don't forget to include the libraries into your project (using the "Buildpath" properties). Further you have to create a dependency of the _Helloi18_ project on the new Jump (\OpenJump) project, which can be also done in the project properties of _Helloi18_

# create in your project a new file and call it workbench-properties.xml ("example workbench file":http://www.geo.unizh.ch/publications/sstein/openjump/workbench-properties.xml )
# write the package path to your plugin inside the file (see file)
# create a new _run entry_: the class which is the entry point for jump
is com.vividsolutions.jump.workbench.JUMPWorkbench
# add to the "Arguments" of the run entry:
-properties _C:\myRealProjectPath\workbench-properties.xml_
-plug-in-directory _C:\Programme\Jumpi18n\lib\ext_
# add to your "run entry" the "classpaths" for the jar files in
jump/lib/ (as Bootstrap Entries) and the project you just created (as
User Entries)
# start the _run_ entry

h2. Notes

the examples above use the parent class \AbstractPlugIn which has disadvatanges for long computations. For such a case use "implements \ThreadedPlugIn". Here also a _monitor_ can be used to send messages to the user. Apart from that a second method _run()_ has to be implemented which contains the now the time consuming code while _execute()_ should contain dialogs for initial interatcion. (I will make this clearer in future - hopefully)

Please don't forget to document your plugin. I've done a template that can be downloaded here: http://sourceforge.net/project/showfiles.php?group_id=118054&package_id=209987

have fun,
Stefan (sstein)

@@ Line 93: / Line 93: @@
 '''Example'''
-For Eclipse i have done an example Project, which needs OpenJump or Jumpi18n core (http://www.geo.unizh.ch/publications/sstein/openjump/eclipsehelloi18.zip donwload here). To use that in Eclipse:
+For Eclipse i have done an example Project, which needs OpenJump ([http://sourceforge.net/projects/mentaer.u/files/openjump/development_resources/eclipsehelloi18.zip/download donwload here]). To use that in Eclipse:
 * download it and unpack. Put it into your Eclipse workspace folder
 * use the following menu entry to load "\File\Import\". Select "Existing Project into Workspace"
@@ Line 118: / Line 118: @@
 # export the compiled directory/files to a jar file (it is like
 zipping the project and renaming the ending to jar)
-# then put the jar file in Jumpi18n/lib/ext and start jump as usual ([http://www.geo.unizh.ch/publications/sstein/openjump/myhelloi18nplugin.jar example myhelloi18nplugin.jar])
+# then put the jar file in Jumpi18n/lib/ext and start jump as usual ([http://sourceforge.net/projects/mentaer.u/files/openjump/development_resources/myhelloi18nplugin.jar/download example myhelloi18nplugin.jar])
 How does such an Extension class look like:
@@ Line 160: / Line 160: @@
 '''note''': for this version is might be good to have the original openjump sources in a project (since one can better trace errors and has good examples on programming). The Jump sources can be obtained from the Jump or OpenJUMP SVN or as zip files. If you create your own Openjump project, don't forget to include the libraries into your project (using the "Buildpath" properties). Further you have to create a dependency of the ''Helloi18'' project on the new Jump (OpenJump) project, which can be also done in the project properties of ''Helloi18''
-* 1 - create in your project a new file and call it workbench-properties.xml ([http://www.geo.unizh.ch/publications/sstein/openjump/workbench-properties.xml example workbench file])
+* 1 - create in your project a new file and call it workbench-properties.xml ([http://sourceforge.net/projects/mentaer.u/files/openjump/development_resources/workbench-properties.xml/download example workbench file])
 * 2 - write the package path to your plugin inside the file (see file)
 * 3 - create a new ''run entry'': the class which is the entry point for OpenJUMP
@@ Line 176: / Line 176: @@
 the examples above use the parent class AbstractPlugIn which has disadvatanges for long computations. For such a case use "implements ThreadedPlugIn". Here also a _monitor_ can be used to send messages to the user. Apart from that a second method ''run()'' has to be implemented which contains the now the time consuming code while ''execute()'' should contain dialogs for initial interatcion. (I will make this clearer in future - hopefully)
-Please don't forget to document your plugin. I've done a template that can be downloaded: [http://sourceforge.net/projects/jump-pilot/files/Documentation/PlugIn%20description%20example_template/Openjump_exampleplugin_description_template.doc/download here]
+Please don't forget to document your plugin. I've done a template that can be downloaded: [http://sourceforge.net/projects/jump-pilot/files/Documentation/PlugIn%20Documentation/Openjump_exampleplugin_description_template.doc/download here]
 have fun,
 Stefan (sstein)