Attributes

An attribute is a value that a processor requires as its input (if it is not satisfied by the output of another processor) or the report template. An attribute represents one or more values. Usually simple values (numbers, strings, etc...) are values required by the report template but on occasion they might be required by a processor. Typically a processor will require a specific attribute type, for example the !createMap processor requires a !map attribute, which contains all of the information required to render a map (layers, bbox, projections, etc...)

Attributes are declared in the configuration yaml file in the !attribute block. The attribute block is a map of name - > attributeType pairs. This means that each attribute consists of a name and a type. Each processor has a inputs which must be satisfied by an attribute or the output of another processor. Each input has a name/key that is used to look up the attribute (or output). If an input of a processor is not satisfied, an error will be reported to the client detailing the attribute(s) that are missing.

All attributes can have a default block where the values of the attribute can be supplied. As the term implies, an attribute with default values does not need to be supplied by the client (although they can be overridden). Further, if an attribute has multiple values the default block may only provide defaults for a subset of the values (the client must supply the rest).

Defaults provide a way to make the API the client must use to be very simple (when designing a custom client) but remain flexible.

Example

config.yaml

templates:
  A4 portrait: !template
    reportTemplate: simpleReport.jrxml
    attributes:
      number: !integer {}
      title: !string {}
      description: !string {}
      map: !map
        height: 200
        width: 400

request.json

{
    "layout": "A4 portrait",
    "outputFormat": "pdf",
    "attributes": {
        "number": 45,
        "title": "The map",
        "description": "A map showing...",
        "map": {
          "bbox": [100, -1, 106, 2],
          "projection": "CRS:84",
          "dpi": 72,
          ...
        }
    }
}
  
<

!boolean

A boolean type attribute.

Example

 verboseExample 

Configuration

default
A default value for this attribute. Example:
     attributes:
title: !boolean
default: True

!datasource

This attribute represents a collection of attributes which can be used as the data source of a Jasper report's table/detail section.

For example consider the case where the report should contain multiple tables or charts but the number of reports may change depending on the request. In this case the client will post a datasource attribute json object containing an array of all the table attribute objects. The DataSourceProcessor will process the datasource attribute and create a Jasper datasource that contains all the tables.

This datasource must be used in tandem with the DataSourceProcessor processor (see !createDataSource processor).

The json data of this attribute is special since it represents an array of attributes, each element in the array must contain all of the attributes required to satisfy the processors in the DataSourceProcessor.

Example configuration:

 datasource: !datasource
table: !table
map: !map
width: 200
height: 100

Example request data:

 datasource: [
{
table: {
... // normal table attribute data
},
map: {
... // normal map attribute data
}
}, {
table: {
... // normal table attribute data
},
map: {
... // normal map attribute data
}
}
]
[[examples=verboseExample,datasource_dynamic_tables,datasource_many_dynamictables_legend, datasource_multiple_maps,customDynamicReport,report]]

Configuration

attributes
The attributes that are acceptable by this dataSource. The format is the same as the template attributes section.
default
Default values for this attribute. Example:
     attributes:
datasource: !datasource
attributes:
name: !string {}
count: !integer {}
default:
- name: "name"
- count: 3

!features

Attribute for GeoJson feature collection.

Example

 report 

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"

Inputs

features required
The geojson features.
longitudeFirst
By default the normal axis order as specified in EPSG code will be used when parsing projections. However the requester can override this by explicitly declaring that longitude axis is first.

!float

A float type attribute.

Example

 verboseExample 

Configuration

default
A default value for this attribute. Example:
     attributes:
title: !float
default: 4.2

!integer

An integer type attribute.

Example

 verboseExample 

Configuration

default
A default value for this attribute. Example:
     attributes:
title: !integer
default: 42

!jsonDatasource

A JSON data source attribute. To be declared as net.sf.jasperreports.engine.data.JsonDataSource in Jasper. Accepts only JSON objects at the root. To use it, you must pass it to a sub report like that:
 < subreport>
...
< dataSourceExpression>
< ![CDATA[$P{json_attribute}.subDataSource("path.to.list")]]>
< /dataSourceExpression>
< subreportExpression>< /subreportExpression>
< /subreport>

The expression given to the subDataSource method must select an array in the JSON structure.

!legend

Objects needed by the LegendProcessor (see !prepareLegend processor).

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"

