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

Example

verboseExample legend_cropped

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

Example

verboseExample print_osm_new_york_nosubreports

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

Example

verboseExample overviewmap_tyger_ny_EPSG_3857

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

Example

verboseExample print_osm_new_york_EPSG_3857 print_osm_new_york_nosubreports

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.

Example

add_overlay_layer report

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

Example

verboseExample datasource_dynamic_tables customDynamicReport

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.