Working With the Map Component

The Map element in the Palette view lets you add Google Maps to your reports. You can set the center, zoom, and scale for your map, as well as static and dynamic markers and paths. The Properties view for a map element has tabs to control appearance and map properties, set authentication for Google business license, and create markers and paths.

To add a Map component to your report:

Drag the Map component

This topic contains the following sections:

•

Working with Map Properties

•

Viewing Authentication Properties

•

Working with Markers

•

Working with Paths

•

Properties for Markers and Paths

Working with Map Properties

The Map tab in the Properties view lets you set the basic properties for the map:

Select a map component in your report and click Map in the Properties view.

Map tab in Map Properties

You can set the following map properties using the Map tab:

•

Map Preview – Opens a Google Maps window. This window supports standard Google Maps functionality, such as dragging, zooming, and switching between Map and Satellite views.

Setting a map location

Changes to this window are reflected in the map in your report. In addition, the following actions are available:

•

Address Lookup – Enter an address in the entry bar. Then press Enter or click the search button

You must click

•

Right-click – Right-click on any location to display a context menu with the following options:

•

Zoom in

•

Zoom out

•

Center map here – Selecting this option sets the latitude and longitude for your map center. However, if you previously entered text for the Address, this text is not removed.

•

Map Type – The Google Maps view. Options are: roadmap, satellite, terrain, and hybrid.

•

Latitude – The latitude of the map center. You can type directly in the entry bar, or click

•

Longitude – The longitude of the map center. You can type directly in the entry bar, or click

•

Address – A String representing the address of the center. You can type directly in the entry bar, or click

•

Zoom – Integer representing the Google Maps zoom level. You can type directly in the entry bar, or click

•

Language – String that sets the in-map language. You can type directly in the entry bar, or click

•

Map Scale – Sets the size of the scale bar at the bottom of the map.

•

Evaluation Time – Drop-down that lets you set the evaluation time of the map. See Evaluation Time for more information.

•

Image Type – Drop-down that lets you set the image type to use when the map is embedded in your report.

•

On Error Type – Drop-down that lets you set the type of message to display when there is an error with the map.

Viewing Authentication Properties

If you want to use a Google Maps key or business client license, we recommend that you configure these as global Jaspersoft® Studio properties. You can view the status of your Google Maps license information on the Authentication tab.

Authentication tab in Properties view for a map component

To configure your Google Maps license and/or version information:

Select Window > Preferences to open the Preferences dialog box.

Navigate to Jaspersoft Studio > Properties.

To configure a property, click Add to open the Properties dialog, enter the name of the property and the property's value, then click OK. You can configure the following Google Maps APIs properties. See the JasperReports® Library configuration reference for more information on each property:

•

net.sf.jasperreports.components.map.client.id – Specifies the client ID for Google Maps API for Business. If set, it takes precedence over the API key property. Usually works along with the signature property for signed URLs.

•

net.sf.jasperreports.components.map.key – Specifies the Google Maps API key.

•

net.sf.jasperreports.components.map.signature – Specifies the encrypted client signature for signed request URLs.

•

net.sf.jasperreports.components.map.version – Indicates which version of the Google Maps API should be loaded.

When you have specified all your properties, click OK to exit the Preferences dialog box.

Setting the property globally sets the properties when the report is run inside Jaspersoft® Studio. If you are publishing your reports to another environment, you must enable these properties in the jasperreports.properties file in your environment.

Working with Markers

A marker identifies a location on a map. You can create markers for fixed locations that are known when the report is created. You can also dynamically define markers based on locations defined in your report's data. A single map can use both static and dynamic markers, and locations can be based on data from more than one data source. This section describes:

•

Marker Properties

•

Static Markers

•

Dynamic Markers

Marker Properties

You can set properties for each marker. The marker properties available are a subset of Google Maps' properties. See Marker and Path Properties for more information.

Static Markers

Static markers are used for a fixed address or location that is known when the report is created.

To define a static marker:

Open or create a report and add a map component. Make sure to set the map's center to a location near your marker. For this example, use the following coordinates:

Latitude – 37.7656842

Longitude – -122.403

