<?xml version="1.0" encoding="UTF-8"?>

<sample>

  <name>map</name>
  <title>Map Component Sample</title>
  <description>Illustrates the usage of the map component element.</description>

  <mainFeature ref="map"/>
  
  <!-- map -->
  
  <feature name="map" title="Using the Built-in Map Component">
    <description>
How to render maps using the built-in map component.
    </description>
    <since>4.1.1</since>
    <documentedBy>
      <author>
      <name>Sanda Zaharia</name>
      <email>shertage@users.sourceforge.net</email>
      </author>
    </documentedBy>
    <content>
<b>Map Component Overview</b>    
<br/>
<br/>
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. 
<br/>
<br/>
<b>Important notes:</b>
<ol><li>
<b>The JR built-in <code>map</code> component is based on the public 
<a href="http://code.google.com/apis/maps/documentation/javascript/reference.html">Google Maps APIs</a> licensed 
under the <a href="http://creativecommons.org/licenses/by/3.0">Creative Commons Attribution 3.0 License</a>. Prior to 
start using this component, please consult both <a href="https://developers.google.com/maps/terms">Google terms of service</a> 
and <a href="https://developers.google.com/readme/policies">Google site policies</a> pages. 
<br/>
Ensure the map component in your application is used in accordance with these terms and conditions.</b><br/> <br/></li>
<li><b>In order to get accurate results with Google maps, you need to set the <code>net.sf.jasperreports.components.map.key</code> 
property with an appropriate Google API key value. <br/>The Google API key must be enabled for Google Javascript API, Google Maps Static API 
and Google Geocoding API. More information about API keys can be found at 
<a href='https://developers.google.com/maps/gmp-get-started'>https://developers.google.com/maps/gmp-get-started</a>.<br/>The 
<code>net.sf.jasperreports.components.map.key</code> property can be set either in the report itself or per report context.</b></li>
</ol>
<br/>


