Jaspersoft Studio leverages TIBCO GeoAnalytics Maps to produce data-rich maps. This section describes their set-up and configuration, including:
• | Configuring a Basic Map |
• | Using Expressions for Properties |
• | Understanding Layers |
• | Working with Markers |
• | Working with Paths |
This section describes functionality that can be restricted by the software license for JasperReports Server. If you don’t see some of the options described in this section, your license may prohibit you from using them. To find out what you're licensed to use, or to upgrade your license, contact Jaspersoft. |
In addition to the other types of map component that Jaspersoft Studio supports, TIBCO GeoAnalytics Maps are also supported. These multi-layer maps are designed for use in interactive web environments, and support both markers and paths. They also support the ability to provide a street address and resolve it to the correct latitude and longitude (sometimes called geolocation).
Because these components download content from either TIBCO's service or from Google Maps, they require a connection to the Internet. While the maps themselves are freely available, using the GeoAnalytics geolocation serve to resolve street addresses requires an additional license.
These maps are well suited to web-based environments, such as HTML export or when viewed through an interactive viewer such as JasperReports Server; however, limitations in the underlying technology prevent some TIBCO GeoAnalytics Map features from working in static formats, such as PDF. In this case, the map is converted to an image, which is always downloaded from Google Maps instead of TIBCO's server. In addition, if the map's location is resolved from a street address, the canvas may be blank (or blue); this happens when the address's latitude and longitude aren't available. If your target output format is something other than HTML, consider using the standard map component. |
The map component consists of three layers: a map, a set of paths, and a set of markers. The lowest layer contains the map itself, rendered by your choice of providers: TIBCO Maps or Google Maps. In both cases, the image is formed of tiles retrieved from a remote server. The next two layers (first paths then markers) can contain paths and markers or shapes.
Basic structure of the TIBCO GeoAnalytics Map component |
Configuring a Basic Map
To create a TIBCO Map component:
1. | First locate the component in the Palette; it uses this icon: |
At a minimum, the TIBCO Map component requires the location of the area to display, which can be defined by these manually-exclusive options:
a. | The latitude and longitude of the location. |
b. | The street address of the location (assuming you have a license for TIBCO GeoAnalytics geolocation services). To use this option, you must also provide credentials for TIBCO's geolocation service. You can either enter these in the Maparama Credentials section of the TIBCO map component's properties, or by defining them in the jasperreports.properties file so that they can shared across multiple reports. These properties are: |
• | com.jaspersoft.jasperreports.tibco.maps.customer - the customer name used with TIBCO GeoAnalytics Maps |
• | com.jaspersoft.jasperreports.tibco.maps.key - the corresponding license key for the specified user |
2. | To define a location, edit the TIBCO Maps component's Location properties. Entering a latitude/longitude pair or address defines a static location. You can also use parameters to dynamically define the components location as well as all other TIBCO Map properties. |
TIBCO Map Attributes |
Map attributes determine how the map layer of the component is rendered. The attributes are all optional:
Property | Property Value |
Use Canvas true | false This property refers to the way the map is rendered (by using a canvas or SVG layers) |
Opacity | 0.0- 1.0 Level of opacity of the map. |
Max Zoom 1 - 18 | The maximum allowed zoom |
Min Zoom 1 - 18 | The minimum allowed zoom |
Repeat X true | false | Specifies whether tiles are repeated when the world's bounds are exceeded horizontally |
Clip Offset integer | The clip offset of the map |
Using Expressions for Properties
The simplest way to define the map layer's properties is to set them to static values; however, this is a much more limited approach than using expressions to pass parameters to the component dynamically, which allows you to evaluate data in your data set and use the results to populate the map layer's properties. If you don't specify a different data set, the component uses the main dataset of the report. In the components properties, properties based on expressions are indicated by displaying f(x) next to the field, as shown below.
Map properties showing Zoom defined by an expression |
To specify a different dataset to resolve the map attributes based on expressions, click the Use Dataset check box to select it, and select the dataset to use in the Dataset Run.
Defining the Dataset to use to resolve map attribute expressions |
Data Runs are used throughout Jaspersoft Studio and its related products when a report includes a subdataset. Use a Data Run to define values for the subdataset's parameters.
Understanding Layers
Each layer in the map component controls different aspects of the final map rendered in your report:
• | The maps layer defines the map tiles that are displayed by the component's image, which are determined by its location and zoom, the maximum and minimum zoom allowed in the component, and the image's opacity. |
• | The marker layer defines locations on the map that display an image you select. |
• | The path layer defines lines between locations on the map. |
Each layer can be named uniquely; these names can be displayed in the JasperReports Serverinteractive report viewer in the Layers drop down; this allows your user to select which layers to drawn.
Layer names defined in the component can control the layers drawn in the final report |
Working with Markers
Markers are points rendered on the second layer of the TIBCO Map component.
This section describes:
• | Static Markers |
• | Dynamic Markers |
Static Markers
To define a marker in Jaspersoft Studio:
1. | Edit the map component's properties. |
2. | On the Markers tab, click Add. |
3. | Define your markers by specifying a location and icon. The list of properties for a marker includes: |
• | target |
• | string |
• | optional |
• | _blank |
• | the hyperlink target for the marker |
Defining a map's markers |
4. | Specify the icon as a URL that points to the image to use; it's loaded by the JavaScript API. |
Jaspersoft doesn't currently support loading an image directly from the repository, or as a resource local to the report.
The location can be set by latitude/longitude coordinates or an address to be geolocated, as described above.
A map with a marker |
5. | For the addresses, set each property to form the address: country, state, zip, city, street. |
Marker properties set to a static location |
Marker properties include:
Property Name | Type | Required? | Possible Values | Description |
xoffset | Numeric (integer) | Optional | 0 | The horizontal offset of the marker icon measured in pixels |
yoffset | Numeric (integer) | Optional | 0 | The vertical offset of the marker icon measured in pixels |
anchor | String | Optional | bottom-left, bottom-right, bottom-center | The anchor point of the marker icon |
draggble | Boolean | Optional | false | Specifies whether users can drag the marker |
icon.url | String | Required | N/A | URL for the icon |
title | String | Optional | N/A | The ToolTip for the marker icon; works in conjunction with icon.url |
hyperlink | String | Optional | N/A | The hyperlink text for the marker |
target | String | Optional | N/A | The hyperlink target for the marker. The default value is _blank. |
This is a simplified example; the more common scenario is to read location data from the database.
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 marker, and locations can be based on data from more than one data source.
In this example, we'll use data from City College of San Francisco's public facilities data set that we've saved as an Excel file:
Facilities | Street Address | City | State | Zip | Latitude | Longitude |
Airport | SF International Airport, North Access Road, Building 928 | San Francisco | CA | 94128 | 37.622511278000445 | -122.39519978799973 |
Civic Center | 750 Eddy Street | San Francisco | CA | 94109 | 37.783008003000475 | -122.42000284399973 |
Castro | 450 Castro Street | San Francisco | CA | 94114 | 37.76168744600045 | -122.43511354199973 |
Chinatown/North Beach | 808 Kearny Street | San Francisco | CA | 94108 | 37.79551773600048 | -122.40496557999973 |
Downtown | 88 4th Street | San Francisco | CA | 94103 | 37.784588004000454 | -122.40438877299971 |
Evans | 1400 Evans Avenue | San Francisco | CA | 94124 | 37.74169579700049 | -122.38589540299972 |
Fort Mason | Laguna Street & Marina Boulevard, Building B | San Francisco | CA | 94123 | 37.80001344200048 | -122.43517818299972 |
John Adams | 1860 Hayes Street | San Francisco | CA | 94117 | 37.77385843900049 | -122.4469528999997 |
Mission | 1125 Valencia Street | San Francisco | CA | 94110 | 37.754794183000456 | -122.42088522899968 |
Ocean | 50 Phelan Avenue | San Francisco | CA | 94112 | 37.72408746400049 | -122.45231737299969 |
Southeast | 1800 Oakdale Avenue | San Francisco | CA | 94124 | 37.73684564000047 | -122.39424548999972 |
Gough Street | 31/33 Gough Street | San Francisco | CA | 94103 | 37.772268634000454 | -122.42098248799971 |
Since the data set includes both street addresses and latitude/longitude pairs, we can explore both functions.
To use dynamic locations:
1. | Create an Excel file with the data provided above and a data adapter that points to it. Export the data adapter to the project folder; name it CollegeFacilities.xml. |
2. | In the report, create a new dataset: right-click the root in the outline view and select Create Dataset. |
3. | Right-click the new dataset and select Dataset and Query. |
4. | In the Query dialog, select the CollegeFacilities.xml data adapter and click Read Fields. |
5. | Use the data adapter to populate the dataset. With the CollegeFacilities dataset selected in the outline view, click the Advanced tab in the Properties view, then select the property Properties and click the button ellipsis to open the properties dialog. |
6. | Add a new property: net.sf.jasperreports.data.adapter, and specify the name of the data adapter file saved earlier (CollegeFacilities.xml). |
We can use this new dataset to set markers on the map.
7. | Select the map in the design view, click the Markers tab, and click Add. |
8. | Click Dataset, check the Use Dataset check box, and click Add. |
9. | Select the CollegeFacilities dataset and accept the defaults. Studio uses the data adapter referenced by the net.sf.jasperreports.data.adapter property set previously for this dataset. |
10. | Click OK. |
The dataset is added to the list of datasets we'll use for markers.
11. | Click Values and create an expression for each marker property: for example, provide the title, street, city, state, country, and so forth. |
Location values defined as expressions |
This example uses an icon from the web: Pink Push Pin.
12. | Click OK. |
13. | Preview your report in HTML. |
San Francisco City College facilities marked on a map |
Working with Paths
Paths are lines rendered on the third layer of the TIBCO Map component.A path is defined by:
• | A name that serves as a path identifier in case different paths will appear on the map |
• | A style that specifies various style configuration properties, such as line and fill color, line weight, and opacity |
• | A collection of places (points) on the map defined by latitude/longitude coordinates or addresses; these are connected to form the path |
To define a path in Jaspersoft Studio:
1. | 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.
2. | Use the Paths section to add points to the path: click Add in this UI area to do so. For each point, specify: |
a. | the path name (to identify which path includes the point) |
b. | the style property (to identify the style associated with this path) |
c. | the latitude/longitude coordinates or the address of the point |
Like styles, points can be added manually or by using a specific dataset. Pay close attention when adding points: they are connected on the map in the order that they are declared in the JRXML file. If they aren't declared in a sensible order, the path won't make sense, either.
Recommended Comments
There are no comments to display.