Adding Maps to BIRT Reports

This documentation describes the mapping components provided as part of Weave 2.3, for changes in Weave 2.4 see BIRT Map Updates for Weave 2.4

The BIRT designer installed along with Weave contains a map component in the tool palette for adding a map image to the generated report.

By selecting the tool and clicking in the report design you can add a new map place holder.

The map place holder will be replaced by a map when the report is generated.

Resizing the map

You can resize the map using the handles directly within the design or you can set the width and height exactly by editing the advanced properties of the map

Currently the map size must be set to specific units (cm, pixels, etc) and can not be set as a percentage.

Map spatial settings

The Spatial tab in the map properties contains settings that adjust the display of the generated map.

General spatial settings

The general tab contains three setting.

The first is the colour to use to draw highlighted features (this is different from the colour used for drawing selections). This is used in the situation when a single feature within a selection needs to be highlighted in a BIRT report (i.e. when a map is contained within a report that will generate a map image for each selected feature).

The second used when the map is embedded in a dataset and will be covered later.

And the third setting sets the DPI of the generated map image. The little button to the right of the DPI field allows the value to be set from a formula, which can be use for example to allow the user to choose between high, medium and low quality map output when they generate the report by associating the DPI value with a report parameter.

As of Weave 2.5.8 there is a fourth setting, Show Highlight, that allows you to turn off the highlighting defined by the Highlight Color.

Location settings

The Location setting for the map determine where the map will be centred and is used in conjunction with the Scale setting to determine what area of the world the map will cover.

There are three choices:

Value	Description
Original	Centre on the area that the user was viewing. This will ensure that the map covers at least the area the user was looking at, it may be more vertically or horizontally because the size of the map on the page may be different to that of the browser. There are no input parameters for this option.
Selection	Centre on the current selection. This will pan the map so that it is centred on the current selection. This would normally be used in conjunction with the Scale setting of the same name. There are no input parameters for this option.
Specific	Match an area entered directly. The report designer must enter the area of the map to be displayed directly.

Scale settings

The Scale setting for the map determine what scale the map will be generated at and are used in conjunction with the Location settings to determine the actual area of the world the map will cover.

There are three choices:

Value	Description
Original	Match the scale that the user was viewing. This basically does nothing to calculate a scale but instead uses the current location (as set by the Location setting) to determine the map scale. This may not be the exact scale the the user had selected on the client because of differences in page and screen sizes, if you want the map scale to be exactly what the user was viewing then the Specific value should be chosen for this option and a formula should be used to set the scale. There are no input parameters for this option.
Selection	Set the scale to ensure the map covers at least the current selection. This will scale the map so that it displays the current selection. This would normally be used in conjunction with the Location setting of the same name. You can also specify the size of a buffer around the selection so that the map covers more of the surrounding area
Specific	Set the scale directly. The report designer must enter the scale of the map to be displayed directly.

Setting a map scale

Like the DPI setting the scale setting, when set to Specific, allows its value to be set from a formula.

Automatically matching the users current scale

One option when using a formula is to set the formulas value from a parameter that's automatically set by Weave each time a report is generated, the name of this parameter is 'client.scale' and the value for this parameters is always set to the users current map scale at the time of the report generation. So, by setting the Scale formula to

params['client.scale']

you can ensure that the map in the report will be generated at the same scale that the user was originally using.

This is different from setting the Scale Type to Original, which actually maintains the original extent rather than the original scale. Using 'client.scale' maintains the original scale which may result in a different map extent from what the client was viewing.

This may be incorporated directly as a new Scale option in future versions of the BIRT mapping component

From a value entered by the user

Another option is to add a report parameter to the report and allow the user to choose a map scale when they generate the report (note that this is different from 'client.scale' which is automatically generated by Weave).

By right clicking on the Report Parameter item in the Outline you can create a new report parameter

Here we've created a new report parameter called 'scale'

which we can then use in the formula for our report parameter (by using the value params["scale"] as our formula)

and it will appear when the user generates the report.

then the map scale will be taken from the value the user has selected.

This is also a useful option if you wish to restrict the scales available for generating a report map.

Displaying the map scale

All of these parameters can also be used to display the map scale using a dynamic label, but as of Weave 2.4.3 there is also an additional parameter available, after the map is generated, that contains the actual map scale that the map is generated at.

The parameter will be named scale, if the map doesn't have a name, or <name>.scale if the map does have a name.
The numeric value is directly available as params["scale"] (or params["<name>.scale"]) or a formatted string value available using params["scale"].displayText (or params["<name>.scale"].displayText).

Layers Settings

The layers settings allow you to alter the layers that are displayed on the map.

By entering a comma separated list of layer ids into the Show Layers value you can force layers to be turned on.

This will just turn the layer on, if the map engine still won't show the layer, for example because it is outside of a certain scale range, then the layer may still not display.

Similarly by entering a comma separated list of layer ids into the Hide Layers value you can force layers to be turned off.

Finally by checking the Display only shown layers check box you can provide a list of exactly the layer ids that should be turned on.

Layer ids for showing/hiding map layers

The values for the layer ids are taken from the map engine that the layer belongs to, for example if the map engine is ArcIMS then the layer id will be the 'id' parameter for the layer in the AXL file, and are generally the unique identifier for the actual layer.

If the map is going to be created from multiple overlayed map engines and the layer id is not unique then you can specify which map engine the layer id corresponds to be suffixing the layer id with a "/" and the id of the map engine, for example "roads/me.vector" (the id of the map engine is the Weave map engine id).

In reality unless you specify a map engine id explicitly each layer id is actually suffixed with "/*", which will match any map engine id. This will effectively remove all layers matching the specified name from all map engines.

So using a layer id of "property" is the same as using "property/*".

It's not yet possible to specify "*/mapengineid", that is indicate that all layers from a particular map engine should be on or off.