Developing a jGnash plugin

jGnash is a personal financial software, available as Free Libre Open Source Software (FLOSS). I've been using it since some years, and i can say that is a great software. It has many functionalities, PDF reports and charts, to register and control your incomes and expenses. It just lack of some analysis reports, so i decided to build my own.

It's possible to create plug-ins for jGnash. So you can add a new functionality or a new report, without recompile the whole software. There's a folder in jGnash installation directory called "plugins", in this folder you can add a JAR file containing the new plug-in and next time you start jGnash, it will load your plug-in.

Requirements to build a new plug-in

For build a new plug-in you will need Java programing knowledge, and some specifics thing depending on the kind of functionalities that you are trying to extend. For building new graph charts or reports, I will suggest experience related to: Java Swing, JFreeChart, DynamicJasper and JasperReports. There is not good documentation about packages and source code of jGnash, but you can download the source code and will find is not hard to read, also you will find help on email lists.

According to jGnash help menu, these are the external libraries they use, so could be good also know a little bit about them: args4j, db4o, JasperReports, DynamicJasper, JFreeChart, JGoodies Animation, JGoodies Forms, JGoodies Looks, Apache MINA, XStream and SwingX.

I like Eclipse IDE, so I will use it, but any Java IDE should be good.

Of course, you must have installed jGnash, to link the jars files to your new plugin project.

Architecture

jGnash provides a plug-in system that is easy to understand. The jgnash2.jar provides a interface called: jgnash.plugin.Plugin and a abstract class called: jgnash.plugin.AbstractEnabledAction, to create a new plugin, inside the new plugin jar, just implement the Plugin interface and extend the AbstractEnabledAction.

Also it will be needed to write a couple of lines inside the jar MANIFEST file.

Steps to create a basic plugin

1- Start a new Java Project, this is a normal Java project in Eclipse IDE.

2-In the Java Build Path of the project (Right click on the project, Properties, Java Build Path, Libraries) add the External Jar: jgnash2.jar from your jGnash installation path.

3- Inside the project, create a new file called: MANIFEST.MF

This file must contain something similar to this:

Manifest-Version: 1.0
Plugin-Activator: myplugin.mypackage.MyPlugin
Plugin-Version: 1.0

Where "Plugin-Activator:" points to the class that implements the jgnash.plugin.Plugin interface.

4- Create the Plugin implementation class, that indicate, which menus will be added to the user interface and which actions will be executed. This is a simple example:

package myplugin.mypackage;

import javax.swing.JMenuItem;
import javax.swing.JPanel;

import jgnash.plugin.Plugin;

public class MyPlugin implements Plugin{

    @Override
    public JMenuItem[] getMenuItems() {
        JMenuItem menuItem = new JMenuItem();

        menuItem.putClientProperty(Plugin.PRECEDINGMENUIDREF, "new-command");
        menuItem.setAction(new MyAction());

        return new JMenuItem[] { menuItem };
    }

    @Override
    public String getName() {
        return "My Plugin";
    }

    @Override
    public JPanel getOptionsPanel() {
        return null;
    }

    @Override
    public void start() {
    }

    @Override
    public void stop() {  
    }
}

The line menuItem.putClientProperty(Plugin.PRECEDINGMENUIDREF, "new-command"); will tell to jGnash where to add the new menuItem, the preceding code, indicate before New Command menuItem. Other places you can choose are listed in the source code of jGnash, check this file:

/jgnash2/jgnash-resources/src/main/resources/jgnash/resource/main-frame-actions.xml

Another important line is: menuItem.setAction(new MyAction()); it says, when user clicks this menuItem execute the code inside MyAction class, that we must create later.

5- Implementing AbstractEnabledAction.

package myplugin.mypackage;

import java.awt.event.ActionEvent;

import javax.swing.Action;
import javax.swing.JOptionPane;

import jgnash.ui.actions.AbstractEnabledAction;

public class MyAction extends AbstractEnabledAction {

    public MyAction(){
        putValue(NAME, "Title");
        putValue(Action.SHORT_DESCRIPTION, "Description");
    }
  
    @Override
    public void actionPerformed(ActionEvent e) {
        JOptionPane.showMessageDialog(null, "Hello World");
    }
}

It's important to set the "NAME" and "Action.SHORT_DESCRIPTION" values, they will be shown as the title and tool tip text of the menuItem.

The actionPerformed method will be executed when the menuItem is clicked by the user, in this example will show a simple dialog window saying "Hello World".

6- Creating the jar file. In Eclipse, right click over your project, select Export, and then Jar File.

 

After that, follow the instructions, and take care when "Jar Manifest Specification" windows appear, select the option: "Use existing manifest from workspace", and choose the "MANIFEST.MF" file that we have created before.

7- Copy the generated jar file inside "plugins" folder of jGnash, run jGnash and you will see the message "Hello World" when you click the new menu "Title" inside "File" menu.

Thanks to jGnash developers for this great software. My hope is that lots of jGnash plug-ins come alive to make it a better software for all.