Developing Plugins in Buddi 3.0

This is the first draft of a document I am creating for how to develop plugins in Buddi 3.0. Eventually it will be on the website in the Developers section, but for now I have included it here. It should currently be accurate as of Buddi 2.9.0.0; if you have any questions or changes to make, please feel free to add to the comments below or on the General forum. This document is still a work in progress (as is Buddi 3.0), and is liable to change at any time.

Developing Plugins in Buddi 3.0

Background
Ever since the plugin framework has been released in 2.0 and the API has been
released in 2.4, I have been paying attention to areas where these
frameworks either fall short, or approached their functions in a strange
way. Almost a year after the first plugin interface was released, I think
that I have a much better idea of how to correctly implement this.

Starting in Buddi 3.0 (Development release 2.9), there is a completely new
API and Plugin framework. While there are many minor differences, it is
still close enough to convert existing plugins to with little effort (I
converted all of the built in reports and graphs, as well as the plugins which
I created, and from what I have see, it does not take more than 10 or 15
minutes for an average sized class.

For a complete listing of classes and methods, please refer to the Javadocs
for the package org.homeunix.thecave.buddi.plugin.api. This is where all
the plugin interfaces, API model, and report creation utilities are located.
You should be able to create most plugins without using any core classes
outside of this package.

For a UML diagram of the API model, please see the API Model.pdf file.

Details
What Buddi identifies as a plugin consists of one single .jar file (with the
extension renamed from .jar to .buddi3plugin), containing one or more
implementations of the specified BuddiPlugin interfaces, listed below. Unlike
previous versions of Buddi, in Buddi 3.0 the plugin is one single entity -
if you load it, you load the entire plugin, and cannot pick and choose which
classes are to be run. This has the benefit that a plugin author can create
a suite of plugins which all work together, and keep them all in the same
buddi3plugin file.

To create a new plugin, there are a few steps which you must first take. The
first is to decide what plugin type fits your design the best. There are
currently six different types of plugins for Buddi. Each are listed below,
with some details about their use:

1) BuddiReportPlugin - This is the interface for anything which is to appear
in the "My Reports" section, whether it be a report or a graph (the concept
that these two are different has been removed in Buddi 3.0 - since they
are both just the output of HTML, there is no functional difference).

2) BuddiExportPlugin,
3) BuddiImportPlugin,
4) BuddiSynchronizePlugin - These three plugins are very similar from an
interface point of view, and differ only in function. The first provides
an Immutable API object which allows you to read data, but not change anything.
The second two allow changes to the data model, and are different in semantics
only.

5) BuddiPreferencePlugin - This class allows plugin authors to create their
own preference panes, and provides a method for saving and retreiving data
from the main Buddi preferences file.

6) BuddiRunnablePlugin - This class implements Runnable, and is called when
Buddi is first loaded. It generally allows for doing things that would not
otherwise be allowed, such as changing the Java Look and Feel, running a
server locally to listen for incoming requests to display transactions, or
just about anything else.

Once you have decided on what type of plugin you are going to create, you can
start coding. Simply implement one of the interfaces listed above, and fill
in the methods you need to provide.

Something new which has been added in Buddi 3.0 is the concept of 'Preference
Plugins'. This is a class which plugin authros can use to include a tab in
the Preferences screen. It also provides methods for saving and reading
preferences from the main Buddi preferences file, which can allow plugin
authors to concentrate on making clean and simple plugins, and not worry
about OS specific issues such as where to store preferences, etc.

Once you are finished, you need to bundle the plugin. You can use the 'jar'
command (included with the Java Development Kit) to do this. For instance,
if your class naming is of the form "org.example.buddi.plugin.MyPlugin", type
'jar -cvf MyPluginPackage.buddi3plugin org/'. If you have translations of your
plugin (which is highly recommended, even if you only include an English one),
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.

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.

The new plugin and API framework in Buddi should allow simple and powerful
customizations from third party plugin developers. These additions will
continue to allow Buddi to improve, and ensure that it is always the best
solution for simple home budgeting.

--Wyatt

Posted by Wyatt 2007-09-07