The current <code>map</code> component description is found in the <a href="../../components.schema.reference.html">components.xsd</a> schema:
<pre><![CDATA[
<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>]]></pre>
<b>Map Attributes</b>
<br/>    
<br/> 
One can customize the map component using the following attributes:
<ul>
<li><code>mapType</code> - indicates the map type. Possible values are:
<ul>
<li><code>roadmap</code> (default)</li>
<li><code>satellite</code></li>
<li><code>terrain</code></li>
<li><code>hybrid</code><br/><br/></li>
</ul>
</li>
<li><code>mapScale</code> - represents the <code>scale</code> value used to return higher-resolution map images when 
working with high resolution screens available on mobile devices.  Possible values are:
<ul>
<li><code>1</code> (default)</li>
<li><code>2</code></li>
<li><code>4</code> (for Business customers only)<br/><br/></li>
</ul>
</li>
<li><code>imageType</code> - represents the image format of the map. Possible values are:
<ul>
<li><code>png</code> (default)</li>
<li><code>png8</code></li>
<li><code>png32</code></li>
<li><code>gif</code></li>
<li><code>jpg</code></li>
<li><code>jpg-baseline</code></li>
</ul>
</li>
<li><code>onErrorType</code> - Applies to static maps only. This attribute specifies the behavior of the engine when the image is not available. Possible values are:
<ul>
<li><code>Error</code> - An exception is raised when loading the map image. This is the default behavior.</li>
<li><code>Blank</code> - The exception is ignored and the map image displays as blank.</li>
<li><code>Icon</code> - The exception is ignored and an image replacement icon is displayed.</li>
</ul>
</li>
</ul>   
<b>The Latitude Expression</b>    
<br/>
<br/>
The <code>&lt;c:latitudeExpression/&gt;</code> 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&#176; to 90&#176;.
<br/>
<br/>
<b>The Longitude Expression</b>    
<br/>
<br/>
The <code>&lt;c:longitudeExpression/&gt;</code> 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&#176; to 180&#176;.
<br/>
<br/>
<b>The Address Expression</b>    
<br/>
<br/>
The <code>&lt;c:addressExpression/&gt;</code> 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. 
<br/>
<br/>
<b>The Zoom Expression</b>    
<br/>
<br/>
The <code>&lt;c:zoomExpression/&gt;</code> represents the initial map zoom level. The expression allows integer values and defaults to 0. 
<br/>
<br/>
<b>The Language Expression</b>    
<br/>
<br/>
The <code>&lt;c:languageExpression/&gt;</code> 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 
<a href="https://spreadsheets.google.com/spreadsheet/pub?key=0Ah0xU81penP1cDlwZHdzYWkyaERNc0xrWHNvTTA1S1E&amp;gid=1" target="_blank">here</a>.
<br/>
<br/>
<b>The Marker Dataset</b>   
<br/>
<br/>
<b>Warning:</b> The <code><b>&lt;c:markerDataset/&gt;</b></code> element is now <b>deprecated</b>, as replaced by the <a href="#markerData"><b>&lt;c:markerData/&gt;</b></a> element below:
<!--
<br/>
<br/>
The <code>&lt;c:markerDataset/&gt;</code> element still can be 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 elements as shown in the component schema. 
<br/>
The marker element contains a list of specific properties that can be set either by value or by valueExpression. With few exceptions, property names must 
match the names of supported marker options available <a href="https://developers.google.com/maps/documentation/javascript/reference#MarkerOptions" target="_blank">here</a>. 
<br/>
The exceptions are the <code>latitude</code> and <code>longitude</code> property names, both required in order to compute the marker position on the map. If at least one 
of these two properties is missing or is empty, an exception will be thrown.
<br/>
<br/>
<b>Note:</b> To avoid such exceptions when using a subdataset, use a <code>&lt;filterExpression&gt;</code> to skip markers with empty latitude/longitude 
properties. An example can be found in the map component sample.
-->
<br/>
<br/>
<subtitle name="markerData">The Marker Data Element</subtitle>
<br/>
<br/>
The <code>&lt;c:markerData/&gt;</code> 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. 
<br/>
The marker item element contains a list of specific item properties that can be set either by <code>value</code> or by <code>valueExpression</code>. If both are set, the 
<code>valueExpression</code> takes precedence over the <code>value</code> attribute. With few exceptions, property names must 
match the names of supported marker options available <a href="https://developers.google.com/maps/documentation/javascript/reference#MarkerOptions" target="_blank">here</a>. 
<br/>
The main exception is the <code>position</code> option, currently undefined in JR. It is actually replaced by the <code>latitude</code> and <code>longitude</code> 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 <code>address</code> property. 
If no address is available, an exception will be thrown. 
<br/>
<br/>
<b>Warnings:</b> 
<ul>
<li>To avoid such exceptions when using a subdataset, use a <code>&lt;filterExpression&gt;</code> to skip markers with empty latitude/longitude and address 
properties. A data filtering example can be found in the map component sample.
</li>
<li>The intensive use of the <code>address</code> property is not recommended, because it will definitely slow the report generation. Try to use the latitude and longitude 
properties when they are available.</li>
</ul>
Below is a list of valid <code>itemProperty</code> names:
<ul>
<li><code>latitude</code> - floating-point value</li>
<li><code>longitude</code> - floating-point value</li>
<li><code>address</code> - optional; string value; considered only when latitude and/or longitude are missing or empty</li>
<li><code>title</code> - string value</li>
<li><code>url</code> - string value. Link to a page or document that will be open when the marker is clicked on. See also <a href="#infoWindows">Info Windows</a></li>
<li><code>target</code> - string value. The target window/frame to load the marker URL. Allowed values are:
<ul>
<li><code>_blank</code> - the URL is loaded into a new window</li>
<li><code>_parent</code> - the URL is loaded into the parent frame</li>
<li><code>_self</code> - the URL replaces the current page</li>
<li><code>_top</code> - the URL replaces any framesets that may be loaded</li>
<li>a valid window/frame name</li>
</ul>
</li>
<li><code>icon</code> - string value (representing the icon URL). See also <a href="#customIcons">Custom Icons</a></li>
<li><code>shadow</code> - string value (representing the shadow icon URL). See also <a href="#customIcons">Custom Icons</a></li>
<li><code>color</code> - string value representing the color for the default pin icons. This property is taken into account when none of  
<code>icon</code> or <code>icon.url</code> properties are set. Its value may represent:
<ul>
<li>one of the predefined color names in the following list (see also <api href="net/sf/jasperreports/engine/type/ColorEnum.html">ColorEnum</api>):
<ul>
<li><code>black</code></li>
<li><code>blue</code></li>
<li><code>cyan</code></li>
<li><code>darkGray</code></li>
<li><code>gray</code></li>
<li><code>green</code></li>
<li><code>lightGray</code></li>
<li><code>magenta</code></li>
<li><code>orange</code></li>
<li><code>pink</code></li>
<li><code>red</code></li>
<li><code>yellow</code></li>
<li><code>white</code></li>
</ul>
</li>
<li>a valid color hex code (prefixed by #). For instance: #0000FF.</li>
<li>the color RGB value.</li>
</ul>
</li>
<li><code>label</code> - string value representing the label for the default pin icons. This property is taken into account when none of  
<code>icon</code> or <code>icon.url</code> properties are set.
<br/>
<br/>
<b>Note:</b> Unlike interactive maps, Google static maps require single uppercase alphanumeric character labels. If multiple character 
labels are set, the JR engine will process the entire label for dynamic maps and only the first character in the label for static maps. 
Labels are displayed only for default and mid sized markers, small and tiny markers provide no capability to display labels.
<br/>
<br/>
</li>
<li><code>cursor</code> - string value</li>
<li><code>zIndex</code> - integer value</li>
<li><code>clickable</code> - boolean value</li>
<li><code>draggable</code> - boolean value</li>
<li><code>flat</code> - boolean value</li>
<li><code>optimized</code> - boolean value</li>
<li><code>raiseOnDrag</code> - boolean value</li>
<li><code>visible</code> - boolean value</li>
<li><code>size</code> - predefined string value. This property is considered for static maps only. See the 
<a href="#googleStaticMaps">Google Static Maps</a> section.</li>
</ul>
<subtitle name="customIcons">Custom Icons</subtitle>
<br/>
<br/>
Both <code>icon</code> and <code>shadow</code> 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:
<br/>
<br/>
For marker icons:
<ul>
<li><code>icon.url</code> - string value (representing the custom icon URL). If set, it takes precedence over the <code>icon</code> property.</li>
<li><code>icon.width</code> - integer value representing the icon width, in pixels. To be considered, <code>icon.height</code> must be also set.</li>
<li><code>icon.height</code> - integer value representing the icon height, in pixels. To be considered, <code>icon.width</code> must be also set.</li>
<li><code>icon.origin.x</code> - integer value representing the horizontal position of the image within a sprite, if any, in pixels. Default value is <code>0</code>.</li>
<li><code>icon.origin.y</code> - integer value representing the vertical position of the image within a sprite, if any, in pixels. Default value is <code>0</code>.</li>
<li><code>icon.anchor.x</code> - integer value representing the horizontal position to anchor an image with respect to the location of the marker on the map. 
Default value is <code>0</code>.</li>
<li><code>icon.anchor.y</code> - integer value representing the vertical position to anchor an image with respect to the location of the marker on the map. 
Default value is <code>0</code>.</li>
</ul>
For shadow icons:
<ul>
<li><code>shadow.url</code> - string value (representing the custom shadow icon URL). If set, it takes precedence over the <code>shadow</code> property.</li>
<li><code>shadow.width</code> - integer value representing the shadow icon width, in pixels. To be considered, <code>shadow.height</code> must be also set.</li>
<li><code>shadow.height</code> - integer value representing the shadow icon height, in pixels. To be considered, <code>shadow.width</code> must be also set.</li>
<li><code>shadow.origin.x</code> - integer value representing the horizontal position of the shadow image within a sprite, if any, in pixels. Default value is <code>0</code>.</li>
<li><code>shadow.origin.y</code> - integer value representing the vertical position of the shadow image within a sprite, if any, in pixels. Default value is <code>0</code>.</li>
<li><code>shadow.anchor.x</code> - integer value representing the horizontal position to anchor a shadow image with respect to the location of the marker on the map. 
Default value is <code>0</code>.</li>
<li><code>shadow.anchor.y</code> - integer value representing the vertical position to anchor a shadow image with respect to the location of the marker on the map. 
Default value is <code>0</code>.</li>
</ul>
<subtitle name="infoWindows">Info Windows</subtitle>
<br/>
<br/>
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 <a href="http://www.w3schools.com/tags/ref_entities.asp">here</a>.) 
<br/>
If both <code>url</code> 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.
<br/>
To configure an info window, the following item properties are available:
<ul>
<li><code>infowindow.content</code> - string value. Represents the content to be displayed in an info window, processed as HTML fragment. Is mandatory for info windows. 
Empty contents are not processed.</li>
<li><code>infowindow.latitude</code> - floating-point value. Represents the latitude used to determine the info window position on the map. Neglected for info windows attached to markers.</li>
<li><code>infowindow.longitude</code> - floating-point value. Represents the longitude used to determine the info window position on the map. Neglected for info windows attached to markers.</li>
<li><code>infowindow.pixelOffset</code> - integer value. Represents the offset (in pixels) from the tip of the info window to the location on which the info window is anchored.</li>
<li><code>infowindow.maxWidth</code> - integer value. Specifies the maximum width in pixels of the info window</li>
</ul>
<subtitle name="paths">Paths on Google Maps</subtitle>
<br/>
<br/>
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:
<ul>
<li>an ordered sequence of points to be connected. The sequence must contain at least 2 points in order to be considered.</li>
<li>various style descriptors (such as line color, opacity or weight), in order to create custom appearances for paths</li>
</ul>
<subtitle name="pathData">The Path Data Element</subtitle>
<br/>
<br/>
Points that have to be connected in a path are grouped into the <code>&lt;pathData/&gt;</code> element. A path data element is very similar to the 
<a href="#markerData">marker data element</a> 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 <code>latitude</code> and <code>longitude</code>, or the equivalent <code>address</code> 
property from the following list of allowed properties:
<ul>
<li><code>latitude</code> - floating-point value</li>
<li><code>longitude</code> - floating-point value</li>
<li><code>address</code> - optional; string value</li>
<li><code>name</code> - optional; string value. Represents the identifier of a given path, necessary when multiple paths have to be represented on the same map. 
Points with the same <code>name</code> property belong to the same path. If not provided, the point will be added to the default path.</li>
<li><code>style</code> - optional; string value. Represents the name of a given path style (path styles are discussed in the next section of this document). 
If not provided, the path will be generated using Google default style settings for paths.</li>
<li><code>strokeColor</code> - optional; string value. Represents the path line color. Named colors are not supported for all Google Maps APIs, so the hex value 
representation for the color would be more suited in this case.</li>
<li><code>strokeOpacity</code> - optional; numeric value between 0 and 1 (default). Represents the path line opacity. 1 means 100% opaque, 0 means 100% transparent.</li>
<li><code>strokeWeight</code> - optional; integer value. Represents the path line weight in pixels. Default value is 5.</li>
<li><code>fillColor</code> - optional; string value. Considered for polygons only, represents the fill color for the polygonal contour. Also named colors are 
not recommended in this case.</li>
<li><code>fillOpacity</code> - optional; numeric value between 0 (default) and 1. Considered for polygons only, represents the fill opacity for the polygonal contour. 
1 means 100% opaque, 0 means 100% transparent.</li>
<li><code>isPolygon</code> - optional; boolean value. If set to <code>true</code> the last point in the path is connected to the first point in order to form a polygon (closed path).
Default value is <code>false</code></li>
<li><code>clickable</code> - optional; boolean value. If set to <code>true</code>, the path object may handle mouse events. Defaults to <code>true</code>.</li>
<li><code>editable</code> - optional; boolean value. If set to <code>true</code>, the user may edit the path using the control points shown along the path line. Defaults to <code>false</code>.</li>
<li><code>draggable</code> - optional; boolean value. If set to <code>true</code>, the user may drag the path contour over the map. Defaults to <code>false</code>.</li>
<li><code>geodesic</code> - optional; boolean value. Defines the mode of dragging. If set to <code>true</code>, edges of the polygon are interpreted as geodesic and will 
follow the curvature of the Earth when the path contour is dragged. Defaults to <code>false</code>.</li>
<li><code>visible</code> - optional; boolean value. If set to <code>true</code>, the path is visible on the map. Defaults to <code>true</code>.</li>
<li><code>zIndex</code> - optional; integer value. Represents the zIndex compared to other path elements</li>
<li><code>path.hyperlink</code> - optional; string value. Represents the hyperlink associated with this path on click event.</li>
<li><code>path.hyperlink.target</code> - optional; string value. Represents the hyperlink target associated with this path on click event. Allowed values are:
<ul>
<li><code>_blank</code></li>
<li><code>_parent</code></li>
<li><code>_self</code></li>
<li><code>_top</code></li>
<li>a valid window/frame name</li>
</ul>
</li>
</ul>
<b>Notes:</b> 
<ul>
<li>A map component may contain 0, one or several <code>&lt;pathData/&gt;</code> elements.</li>
<li>Points in a given path are connected one by one, in the same order they were declared in the report. To get consistent results, make sure items 
in the path data element are declared in the right order.</li>
<li>If points in the same path provide different values for the same item property, the property value will be set by the last point in the path that provides this property.</li>
<li>The intensive use of the <code>address</code> property is not recommended, because it will definitely slow the report generation. Try to use the latitude and longitude 
properties when they are available.</li>
</ul>
<subtitle name="pathStyle">The Path Style Element</subtitle>
<br/>
<br/>
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 <code>&lt;pathStyle/&gt;</code> element, 
very similar to <code>&lt;pathData/&gt;</code>, excepting the <code>latitude</code> and <code>longitude</code> properties that are not considered in a path style.
<br/>
Below is the list of allowed properties in a path style, with the same meaning and defaults (excepting the <code>name</code> property) as in the path data element:
<ul>
<li><code>name</code> - required; string value. Represents the name (unique identifier) of a given style.</li>
<li><code>style</code> - optional; string value. Represents the name of a parent path style. If present, all the properties in the parent style will be inherited by the current style.
The own properties of the current style will override the parent properties.</li>
<li><code>strokeColor</code></li>
<li><code>strokeOpacity</code></li>
<li><code>strokeWeight</code></li>
<li><code>fillColor</code></li>
<li><code>fillOpacity</code></li>
<li><code>isPolygon</code></li>
<li><code>clickable</code></li>
<li><code>editable</code></li>
<li><code>draggable</code></li>
<li><code>geodesic</code></li>
<li><code>visible</code></li>
<li><code>zIndex</code></li>
<li><code>path.hyperlink</code></li>
<li><code>path.hyperlink.target</code></li>
</ul>
<b>Notes:</b> 
<ul>
<li>A map component may contain 0, one or several <code>&lt;pathStyle/&gt;</code> elements.</li>
<li>If style items with the same name provide different values for the same item property, the property value will be set by the last item in the list that provides this property.</li>
<li>If present, an own style property in a path data item will override the same property inherited from the path style.</li>
</ul>
<subtitle name="googleStaticMaps">Google Static Maps</subtitle>
<br/>
<br/>
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.
<br/>
In these conditions, not all item properties defined for markers are considered in static maps. The available properties in this case are:
<ul>
<li><code>latitude</code></li>
<li><code>longitude</code></li>
<li><code>icon</code> - the icon URL has to be accessible for the Google Static Map service</li>
<li><code>icon.url</code> - the icon URL has to be accessible for the Google Static Map service</li>
<li><code>color</code></li>
<li><code>label</code></li>
<li><code>size</code> - predefined string value. Specifies the marker size (for the built-in markers only). Allowed values are:
<ul>
<li><code>mid</code></li>
<li><code>tiny</code></li>
<li><code>small</code></li>
</ul>
If no size is set, the default icon is loaded with its normal size
</li>
</ul>
For similar reasons, path style properties considered in static maps are the following:
<ul>
<li><code>strokeColor</code></li>
<li><code>strokeOpacity</code></li>
<li><code>strokeWeight</code></li>
<li><code>fillColor</code></li>
<li><code>fillOpacity</code></li>
<li><code>isPolygon</code></li>
<li><code>geodesic</code></li>
</ul>
<b>Map Component Example</b>    
<br/>
<br/>
The JRXML sample contains five <code>map</code> 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 <code>data</code> subfolder.
<br/>
<br/>
<subtitle name="map1">Map #1: Simple Road Map</subtitle>
<br/>
<br/>
The first map is loaded from the <code>reports/MapReport1.jrxml</code> template, and illustrates a road map with minimal settings. There are no 
markers and no additional information on the map:
<pre><![CDATA[
<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>]]></pre>
<subtitle name="map2">Map #2: Satellite Map with Default Marker Icons</subtitle>
<br/>
<br/>
The second map is loaded from the <code>reports/MapReport2.jrxml</code> template. One can notice the <code>mapType="satellite" mapScale="1" imageType="jpg"</code> 
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 
<code>&lt;c:markerData/&gt;</code> section which collects its data from the <code>MarkersDataset</code> subdataset. Data with invalid latitude/longitude values are 
skipped due to the <code>&lt;filterExpression/&gt;</code> in the subdataset:
<pre><![CDATA[
<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>]]></pre>
The map component configuration is the following:
<pre><![CDATA[
<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>]]></pre>
<subtitle name="map3">Map #3: Terrain Map with Custom Marker Icons</subtitle>
<br/>
<br/>
The 3rd map is a terrain sample loaded from the <code>reports/MapReport3.jrxml</code> template. It comes with the same set of markers as 
<a href="#map2">Map #2</a>, 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):
<pre><![CDATA[
<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>]]></pre>
<subtitle name="map4">Map #4: Satellite Map with Marker Hyperlinks and Paths</subtitle>
<br/>
<br/>
In the 4th sample loaded from the <code>reports/MapReport4.jrxml</code> 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.
<br/>
<br/>
Two additional subdatasets were added in order to generate path styles and path data.See the configuration below:
<pre><![CDATA[
<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>]]></pre>
<subtitle name="map5">Map #5: Hybrid Map with Custom Icons and Info Windows</subtitle>
<br/>
<br/>
The last sample is loaded from <code>reports/MapReport5.jrxml</code> 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 <code>infowindow.content</code> 
property is a HTML fragment with escaped open and end tags.
<pre><![CDATA[
<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>
]]></pre>
<b>Running the Sample</b>
<br/>
<br/>
Running the sample requires the <a href="http://ant.apache.org/">Apache Ant</a> library. Make sure that <code>ant</code> is already installed on your system (version 1.5 or later).
<br/>
In a command prompt/terminal window set the current folder to <code>demo/samples/map</code> within the JasperReports source project and run the <code>&gt; ant test view</code> command.
<br/>
It will generate all supported document types containing the sample report in the <code>demo/samples/map/build/reports</code> directory. 
<br/>
Then the report will open in the JasperReports internal viewer.
    </content>
  </feature>

</sample>
