JasperReports Ultimate Guide - Samples - Schema - Configuration - Functions - FAQ - API (Javadoc)
|
|
|
|
JasperReports - Map Component Sample (version 6.21.0) | |
|
|
|
Main Features in This Sample | |
| Using the Built-in Map Component |
|
|
||||
top | |||||
|
|||||
Using the Built-in Map Component | Documented by Sanda Zaharia | ||||
|
|||||
| Description / Goal |
| How to render maps using the built-in map component. | ||
| Since |
| 4.1.1 | ||
|
|||||
|
Map Component Overview
The map component in JasperReports exposes some of the main characteristics necessary to generate the most common Google maps, but feature upgrades for this component are planned for future development. Important notes:
The current map component description is found in the components.xsd schema:
<element name="map" substitutionGroup="jr:component"> <complexType> <complexContent> <extension base="jr:componentType"> <sequence> <element name="latitudeExpression" minOccurs="0" maxOccurs="1"> <complexType mixed="true"/> </element> <element name="longitudeExpression" minOccurs="0" maxOccurs="1"> <complexType mixed="true"/> </element> <element name="addressExpression" minOccurs="0" maxOccurs="1"> <complexType mixed="true"/> </element> <element name="zoomExpression" minOccurs="0" maxOccurs="1"> <complexType mixed="true"/> </element> <element name="languageExpression" minOccurs="0" maxOccurs="1"> <complexType mixed="true"/> </element> <choice minOccurs="0" maxOccurs="1"> <element ref="c:markerDataset"/> <element ref="c:markerData"/> </choice> </sequence> <attribute name="evaluationTime" type="jr:basicEvaluationTime" use="optional" default="Now"/> <attribute name="evaluationGroup" type="string" use="optional"/> <attribute name="mapType" use="optional" default="roadmap"> <simpleType> <restriction base="string"> <enumeration value="roadmap"/> <enumeration value="satellite"/> <enumeration value="terrain"/> <enumeration value="hybrid"/> </restriction> </simpleType> </attribute> <attribute name="mapScale" use="optional" default="1"> <simpleType> <restriction base="unsignedInt"> <enumeration value="1"/> <enumeration value="2"/> <enumeration value="4"/> </restriction> </simpleType> </attribute> <attribute name="imageType" use="optional" default="png"> <simpleType> <restriction base="string"> <enumeration value="png"/> <enumeration value="png8"/> <enumeration value="png32"/> <enumeration value="gif"/> <enumeration value="jpg"/> <enumeration value="jpg-baseline"/> </restriction> </simpleType> </attribute> </extension> </complexContent> </complexType> </element> <complexType name="ItemData" abstract="true"> <sequence> <element ref="jr:dataset" minOccurs="0" maxOccurs="1"/> <element ref="c:item" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> <complexType name="ItemProperty"> <sequence> <element ref="jr:valueExpression" minOccurs="0" maxOccurs="1"/> </sequence> <attribute name="name" type="string" use="required" /> <attribute name="value" type="string" use="optional" /> </complexType> <element name="item"> <complexType> <sequence> <element name="itemProperty" type="c:ItemProperty" minOccurs="0" maxOccurs="unbounded" /> </sequence> </complexType> </element> <element name="markerData"> <complexType> <complexContent> <extension base="c:ItemData"> </extension> </complexContent> </complexType> </element> <element name="markerDataset"> <annotation> <documentation>Creates a dataset with one or more marker objects</documentation> </annotation> <complexType> <sequence> <element ref="jr:datasetRun" minOccurs="0" maxOccurs="1"/> <element ref="c:marker" minOccurs="0" maxOccurs="unbounded"/> </sequence> </complexType> </element> <element name="marker"> <complexType> <sequence> <element name="markerProperty" type="c:ItemProperty" minOccurs="0" maxOccurs="unbounded" /> </sequence> </complexType> </element>Map Attributes One can customize the map component using the following attributes:
The <c:latitudeExpression/> represents the latitude coordinate of the map center, necessary to locate it on the Earth surface.
Allowed values are floating point numbers representing degrees from -90° to 90°.
The Longitude Expression The <c:longitudeExpression/> represents the longitude coordinate of the map center, necessary to locate it on the Earth surface.
Allowed values are floating point numbers representing degrees from -180° to 180°.
The Address Expression The <c:addressExpression/> represents the address of the map center and is optional. It will be considered only when the latitude and/or
longitude expressions are missing or empty. Computing address expressions relies on expensive time and resources consumption, therefore the report
filling performance may visibly decline. It is highly recommended to use latitude and longitude expressions whenever possible.
The Zoom Expression The <c:zoomExpression/> represents the initial map zoom level. The expression allows integer values and defaults to 0.
The Language Expression The <c:languageExpression/> represents the language code used to localize the textual information displayed on the map,
such as control names, copyright notices and other various labels. Supported languages can be found
here.
The Marker Dataset Warning: The <c:markerDataset/> element is now deprecated, as replaced by the <c:markerData/> element below:
The Marker Data Element The <c:markerData/> element is used to generate the list of marker elements to be displayed on the map. It can collect
its data either from a subdataset, or from a hardcoded list of marker item elements as shown in the map component schema.
The marker item element contains a list of specific item properties that can be set either by value or by valueExpression . If both are set, the
valueExpression takes precedence over the value attribute. With few exceptions, property names must
match the names of supported marker options available here.
The main exception is the position option, currently undefined in JR. It is actually replaced by the latitude and longitude property
names, both necessary to compute the marker position on the map. If at least one of these two properties is missing or empty, try to set the equivalent address property.
If no address is available, an exception will be thrown.
Warnings:
itemProperty names:
Both icon and shadow properties indicate an image location, without any additional information. In this case
the image is loaded as it is and is placed in built-in positions on the map, using Google Maps defaults. But sometimes, marker icons need
more detailed configurations, in order to get a better map appearance. In this case one can build custom icons, with the following properties:
For marker icons:
When a marker icon is clicked on the map, additional information can be displayed either in a separate window/frame or in an info window floating above the map. The text content in an info window is processed as HTML, therefore the HTML notation should be used for special characters (see reserved characters here.) If both url and info window settings are present in a marker definition, the info window takes precedence over the marker URL. Clicking on the marker
icon will open the info window.
To configure an info window, the following item properties are available:
Various locations on a given map can be connected to form a path. To configure a path on the map, the following information is needed:
Points that have to be connected in a path are grouped into the <pathData/> element. A path data element is very similar to the
marker data element described above, but comes with a different set of item properties. Each item in the path data element
represents a place on the map and must provide either the latitude and longitude , or the equivalent address
property from the following list of allowed properties:
In order to avoid redundant data, common style properties for a given path can be grouped in a style element, so that individual items (points) in the path have to remember only the name of the path style, instead of carrying several style properties by themselves. Path styles are grouped together into a <pathStyle/> element,
very similar to <pathData/> , excepting the latitude and longitude properties that are not considered in a path style.
Below is the list of allowed properties in a path style, with the same meaning and defaults (excepting the name property) as in the path data element:
Exporters that don't allow JavaScript or dynamic page loading may use the Google Static Map service that creates and returns a map image depending on a given set of HTTP request parameters. The map image does not support user interactivity, but can be used to substitute with some inherent limitations a dynamic map, for read-only purposes. In these conditions, not all item properties defined for markers are considered in static maps. The available properties in this case are:
The JRXML sample contains five map components that illustrate how various settings can be applied in order to get the desired map
rendering. Each map is loaded from a subreport and collect its data from the CSV datasource located in the data subfolder.
Map #1: Simple Road Map The first map is loaded from the reports/MapReport1.jrxml template, and illustrates a road map with minimal settings. There are no
markers and no additional information on the map:
<componentElement> <reportElement x="0" y="150" width="515" height="326" positionType="Float"/> <c:map xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" evaluationTime="Report" onErrorType="Icon"> <c:latitudeExpression><![CDATA[$P{latitude}]] ></c:latitudeExpression> <c:longitudeExpression><![CDATA[$P{longitude}]] ></c:longitudeExpression> <c:zoomExpression><![CDATA[$P{zoom}]] ></c:zoomExpression> <c:languageExpression><![CDATA[new java.util.Locale("ro").getLanguage()]] ></c:languageExpression> </c:map> </componentElement>Map #2: Satellite Map with Default Marker Icons The second map is loaded from the reports/MapReport2.jrxml template. One can notice the mapType="satellite" mapScale="1" imageType="jpg"
attribute settings. The satellite map also contains a set of 5 markers with default icons and tooltips enabled. All marker settings are grouped in the
<c:markerData/> section which collects its data from the MarkersDataset subdataset. Data with invalid latitude/longitude values are
skipped due to the <filterExpression/> in the subdataset:
<subDataset name="MarkersDataset"> <property name="net.sf.jasperreports.data.adapter" value="/data/CsvDataAdapter.jrdax"/> <queryString language="csv"> <![CDATA[]] > </queryString> <field name="address" class="java.lang.String"/> <field name="latitude" class="java.lang.String"/> <field name="longitude" class="java.lang.String"/> <filterExpression> <![CDATA[!($F{latitude}==null || $F{latitude}.length()==0) || $F{longitude}==null || $F{longitude}.length()==0)]] > </filterExpression> </subDataset>The map component configuration is the following: <componentElement> <reportElement x="0" y="150" width="515" height="326" positionType="Float"/> <c:map xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" mapType="satellite" mapScale="1" imageType="jpg" onErrorType="Blank"> <c:latitudeExpression><![CDATA[37.800056f]] ></c:latitudeExpression> <c:longitudeExpression><![CDATA[-122.4075f]] ></c:longitudeExpression> <c:zoomExpression><![CDATA[$P{zoom} + 1]] ></c:zoomExpression> <c:markerData> <dataset> <datasetRun subDataset="MarkersDataset"/> </dataset> <c:item> <c:itemProperty name="latitude"> <valueExpression>$F{latitude}</valueExpression> </c:itemProperty> <c:itemProperty name="longitude"> <valueExpression>$F{longitude}</valueExpression> </c:itemProperty> <c:itemProperty name="title"> <valueExpression>$F{address}</valueExpression> </c:itemProperty> </c:item> </c:markerData> </c:map> </componentElement>Map #3: Terrain Map with Custom Marker Icons The 3rd map is a terrain sample loaded from the reports/MapReport3.jrxml template. It comes with the same set of markers as
Map #2, but this time marker icons are loaded from custom URLs, with the specified width and height. Below is the map
component configuration (and the subdataset):
<subDataset name="MarkersDataset"> <property name="net.sf.jasperreports.data.adapter" value="/data/CsvDataAdapter.jrdax"/> <queryString language="csv"> <![CDATA[]] > </queryString> <field name="address" class="java.lang.String"/> <field name="latitude" class="java.lang.String"/> <field name="longitude" class="java.lang.String"/> <field name="iconurl" class="java.lang.String"/> <field name="iconwidth" class="java.lang.Integer"/> <field name="iconheight" class="java.lang.Integer"/> <filterExpression> <![CDATA[!($F{latitude}==null || $F{latitude}.length() == 0 || $F{longitude}==null || $F{longitude}.length() == 0)]] > </filterExpression> </subDataset> ... <componentElement> <reportElement x="0" y="150" width="515" height="326" positionType="Float"/> <c:map xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" mapType="terrain" mapScale="1" imageType="jpg" onErrorType="Icon"> <c:latitudeExpression><![CDATA[37.800056f]] ></c:latitudeExpression> <c:longitudeExpression><![CDATA[-122.4075f]] ></c:longitudeExpression> <c:zoomExpression><![CDATA[$P{zoom} + 1]] ></c:zoomExpression> <c:markerData> <dataset> <datasetRun subDataset="MarkersDataset"/> </dataset> <c:item> <c:itemProperty name="latitude"> <valueExpression>$F{latitude}</valueExpression> </c:itemProperty> <c:itemProperty name="longitude"> <valueExpression>$F{longitude}</valueExpression> </c:itemProperty> <c:itemProperty name="title"> <valueExpression>$F{address}</valueExpression> </c:itemProperty> <c:itemProperty name="icon.url"> <valueExpression>$F{iconurl}</valueExpression> </c:itemProperty> <c:itemProperty name="icon.width"> <valueExpression>$F{iconwidth}</valueExpression> </c:itemProperty> <c:itemProperty name="icon.height"> <valueExpression>$F{iconheight}</valueExpression> </c:itemProperty> </c:item> </c:markerData> </c:map> </componentElement>Map #4: Satellite Map with Marker Hyperlinks and Paths In the 4th sample loaded from the reports/MapReport4.jrxml template the same set of markers with default icons are placed on a
satellite map. This time marker icons display custom colors, and in static maps only, custom sizes. Marker tooltips are disabled, but markers
provide hyperlinks. Clicking on a marker icon will open a new browser window/tab with related information. In addition, all markers are connected to form
a green polygonal contour and two of them are also connected with a blue line.
Two additional subdatasets were added in order to generate path styles and path data.See the configuration below: <subDataset name="MarkersDataset"> <property name="net.sf.jasperreports.data.adapter" value="/data/CsvDataAdapter.jrdax"/> <queryString language="csv"> <![CDATA[]] > </queryString> <field name="latitude" class="java.lang.String"/> <field name="longitude" class="java.lang.String"/> <field name="size" class="java.lang.String"/> <field name="color" class="java.lang.String"/> <field name="url" class="java.lang.String"/> <filterExpression> <![CDATA[!($F{latitude}==null || $F{latitude}.length() == 0 || $F{longitude}==null || $F{longitude}.length() == 0)]] > </filterExpression> </subDataset> <subDataset name="PathStyleDataset"> <property name="net.sf.jasperreports.data.adapter" value="/data/PathStyleDataAdapter.jrdax"/> <queryString language="csv"> <![CDATA[]] > </queryString> <field name="name" class="java.lang.String"/> <field name="strokecolor" class="java.lang.String"/> <field name="strokeopacity" class="java.lang.Double"/> <field name="strokeweight" class="java.lang.Integer"/> <field name="fillcolor" class="java.lang.String"/> <field name="fillopacity" class="java.lang.Double"/> <field name="draggable" class="java.lang.Boolean"/> <filterExpression><![CDATA[$F{name} != null && $F{name}.length() != 0]] ></filterExpression> </subDataset> <subDataset name="PathLocationDataset"> <property name="net.sf.jasperreports.data.adapter" value="/data/PathLocationDataAdapter.jrdax"/> <queryString language="csv"> <![CDATA[]] > </queryString> <field name="name" class="java.lang.String"/> <field name="style" class="java.lang.String"/> <field name="latitude" class="java.lang.String"/> <field name="longitude" class="java.lang.String"/> <field name="ispolygon" class="java.lang.String"/> <filterExpression> <![CDATA[!($F{latitude}==null || $F{latitude}.length() == 0 || $F{longitude}==null || $F{longitude}.length() == 0)]] > </filterExpression> </subDataset> ... <componentElement> <reportElement x="0" y="150" width="515" height="326" positionType="Float"/> <c:map xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" mapType="satellite" mapScale="1" imageType="jpg" onErrorType="Icon"> <c:latitudeExpression><![CDATA[37.800056f]] ></c:latitudeExpression> <c:longitudeExpression><![CDATA[-122.4075f]] ></c:longitudeExpression> <c:zoomExpression><![CDATA[$P{zoom} + 1]] ></c:zoomExpression> <c:markerData> <dataset> <datasetRun subDataset="MarkersDataset"/> </dataset> <c:item> <c:itemProperty name="latitude"> <valueExpression>$F{latitude}</valueExpression> </c:itemProperty> <c:itemProperty name="longitude"> <valueExpression>$F{longitude}</valueExpression> </c:itemProperty> <c:itemProperty name="color"> <valueExpression>$F{color}</valueExpression> </c:itemProperty> <c:itemProperty name="size"> <valueExpression>$F{size}</valueExpression> </c:itemProperty> <c:itemProperty name="url"> <valueExpression>$F{url}</valueExpression> </c:itemProperty> <c:itemProperty name="target"> <valueExpression>"_blank"</valueExpression> </c:itemProperty> </c:item> </c:markerData> <c:pathStyle> <dataset> <datasetRun subDataset="PathStyleDataset" uuid="2f83580b-a7e7-496e-8eca-d2993a5f1120"/> </dataset> <c:item> <c:itemProperty name="name"> <valueExpression><![CDATA[$F{name}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="strokeColor"> <valueExpression><![CDATA[$F{strokecolor}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="strokeOpacity"> <valueExpression><![CDATA[$F{strokeopacity}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="strokeWeight"> <valueExpression><![CDATA[$F{strokeweight}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="fillColor"> <valueExpression><![CDATA[$F{fillcolor}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="fillOpacity"> <valueExpression><![CDATA[$F{fillopacity}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="draggable"> <valueExpression><![CDATA[$F{draggable}]] ></valueExpression> </c:itemProperty> </c:item> </c:pathStyle> <c:pathData> <dataset> <datasetRun subDataset="PathLocationDataset" uuid="b9d465b5-397d-4c65-8814-e85e757c97d0"/> </dataset> <c:item> <c:itemProperty name="name"> <valueExpression><![CDATA[$F{name}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="style"> <valueExpression><![CDATA[$F{style}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="latitude"> <valueExpression><![CDATA[$F{latitude}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="longitude"> <valueExpression><![CDATA[$F{longitude}]] ></valueExpression> </c:itemProperty> <c:itemProperty name="isPolygon"> <valueExpression><![CDATA[$F{ispolygon}]] </valueExpression> </c:itemProperty> </c:item> </c:pathData> </c:map> </componentElement>Map #5: Hybrid Map with Custom Icons and Info Windows The last sample is loaded from reports/MapReport5.jrxml template. Markers provide custom icons and tooltips. Clicking on
a marker icon will open an info window with related information about the marker position. The value of the infowindow.content
property is a HTML fragment with escaped open and end tags.
<subDataset name="MarkersDataset"> <property name="net.sf.jasperreports.data.adapter" value="/data/CsvDataAdapter.jrdax"/> <queryString language="csv"> <![CDATA[]] > </queryString> <field name="address" class="java.lang.String"/> <field name="latitude" class="java.lang.String"/> <field name="longitude" class="java.lang.String"/> <field name="iconurl" class="java.lang.String"/> <field name="iconwidth" class="java.lang.Integer"/> <field name="iconheight" class="java.lang.Integer"/> <filterExpression> <![CDATA[!($F{latitude}==null || $F{latitude}.length() == 0 || $F{longitude}==null || $F{longitude}.length() == 0)]] > </filterExpression> </subDataset> ... <componentElement> <reportElement x="0" y="150" width="515" height="326" positionType="Float"/> <c:map xmlns:c="http://jasperreports.sourceforge.net/jasperreports/components" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports/components http://jasperreports.sourceforge.net/xsd/components.xsd" mapScale="1" imageType="jpg" mapType="hybrid" onErrorType="Icon"> <c:latitudeExpression><![CDATA[37.800056f]] ></c:latitudeExpression> <c:longitudeExpression><![CDATA[-122.4075f]] ></c:longitudeExpression> <c:zoomExpression><![CDATA[$P{zoom} + 1]] ></c:zoomExpression> <c:markerData> <dataset> <datasetRun subDataset="MarkersDataset"/> </dataset> <c:item> <c:itemProperty name="latitude"> <valueExpression>$F{latitude}</valueExpression> </c:itemProperty> <c:itemProperty name="longitude"> <valueExpression>$F{longitude}</valueExpression> </c:itemProperty> <c:itemProperty name="title"> <valueExpression>$F{address}</valueExpression> </c:itemProperty> <c:itemProperty name="icon.url"> <valueExpression>$F{iconurl}</valueExpression> </c:itemProperty> <c:itemProperty name="icon.width"> <valueExpression>$F{iconwidth}</valueExpression> </c:itemProperty> <c:itemProperty name="icon.height"> <valueExpression>$F{iconheight}</valueExpression> </c:itemProperty> <c:itemProperty name="infowindow.content"> <valueExpression>"<p style='text-align:right;'><img src='https://jasperreports.sourceforge.net/jasperreports.png'/></p> <p style='text-align:left;'>current latitude: <b>"+$F{latitude}+"</b><br/>current longitude: <b>"+$F{longitude}+"</b></p>" </valueExpression> </c:itemProperty> </c:item> </c:markerData> </c:map> </componentElement>Running the Sample Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/samples/map within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/map/build/reports directory.
Then the report will open in the JasperReports internal viewer. |
||||
|
|
© 2001- Cloud Software Group, Inc. www.jaspersoft.com |