Changes between Version 38 and Version 39 of DevelopersGuide/DevelopingPlugins

Timestamp:

2010-01-12T19:31:16+01:00 (16 years ago)

Author:

Gubaer

Comment:

updated

DevelopersGuide/DevelopingPlugins

@@ -18 +18 @@
  * If you need other OSM resources you can check out the complete osm - trunk: {{{svn co http://svn.openstreetmap.org/}}}
 
-== The ''Plugin'' class ==
-After setting everything up, you need to create the plugin main class specified in the jar's manifest. The only prerequisite of this class is, that it must have a standard constructor taking no arguments. The constructor of the plugin class will be called during the JOSM startup if the plugin is registered. Here, you have full access to the object tree within JOSM.
+== JOSM plugins ==
 
-It is recommended (but not required), that you subclass org.openstreetmap.josm.plugins.Plugin. This way you get some helper functions and always have the latest callback function signatures (see below) as hints in your baseclass to override them ;)
+=== A POJO as entry point ===
 
-The required minimum in naming is one individual part in the path structure of you plugin class names. The path of the base class is used to detect the source of exceptions. So when you base class is my.example.class.MyPlugin, then "my.example.class" is used to detect your plugin code. All important parts of your plugin should use that and also it should be unique for the plugin (i.e. add at least one part with the name of your plugin).
+The entry point for a JOSM plugin, the '''plugin main class''' is a Plain Old Java Object (POJO) which provides a constructor with one parameter of type [source:/trunk/src/org/openstreetmap/josm/plugin/PluginInformation.java PluginInformation]. 
+{{{
+#!java
+  public class MyPlugin {
+     /**
+      * Will be invoked by JOSM to bootstrap the plugin
+      *
+      * @param info  information about the plugin and its local installation    
+      */
+      public MyPlugin(PluginInformation info) {
+      }
 
-== Callbacks ==
+      /* ... */
+  }
+}}}
+
+You don't have to derive the plugin main class from a common superclass but currently you are '''recommended''' to derive it from [source:/trunk/src/org/openstreetmap/josm/plugin/Plugin.java org.openstreetmap.josm.plugin.Plugin]. 
+
+{{{
+#!java
+  import org.openstreetmap.josm.plugin.Plugin;
+  import org.openstreetmap.josm.plugin.PluginInformation;
+
+  public class MyPlugin extends Plugin {
+  
+     /**
+      * Will be invoked by JOSM to bootstrap the plugin
+      *
+      * @param info  information about the plugin and its local installation    
+      */
+      public MyPlugin(PluginInformation info) extends Plugin {
+         super(info);
+         // init your plugin 
+      }
+  }
+}}}
+
+For legacy reasons, JOSM currently also allows POJOs with a no-arg constructor as plugin main classes. This approach is '''deprecated''' and will be disabled in Q2/2010. New plugins should provide a constructor with one parameter of type [source:/trunk/src/org/openstreetmap/josm/plugin/PluginInformation.java PluginInformation]. 
+
+=== Naming the plugin ===
+Each plugin has a unique name to identify it. The name is a short identifier like {{{wmsplugin}}} or {{{validator}}}. 
+  * '''DONT''' use white space characters in the name. Call the plugin {{{BuildingUtility}}}, not {{{Jim's Building Utitlities}}}
+  * '''DONT''' use special characters in the plugin name, stick to alphanumeric characters. Call the plugin {{{routing4all}}} not {{{routing 4 all :-) !}}}. Note that the plugin name is used to '''create file and directory names''' on the computer where plugins are installed. If it included special characters like /, ., \, etc. these operations may fail. 
+
+You are recommended to use a Java package for the plugin main class and all other classes you need in the plugin, i.e. {{{org.foobar.josm.routing4all}}}. Stick to the well-established naming conventions used in the Java world (lower case package name, camel case class names, etc.).
+
+
+== Callbacks == #Callbacks
 Most of your plugin work will probably be tweaking the JOSM object tree at startup time, but there are a few callbacks that get automatically called on every plugin (whether you subclass Plugin or not, just the signature matters).