Building Report Templates
Report templates are zip files containing all resources required to generate a report. This section describes the structure of report templates.
For a deep understanding of Jasper Reports the following sources are recommended:
|
Tooling
Jaspersoft provides two tools to edit jrxml files: Jaspersoft Studio and iReport Designer.
-
Jaspersoft Studio is the recommended tool by Jaspersoft
-
iReport Designer is the predecessor of the Jaspersoft Studio and no longer developed actively
Both tools are Open Source and free to use.
Basic Structure
A report template contains at least one single jrxml file, an XML file which describes the layout of the generated report.
The following code block shows a sample of a report which only prints a page header and footer. It can be considered as a minimal report template.
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport
xmlns="http://jasperreports.sourceforge.net/jasperreports"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd"
name="Test" pageWidth="595" pageHeight="842" whenNoDataType="AllSectionsNoDetail"
columnWidth="555" leftMargin="20" rightMargin="20" topMargin="20" bottomMargin="20"
uuid="3404c519-e6e3-4a8c-ba35-4f49f7561b1a">
<background>
<band splitType="Stretch"/>
</background>
<title>
<band splitType="Stretch"/>
</title>
<pageHeader>
<band height="50" splitType="Stretch">
<line>
<reportElement x="0" y="36" width="555" height="1" uuid="1f3f78b4-8e27-4d14-bf42-b78a56195112"/>
</line>
<staticText>
<reportElement x="0" y="14" width="315" height="20" uuid="bb0ae07d-f417-47dc-8b52-982f02b6f99e"/>
<textElement>
<font isBold="true"/>
<paragraph leftIndent="10" rightIndent="10"/>
</textElement>
<text><![CDATA[Sample Report]]></text>
</staticText>
</band>
</pageHeader>
<columnHeader>
<band splitType="Stretch"/>
</columnHeader>
<detail>
<band height="24" splitType="Stretch">
</band>
</detail>
<columnFooter>
<band splitType="Stretch"/>
</columnFooter>
<pageFooter>
<band height="34" splitType="Stretch">
<textField>
<reportElement x="164" y="10" width="80" height="20" uuid="6b60238f-9f9d-4653-acff-9faffc2570ee"/>
<textElement textAlignment="Right"/>
<textFieldExpression><![CDATA["Page "+$V{PAGE_NUMBER}+" of"]]></textFieldExpression>
</textField>
<textField evaluationTime="Report">
<reportElement x="244" y="10" width="40" height="20" uuid="c4dafacf-0621-4abe-99f5-d1df21c004de"/>
<textFieldExpression><![CDATA[" " + $V{PAGE_NUMBER}]]></textFieldExpression>
</textField>
<line>
<reportElement x="0" y="6" width="555" height="1" uuid="1732aabe-c5b2-49e5-9bd4-785a6ae75c89"/>
</line>
<textField pattern="yyyy-MM-dd HH:mm:ss">
<reportElement x="455" y="10" width="100" height="20" uuid="eccec6c9-ef07-46a4-b6cd-b67a582d080b"/>
<textFieldExpression><![CDATA[new java.util.Date()]]></textFieldExpression>
</textField>
</band>
</pageFooter>
<summary>
<band splitType="Stretch"/>
</summary>
</jasperReport>
The attribute whenNoDataType="AllSectionsNoDetail" on the root <jasperReport> element is required.
Otherwise a blank page is produced.
|
Referencing Resources
Included in the jrxml file any other kind of file can be part of a report template. A typical example is for example an image file which should be used as a logo inside the report.
The structure of the report template can be extended like this:
/+- sample.jrxml
+- logo.png
The path that references the image file inside the jrxml file is the filename logo.png
.
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport ...>
...
<pageHeader>
<band height="50" splitType="Stretch">
...
</staticText>
<image>
<reportElement x="430" y="9" width="125" height="40" uuid="18cab714-55f3-4b3c-a542-055dd1c6238c"/>
<imageExpression><![CDATA["logo.png"]]></imageExpression>
</image>
</band>
</pageHeader>
...
If images are stored in sub folders, the structure might look like this:
/+- sample.jrxml
+- images
+- logo.png
The path used to reference the file from the jrxml file is "images/logo.png".
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport ... >
...
<pageHeader>
<band height="50" splitType="Stretch">
...
</staticText>
<image>
<reportElement x="430" y="9" width="125" height="40" uuid="18cab714-55f3-4b3c-a542-055dd1c6238c"/>
<imageExpression><![CDATA["images/logo.png"]]></imageExpression>
</image>
</band>
</pageHeader>
...
Fields
A field defines an access name and the type of a value inside one row (or feature) of a data source.
A field value can be accessed in data expressions using the $F{<field name>}
syntax.
<!-- declare a well-known field of an entry in the data source -->
<field name="Name" class="java.lang.String"/>
<!-- now this can be used to access the value of a field -->
<staticText>
...
<text><![CDATA[$F{Name}]]></text>
</staticText>
<!-- also methods of the value instance can be called -->
<staticText>
...
<text><![CDATA[$F{Name}.toLowerCase()]]></text>
</staticText>
Parameters
A parameter defines a static constant or a value required to be set before report generation.
A parameter value can be accessed in data expressions using the $P{<parameter name>}
syntax.
<!-- a constant -->
<parameter name="ARCGIS_SERVER_BASE_URL" class="java.lang.String" isForPrompting="false">
<defaultValueExpression><![CDATA[http://localhost:6090/arcgis/services]]></defaultValueExpression>
</parameter>
<!-- a required parameter -->
<parameter name="FEATURE_IDS" class="java.lang.String" isForPrompting="true"></parameter>
<!-- use a parameter -->
<staticText>
...
<text><![CDATA[$P{ARCGIS_SERVER_BASE_URL}]]></text>
</staticText>
The JasperReport engine provides some built-in parameters, which don’t need to be declared.
Here is a list of some of the generated parameters.
Name | Description |
---|---|
|
Contains a map with all user defined and built-in parameters |
|
User supplied |
|
User supplied instance of JRDataSource representing either one of the built-in data source types or a user-defined one |
|
A |
|
Points to |
|
A |
|
Points to |
|
A |
|
An instance of |
|
A |
|
If set to |
|
The current report instance |
Variables
A variable can be used to encapsulate frequently used data expressions and to perform some calculations.
A variable value can be accessed in data expressions using the $V{<variable name>}
syntax.
<!-- declare a variable -->
<variable name="FeatureTitle" class="java.lang.String">
<variableExpression><![CDATA["This is feature " + $F{Name}]]></variableExpression>
</variable>
<!-- use a variable -->
<staticText>
...
<text><![CDATA[$V{FeatureTitle}]]></text>
</staticText>
The JasperReport engine provides some built-in variables, which don’t need to be declared.
Here is a list of some of the generated variables.
Name | Description |
---|---|
|
Current page number.
It can be used to display both the current page number and the total number of pages using a special feature of JasperReports text field elements, the |
|
Current column number |
|
Total number of records processed. |
|
Number of records that were processed when generating the current page. |
|
Number of records that were processed when generating the current column. |
|
Derived from the name of the group it corresponds to, suffixed with the |
Scriptlets
map.apps ships with an extension for JasperReports that allows to include feature information provided by an ArcGIS Server into a report. This extension is built on top of the scriptlet mechanism of Jasper Reports.
A scriptlet is an Java class which extends the class net.sf.jasperreports.engine.JRDefaultScriptlet or net.sf.jasperreports.engine.JRAbstractScriptlet .
|
To ensure that a report can use a scriptlet the compiled class must be deployed inside a JAR archive and copied to the WEB-INF/lib
folder of the map.apps web application.
If a scriptlet requires other Java libraries, these must also be installed into the WEB-INF/lib
folder.
Within a jrxml file a scriptlet can be used in two ways: As default scriptlet or as scriptlet tag:
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport scriptletClass="de.company.MyScriptlet" ...>
...
<pageHeader>
<band height="50" splitType="Stretch">
<staticText>
...
<text><![CDATA[$P{REPORT_SCRIPTLET}.methodNameInTheClass()]]></text>
</staticText>
</band>
</pageHeader>
...
<?xml version="1.0" encoding="UTF-8"?>
<jasperReport ...>
...
<scriptlet name="myscriptlet" class="de.company.MyScriptlet"/>
...
<pageHeader>
<band height="50" splitType="Stretch">
<staticText>
...
<text><![CDATA[$P{myscriptlet_SCRIPTLET}.methodNameInTheClass()]]></text>
</staticText>
</band>
</pageHeader>
...
Map Scriptlet
This scriptlet allows the production of map images inside the report. To generate map images the scriptlet communicates with a ArcGIS Server Print Task.
de.conterra.reporting.jasper.agsds.ScriptletCTMap
All parameters except This postfix is also provided in the image generation methods of the scriptlet, for example This allows a different specification of parameters for different method calls. |
Following report parameters can be defined.
Parameter | Description | Comments and Examples | ||
---|---|---|---|---|
|
The URL of the ArcGIS Server Print Task used to generate map images.
|
|
||
|
Scale of the map image. |
|
||
|
Defines the print quality of the image, dots per inch (DPI). |
|
||
|
Defines the algorithm how the scriptlet calculates the extent of the map image. |
|
||
|
Explicit definition of the map extent.
This parameter is only required if the algorithm is |
|
||
|
EPSG number of the spatial reference system of the extent.
If |
|
||
|
A polygon drawn on the map to display an area. At least 4 points have to be specified. |
|
||
|
EPSG number of the spatial reference system of the polygon. |
|||
|
The style of the line symbol. |
default: |
||
|
The color of the line symbol. |
|
||
|
The width of the line symbol. |
|
||
|
Defines the position of a marker on the map. |
|
||
|
EPSG number of the spatial reference system of the marker.If |
|
||
|
URL of an image which should be used as symbol for the marker.
This image must be accessible from the print task specified in |
|
||
|
Base64 encoded bytes of the marker symbol image.
This is an alternative to the |
|||
|
Width of the marker symbol. |
|
||
|
Height of the marker symbol. |
|
||
|
Offset of the position of the symbol image in x direction from the point specified by |
|
||
|
Offset of the position of the symbol image in y direction from the point specified by |
|
||
|
Rotates the symbol image by the specified angle. |
|||
|
Type of the base layer |
Shared |
||
|
Url of the base layer |
|
||
|
Opacity value of the base layer |
|
||
|
Type of the operational layer |
MapService WMS |
||
|
URL of the operational layer |
|
||
|
Token for token based protected services |
|
||
|
Opacity value of the operational layer |
|
||
|
Visible layers of the operational layer |
|
||
|
Version of the operational layer.
This is the WMS-Version and therefore only of interest if |
|
||
|
Output format of the image produced by the operational layer.
This is only of interest if |
Default ist |
||
|
Should NO DATA values be transparent in the created image.
This is only of interest if |
Default ist |
||
|
This is the drawing order of operational layers. The first layer in the list is interpreted as top most layer. |
|
||
|
URL of Layer of an ArcGIS Server map service or feature service which is the selection data source |
|
||
|
"Where" expression used to select features in the data source |
|||
|
List of object IDs which define the filter for the selection. |
|
||
|
List of order by fields appended to the selection query |
|
||
|
Constrain selection to maximal amount of features |
|
||
|
Flag if the filter expression used for the main report data source should be appended to the selection filter expression. |
Boolean.FALSE |
||
|
Fall-back parameter required if CT_MAP_EXTENT_TYPE is set to FROM_SELECTION and the calculated extent is a point. This parameter defines a scale to correct the selection extent |
|
||
|
JSON string defining the drawing info for the selection layer |
|||
|
URL of an image which should be used as symbol for point features from the selection |
|||
|
Base64 encoded image which should be used as symbol for point features from the selection |
|||
|
Width of the symbols for points |
|
||
|
Height of the symbols for points |
|
||
|
Offset of the position of the symbol image in x direction from the point location |
|
||
|
Offset of the position of the symbol image in y direction from the point location |
|
||
|
Rotates the symbol image by the specified angle. |
|||
|
Well-known name of the outline color of selection polygons |
|
||
|
Color of the outline of selection polygons |
|
||
|
Opacity value of the selection polygons. It overwrites the alpha value of CT_MAP_SELECTION_POLYGON_OUTLINE_COLOR_RGBA if provided |
|
||
|
Width of the outline of selection polygons |
|
||
|
Style of the outline of selection polygons |
|
||
|
Well known name of the fill color of selection polygons |
|
||
|
Fill color of the selection polygons |
|
||
|
Fill opacity value of the selection polygons. It overwrites the alpha value of CT_MAP_SELECTION_POLYGON_FILL_COLOR_RGBA if provided |
|
||
|
Fill style of the selection polygons |
|
||
|
Well known name of the fill color of selection polylines |
|
||
|
Color of the selection polylines |
|
||
|
Opacity value of the selection polylines. It overwrites the alpha value of CT_MAP_SELECTION_POLYLINE_COLOR_RGBA if provided |
|
||
|
Width of the selection polylines |
|
||
|
Style of the selection polylines |
|
||
|
A webmap JSON definition as direct input to the print task. |
The scriptlet provides following methods:
Method syntax | Description |
---|---|
|
Executes the print task and returns the URL of the created map image. Parameter:
|
|
Executes the print task and returns the URL of the created map image. Parameter:
|
|
Executes the print task and returns the created map image. Parameter:
|
|
Merges two images |
ArcGIS server data source
Part of the JasperReports extension is the ESRIAGSCustomDataSource which allows to iterate over features of an ArcGIS Server map service or feature service.
To create a report data source the queryString element must be provided and the report has to be initialized without any data source.
<!-- the query string has following syntax -->
<URL>;<'query' | 'objectids'>; < query string | object ID list >;( <sort fields>; <maxrecords> )?
<!-- Sample for a data source initialization with an object ID query -->
<queryString language="ags">
<![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;objectids;1,2,3]]>
</queryString>
<!-- Sample for a data source initialization with a where clause -->
<queryString language="ags">
<![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;query;OBJECTID>0]]>
</queryString>
<!-- Sample for a data source initialization with a where clause and sort field and max records -->
<queryString language="ags">
<![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;query;OBJECTID>0;OrgFullName ASC;100]]>
</queryString>
<!-- Sample for a data source initialization with a where clause and only maxrecords (note the double ;;) -->
<queryString language="ags">
<![CDATA[http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer/0;query;OBJECTID>0;;100]]>
</queryString>
Reference a field value of a feature:
<!-- first define the field -->
<field name="title" class="java.lang.String"/>
<!-- now the following expression is allowed during the iteration of the features -->
<textField>
...
<textFieldExpression>
<![CDATA["Title of object is: " + $F{title}]]>
</textFieldExpression>
</textField>
Iterate all fields of a feature:
<!-- first define a sub dataset -->
<subDataset name="NameValueDataset">
<field name="Name" class="java.lang.String"/>
<field name="Value" class="java.lang.String"/>
</subDataset>
<!-- A dataset run can be defined, e.g for iteration within a table -->
<jr:table>
<datasetRun subDataset="NameValueDataset">
<dataSourceExpression>
<![CDATA[((de.conterra.reporting.jasper.agsds.ESRIAGSCustomDataSource)$P{REPORT_DATA_SOURCE}).createAGSFeatureGenericJRDatasource()]]>
</dataSourceExpression>
</datasetRun>
<!-- within this dataset run the fields Name and Value can be accessed -->
<jr:column width="155">
<jr:detailCell height="20" rowSpan="1">
<textField>
...
<textFieldExpression>
<![CDATA[$F{Name}]]>
</textFieldExpression>
</textField>
</jr:detailCell>
</jr:column>
<jr:column width="155">
<jr:detailCell height="20" rowSpan="1">
<textField>
...
<textFieldExpression>
<![CDATA[$F{Value}]]>
</textFieldExpression>
</textField>
</jr:detailCell>
</jr:column>
</jr:table>