Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of Jaspersoft Studio User Guide. View the latest documentation.

    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 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:

    1. Drag the Map component jss-icon-map.png.6d8022738f6e6ca889b5670d9f73ab6b.png

    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:

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

    jss-google-maps-properties-map.png.004887cfb928416de6a866356c8449b6.png

    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.

    jss-google-maps-center.png.b53cabdd9bd0a03a9d43fa62a7d3ed15.png

    Setting a map location

    Changes to this window are reflected in the map in your report. In addition, you can change the map's center in any of the following ways. When you close the preview, the map is automatically centered at the selected location:

    •      Address – Enter an address in the entry bar to center the map at that location.
    •      Latitude and Longitude – Enter a latitude and longitude to center your map at that location.
    •      Double-click – Double-click anywhere on the map to center it at that location.
    • 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 jss-icon-edit.png.9b614edc1cd5f2dda70ad9042c3a5082.png
    • Longitude – The longitude of the map center. You can type directly in the entry bar, or click jss-icon-edit.png.b9ea0d558d4e41f83740c34bb41a6937.png
    • Address – A String representing the address of the center. You can type directly in the entry bar, or click jss-icon-edit.png.3515a9a5f9eb056d7112472ab709a8df.png
    • Zoom – Integer representing the Google Maps zoom level. You can type directly in the entry bar, or click jss-icon-edit.png.ba13d551085c54a0582292bc09bf62e6.png
    • Language – String that sets the in-map language. You can type directly in the entry bar, or click jss-icon-edit.png.7c1f3e18d4bc3c17eab20ee10c884f30.png
    • 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.

    jss-google-maps-properties-authentication.png.0176756652b64f15fc3901606cf7b155.png

    Authentication tab in Properties view for a map component

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

    1. Select Window > Preferences to open the Preferences dialog box (Eclipse > Preferences on Mac).
    2. Navigate to Jaspersoft Studio > Properties.
    3. 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.
    4. When you have specified all your properties, click OK to exit the Preferences dialog box.

    note-icon-ns.png.0c6f14b642aad6009d930486e9d91b84.png

    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 manually, either using a fixed location that is known when the report is created, or using an expression based on report data. You can also define markers based on a dataset. A single map can include both manual markers and markers from one or more datasets. This section describes:

    • Marker Properties
    • Adding Markers Manually
    • Adding Markers Using the Map
    • Adding Markers Using a Dataset
    • Modifying 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.

    Adding Markers Manually

    Manually-added markers can be used for a fixed address or location that is known when the report is created. You can also use an expression, for example to set a location based on a parameter value. This method only displays as many markers as you explicitly create.

    To manually define a marker:

    1. 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

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

    jss-google-maps-properties-markers.png.a0531e87a10f9aa2f1486feceec16e9b.png

    Markers tab with one marker
    3. To specify the marker properties, click Add in the Markers tab.

    The Markers dialog box opens.

    4. To enter an individual marker, select the Markers tab and click Add again.

    The Marker dialog box opens.

    jss-google-maps-static-marker.png.7433d68b3bf22bfa8233a2193a2048a5.png

    Defining a static marker
    5. 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 jss-icon-edit.png.1946572041d7ea8c71858d722802058b.png
    • 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 jss-icon-edit.png.8f2e54975fd53af5a8da24cb427ed6ac.png
    6. (Optional) Set the title for your marker, if any.
    7. (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.
    8. (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.

    jss-google-maps-static-marker-color.png.a7fd57e0de663dd2af76732a564d9147.png

    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.
    9. Click OK to return to the Markers dialog box.
    10. To create additional markers, click Add, enter the marker properties, then click OK to return to the Markers dialog box.
    11. Click OK to create your markers.
    12. 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.17cd1a4dabe67240c89128e40ba1b124.png

    A map with a marker

    Adding Markers Using the Map

    You can also add markers using the map preview. This only supports a fixed address or location that is known when the report is created.

    To manually define a marker using the map:

    1. 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

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

    jss-google-maps-properties-markers.png.d93421ab2857597979bf524ce9a402e2.png

    Markers tab with one marker
    3. To specify the marker properties, click Add in the Markers tab.

    The Markers dialog box opens.

    4. To enter an individual marker, select the Map tab. You can perform the following tasks:
    •      To create a marker by selecting a location on the map, right-click on the location you want and select Add marker.
    •      To delete one or more markers, select the marker(s) in the panel at the right and press Delete, or right-click on the marker and select Delete.
    •      To edit a marker's location, double-click on the marker to open the Marker dialog box.

    Adding Markers Using a Dataset

    The steps above define a fixed number of markers. You can also dynamically define the markers based on locations defined in your report's data or another dataset. A single map can include both manual markers and markers from one or more datasets.

    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:

    1. 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.
    2. Click jss-icon-new-data-adapter.png.e0b4a17f059bf3533f04af2035984fb5.png
    3. Name the file SFDataAdapter.xml and click Next.
    4. Select CSV File as the data adapter type and click Next. The CSV File dialog opens.

    jss-google-maps-dataadapter.png.0a28728a3923fd496f3f486236b75765.png

    Creating a sample data adapter for markers and paths
    5. Name your adapter, for example, SF Landmarks Data Adapter.
    6. Click File and select the CSV file you created.
    7. Click Get column names from the first row of the file.
    8. Select Skip the first line.
    9. Click Finish to create the adapter.

    Create a dataset in your report:

    1. Right-click the root node of the report in the outline view and select Create Dataset.
    2. Name the dataset SFLandmarksDataset, make sure Create new dataset from a connection or Data Source is selected, and click Next.
    3. Select the SFDataAdapter.xml data adapter and click Next.
    4. Click >> to select all fields and click Finish.

    The dataset is created in your report.

    5. Click on the SFLandmarksDataset in outline view.
    6. 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.

    jss-google-maps-dataset-properties-default-adapter.png.9f812fb521050e3e1ad1cbf7d3e43059.png

    Setting the default data adapter for a dataset

    Using the dataset to set markers

    1. Add a map component to the report, or select an existing map in the Design tab.
    2. 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.
    3. Click the Markers tab in the Properties view.
    4. Click Add to open the Markers dialog box.
    5. Select the Dataset tab and select Use Dataset.
    6. 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.
    7. Click the Markers tab and then click Add. The Marker dialog box opens.

    jss-google-maps-markers-expressions.png.d81b9a8bc765dc14cbd39250190b36cd.png

    Using expressions to set markers from a dataset
    8. For a dataset, you typically want to use expressions for your values. For each property you want to read from the dataset, click jss-icon-edit.png.dcc0294ede38ddf7b28ba35c02b66724.png
    •      Latitude – $F{latitude}
    •      Longitude – $F{longitude}
    •      Address – $F{landmark}

    note-icon-ns.png.28738d55f4cee9c085db98545be50dd4.png

    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.

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

    jss-google-maps-item-data-markers-from-dataset.png.e9f423a55e1d9abcb76c799a6b8e2c89.png

    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.

    jss-google-maps-markers-from-dataset.png.36bc9deabf28d6e21b145f74df5f822f.png

    Properties view showing markers added manually and markers defined from a dataset
    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.dc51aa9467981cd7db2b8f80e5d80527.png

    San Francisco landmarks shown on a map

    Modifying Markers

    To edit a marker:

    1. Select the map and click on the Markers tab in Properties view.
    2. Select the marker you want to change and click Edit.
    3. 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.
    4. To change marker properties, select the Markers tab, and edit your properties.

    To delete a marker:

    1. Select the map and click on the Markers tab in Properties view.
    2. 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 Manually

    1. Edit the map component's properties.
    2. On the Paths tab, in the Styles section, click Add.
    3. In the Style dialog box, enter the properties you want for the path. See Marker and Path Properties for more information about available properties.
    4. Click OK.

    Defining Path Styles Using a Dataset

    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:

    1. 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.
    2. Click jss-icon-new-data-adapter.png.bfb7aee72fa831ad6b9649c06502afb4.png
    3. When prompted, navigate to the same folder as your report.
    4. For this example, name the file PathStylesDataAdapter.xml and click Next.
    5. Select CSV File as the data adapter type and click Next.
    6. Name your adapter, for example, Path Styles Adapter.
    7. Click File and select the CSV file you created.
    8. For this example, click Get column names from the first row of the file and select Skip the first line.
    9. Click Finish to create the adapter.

    Create a dataset in your report:

    1. Right-click the root in the outline view and select Create Dataset.
    2. Name the dataset and click Next. For this example, name the dataset PathStyles.
    3. Select the data adapter for your path styles (Path Styles Data Adapter) and click Next.
    4. Click >> to select all fields and click Finish.
    5. Select the dataset (PathStyles) you just created in outline view.
    6. 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:

    1. Create your data source, a data adapter that points to it, and a dataset that uses the data adapter.
    2. Add a map component to the report, or select an existing map in the Design tab.
    3. Select the Paths tab in the Properties view.
    4. In the Styles section, click Add to open the Items dialog box.
    5. Click the Dataset tab in the Path dialog box and select Use Dataset.
    6. 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.
    7. Select the Items tab and click Add to open the Style dialog box.
    8. For each property you want to read from the dataset, click jss-icon-edit.png.d01d387a0c62fa5a8d70e79b01ba34c5.png
    •      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}
    9. Click OK to return to the Items dialog box.
    10. Click OK to create the style set.

    jss-google-maps-properties-path-styles.png.f866a79f20f115e6726eedffded4933b.png

    Styles on the Path tab of the Properties view for a map

    Defining a Path Manually

    To define a path using the Add button:

    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. In the Paths section, click Add to open the Markers dialog.
    3. To add a point to the path, click Add to open Path dialog box. For each point, specify the following:
    a. the path name (to identify which path includes the point)
    b. the latitude/longitude coordinates or the address of the point
    c. additional optional properties, such as the name of a path style

    Click OK to add your point.

    4. Use the Up and Down buttons to change the order in which the points appear.
    5. Preview your report in HTML to see your path.

    To add points to a path using the map preview:

    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. In the Paths section, click Add to open the Markers dialog.
    3. Select the Maps tab in the Markers dialog box.
    4. 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.
    5. To add a point to the current path, right-click on the location you want and select Add marker.
    6. To delete one or more markers, select the marker(s) in the panel at the right and press Delete, or right-click on the marker and select Delete.

    note-icon-ns.png.c5f856c16c9d73003303f7110f3c6dc0.png

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

    Defining a Path Using a Dataset

    1. 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.
    2. Define any styles your paths use. This example uses the styles defined in Defining Path Styles Using a Dataset.
    3. Add a map component to the report, or select an existing map in the Design tab.
    4. 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.
    5. Select the Paths tab in the Properties view.
    6. In the Paths section, click Add to open the Markers dialog box.
    7. Click the Dataset tab in the Markers dialog box and select Use Dataset.
    8. In the Dataset Run section, select SFLandmarksDataset and accept the default settings. You have already set the default data adapter for this dataset.
    9. For each property you want to read from the dataset, click jss-icon-edit.png.290c962202fd81d6ea300b7b7c88fabf.png
    •      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.

    jss-google-maps-paths-result.png.76070444137f84bb925fb48d2d93f179.png

    Paths on a map

    Modifying Paths and Path Styles

    To edit a path or path style:

    1. Select the map and click on the Paths tab in Properties view.
    2. Select the path or style you want to change and click Edit.
    3. 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.
    4. To change path or style properties, select the Items tab, and edit your properties.

    To delete a path or path style:

    1. Select the map and click on the Paths tab in Properties view.
    2. 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.

     Share
    Go to documents

    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...

© 2024 Cloud Software Group,
Inc. All rights reserved.

Products

Explore