With the map component selected, click the Markers tab in the Properties view.

Markers tab with one marker

(Optional) To specify marker location using the map preview, click Map Preview in the Markers tab. You can use the map preview to perform the following tasks:

•

To set a marker using an address, enter the address in the entry bar. Then press Enter or click the search button

•

To create a marker by selecting a location on the map, right-click on the location you want and select Add marker.

•

To delete a single marker, highlight the marker in the panel at the right and press Delete, or right-click on the marker and select Delete marker.

•

To clear all markers, click Delete markers at the bottom right of the window, or right-click anywhere on the map, and select Delete all markers.

•

To set the map's center, right-click on the location you want and select Center map here.

To specify the marker properties by typing, click Add in the Markers tab.

The Items dialog box opens.

Make sure the Items tab is selected and click Add again.

The Marker dialog box opens.

Defining a static marker

Specify a location for your marker. You can do this by entering latitude and longitude, entering an address, or defining markers on the map preview:

•

Latitude and Longitude – Enter the latitude and longitude coordinates for your marker. You can type directly in the entry bar, or click

•

Latitude – 37.833

•

Longitude – -122.4167

•

Address – The address is used only if Latitude and Longitude are blank. You can type directly in the entry bar, or click

(Optional) Set the title for your marker, if any.

(Optional) To have a new browser window or tab open with related information when a user clicks on the marker, enter the URL and select the Target type.

(Optional) Set your icon type (default or custom) and icon properties:

•

If you are using the default marker, you can set additional properties, such as color, label, etc. These properties are not available for a custom icon. This example uses the color 00CCFF and the label J.

Setting color and label for a marker

•

To use a marker icon other than the default, click Custom Icon to specify a URL that points to the image to use. Currently, we don't support loading an image directly from the repository or as a resource local to the report. Instead, the JavaScript API loads the icon from the URL. Then set additional optional properties for your marker, such as icon height, width, origin, and anchor.

10.

Click OK to return to the Items dialog box.

11.

To create additional markers, click Add, enter the marker properties, then click OK to return to the Items dialog box.

12.

Click OK to create your markers.

13.

Once you have defined your markers, preview your report in HTML. For the example, select the Empty Data Set for your preview.

jss-google-map-static-marker.png.c44449174fad81371308fd8888bb5ee8.png

A map with a marker

Dynamic Markers

The steps above define the marker as a static address known when the report was created. But it is far more useful to dynamically define the markers based on locations defined in your report's data. A single map can use both static and dynamic markers, and locations can be based on data from more than one data source.

Sample Data

In this example, we'll use a CSV file containing the following data for San Francisco landmarks. This file includes data used by markers and paths.

Sample CSV Data for Markers and Paths

landmark, latitude, longitude, path, styleFisherman's Wharf, 37.8085636, -122.409714, path1, style1Golden Gate Bridge, , , path1, style1Cliff House, 37.778485, -122.513963, path1, style1Stern Grove, 37.7358667, -122.4771518, path1, style1Stern Grove, 37.7358667, -122.4771518, path2, style2Golden Gate Park, , , path2, style2Union Square, 37.788527, -122.407235, path2, style2"Willie Mays Plaza, San Francisco, CA", 37.778595, -122.38927, path1, style1Twin Peaks, 37.7544066, -122.4476845, path2, style2[/code]

Define the San Francisco data adapter:

Create a data file with the path data you want. For this example, create a CSV file with the data provided above. Make sure to include a blank line at the end of the file.

Click

Name the file SFDataAdapter.xml and click Next.

Select CSV File as the data adapter type and click Next. The CSV File dialog opens.

Creating a sample data adapter for markers and paths

Name your adapter, for example, SF Landmarks Data Adapter.

Click File and select the CSV file you created.

Click Get column names from the first row of the file.

Select Skip the first line.

Click Finish to create the adapter.

Create a dataset in your report:

Right-click the root node of the report in the outline view and select Create Dataset.

Name the dataset SFLandmarksDataset, make sure Create new dataset from a connection or Data Source is selected, and click Next.

Select the SFDataAdapter.xml data adapter and click Next.

