Manual for iReport 0.2.0 and above

6 iReport Plugins
6.1 The Abstract iReport Plugin
6.2 The Plugin File Descriptor
6.3 The Hello World Plugin

6 iReport Plugins

From version 0.3.1, iReport supports a plugin system to extend its features. In this chapter, we'll learn how to create an iReport plugin and how to deploy it.

An iReport plugin is composed by a descriptor file (an XML document placed in the "plugin" directory) and a set of classes (or a jar) placed in the classpath.

Normally, when plugin is loaded, iReport creates an item in the plugin menu on the main frame. Plugins are loaded only on iReport startup. When the plugin menu item is selected, iReport instances the plugin (if not yet instanced) and calls the plugin's call() method.

A plugin is instanced only one time, and in the descriptor file it's possible to specify to instance it at iReport startup instead of waiting for the first user invocation. This is useful when the plugin is marked as "hidden", and it is not visible on the plugin menu.

Fig.6.1: The plugin menu on iReport main frame

A plugin can be marked as configurable. In this case, the plugin must implement the method configure() that will be executed when the user asks to configure the plugin.

6.1 The Abstract iReport Plugin

All iReport plugins extends the abstract class it.businesslogic.ireport.plugin.IReportPlugin. This class is really simple:

1   /*
2    * IReportPlugin.java
3    *
4    * Created on 19 maggio 2004, 7.23
5    */
6   
7   package it.businesslogic.ireport.plugin;
8   
9   import it.businesslogic.ireport.gui.MainFrame;
10  /**
11   * This class must be extended by all iReport plugin.
12   * To install a plugin into iReport, put the plugin xml in the plugin directory of iReport.
13   * See plugin documentation on how to create a plugin for iReport
14   * 
15   * This is the first very simple interface to plugin. I hope to don't change it, but we can't say
16   * what it'll happen in he future...
17   *
18   * @author  Administrator
19   */
20  public abstract class IReportPlugin {
21      
22      MainFrame mainFrame = null;
23      String name = "";
24      
25     
26      
27      /**
28       *  This method is called when the plugin is selected from the plugin menu
29       */
30      public abstract void call();
31      
32      /**
33       *  This method is called when the plugin configuration button on plugin list is selected.
34       *  Configuration file of plugin should be stored in IREPORT_USER_HOME_DIR/plugins/
35       */
36      public void configure(){}
37  
38      /**
39       *  Retrive the plugin name. Please note that the plugin name must be unique and should be used as
40       *  filename for the configuration file if needed. This name can be different from the name specified
41       *  in XML, that is the name used for the menu item.
42       */
43      public String getName(){
44          return name;
45      }
46      
47      /** Getter for property mainFrame.
48       * @return Value of property mainFrame.
49       *
50       */
51      public it.businesslogic.ireport.gui.MainFrame getMainFrame() {
52          return mainFrame;
53      }
54      
55      /** Setter for property mainFrame.
56       * @param mainFrame New value of property mainFrame.
57       *
58       */
59      public void setMainFrame(it.businesslogic.ireport.gui.MainFrame mainFrame) {
60          this.mainFrame = mainFrame;
61      }
62      
63  }
64  

Please note that the ONLY abstract method that must be implemented is call() that is called each time the plugin is invoked from the user.
If you want to add a configuration GUI for your plugin, then you must implement the configure() method too.

6.2 The plugin file descriptor

The plugin file descriptor is a file with an arbitrary name that describes a plugin. The main information about the plugin is:

• NAME: this is the name that will be displayed in the menu item);
• CLASS: the plugin class that extendes IReportPlugin;
• ICON FILE: an icon used on menu (must be 16x16);

  <?xml version="1.0" encoding="UTF-8"?>
  <!--
      Document   : iReportPlugin.dtd
      Created on : 19 maggio 2004, 8.09
      Author     : Giulio Toffoli
      Description: This DTD define the XML descriptor for an iReport plugin.    
  -->
  <!-- 
      iReportPlugin is the root element.
      ATTRIBUTES:
      name          The name of plugin
      class         The class that extends 
                              it.businesslogic.ireport.plugin.IReportPlugin
      loadOnStartup If true, the plugin will be instanced on iReport startup
      hide          If true, this plugin will be not visible on plugin menu
  -->        
  <!ELEMENT iReportPlugin (Author?,Description?, IconFile?)>
  <!ATTLIST iReportPlugin
          name NMTOKEN #REQUIRED
          class NMTOKEN #REQUIRED
          loadOnStartup (true | false) "false"
          hide (true | false) "false"
          congigurable (true | false) "false">
  
  <!ELEMENT Author (#PCDATA)>
  <!ELEMENT Description (#PCDATA)>
  
  <!--
      Icon file should be a file in the classpath i.e. com/my/plug/in/icon.gif
      Is used as optional icon for menu.
      Dim: 16x16 
  -->
  <!ELEMENT IconFile (#PCDATA)>

6.3 The Hello World Plugin

The following example shows a really simple plugin that shows a simple message when invoked or configured: HelloWorld.java.

1   /*
2    * HelloWorld.java
3    *
4    * Created on 21 maggio 2004, 7.36
5    */
6   
7   package it.businesslogic.ireport.plugin.examples;
8   
9   /**
10   *
11   * @author  Administrator
12   */
13  public class HelloWorld extends it.businesslogic.ireport.plugin.IReportPlugin {
14      
15      /** Creates a new instance of HelloWorld */
16      public HelloWorld() {
17      }
18      
19      public void call() {
20          javax.swing.JOptionPane.showMessageDialog(this.getMainFrame(), "Hello from plugin!");
21      }
22      
23      public void configure() {
24          javax.swing.JOptionPane.showMessageDialog(this.getMainFrame(), "Hello from plugin configuration!");
25      }
26      
27  }
28  

helloworld_descriptor.xml

<iReportPlugin 	
	name="Example 1"
	class="it.businesslogic.ireport.plugin.examples.HelloWorld"
	loadOnStartup="false"
	hide = "false"
	configurable = "true">
	
	<IconFile>/it/businesslogic/ireport/icons/menu/new.gif</IconFile>
	
	<Description>This example shows how to create a very simple plugin for iReport.</Description>

</iReportPlugin>