Inputs

classes
Other embedded classes.
dpi
DPI of the legend icons.
icons
Urls for downloading icons for each legend row.
name
Name of the legend class.

!map

The attributes for CreateMapProcessor (see !createMap processor).

Example

 verboseExample 

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"
dpiSuggestions
Suggestions for DPI values to use. Typically these are used by the client to create a UI for a user.
height
The height of the map in pixels. This value should match the height of the sub-report in the JasperReport template.
maxDpi
The maximum DPI allowed for maps.

If a request is made with a higher DPI, the request fails.

maxHeight
Limits the maximum height of the map.
maxWidth
Limits the maximum width of the map.
width
The width of the map in pixels. This value should match the width of the sub-report in the JasperReport template.
zoomLevelSnapStrategy
The strategy to use to compute the actual zoom level to use.

If you specify this value, you must set the zoomLevels as well.

Possible values are:

  • CLOSEST_LOWER_SCALE_ON_TIE: Find the closest zoom level. If the targetScale is directly between two zoomLevels then the smaller/higher resolution scale will be chosen.
  • CLOSEST_HIGHER_SCALE_ON_TIE: Find the closest zoom level. If the targetScale is directly between two zoomLevels then the larger/lower resolution scale will be chosen.
  • HIGHER_SCALE: Always choose the zoom-level that is just higher than the target value.
  • LOWER_SCALE: Always choose the zoom-level that is just lower than the target value.

zoomLevels
The list of Zoom Levels.

Depending on the zoomLevelSnapStrategy, this will be used to compute the actual zoom level of the map.

zoomSnapGeodetic
If true, snap to geodetic scales.
zoomSnapTolerance
The zoom level tolerance.

Used in ZoomLevelSnapStrategy.HIGHER_SCALE and ZoomLevelSnapStrategy.LOWER_SCALE to specify the cutoff value.

Inputs

areaOfInterest
A GeoJSON geometry that is essentially the area of the area to draw on the map.
bbox required
An array of 4 doubles, minX, minY, maxX, maxY. The bounding box of the map.

Either the bbox or the center + scale must be defined

center required
An array of 2 doubles, (x, y). The center of the map.
dpi required
The output dpi of the printed map.
dpiSensitiveStyle
Should the vector style definitions be adapted to the target DPI resolution? (Default: true)

The style definitions are often optimized for a use with OpenLayers (which uses a DPI value of 72). When these styles are used to print with a higher DPI value, lines often look too thin, label are too small, etc.

If this property is set to `true`, the style definitions will be scaled to the target DPI value.

height
The height of the map.
layers
The json with all the layer information. This will be parsed in postConstruct into a list of layers and therefore this field should not normally be accessed.

The first layer in the array will be the top layer in the map. The last layer in the array will be the bottom layer in the map. There for the last layer will be hidden by the first layer (where not transparent).

longitudeFirst
By default the normal axis order as specified in EPSG code will be used when parsing projections. However the requester can override this by explicitly declaring that longitude axis is first.
pdfA
Whether to merge all layers into one. This is great to reduce pdf size but needs layers having an imagebufferscaling of 1. Also see the pdfA option of the print config.
projection
The projection of the map.
rotation
The rotation of the map.
scale
If center is defined then this is the scale of the map centered at center.
useAdjustBounds
Indicates if the map should adjust its bounds.
useNearestScale
Indicates if the map should adjust its scale/zoom level to be equal to one of those defined in the configuration file.
width
The width of the map.
zoomToFeatures required
Zoom the map to the features of a specific layer or all features of the map.

!northArrow

The attributes for CreateNorthArrowProcessor (see !createNorthArrow processor).

Configuration

createSubReport
Specifies whether a subreport should be created, or only a graphic.
default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"
size
The size (width and height) of the north-arrow graphic in the JasperReport template.

The graphic is a square so that the arrow can be rotated properly.

Inputs

backgroundColor
The background color for the north-arrow graphic (default: rgba(255, 255, 255, 0)).
graphic
The path to a graphic to use for the north-arrow.

It can either be an URL ("http://xyx.com/img/north-arrow.png") or a file in the configuration folder ("file://NorthArrow.svg"). Both SVG graphics and raster graphics (png, jpeg, tiff, ...) are supported.