Click >> to select all fields and click Finish.

The dataset is created in your report.

Click on the SFLandmarksDataset in outline view.

In the Properties view, enter SFDataAdapter.xml in the Default Data Adapter entry box. Setting the default data adapter lets you use a different dataset from the one used in the main report. See Default Data Adapter for more information.

Setting the default data adapter for a dataset

Using a dataset to set markers on the map

Add a map component to the report, or select an existing map in the Design tab.

If you have not set the map center or zoom level, do so. For this example, click the Map tab in the Properties view, and use the map preview to select "San Francisco, CA" as the center. Then enter 11 in the Zoom field.

Click the Markers tab in the Properties view.

Click Add to open the Items dialog box.

Select the Dataset tab and select Use Dataset.

In the Dataset Run section, select your dataset and accept the default settings. For this example, use SFLandmarksDataset. You have already set the default data adapter for this dataset.

Click the Items tab and then click Add. The Marker dialog box opens.

Using expressions to set markers from a dataset

For a dataset, you typically want to use expressions for your values. For each property you want to read from the dataset, click

•

Latitude – $F{latitude}

•

Longitude – $F{longitude}

•

Address – $F{landmark}

You can use expressions to pass parameters to a map component dynamically. Expressions allow you to evaluate data in your dataset and use the results to populate the map. In the component's properties, properties based on expressions show f(x) next to the field.

Click OK. The Items dialog box displays the markers you just created.

Item data for markers created from a dataset

10.

Click OK. Your markers are displayed on the Marker tab of the Properties view, along with any other markers you have created.

Properties view showing both static and dynamic markers

11.

Preview your report in HTML. The example below shows the markers from the sample dataset along with a static marker.

jss-google-maps-markers-result.png.1b40428d6dbe2a335f3e649ea05cd6fa.png

San Francisco landmarks shown on a map

Modifying Markers

To edit a marker:

Select the map and click on the Markers tab in Properties view.

Select the marker you want to change and click Edit.

To change the dataset, make sure you have set up another dataset in your report before editing the marker. Then you can select the Dataset tab here and select the new dataset from the Dataset Run menu.

To change marker properties, select the Items tab, and edit your properties.

To delete a marker:

Select the map and click on the Markers tab in Properties view.

Select the marker you want to delete and click Delete.

Working with Paths

You can add one or more paths to your maps. A path is defined by:

•

A name that serves as a path identifier; the name must be unique in your report

•

A collection of places (points) on the map defined by latitude/longitude coordinates or addresses; these are connected to form the path

•

(Optional) A style that specifies various style configuration properties, such as line and fill color, line weight, and opacity

Defining Path Styles

A path style specifies the properties (for example, color and weight) of the lines between the points on your path. See Marker and Path Properties for more information. You can create a path style manually, or you can save your path styles as a dataset.

Defining Path Styles Statically

Edit the map component's properties.

On the Paths tab, in the Styles section, click Add.

In the Style dialog box, enter the properties you want for the path. See Marker and Path Properties for more information about available properties.

Click OK.

Defining Path Styles Dynamically

Sample CSV Data for Path Styles

name, strokecolor, strokeopacity, strokeweight, fillcolor, fillopacity, ispolygon"style1", "#0000FF", 0.6, 1, "#FF33FF", 0.4, true"style2", "#FF0000", 0.8, 2, , , false[/code]

Create a data adapter for your path styles:

Create a data file with the path data you want. For this example, create a CSV file with the data provided above. Make sure to include a blank line at the end of the file.

Click

When prompted, navigate to the same folder as your report.

For this example, name the file PathStylesDataAdapter.xml and click Next.

Select CSV File as the data adapter type and click Next.

Name your adapter, for example, Path Styles Adapter.

Click File and select the CSV file you created.

For this example, click Get column names from the first row of the fileand select Skip the first line.

Click Finish to create the adapter.

Create a dataset in your report:

Right-click the root in the outline view and select Create Dataset.

Name the dataset and click Next. For this example, name the dataset PathStyles.

Select the data adapter for your path styles (Path Styles Data Adapter) and click Next.

Click >> to select all fields and click Finish.

