<html>
<head>
<title>iReport</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK REL=STYLESHEET TYPE="text/css" HREF="manual0.2.0/stylesheet.css" TITLE="Style">
<style>
FONT.fsmall { font: normal 9pt Arial; }
FONT.fmedio { font: normal 10pt Arial; }
FONT.ftitparagrafo { font: bold 13pt Arial; }
FONT.fparagrafo { font: bold 11pt Arial; }
FONT.smaaaaal { font: bold 8pt Arial; }
FONT.ftitle { font: normal 20pt Arial; }
A.fmedio { COLOR: #000000; TEXT-DECORATION: underline; font: normal 10pt Arial; }
A.fmedio:hover { COLOR: #AA0000; TEXT-DECORATION: underline; font: normal 10pt Arial; }

A.fmed2 { COLOR: #000000; TEXT-DECORATION: underline; font: normal 12pt Arial; }
A.fmed2:hover { COLOR: #AA0000; TEXT-DECORATION: underline; font: normal 12pt Arial; }

A.fmedim { COLOR: #000000; TEXT-DECORATION: none; font: normal 10pt Arial; }
A.fmedim:hover { COLOR: #AA0000; TEXT-DECORATION: underline; font: normal 10pt Arial; }
</style>
</head>

<body bgcolor="#FFFFFF" text="#000000" topmargin="0" leftmargin="0" marginwidth="0" marginheight="0">
<table width="100%" height="100%" border="0" cellspacing="0" cellpadding="0">
  <tr height="99"><td><table height="99" width="100%" border="0" cellspacing="0" cellpadding="0"><tr height="99">
    <td width="200" height="99" valign="top"><img src="images/logo_igor.gif" ></td>
    <td valign="top" width="99%" height="99"><table  width="100%" border="0" cellspacing="0" cellpadding="0">
	<tr> 
	  <td   height="49" bgcolor="#D4D0C8" valign="bottom" align="left"><font class="ftitle"><b>.:Documentation and tutorials</b></font></td>
	  <td   height="49" bgcolor="#D4D0C8" valign="middle" align="right"><A href="http://sourceforge.net"><img border=0 src="images/sflogo.gif" width="105" height="31"></a><img src="images/null.gif"49" width="10" border=0 height="1"></td>
	</tr>
	<tr> 
	  <td height="1" colspan="2" bgcolor="#000000"><img src="images/null.gif height="1" width="1"></td>
	</tr>
      </table></td>
		</tr></table></td>
  </tr> 
  <tr><td><table width="100%" height="100%" border="0" cellspacing="0" cellpadding="0"><tr><td width="120" valign="top" bgcolor="#C98890"><img src="images/null.gif" width="120" height="10">
  <table cellspacing=2 cellpadding=0 width="100%">
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="index.php" class="fmedim">Home</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="screenshots.html" class="fmedim">Screenshots</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="docs.html" class="fmedim">Docs</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="http://sourceforge.net/project/showfiles.php?group_id=64348" class="fmedim">Download</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="http://sourceforge.net/projects/ireport" class="fmedim">Project page</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="credits.html" class="fmedim">Credits</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="http://ireport.sourceforge.net/donations.html" class="fmedim">Donations</a></font></td></tr>
  </table>
  <form method="post"
    action="http://www.osdir.com/
    modules.php?op=modload&amp;name=Downloads&amp;file=index">
<table border="0" cellspacing="0" cellpadding="0">
  <tr>
    <td align="center">
      <font class=fsmall>Vote for iReport on O'Reilly's OSDir.com</font>
    </td>
  </tr>
  <tr>
    <td><center>
      <table border="0" cellspacing="0" cellpadding="0">
        <tr>
          <td valign="top" align="center" nowrap>
            <select name="rating">
              <option selected>--</option><br>
              <option value="10">10</option><br>
              <option value="9">9</option><br>
              <option value="8">8</option><br>
              <option value="7">7</option><br>
              <option value="6">6</option><br>
              <option value="5">5</option><br>
              <option value="4">4</option><br>
              <option value="3">3</option><br>
              <option value="2">2</option><br>
              <option value="1">1</option><br>
            </select>
            <input type="submit" value="Vote!"><input type="hidden" name="ratinglid" value="396"><input type="hidden" name="req" value="addrating"><input type="hidden" name="ratinguser" value="outside">
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>
</form>
  </td>
    <td width="1" height="1" bgcolor="#6F6F6F"><img src="images/null.gif height="1" width="1"></td>
    <td valign="top"><table cellspacing=2 cellpadding=0 width="100%"><tr><td>
		<br>
		  <table align="center" width="95%" border="0" cellspacing="0" cellpadding="0">
		  <tr valign="top"><td>
			<a href="cap5.html"  class="fmedim">&lt;&lt; Previous</a> &nbsp;&nbsp;|&nbsp;&nbsp; <a href="cap7.html"  class="fmedim">Next &gt;&gt;</a> &nbsp;&nbsp;|&nbsp;&nbsp; <a href="manual0.2.0.html"  class="fmedim">Table of Contents</a>
			<hr height=1 width=100%>
		      
		      <font class="ftitparagrafo"><a name="6.0"></a><b>6 iReport plugins</b></font><br><br>
		      <font class="fsmall">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.<br>
		      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.<br>
		      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 <code>call()</code> method.<br>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.<br>
		      <table border=0><tr><td><img border=0 src="manual0.2.0/6_1.jpg"></td></tr><tr><td><font class="fsmall"><b>Fig.6.1: The plugin menu on iReport main frame.</b></font></td></tr></table>
		      A plugin can be marked as configurable. In this case, the plugin must implement the method <code>configure()</code> that will be executed when the user ask to configure the plugin.<br>
		      		      
		      </font><br><br>
		      </font>
		      <font class="fparagrafo"><a name="6.1"></a><b>6.1 The abstract iReport plugin</b></font><br><br>
		      <font class="fsmall">All iReport plugins extends the abstract class <code>it.businesslogic.ireport.plugin.IReportPlugin</code>. This class is really simple:<br>
		      <br>
		      <TABLE id="Header" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td colspan="2" width="33%">&nbsp;</td>
<td align="center" colspan="2" width="33%">
<font size="4">IReportPlugin.java</font>
</td>
<td align="right" colspan="2" width="33%">&nbsp;</td>
</tr>
</TABLE>
<pre ID="Classes">
<FONT ID="LN">1   </FONT><A NAME="1"></A><FONT ID="MultiLineComment">/*
<FONT ID="LN">2   </FONT><A NAME="2"></A> * IReportPlugin.java
<FONT ID="LN">3   </FONT><A NAME="3"></A> *
<FONT ID="LN">4   </FONT><A NAME="4"></A> * Created on 19 maggio 2004, 7.23
<FONT ID="LN">5   </FONT><A NAME="5"></A> */</FONT>
<FONT ID="LN">6   </FONT><A NAME="6"></A>
<FONT ID="LN">7   </FONT><A NAME="7"></A><FONT ID="Package">package</FONT> <A HREF="" target="packageFrame">it.businesslogic.ireport.plugin</A>;
<FONT ID="LN">8   </FONT><A NAME="8"></A>
<FONT ID="LN">9   </FONT><A NAME="9"></A><FONT ID="Import">import</FONT> it.businesslogic.ireport.gui.MainFrame;
<FONT ID="LN">10  </FONT><A NAME="10"></A><FONT ID="FormalComment">/**
<FONT ID="LN">11  </FONT><A NAME="11"></A> * This class must be extended by all iReport plugin.
<FONT ID="LN">12  </FONT><A NAME="12"></A> * To install a plugin into iReport, put the plugin xml in the plugin directory of iReport.
<FONT ID="LN">13  </FONT><A NAME="13"></A> * See plugin documentation on how to create a plugin for iReport
<FONT ID="LN">14  </FONT><A NAME="14"></A> * 
<FONT ID="LN">15  </FONT><A NAME="15"></A> * This is the first very simple interface to plugin. I hope to don't change it, but we can't say
<FONT ID="LN">16  </FONT><A NAME="16"></A> * what it'll happen in he future...
<FONT ID="LN">17  </FONT><A NAME="17"></A> *
<FONT ID="LN">18  </FONT><A NAME="18"></A> * @author  Administrator
<FONT ID="LN">19  </FONT><A NAME="19"></A> */</FONT>
<FONT ID="LN">20  </FONT><A NAME="20"></A><FONT ID="Public">public</FONT> <FONT ID="Abstract">abstract</FONT> <FONT ID="Class">class</FONT> IReportPlugin {
<FONT ID="LN">21  </FONT><A NAME="21"></A>    
<FONT ID="LN">22  </FONT><A NAME="22"></A>    MainFrame mainFrame = <FONT ID="Null">null</FONT>;
<FONT ID="LN">23  </FONT><A NAME="23"></A>    String name = <FONT ID="StringLiteral">""</FONT>;
<FONT ID="LN">24  </FONT><A NAME="24"></A>    
<FONT ID="LN">25  </FONT><A NAME="25"></A>   
<FONT ID="LN">26  </FONT><A NAME="26"></A>    
<FONT ID="LN">27  </FONT><A NAME="27"></A>    <FONT ID="FormalComment">/**
<FONT ID="LN">28  </FONT><A NAME="28"></A>     *  This method is called when the plugin is selected from the plugin menu
<FONT ID="LN">29  </FONT><A NAME="29"></A>     */</FONT>
<FONT ID="LN">30  </FONT><A NAME="30"></A>    <FONT ID="Public">public</FONT> <FONT ID="Abstract">abstract</FONT> <FONT ID="Void">void</FONT> call();
<FONT ID="LN">31  </FONT><A NAME="31"></A>    
<FONT ID="LN">32  </FONT><A NAME="32"></A>    <FONT ID="FormalComment">/**
<FONT ID="LN">33  </FONT><A NAME="33"></A>     *  This method is called when the plugin configuration button on plugin list is selected.
<FONT ID="LN">34  </FONT><A NAME="34"></A>     *  Configuration file of plugin should be stored in IREPORT_USER_HOME_DIR/plugins/
<FONT ID="LN">35  </FONT><A NAME="35"></A>     */</FONT>
<FONT ID="LN">36  </FONT><A NAME="36"></A>    <FONT ID="Public">public</FONT> <FONT ID="Void">void</FONT> configure(){}
<FONT ID="LN">37  </FONT><A NAME="37"></A>
<FONT ID="LN">38  </FONT><A NAME="38"></A>    <FONT ID="FormalComment">/**
<FONT ID="LN">39  </FONT><A NAME="39"></A>     *  Retrive the plugin name. Please note that the plugin name must be unique and should be used as
<FONT ID="LN">40  </FONT><A NAME="40"></A>     *  filename for the configuration file if needed. This name can be different from the name specified
<FONT ID="LN">41  </FONT><A NAME="41"></A>     *  in XML, that is the name used for the menu item.
<FONT ID="LN">42  </FONT><A NAME="42"></A>     */</FONT>
<FONT ID="LN">43  </FONT><A NAME="43"></A>    <FONT ID="Public">public</FONT> String getName(){
<FONT ID="LN">44  </FONT><A NAME="44"></A>        <FONT ID="Return">return</FONT> name;
<FONT ID="LN">45  </FONT><A NAME="45"></A>    }
<FONT ID="LN">46  </FONT><A NAME="46"></A>    
<FONT ID="LN">47  </FONT><A NAME="47"></A>    <FONT ID="FormalComment">/** Getter for property mainFrame.
<FONT ID="LN">48  </FONT><A NAME="48"></A>     * @return Value of property mainFrame.
<FONT ID="LN">49  </FONT><A NAME="49"></A>     *
<FONT ID="LN">50  </FONT><A NAME="50"></A>     */</FONT>
<FONT ID="LN">51  </FONT><A NAME="51"></A>    <FONT ID="Public">public</FONT> it.businesslogic.ireport.gui.MainFrame getMainFrame() {
<FONT ID="LN">52  </FONT><A NAME="52"></A>        <FONT ID="Return">return</FONT> mainFrame;
<FONT ID="LN">53  </FONT><A NAME="53"></A>    }
<FONT ID="LN">54  </FONT><A NAME="54"></A>    
<FONT ID="LN">55  </FONT><A NAME="55"></A>    <FONT ID="FormalComment">/** Setter for property mainFrame.
<FONT ID="LN">56  </FONT><A NAME="56"></A>     * @param mainFrame New value of property mainFrame.
<FONT ID="LN">57  </FONT><A NAME="57"></A>     *
<FONT ID="LN">58  </FONT><A NAME="58"></A>     */</FONT>
<FONT ID="LN">59  </FONT><A NAME="59"></A>    <FONT ID="Public">public</FONT> <FONT ID="Void">void</FONT> setMainFrame(it.businesslogic.ireport.gui.MainFrame mainFrame) {
<FONT ID="LN">60  </FONT><A NAME="60"></A>        <FONT ID="This">this</FONT>.mainFrame = mainFrame;
<FONT ID="LN">61  </FONT><A NAME="61"></A>    }
<FONT ID="LN">62  </FONT><A NAME="62"></A>    
<FONT ID="LN">63  </FONT><A NAME="63"></A>}
<FONT ID="LN">64  </FONT><A NAME="64"></A></pre>

		       Please note that the ONLY abstract method that must be implemented is <code>call()</code> that is called each time the plugin is invoked from the user.<br>
		       If you want add a configuration GUI for you plugin, then you must implement the <code>configure()</code> method too.<br>
		       <br>
		       
		       
		       </font><br><br>
		      </font>
		      
		      <font class="fparagrafo"><a name="6.2"></a><b>6.2 The plugin file descriptor</b></font><br><br>
		      <font class="fsmall">The plugin file descriptor is a file with an arbitrary name that describe a plugin. The main informations
		      about the plugin are: 
		      <ul>
		      <li>NAME this is the name that will be displayed in the menu item);</li>
		      <li>CLASS the plugin class that extendes IReportPlugin;</li>
		      <li>ICON FILE an icon used on menu (must be 16x16);</li>
		      
		      </ul>
		      
		      <br>
<TABLE id="Header" border="0" cellpadding="0" cellspacing="0">
<tr>
<td nowrap >
		      <pre ID="Classes">
  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  <FONT ID="FormalComment">&lt;!--
      Document   : iReportPlugin.dtd
      Created on : 19 maggio 2004, 8.09
      Author     : Giulio Toffoli
      Description: This DTD define the XML descriptor for an iReport plugin.    
  --&gt;
  &lt;!-- 
      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
  --&gt;</font>        
  &lt;!ELEMENT <FONT ID="Public">iReportPlugin</FONT> (Author?,Description?, IconFile?)&gt;
  &lt;!ATTLIST iReportPlugin
          name NMTOKEN #REQUIRED
          class NMTOKEN #REQUIRED
          loadOnStartup (true | false) "false"
          hide (true | false) "false"
          congigurable (true | false) "false"&gt;
  
  &lt;!ELEMENT <FONT ID="Public">Author</FONT> (#PCDATA)&gt;
  &lt;!ELEMENT <FONT ID="Public">Description</FONT> (#PCDATA)&gt;
  
  <FONT ID="FormalComment">&lt;!--
      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 
  --&gt;</font>
  &lt;!ELEMENT <FONT ID="Public">IconFile</FONT> (#PCDATA)&gt;
</pre>
</td>
</tr>
</TABLE>
		      </font><br><br>
		      </font>
		      
		      <font class="fparagrafo"><a name="6.3"></a><b>6.3 The hello world plugin</b></font><br><br>
		      <font class="fsmall">The following example show a really simple plugin that show a simple message when invoked or configured.
		       
		       <TABLE id="Header" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td colspan="2" width="33%">&nbsp;</td>
<td align="center" colspan="2" width="33%">
<font size="4">HelloWorld.java</font>
</td>
<td align="right" colspan="2" width="33%">&nbsp;</td>
</tr>
</TABLE>
<pre ID="Classes">
<FONT ID="LN">1   </FONT><a name="2_1"></A><FONT ID="MultiLineComment">/*
<FONT ID="LN">2   </FONT><a name="2_2"></A> * HelloWorld.java
<FONT ID="LN">3   </FONT><a name="2_3"></A> *
<FONT ID="LN">4   </FONT><a name="2_4"></A> * Created on 21 maggio 2004, 7.36
<FONT ID="LN">5   </FONT><a name="2_5"></A> */</FONT>
<FONT ID="LN">6   </FONT><a name="2_6"></A>
<FONT ID="LN">7   </FONT><a name="2_7"></A><FONT ID="Package">package</FONT> <A HREF="" target="packageFrame">it.businesslogic.ireport.plugin.examples</A>;
<FONT ID="LN">8   </FONT><a name="2_8"></A>
<FONT ID="LN">9   </FONT><a name="2_9"></A><FONT ID="FormalComment">/**
<FONT ID="LN">10  </FONT><a name="2_10"></A> *
<FONT ID="LN">11  </FONT><a name="2_11"></A> * @author  Administrator
<FONT ID="LN">12  </FONT><a name="2_12"></A> */</FONT>
<FONT ID="LN">13  </FONT><a name="2_13"></A><FONT ID="Public">public</FONT> <FONT ID="Class">class</FONT> HelloWorld <FONT ID="Extends">extends</FONT> <A HREF="">it.businesslogic.ireport.plugin.IReportPlugin</A> {
<FONT ID="LN">14  </FONT><a name="2_14"></A>    
<FONT ID="LN">15  </FONT><a name="2_15"></A>    <FONT ID="FormalComment">/** Creates a new instance of HelloWorld */</FONT>
<FONT ID="LN">16  </FONT><a name="2_16"></A>    <FONT ID="Public">public</FONT> HelloWorld() {
<FONT ID="LN">17  </FONT><a name="2_17"></A>    }
<FONT ID="LN">18  </FONT><a name="2_18"></A>    
<FONT ID="LN">19  </FONT><a name="2_19"></A>    <FONT ID="Public">public</FONT> <FONT ID="Void">void</FONT> call() {
<FONT ID="LN">20  </FONT><a name="2_20"></A>        javax.swing.JOptionPane.showMessageDialog(<FONT ID="This">this</FONT>.getMainFrame(), <FONT ID="StringLiteral">"Hello from plugin!"</FONT>);
<FONT ID="LN">21  </FONT><a name="2_21"></A>    }
<FONT ID="LN">22  </FONT><a name="2_22"></A>    
<FONT ID="LN">23  </FONT><a name="2_23"></A>    <FONT ID="Public">public</FONT> <FONT ID="Void">void</FONT> configure() {
<FONT ID="LN">24  </FONT><a name="2_24"></A>        javax.swing.JOptionPane.showMessageDialog(<FONT ID="This">this</FONT>.getMainFrame(), <FONT ID="StringLiteral">"Hello from plugin configuration!"</FONT>);
<FONT ID="LN">25  </FONT><a name="2_25"></A>    }
<FONT ID="LN">26  </FONT><a name="2_26"></A>    
<FONT ID="LN">27  </FONT><a name="2_27"></A>}
<FONT ID="LN">28  </FONT><a name="2_28"></A></pre>
		      
		      </font><br><br>
		      </font>
		      
		      </td>
		     
		  </tr>
		   </table>
		   </td>
		    </tr> 
		   </table></td></tr></table></td>
  </tr>
  <tr height="15"><td><table  width="100%" border="0" cellspacing="0" cellpadding="0">
	<tr> 
	  <td height="1" colspan="2" bgcolor="#000000"><img src="images/null.gif height="1" width="1"></td>
	</tr>
	 <tr> 
	  <td   height="14" bgcolor="#D4D0C8" valign="bottom" align="center"><font class="fsmall">(c) 2002 by Giulio Toffoli &lt;gt78 at businesslogic.it&gt;</font></td>
	</tr>
      </table></td>
  </tr>
</table></body>
</html>
