Creating an EGL report handler

An EGL report handler provides blocks of code that the JasperReports engine can access at run time. Predefined function names tie some of these code blocks to events that occur when JasperReports fills a report. Such events might include the beginning or end of a page, of a line item, or of the report itself. You can call other, custom functions directly from the XML design file source.

To create an EGL report handler, do as follows:
  1. Identify a project or folder to contain the file. You must create a project or folder if you do not already have one.
  2. In the workbench, click File > New > Other.
  3. In the New window, expand EGL.
  4. Click Report Handler.
  5. Click Next.
  6. Select the project or folder that will contain the EGL source file, then select a package.
  7. In the EGL Source File Name field, type the name report handler source file. As the report handler name will be identical to the file name, choose a file name that adheres to EGL part name conventions (for example, myReportHandler).
  8. Click Finish.

The New EGL Report Handler wizard will give you a list of function names that correspond to report fill events. JasperReports will invoke "beforePageInit()", for example, before entering a page. It is up to you to create the code for these functions.

Alternatively, you can add this template information to an existing file by following these steps:
  1. Create a new EGL source file.
  2. Type handler followed by Ctrl+space.
The remainder of this topic contains code examples that show the following:

These examples barely begin to address the complexities possible in a report handler. For more detail, see the JasperReports documentation.

Report handler template

This is the template code created by the New EGL Report Handler wizard:
handler handlerName type jasperReport

	// Use Declarations
	use usePartReference;

	// Constant Declarations)
	const constantName constantType = literal;

	// Data Declarations
	identifierName declarationType;

	// Pre-defined Jasper callback functions
	function beforeReportInit()
	end

	 function afterReportInit()
	end

	function beforePageInit()
	end

	function afterPageInit()
	end

	function beforeColumnInit()
	end

	function afterColumnInit()
	end

	function beforeGroupInit(stringVariable string)
	end

	function afterGroupInit(stringVariable string)
	end

	function beforeDetailEval()
	end

	function afterDetailEval()
	end
end

Getting report parameters

Reports can contain three types of items: parameters (set in the XML file and not changed), variables (changeable by the XML file or the report handler) and fields (keyed to names in the data source). The following code snippet shows how to get report parameters in a report handler:
handler my_report_handler type jasperReport

	// Data Declarations 
	report_title	String;

	// Jasper callback function
	function beforeReportInit()
		report_title = getReportParameter("ReportTitle");
	end

end

Getting and setting report variables

The following code snippet shows how to get and set report variables in a report handler:
handler my_report_handler type jasperReport

	// Data Declarations 
	item_count	int;

	// Jasper callback function
	function beforeDetailEval()
		item_count = getReportVariableValue("itemCount");
	end

	function afterDetailEval()
		setReportVariableValue("itemCount", (item_count + 1));
	end
end
Remember to match variable types in the report handler with those in your XML source file.

Getting report field values

The following example code snippet shows how to get report field values in a report handler:
handler my_report_handler type jasperReport
	
	// Data Declarations 
	employee_first_name	String;

	// Jasper callback function
	function beforeColumnInit()
		employee_first_name = getFieldValue("fName");
	end
end

Saving report data in the report handler

The following example code shows how to save a customer record under the name "saveCustomer" for later access:
handler my_report_handler type jasperReport
	
	// Data Declarations 
	customer_array	customerRecordType[];
	c             	customerRecordType;

	// Jasper callback function
	function beforeReportInit()
		customer ReportData;

		//create the ReportData object for the Customer subreport
		c.customer_num = getFieldValue("c_customer_num");
		c.fname        = getFieldValue("c_fname");
		c.lname        = getFieldValue("c_lname");
		c.company      = getFieldValue("c_company");
		c.address1     = getFieldValue("c_address1");
		c.address2     = getFieldValue("c_address2");
		c.city         = getFieldValue("c_city");
		c.state        = getFieldValue("c_state");
		c.zipcode      = getFieldValue("c_zipcode");
		c.phone        = getFieldValue("c_phone");	
		customer_array.appendElement(c);
		customer.data = customer_array;
		addReportData(customer, "saveCustomer");
	end	
end

Retrieving report data in the XML file

Now that we have saved the report data in the report handler, we can retrieve it in the XML source file and pass it to a subreport:
<jasperReport name="MasterReport" ... scriptletClass="subreports.my_report_handler">
...

<subreport>
	<dataSourceExpression>
		<![CDATA[(JRDataSource)(((subreports.SubReportHandler) 
			$P{REPORT_SCRIPTLET}).getReportData( new String("saveCustomer")))]]>;
	</dataSourceExpression>
	<subreportExpression class="java.lang.String">
		<![CDATA["C:/RAD/workspaces/customer_subreport.jasper"]]>;
	</subreportExpression>
</subreport>

...
</jasperReport>

Invoking a function from the XML design document

Here's a report handler with one very simple function:
handler my_report_handler type jasperReport
	
function hello () returns (String)
		return("Hello, world!");
	end
end
Invoke it from the XML design document with this code:
<jasperReport name="MasterReport" ... scriptletClass="my_package.my_report_handler">
...

	<summary>
		<band height="40">
			<textField>
				<reportElement positionType="Float" x="0" y="20" width="500" height="15"/>
				<textElement textAlignment="Center">
					<font reportFont="Arial_Bold" size="10"/>
				</textElement>
				<textFieldExpression class="java.lang.String">
					<![CDATA[((my_package.my_report_handler)$P{REPORT_SCRIPTLET}).hello()]]>
				</textFieldExpression>
			</textField>
		</band>
	</summary>

...
</jasperReport>

The phrase "Hello, world!" will print at the end of the report.

Related concepts
EGL report creation process overview
EGL reports overview

Related tasks
Creating an EGL source file
Using report templates

Related Reference
Additional EGL report handler functions
EGL library ReportLib
EGL report handler
Predefined EGL report handler functions

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.