Select the dataset (PathStyles) you just created in outline view.

In the Properties view, enter the filename of the data adapter (PathStylesDataAdapter.xml) in the Default Data Adapter entry box. Setting the default data adapter lets you use a different dataset from the one used in the main report. See Default Data Adapter for more information.

Define a style using a dataset:

Create your data source, a data adapter that points to it, and a dataset that uses the data adapter.

Add a map component to the report, or select an existing map in the Design tab.

Select the Paths tab in the Properties view.

In the Styles section, click Add to open the Items dialog box.

Click the Dataset tab in the Path dialog box and select Use Dataset.

In the Dataset Run section, select your styles dataset (PathStyles) and accept the default settings. You have already set the default data adapter for this dataset.

Select the Items tab and click Add to open the Style dialog box.

For each property you want to read from the dataset, click

•

Name – $F{name}

•

Stroke Color – $F{strokecolor}

•

Stroke Opacity – $F{strokeopacity}

•

Stroke Weight – $F{strokeweight}

•

Fill Color – $F{fillcolor}

•

Fill Opacity – $F{fillopacity}

•

Is Polygon– $F{ispolygon}

Click OK to return to the Items dialog box.

10.

Click OK to create the style set.

Dynamic styles on the Path tab of the Properties view for a map

Defining a Path Statically

To define a path using the Add button:

On the Paths tab, use the Styles section to define a style to associate with the path: click Add to do so.

Style properties can be added manually or by specifying a dataset. The style name sets the style property when adding points to the path.

In the Paths section, click Add to add points to the path. In the Path dialog box, for each point, specify:

the path name (to identify which path includes the point)

the latitude/longitude coordinates or the address of the point

additional optional properties, such as the name of a path style

Click OK to add your point.

Use the Up and Down buttons to change the order in which the points appear.

Preview your report in HTML to see your path.

To add points to a path using the map preview:

Click Map Preview in the Paths tab.

Select your path from the Paths menu. The Paths menu has the following characteristics:

•

If you already have static paths defined for your map, you can select a path name from the Paths menu. Points you create are added to the currently-selected path. You can switch between paths at any time.

•

If you have not created any static paths, then you can enter a name on this menu. If a static path already exists, you cannot create a new one.

To add a point to the current path, right-click on the location you want and select Add marker.

To delete a single point, highlight the marker in the panel at the right and press Delete, or right-click on the marker and select Delete marker.

To clear all points from the current path, click Delete Points at the bottom right of the window, or right-click anywhere on the map, and select Delete all markers.

To set the map's center, right-click on the location you want and select Center map here.

You can't set formatting or styles using the map preview.

Defining a Path Dynamically

Create a CSV file, a data adapter that points to it, and a dataset that uses the data adapter. This example uses the same data as in Sample Data. Pay close attention when adding points to your data: they are connected on the map in the order that they appear in the data. If they aren't in a sensible order in the data, the path won't make sense, either.

Define any styles your paths use. This example uses the styles defined in Defining Path Styles Dynamically.

Add a map component to the report, or select an existing map in the Design tab.

If you have not set the center or zoom, do so. For this example, click the Map tab in the Properties view, enter "San Francisco, CA" in the Address field, and enter 11 in the Zoom field.

Select the Paths tab in the Properties view.

In the Paths section, click Add to open the Items dialog box.

Click the Dataset tab in the Items dialog box and select Use Dataset.

In the Dataset Run section, select SFLandmarksDataset and accept the default settings. You have already set the default data adapter for this dataset.

For each property you want to read from the dataset, click

•

Path Name – $F{path}

•

Latitude – $F{latitude}

•

Longitude – $F{longitude}

•

Address – $F{landmark}

•

Style – $F{style}

10.

Click OK. The path information is added to the Path section in the Properties view.

11.

Preview your report in HTML. The following image shows the example without markers. If you added the markers earlier, they will also be visible.

Paths on a map

Modifying Paths and Path Styles

To edit a path or path style:

Select the map and click on the Paths tab in Properties view.

Select the path or style you want to change and click Edit.