While the resulting graphic used in the JasperReport template is a square, this graphic can have an arbitrary aspect ratio. The graphic will be scaled to the output size and rotated around its center.

If no graphic is given, a default north-arrow is used.

!overviewMap

The attributes for an overview map (see !createOverviewMap processor).

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"
dpiSuggestions
Suggestions for DPI values to use. Typically these are used by the client to create a UI for a user.
height
The height of the map in pixels. This value should match the height of the sub-report in the JasperReport template.
maxDpi
The maximum DPI allowed for maps.

If a request is made with a higher DPI, the request fails.

maxHeight
Limits the maximum height of the map.
maxWidth
Limits the maximum width of the map.
style
The style name of a style to apply to the bbox rectangle of the original map during rendering. The style name must map to a style in the template or the configuration objects.
width
The width of the map in pixels. This value should match the width of the sub-report in the JasperReport template.
zoomFactor
The zoom factor by which the extent of the main map will be augmented to create an overview.
zoomLevelSnapStrategy
The strategy to use to compute the actual zoom level to use.

If you specify this value, you must set the zoomLevels as well.

Possible values are:

  • CLOSEST_LOWER_SCALE_ON_TIE: Find the closest zoom level. If the targetScale is directly between two zoomLevels then the smaller/higher resolution scale will be chosen.
  • CLOSEST_HIGHER_SCALE_ON_TIE: Find the closest zoom level. If the targetScale is directly between two zoomLevels then the larger/lower resolution scale will be chosen.
  • HIGHER_SCALE: Always choose the zoom-level that is just higher than the target value.
  • LOWER_SCALE: Always choose the zoom-level that is just lower than the target value.

zoomLevels
The list of Zoom Levels.

Depending on the zoomLevelSnapStrategy, this will be used to compute the actual zoom level of the map.

zoomSnapGeodetic
If true, snap to geodetic scales.
zoomSnapTolerance
The zoom level tolerance.

Used in ZoomLevelSnapStrategy.HIGHER_SCALE and ZoomLevelSnapStrategy.LOWER_SCALE to specify the cutoff value.

Inputs

bbox
An array of 4 doubles, minX, minY, maxX, maxY. The bounding box of the overview-map.

If a bounding box is given, the overview-map shows a fixed extent. The configuration parameter zoomFactor is ignored in this case.

center
An array of 2 doubles, (x, y). The center of the overview-map.

If center and scale are given, the overview-map shows a fixed extent. The configuration parameter zoomFactor is ignored in this case.

dpi
The output dpi of the printed map.
dpiSensitiveStyle
Should the vector style definitions be adapted to the target DPI resolution? (Default: true)

The style definitions are often optimized for a use with OpenLayers (which uses a DPI value of 72). When these styles are used to print with a higher DPI value, lines often look too thin, label are too small, etc.

If this property is set to `true`, the style definitions will be scaled to the target DPI value.

height
The height of the map.
layers
The json with all the layer information. This will be parsed in postConstruct into a list of layers and therefore this field should not normally be accessed.
longitudeFirst
By default the normal axis order as specified in EPSG code will be used when parsing projections. However the requester can override this by explicitly declaring that longitude axis is first.
pdfA
Whether to merge all layers into one. This is great to reduce pdf size but needs layers having an imagebufferscaling of 1. Also see the pdfA option of the print config.
projection
The projection of the map.
rotation
The rotation of the map.
scale
If center is defined then this is the scale of the map centered at center
.
useAdjustBounds
Indicates if the map should adjust its bounds.
useNearestScale
Indicates if the map should adjust its scale/zoom level to be equal to one of those defined in the configuration file.
width
The width of the map.

!paging

Attribute that defines how a map is displayed across many pages.

This is used by the paging processor.

Example

 paging 

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"

Inputs

aoiDisplay
Indicates how to render the area of interest on this sub-map. This makes it easier to how the all the sub-maps fit together to for the complete map. Also if the map is rendered as a whole in one part of the report one can easily see where in the complete map the sub-map fits, even without looking at the labeling.

For options see: AreaOfInterest.AoiDisplay

By default the rendering in the map attribute's area of interest will be used

aoiStyle
If this is defined it will override the style used for rendering the Area Of Interest in the main map attribute's Area of Interest definition.
overlap
The amount that each page/sub-map should overlap each other.

