How to use and make own Plugins

From OpenJUMP Wiki
Revision as of 23:00, 18 October 2009 by Mentaer (talk | contribs) (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…')
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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 Eclipse or 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.

  • 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:
      1. the method _initialize()_ is necessary to register and to create a menu item (for the example it is done in the _View_ menu)
      2. the method _execute()_ contains the code which should be evaluated if the menu entry/button is activated. (see below)
<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>


  • 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_

h3. Version 1

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

  1. 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)

  1. export the compiled directory/files to a jar file (it is like

zipping the project and renaming the ending to jar)

  1. 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: 

<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>

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_
  1. 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 )
  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 jump

is com.vividsolutions.jump.workbench.JUMPWorkbench

  1. add to the "Arguments" of the run entry:

-properties _C:\myRealProjectPath\workbench-properties.xml_ -plug-in-directory _C:\Programme\Jumpi18n\lib\ext_

  1. 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)

  1. 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)

Retrieved from "http://ojwiki.soldin.de/index.php?title=How_to_use_and_make_own_Plugins&oldid=317"