Buddi

Personal budget software for the rest of us

Developing Plugins in Buddi 3.0

Bundling Plugins

Once you are finished coding, you need to bundle the plugin. You can either use Apache Ant to compile and bundle the plugins (see the sample Hello World plugin, below). Alternatively, you can use the 'jar' command (included with the Java Development Kit), although it is a little more difficult.

Plugin Naming Convensions

It is highly recommended that when you distribute the plugin, you wrap it and whatever documentation you want to include (such as license, Readme, etc) in a .zip file. The zip file should be in the form "Plugin Name-Version.zip". The plugin itself should not contain the version number in the name, and the name should not change between releases. This will allow users to simply copy new versions of the plugin overtop of existing versions. The sample ant script will package the plugins according to this specification.

For example, version 1.2.3.4 of the Hello World plugin would be distributed in a zip file called "Hello World-1.2.3.4.zip". When extracted, it will contain the file "Hello World.buddi3plugin", along with whatever supporting files and documentation are needed.

Sample 'Hello World' Plugin (Including Ant Script)

I have created a simple Hello World sample plugin, which you can use as a guide for creating your own. It includes an ant script for compilation and bundling, and includes a sample plugin.properties file, some Languages files, etc. After you download and extract the Hello_World.zip sample plugin, you will need to copy Buddi.jar to the lib directory (as javac needs to be able to refer to the Buddi plugin definition classes). You can then use ant to build and package the plugin, by typing 'ant' when in the main plugin directory.

Bundling Plugins using Jar

If you choose not to use ant to compile the plugins, you can use the 'jar' command. For instance, if your class naming is of the form "org.example.buddi.plugin.MyPlugin", type:

jar -cvf MyPluginPackage.buddi3plugin org/

Note that the extension of the plugin must be buddi3plugin. If you use any other extension (including .jar), the plugin will not load.

Third Party Libraries

If you use any third party libraries in your plugin, you need to bundle them into the same 'Fat' Jar as the plugin itself. You can do this manually by unzipping all libraries, and jarring both them and your code into the same jar (this is what I do for the sample plugin). Alternatively, you can use the Eclipse Fat Jar Plugin to do this, which is a little simpler, but requires you to download yet another tool.

Translations

If you have used the translation framework in your plugin (which is highly recommended, even if you only include an English translation by default), you must put these translations in the Languages folder at the root of your jar file. Assuming the Languages folder is at the same level as the org folder in your file system, you can do this with the same command as above, but just adding a 'Languages/' argument after the 'org/' argument:

jar -cvf MyPluginPackage.buddi3plugin org/ Languages/

If you use the sample ant build script, this is already taken care of - all you have to do is to use the Translation framework and include .lang files in the etc/Languages folder.

Specifying Which Class is the Plugin Implementation

If you use lots or classes, or extra libraries in your plugin, you may want to give Buddi a hint of where the main plugin class(es) are located. To do this, you can create a file called 'plugin.properties', in the root of the jar. This file should contain the key 'PLUGIN_ROOT=org/example/buddi/plugins', where the path is the location of the plugin class file (if there is only one class implementing a Buddi plugin in the bundle), or a parent directory (if there are multiple classes implementing a Buddi plugin, such as an Import plugin and a Preference plugin). When Buddi looks for plugin classes, it tries to instantiate all classes in the Jar file; by specifying a subdirectory of the Jar to look in, you can drastically reduce the time needed when loading the plugin.

Specifying Plugin Version

You can include the key VERSION=X.Y.F.B in the plugin.properties file, to specify the plugin version. Buddi will use this property in the Plugins Preference pane if it exists, to display the version.

Adding the Plugin to Buddi

Now that the plugin is bundled, you can add it to Buddi. To do this, open the Preferences screen in Buddi, and select the Plugins tab. Select the plugin on the filesystem. This will actually copy this plugin to the Plugins folder, created by Buddi in your working directory (and which differs by operating system). (Note: the Preferences method is just to simplify things; you can also just copy the file directly to the Plugins folder on the file system, and Buddi will read it the next time you start up). To remove a plugin, either go to Preferences and delete it using the interface, or just remove it from the Plugins folder.

If your operating system has associated .buddi3plugin files with Buddi (currently only Windows and OS X), you can also just double click on the plugin file, and Buddi will copy the file to the correct location.