To change the dataset, make sure you have set up another dataset in your report before editing the path or path style. Then you can select the Dataset tab here and select the new dataset from the Dataset Run menu.

To change path or style properties, select the Items tab, and edit your properties.

To delete a path or path style:

Select the map and click on the Paths tab in Properties view.

Select the path or style you want to delete and click Delete.

Properties for Markers and Paths

The available properties are a subset of the properties available through the Google Maps APIs. See https://developers.google.com/maps for more information.

Marker and Path Properties

Property

Description

Name

String. Name used to identify the marker or path; must be unique for markers or paths in the report.

Latitude Number between -90 and 90. The latitude of a location in degrees. Longitude Number between -180 and 180. The longitude of a location in degrees. Address String. The address or placeID of a location. Only used if Latitude and Longitude are not available. Color String. The color of the path or marker. For best results, use hexadecimal representation, as not all Google API implementations will support color strings. Clickable Boolean. When true, the marker or path can handle mouse events. Default is true. Draggable Boolean. When true, a user can drag the marker or path contour. Default is false. Visible Boolean. When true, the marker or path is visible. Defaults to true. Z Index Number. Index determining the order in which objects are displayed on the map. Elements with higher values are displayed in front of similar elements with lower values. Markers are always displayed in front of paths. Properties for Markers Only Title String. Text shown on rollover. Url String. Target URL to access when marker is clicked. Target String. Target attribute specifying where to open linked document. Icon String. URL for the icon. Custom Icon

Use Custom Icon settings to use a marker icon other than the default. You must specify a URL that points to the image to use. Currently, we don't support loading an image directly from the repository or as a resource local to the report. Instead, the JavaScript API loads the icon from the URL.

You can set additional optional properties for your marker, such as icon height, width, origin, and anchor.

Shadow String. URL for the shadow. Custom Shadow Icon

Use Custom Shadow Icon settings to use a shadow icon other than the default. You must specify a URL that points to the image to use. Currently, we don't support loading an image directly from the repository or as a resource local to the report. Instead, the JavaScript API loads the icon from the URL.

You can set additional optional properties for your shadow, such as height, width, origin, and anchor.

Info Window Use Info Window settings to add an info window. You can define the window content, pixel offset, and maximum width. Label String. Single character that appears on the marker. Not available for custom markers. Cursor String. Mouse cursor to show on hover. Not available for custom markers. Flat Boolean. Not available for custom markers. Optimized Boolean. Not available for custom markers. Raise on Drag Boolean. Not available for custom markers. Size String. Not available for custom markers. Properties for Paths and Path Styles Only Parent Style

String. Name of path style to use as a parent style. The current style inherits the parent's properties if the parent style is present in the report. Elements set locally in the current style override elements set in the parent.

Stroke Color String. Color of the stroke; for most consistent results, use hexadecimal format. Default is #000000. Stroke Opacity Number. The path's opacity. Number between 0 (transparent) and 1 (opaque). Default is 1. Stroke Weight Number. Path weight in pixels. Default Fill Color String. Color of the fill for the polygon when Is Polygon is true. Takes values hexadecimal format. Default is null. Fill Opacity Number. The opacity for the polygon's fill when Is Polygon is true. Number between 0 (transparent) and 1 (opaque). Default is 1. Is Polygon Boolean. When true, creates a polygon (closed path) by connecting the last point on the path to the first point. Default is false (open polyline). Editable Boolean. When true, a user can edit the path by dragging the control points on the path line. Default is false. Geodesic Boolean. When true, dragged paths follow the great circles on the earth's surface; in this case, since the map is a projection, the lines may not appear straight. When false, paths are straight lines on the map. Defaults to false.

Sign In

Working with Map Properties

Viewing Authentication Properties

Working with Markers

Marker Properties

Static Markers

Dynamic Markers

Sample Data

Using a dataset to set markers on the map

Modifying Markers

Working with Paths

Defining Path Styles

Defining Path Styles Statically

Defining Path Styles Dynamically

Defining a Path Statically

Defining a Path Dynamically

Modifying Paths and Path Styles

Properties for Markers and Paths

User Feedback

Recommended Comments

Activity

Products

Explore