by Giulio Toffoli
The plug-in technology used by iReport is the same used by the NetBeans platform. This means that to write a plug-in for iReport is the same as create a plugin for NetBeans. This allows the use of all the plug-in development facilities provided by the NetBeans IDE to create plugins (and this is why the use of NetBeans IDE is strongly encouraged when working with iReport).
This tutorial explains how to setup the environment to create an plugin for iReport. The plugin will just add a textfield element to the title band of an opened report. This will give us the opportunity to see three aspects of the plugin development:
- How to create a NBM (NetBeans Module) file that can be installed in iReport using the plugin manager
- How to set the dependecies of your module to the iReport APIs.
- How to interact with iReport
The NetBeans platform puts at disposal of the developer a big number of features. To use them, it's necessarty to declare dependencies to the modules which implement the specific features. There are modules included in the platform that provide basic services like access to the file system, drag and drop, nodes management, property sheet, database and JDBC connections management, and so on. When working on a plugin for iReport, it's important to keep in mind that the plugin should work on iReport as standalone application, which does not include all the default modules provided by NetBeans IDE.
Anyway all the main APIs are available in iReport.
Preparing the environment for the iReport plugin development
There are several ways to create a plugin for iReport. By the NetBeans point of view, iReport is a suite (or a collection) of modules that forms a cluster on top of the NetBeans platform: the ireport cluster.
The first approach could be to create a module which is part of the iReport suite: in that case you have to change the iReport project to include your module. This approach is simple, but it forces you to customize the iReport project, which is not a good idea, and all the time you run your simple plugin, you are actually deployed the whole application loosing a lot of time.
The best option is to create your plugin on top of a "special" platform based on the iReport cluster.
Here is how to create this platform. Compile iReport as explained in the How to compile iReport from sources tutorial. Be sure iReport compiles correctly. Then run the Ant target called create_platform.
This operation will create a special NetBeans platform (based on the 6.0.1 version) which includes only the modules shipped with iReport (included the ireport cluster). The platform is created inside the /trunk/iReport/dist directory and is called ireport.zip.
Explode this archive somewhere (you may create a directory dev and keep there the netbeans platform, the iReport sources and the new ireport platform (figure 2).
To use this platform for development we have to copy a directory from the NetBeans platform 6.0.1 called harness. Copy it inside the ireport platform (the ireport directory containing all the platform files, see figure 3).
Finally define the new platform in NetBeans by using the NetBeans Platform Manager: select Tools → NetBeans Platforms.
Select Add Platform and locate the ireport directory containing the plarform we have just created. Set the platform name to iReport or keep the specific version proposed.
Remember that if you share the source code of your plugin project, the users must have a platform called iReport inside NetBeans (created in the same way we did here).
Creating a new plug-in
Create a new project in NetBeans of type Module (which is a template inside the NetBeans Modules category).
Press Next. In the second step set a name for your plugin (i.e. MyPlugin), and a location (which is good to be different than the iReport suite project). Set the option to make your plugin a standalone module based on the iReport platform (which is the one we have just created).
Finally set the code base of your plugin (i.e. com.jaspersoft.ireport.plugins.myplugin) and select the checkbox to Generate the XML layer.
Run your project (with the Rub Main Project button on the tool bar). A special version of iReport will start. Even if our plug-in does nothing yet, you can see the it in the list of installed plugin in the plugin manager (Tools → Plugins).
Close iReport and let's back to the IDE. It's time to write some code.
Select the main package of your project, right click and add a new Action class.
A wizard to create Action starts. Select an Always Enabled action and proceed to the next step.
Set "Designer" as category for the Action and add the action at the end of the Format menu.
Set a name for the action class, i.e. AddTitleTextfieldAction, and a label for the new menu item (i.e. Add Title).
You can optionally add an icon for the menu item.
If you run the project, you'll see the new Add Title menu item in the Format menu.
Adding dependencies
To interact with the report designer we have to add some dependencies to our plugin. To do it, right click the project "My Plugin" in the Projects view and select properties.
Add dependencies to the ireport-desgner and Nodes API modules and close the project properties pressiong OK.
Now we can use all the classes provided by iReport and by the Nodes API.
Edit the class AddTitleTextfieldAction.java like follows.
package com.jaspersoft.ireport.plugins.myplugin;
import com.jaspersoft.ireport.designer.IReportManager;
import com.jaspersoft.ireport.designer.utils.Misc;
import javax.swing.JOptionPane;
import net.sf.jasperreports.engine.design.JRDesignBand;
import net.sf.jasperreports.engine.design.JRDesignExpression;
import net.sf.jasperreports.engine.design.JRDesignTextField;
import net.sf.jasperreports.engine.design.JasperDesign;
import org.openide.nodes.Node;
import org.openide.util.HelpCtx;
import org.openide.util.NbBundle;
import org.openide.util.actions.NodeAction;
public final class AddTitleTextfieldAction extends NodeAction {
public String getName() {
return NbBundle.getMessage(AddTitleTextfieldAction.class, "CTL_AddTitleTextfieldAction");
}
@Override
protected void initialize() {
super.initialize();
// see org.openide.util.actions.SystemAction.iconResource() Javadoc for more details
putValue("noIconInMenu", Boolean.TRUE);
}
public HelpCtx getHelpCtx() {
return HelpCtx.DEFAULT_HELP;
}
@Override
protected boolean asynchronous() {
return false;
}
@Override
protected void performAction(Node[] arg0) {
if (IReportManager.getInstance().getActiveReport() != null)
{
JasperDesign jd = IReportManager.getInstance().getActiveReport();
JRDesignBand titleBand = (JRDesignBand)jd.getTitle();
// Check if the band exists and it is height enough...
if (titleBand == null || titleBand.getHeight() > 40)
{
JOptionPane.showMessageDialog(Misc.getMainFrame(),
"This report has not a title band or its size is less than 40 pixels.");
}
else
{
// Calculate the center of the band...
int w = jd.getPageWidth() - jd.getRightMargin() - jd.getLeftMargin();
int h = titleBand.getHeight();
JRDesignTextField titleTf = new JRDesignTextField(jd);
titleTf.setX( w/2 - 100 );
titleTf.setY( h/2 - 20 );
titleTf.setWidth( 200 );
titleTf.setHeight( 40 );
titleTf.setFontSize(30);
titleTf.setHorizontalAlignment( JRDesignTextField.HORIZONTAL_ALIGN_CENTER );
JRDesignExpression textExpression = Misc.createExpression("java.lang.String", ""Title"");
titleTf.setExpression(textExpression);
titleBand.addElement(titleTf);
IReportManager.getInstance().setSelectedObject( titleTf );
}
}
}
@Override
protected boolean enable(Node[] arg0) {
return IReportManager.getInstance().getActiveReport() != null;
}
}
Compile and run the project.
Select the Format menu and you will notice that the Add Title item is disabled. This because there is not an open document. This is what the line 82 is for. It asks to the iReport manager (which is a core class of iReport) the current active report. This method returns a JasperDesign if a report is opened and a valid model is available, null otherwise. So checking if we have a model is a good way to enable or disable this menu item, since we have to change the report when the action is performed.
Now create a new report or open an existing one. The menu item is now enabled. Selecting it a new textfield element is created in the title band. Now resize the title band to be shorter than 40 pixels. If you select Add Title again you'll get a message informing you that there is not enough room to place the textfield.
The core of the plugin is in this simple case the method performAction() at line 38. We check there (just to be sure) that we have a valid model to work with. We look for the title band in the report model. The JasperDesign class is the core of the report object model and is a class of JasperReports, like JRDesignBand, which represents a band in the report model. We check if the title band exists and if it is heigher that 40 pixels. If it is not, we pop up a message using the JOptionPane class (line 48). If the title band exists and there is enough space, we create a JRDesignTextfield, we center it respect to the band, we add an expression (this must be a valid Java or Groovy expression, so notice how double quotes are escaped in the call to Misc.createExpression(class type, expression text)). Finally (line 69) we add the textfield to the band and we select it (line 71).
Deploy the plugin
Now that we have a working plugin, we may want to distribute it. To create an NBM file, which is the file format of the NetBeans (and iReport) plugins, right click the project node in the project view and select Create NBM.
The created NBM file can be distributed and installed in any iReport installation using the plugin manager.
To learn more about plugin development, Google for NetBeans plugin development tutorials.
Recommended Comments
There are no comments to display.