.:Documentation and tutorials |

Home
Screenshots
Docs
Download
Project page
Credits
Donations

Vote for iReport on O'Reilly's OSDir.com

<< Previous | Next >> | Table of Contents

6 iReport plugins
From version 0.3.1, iReport supports a plugin system to extend his 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 main frame. Plugins are loaded only on iReport startup. When the plugin menu item is selected, iReport instance the plugin (if not yet instanced) and call the plagin's `call()` method.
A plugin is instanced only one time, and in descriptor file it's possible specify to instance it at iReport startup instead to wait for the first user invokation. 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 ask 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:

| IReportPlugin.java |

    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 add a configuration GUI for you 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 describe a plugin. The main informations about the plugin are:

- 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 show a really simple plugin that show 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>

(c) 2002 by Giulio Toffoli <gt78 at businesslogic.it>