For example if the value is 1 and the projection of the map is degrees then the overlap will be 1 degree.

The default is to not have any overlap.

scale required
The scale denominator for each page/sub-map.

!scalebar

The attributes for CreateScalebarProcessor (see !createScalebar processor).

Configuration

createSubReport
Specifies whether a subreport should be created, or only a graphic.
default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"
height
The height of the scalebar in pixels. This value should match the height of the sub-report in the JasperReport template.
width
The width of the scalebar in pixels. This value should match the width of the sub-report in the JasperReport template.

Inputs

align
The horizontal alignment of the scalebar inside the scalebar graphic (default: left).
backgroundColor
The background color for the scalebar graphic (default: rgba(255, 255, 255, 0)).
barBgColor
The color used to draw the alternating blocks for style "bar" and "bar_sub" (default: white).
barSize
The thickness of the bar or the height of the tick marks on the line (in pixel).
color
The color used to draw the bar and lines (default: black).
font
The font used for the labels (default: Helvetica).
fontColor
The font color of the labels (default: black).
fontSize
The font size (in pt) of the labels (default: 12).
geodetic
Use geodetic measurement calculations for the scalebar.
intervals
The number of intervals (default: 3). There must be at least two intervals.
labelDistance
The distance between scalebar and labels (in pixel).
labelRotation
Rotate the label to some degree.
lineWidth
The thickness of the lines or the bar border (in pixel).
lockUnits
Force that the given unit is used (default: false). For example if the unit is set to meters and `lockUnits` is enabled, then meters is always used, even when kilometers would create nicer values.
orientation
The scalebar orientation.

Available options:

  • "horizontalLabelsBelow" (default): Horizontal scalebar and the labels are shown below the bar.
  • "horizontalLabelsAbove": Horizontal scalebar and the labels are shown above the bar.
  • "verticalLabelsLeft": Vertical scalebar and the labels are shown left of the bar.
  • "verticalLabelsRight": Vertical scalebar and the labels are shown right of the bar.
padding
The padding around the scalebar (in pixel).
renderAsSvg
Indicates if the scalebar graphic is rendered as SVG (will default to Configuration.defaultToSvg).
subIntervals
Should sub-intervals be shown? Default: false

The main intervals are divided into additional sub-intervals to provide visual guidance. The number of sub-intervals depends on the length of an interval.

type
The scalebar type.

Available types:

  • "line": A simple line with graduations.
  • "bar" (default): A thick bar with alternating black and white zones marking the intervals. The colors can be customized by changing the properties `color` and `barBgColor`.
  • "bar_sub": Like "bar", but with little ticks for the labels.
unit
The unit to use.

The unit can be any of:

  • m (mm, cm, m or km)
  • ft (in, ft, yd, mi)
  • degrees (min, sec, °)

If the value is too big or too small, the module will switch to one of the unit in parenthesis (the same unit is used for every interval). If this behavior is not desired, the `lockUnits` parameter will force the declared unit (or map unit if no unit is declared) to be used for the scalebar.

verticalAlign
The vertical alignment of the scalebar inside the scalebar graphic (default: bottom).

!staticLayers

The attributes for the AddStaticLayersProcessor (see !addBackgroundLayers and !addOverlayLayers processor) which adds the layers in this attribute to the layers in the map. The typical use is to add the background or overlay layers as the "default" in the config.yaml file if the client desires it can override those values.

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"

Inputs

layers required
An array of layers (the same as for MapAttribute.MapAttributeValues.layers).

These layers will be added to the map.

!string

Attribute that reads a string from the request data.

Example

 verboseExample 

Configuration

default
A default value for this attribute. Example:
     attributes:
title: !string
default: The title
maxLength
The maximum number of characters allowed for this field (default: unlimited).

!stringArray

An attribute that can contain an array of strings.

Example

 verboseExample 

Configuration

default
A default value for this attribute. Example:
     attributes:
title: !stringArray
default: [one, two, three]

!style

Attribute for GeoJson Styles collection.

Example

 report 

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"

Inputs

style required
The style string.

!table

The attributes for TableProcessor (see !prepareTable processor).

Configuration

default
Default values for this attribute. Example:
 attributes:
legend: !legend
default:
name: "Legend"

Inputs

columns required
The column configuration names for the table.
data required
An array for each table row.