Adding Plugins to the MBAT source code

These instructions are for adding and creating a new plugin in the MBAT source code. General instructions and Eclipse specific directions are given below.

If you follow the source code plugin file structure, you can run the included ant builds to automatically build and copy your plugin .zip to the correct folder. The following examples assume a new plugin MyPlugin is being added to the mbRegistrationPlugins project.

1. Create file structure for plugin:
   1. Create a plugin folder in the project (mbRegistrationPlugins/plugins/net.nbirn.mbat.plugins.registration.MyPlugin). For Eclipse, in the "Navigator" view, choose "File->New->Folder".
   2. Create a source folder "src" in the plugin folder (mbRegistrationPlugins/plugins/net.nbirn.mbat.plugins.registration.MyPlugin/src. For Eclipse, in the "Navigator" view, choose "File->New->Folder".
   3. Create and place the plugin manifest file plugin.xml in the source folder (mbRegistrationPlugins/plugins/net.nbirn.mbat.plugins.registration.MyPlugin/src/plugin.xml)
   4. For Eclipse, add the source folder to the project: Right click on the project (mbRegistrationPlugins). Choose "New"->"Src Folder". Select the folder name by clicking "Browse" and navigate to the above source folder.
   5. For Eclipse, set the output folder for the plugin. Right-click the newly added source folder and select "Build Path->Configure Build Path". In the "Source" tab, enable "Allow output folders for source folders" by clicking the checkbox. "Output folder" will then appear under the source folders. Double click the "Output folder" item and choose "Specific output folder". Browse for the root source folder and create a classes folder ( mbRegistrationPlugins/plugins/net.nbirn.mbat.plugins.registration.MyPlugin/classes).
2. Add the source directory to the mbRegistrationPlugins/build.xml to automatically create the .zip archive and copy it to the plugin directory:

   <target name="all"> <zip-plugin directory="net.nbirn.mbat.plugins.registration.Core" libname="core" /> <zip-plugin directory="net.nbirn.mbat.plugins.registration.Landmark" libname="landmark" /> <zip-plugin directory="net.nbirn.mbat.plugins.registration.MyPlugin" libname="myplugin" /> </target>

3. Run the ant build:
   1. For Eclipse, in the "Package Explorer" view, right-click on the build.xml file under the !mbRegistrationPlugins project
   2. Select "Run As.." --> "Ant Build"

Adding Plugins Credit

If you would like to show the plugin info on the About dialog, you can edit the plugin.xml like the following:

Example:
<extension plugin-id="net.nbirn.mbat.plugins.viewer.core" point-id="Viewer" id="JLayerImage2D"> ... <parameter id="displayName" value="2D image(s)"/> <parameter id="pluginDesc" value="A viewer plugin displaying 2D image."/> <parameter id="contact" value="mbat_support@loni.ucla.edu"/> <parameter id="author" value="Daren Lee"/> <parameter id="provider" value="LONI UCLA" /> <parameter id="version" value="1.0.11"/> <parameter id="acknowledgement" value="NIH-NCRR P41 RR013642" /> </extension>

Parameters:

Adding JAR libraries to plugins

If your plugin depends on external JAR libraries, there are 2 steps to follow:

1. JPF allows you to specify the JAR libraries in the plugin.xml manifest (see the JPF home page http://jpf.sourceforge.net for more details). An example to add 3 libraries (RegularDiscreteDataTools.jar, ShapeTool.jar, and LandmarkWarpLibrary.jar) to a plugin is given below:

   <runtime> <library id="landmark" path="./" type="code"> <export prefix="*" /> </library> <library id="discrete-data" path="lib/RegularDiscreteDataTools.jar" type="code" /> <library id="shape-tools" path="lib/ShapeTools.jar" type="code" /> <library id="landmark-warp" path="lib/LandmarkWarpLibrary.jar" type="code" /> </runtime>

   Note that the path variable is relative to the location of the plugin.xml. If you are using the soure code file structure mentioned above, you need to create a lib folder under the src folder (ie: net.nbirn.mbat.plugins.registration.Landmark/src/lib. This lib directory will then be included in the archive which is built using the build.xml in the previous section.

2. To get your plugin to compile in Eclipse, you will need to setup an Eclipse classpath variable if it doesn't exist already (see Setup Classpath Variable). By convention, we use the root folder of the plugins for the name the classpath variable (ie: MBREGISTRATION_PLUGINS_SRC_HOME). After the classpath variable is setup, you then have to add the JAR libraries to the project's build path: Right-click project->"Build Path"->"Configure Build Path"->"Libraries"->"Add Variable"->Select the appropriate class path variable->"Extend"->Select JAR file by navigating through the file browser->Click "OK".

Adding JavaHelp resources to plugins

The MBAT framework uses JavaHelp to manage and display the help information. Each plugin can define its own help pages that are merged into a single help document.

1. Create the JavaHelp files as a JAR file. If you are using Eclipse, custom macros have been built to automatically create the JAR files and copy them into the proper directories (instructions below). If you do not wish to use these macros, you must include the JAR file as a resource in the plugin (skip to Step 2).
   1. Create a folder for the help documents under 'src'. All HelpSet files (Help.hs, HelpTOC.xml, Map.jhm, HTML pages) will be stored in this folder (mbRegistrationPlugins/plugins/net.nbirn.mbat.plugins.registration.MyPlugin/src/help). For Eclipse, in the Navigator view, choose File > New > Folder.
   2. Edit the build.xml to automatically create the JAR file using the jar-javahelp macro. The build.xml for plugins is usually at the root level of the project. For example, for registration plugins, the build.xml is found in mbRegistrationPlugins.

      <target name="all"> <jar-javahelp directory="net.nbirn.mbat.plugins.registration.Landmark" jar-resource-path="resources/LandmarkRegistrationHelp.jar" help-directory="src/help" /> </target>

2. Edit the MyPluginTOC.xml and Map.jhm file to follow the master HelpSet topic and target structure. This is required in order for the help topics to be placed under the proper section in the top-level help document. The topic structure for all parents of our target sub-topic must be exactly the same. In the following example, we add our plugin sub-topic "MyPlugin" to the "Registration Workspace" sub-topic under the top-level topic of "MouseBirn Atlasing Toolkit (MBAT)". The "Registration Workspace" topic and target must match the one defined in the HelpTOC.xml in the Registration Workspace plugin (net.nbirn.mbat.plugins.workspace.Registration). The top-level "MouseBirn Atlasing Toolkit (MBAT)" topic and target must match the one defined in the master HelpTOC.xml under the mbat project. By convention, we use the values target="overview" and url="index.html". Note, the actual HTML page for the url doesn't have to exist; it just has to match the values of the parent/master.

   TOC.xml:

   <tocitem text="MouseBirn Atlasing Toolkit (MBAT)" target="overview"> <tocitem text="Registration Workspace" target="overview"> <tocitem text="MyPlugin" target="overview" expand="true"> </tocitem> </tocitem> </tocitem>

   Map.jhm:

   <map version="2.0"> <mapID target="overview" url="index.html" /> ... </map>

3. Create a resource folder for the JavaHelp JAR file (mbRegistrationPlugins/plugins/net.nbirn.mbat.plugins.registration.MyPlugin/src/resources). For Eclipse, in the Navigator view, choose File > New > Folder.

4. Edit plugin.xml to export the resources (this will make the JAR resource visible at run-time). <runtime> <library id="landmark-help" path="resources/LandmarkRegistrationHelp.jar" type="resources" > <export prefix="*" /> </library> ... </runtime>

5. Edit plugin.xml to add extension parameters specifying the location (help-url) and main HelpSet configuration file (helpset).

   <extension plugin-id="net.nbirn.mbat.plugins.registration.core" point-id="Registration" id="MyPlugin"> <parameter id="help-url" value="resources/{Helpfile}.jar" /> <parameter id="helpset" value="{HelpFile}.hs" /> ... </extensions>

6. (Eclipse only) Exclude help files from source files so Eclipse will not copy help folder to classes folder. This will avoid having duplicate copies of the help resources since the files are already stored as a jar file.
   1. Edit the build path options (Right-click Project > Build Path > Configure Build Path).
   2. Go to the Source tab. Go the source configuration for your plugin.
   3. Select the Excluded option by left-clicking it. Click on the Edit button in the right panel. Add the help folder for the plugin. Click Finish.