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¶

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

default

Default values for this attribute. Example:

     attributes:
       datasource: !datasource
         attributes:
           name: !string {}
           count: !integer {}
         default:
           - name: "name"
           - count: 3

!features¶

Configuration

default

Default values for this attribute. Example:

 attributes:
   legend: !legend
     default:
       name: "Legend"

Inputs

features required

longitudeFirst

!float¶

Configuration

default

A default value for this attribute. Example:

     attributes:
       title: !float
         default: 4.2

!integer¶

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

dpi

icons

name

!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

height

maxDpi: The maximum DPI allowed for maps.
If a request is made with a higher DPI, the request fails.

maxHeight

maxWidth

width

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

zoomSnapTolerance: The zoom level tolerance.
Used in ZoomLevelSnapStrategy.HIGHER_SCALE and ZoomLevelSnapStrategy.LOWER_SCALE to specify the cutoff value.

Inputs

areaOfInterest

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

dpi required

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

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

pdfA

projection

rotation

scale

useAdjustBounds

useNearestScale

width

zoomToFeatures required

!northArrow¶

The attributes for CreateNorthArrowProcessor (see !createNorthArrow processor).

Example

verboseExample print_osm_new_york_nosubreports

Configuration

createSubReport

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

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

height

maxDpi: The maximum DPI allowed for maps.
If a request is made with a higher DPI, the request fails.

maxHeight

maxWidth

style

width

zoomFactor

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

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

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

layers

longitudeFirst

pdfA

projection

rotation

scale: If center is defined then this is the scale of the map centered at center.

useAdjustBounds

useNearestScale

width

!paging¶

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

This is used by the paging processor.

Example

paging paging_with_overview_layer

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.

pagingOverviewStyle

renderPagingOverview

scale required

!scalebar¶

The attributes for CreateScalebarProcessor (see !createScalebar processor).

Example

verboseExample print_osm_new_york_EPSG_3857 print_osm_new_york_nosubreports

Configuration

createSubReport

default

Default values for this attribute. Example:

 attributes:
   legend: !legend
     default:
       name: "Legend"

height

width

Inputs

align

backgroundColor

barBgColor

barSize

color

font

fontColor

fontSize

geodetic

intervals

labelDistance

labelRotation

lineWidth

lockUnits

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

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

!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¶

Configuration

default

A default value for this attribute. Example:

     attributes:
       title: !string
         default: The title

maxLength

!stringArray¶

Configuration

default

A default value for this attribute. Example:

     attributes:
       title: !stringArray
         default: [one, two, three]

!style¶

Configuration

default

Default values for this attribute. Example:

 attributes:
   legend: !legend
     default:
       name: "Legend"

Inputs

style required

!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

data required