6.12. Report Objects

The layout of a report is constructed by combining basic graphical report objects into a final template. There are 7 such objects: Ellipse, Image, Line, Rectangle, Static Text, Text Field, Subreport. To form the layout these objects are placed inside report sections (Section 6.10, “Report Sections”).

6.12.1. Common Properties

All the report objects are sharing a common set of properties. These properties determine the position, size, color and printing behavior of the object.

Common Properties

  • Key

    A unique string that identifies the object throughout the report. It is useful to obtain a reference to the object at runtime through the JasperReports API.

  • Location.X

    X coordinate of the object relative to the parent band. The coordinate is specified in report units.

  • Location.Y

    Y coordinate of the object relative to the parent band. The coordinate is specified in report units.

  • Size.Width

    Width of the object specified in report units.

  • Size.Height

    Height of the object specified in report units.

  • Foreground

    The foreground color of the object.

  • Background

    The background color of the object.

  • Mode

    Determines whether the background of an object is transparent or opaque.

  • Stretch Type

    Determines the object's stretch behavior when the report section is affected by stretch.

    • No Stretch - The object does not stretch.

    • Relative To Tallest Object - The object stretches to the height of the tallest object in the group. (Section 6.12.9, “Element Group”)

    • Relative To Band Height - The object stretches to the height of the report section.

  • Position Type

    Determines the object's position when the report section is affected by stretch.

    • Float - The object is positioned relative to the surrounding objects.

      Fix Relative To Top - The object is positioned relative to the top of the band.

      Fix Relative To Bottom - The object is positioned relative to the bottom of the band.

  • Print In First Whole Band

    Flag that determines whether the object gets printed in the first section of a new page or column that is not an overflow from a previous page or column.

  • Print Repeated Values

    Flag that determines whether the repeating values are printed for the dynamic objects such as text fields and images.

  • Print When Detail Overflows

    Flag that determines whether the object is be printed when the band overflows to a new page or a new column.

  • Print When Expression

    A boolean expression that determines whether the object is printed or not.

  • Print When Group Changes

    The object is printed when the specified group changes.

  • Remove Line When Blank

    Flag that determines whether the section should be removed or not when the object is not printed. If the flag is true and the object is not printed, and there are no other objects occupying the same horizontal space, then the report section is removed.

  • Style

    The report style to be used as the base configuration for various visual aspects of the object.

The following properties are shared only by Ellipse, Image, Line and Rectangle objects. These properties are grouped under the Graphic properties category.

Graphic Properties

  • Line Width

    Line width used to draw the object.

  • Line Style

    Line style used to draw the object.

    • Solid - Solid line.

    • Dashed - Dashed line.

    • Dotted - Dotted line.

    • Double - Double line.

  • Line Color

    Line color used to draw the object.

  • Fill

    Determines the fill pattern used to fill the object.

    • Solid - Solid fill.

6.12.2. Ellipse

Ellipse object represents an ellipse graphical element. Ellipse object does not define other properties in addition to common properties.

6.12.3. Image

Image object represents an image graphical element. Image data can be obtained from various locations such as disk file, web URL or a database field.

Image Properties

  • Expression

    Expression that determines the source of image data. The type of image source is determined by the expression's value class:

    • java.lang.String - Image location. First, the report engine tries to determine whether the String represents an URL. If not, it tries to interpret the String as a disk file path. Finally, if the String does not represent a file path, the image is searched in the CLASSPATH using the String as a resource path.

    • java.io.File - Image data is loaded from the java.io.File object that represents a file on disk.

    • java.net.URL - Image data is loaded from the location represented by the java.net.URL object.

    • java.io.InputStream - Image data is loaded from a java.io.InputStream object. The value class is frequently used with JDBC data sources to extract the image data from database.

    • java.awt.Image - Image is represented by a java.awt.Image object.

    • net.sf.jasperreports.engine.JRRenderable - Image is drawn directly on the graphic context by a serializable instance of this interface.

  • Evaluation Time

    Determines the moment of the Image's expression evaluation.

    • Now - The expression is evaluated at the section fill time.

    • Report - The expression is evaluated when the end of the report is reached.

    • Page - The expression is evaluated when the end of the current page is reached

    • Column - The expression is evaluated when the end of the current column is reached.

    • Group - The expression is evaluated when the group specified by the Evaluation Group property changes.

    • Band - The expression is evaluated after the element's parent band has finished rendering all the other elements.

    • Auto - The expression is evaluated at the time that is deduced automatically by the engine. This is useful when the expression combines values evaluated at different times (e.g. percentage out of a total).

  • Evaluation Group

    Specifies the group required by the Evaluation Time property when its value is Group.

  • Horizontal Alignment

    Specifies the horizontal alignment of the Image object.

    • Left - Left.

    • Center - Center.

    • Right - Right.

  • Vertical Alignment

    Specifies the vertical alignment of the Image object.

    • Top - Top.

    • Middle - Middle.

    • Bottom - Bottom.

  • Scale

    Specifies the image scale type.

    • Clip - The image is clipped if it does not fit the bounds of the Image object.

    • Fill Frame - The image is scaled to fit the bounds of the Image object. The scaled image does not preserve the aspect ratio.

    • Retain Shape - The image is scaled to fit the bounds of the Image object. The scaled image preserves the aspect ratio.

    • Real Height - The image is scaled to fit the actual height of the image.

    • Real Size - The image is scaled to fit the actual size of the image.

  • Using Cache

    Flag indicating whether the images that are loaded from the same location should be cached.

  • Anchor Name Expression

    Expression that determines the name of the local anchor that will mark the Image object. This anchor name can be later referred to in document hyperlinks.

  • Bookmark Level

    Specifies the level of the bookmark corresponding to the anchor. This value is used to generate bookmarks in the exported PDF document.

  • Hyperlink Type

    Specifies the type of the hyperlink associated with the Image object.

    • None - No hyperlink.

    • Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.

    • Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.

    • Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.

    • Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.

    • Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.

  • Hyperlink Anchor Expression

    Expression that determines the document anchor to which points the hyperlink associated with the Image object.

  • Hyperlink Page Expression

    Expression that determines the document page to which points the hyperlink associated with the Image object.

  • Hyperlink Reference Expression

    Expression that determines the external document or resource to which points the hyperlink associated with the Image object.

  • Hyperlink Tooltip Expression

    Expression that determines the tooltip to be displayed when hovering the mouse over the hyperlink.

  • Hyperlink Target

    Specifies the target of the hyperlink associated with the Image object.

    • Self - The hyperlink destination document is opened in the same window.

    • Blank - The hyperlink destination document is opened in a new window.

    • Parent - The hyperlink destination document is opened in the parent frame.

    • Top - The hyperlink destination document is opened in the top frame.

  • Box

    Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globally for all sides.

  • On Error Type

    Controls the behavior of the engine in case the image is not available.

    • Error - An exception is raised when loading the image.

    • Blank - The exception is ignored and the image displays as blank.

    • Icon - The exception is ignored and an image replacement icon is displayed.

  • Lazy

    Gives control over when the image is retrieved from the specified location.

    • false - The image is loaded during the report filling process and stored in the resulting document.

    • true - The image is loaded from the specified location only when the document is viewed or exported to other formats.

6.12.4. Line

Line object represents a line graphical element. The endpoints of the line are determined by its bounding box. The line is drawn along one of the bounding box diagonals.

Line Properties

  • Direction

    Determines the diagonal of the bounding box along which the line is drawn

    • Top Down - The line is drawn from the top-left corner to the bottom-right corner.

    • Bottom Up - The line is drawn from the bottom-left corner to the top-right corner.

6.12.5. Rectangle

Rectangle object represents a rectangle graphical element.

Rectangle Properties

  • Radius

    Specifies the radius of the rectangle's corner arc.

6.12.6. Text Objects

There are two special report objects for printing text values. These two objects are Static Text and Text Field. Static Text is used to for static text information. Text Field is used for dynamic text.

6.12.6.1. Common Properties

Static Text and Text Field objects share a set of common properties.

Common Properties

  • Font

    Specifies the font for the text object. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Text Alignment

    Specifies the alignment for the text object.

    • Left - Left.

    • Center - Center.

    • Right - Right.

    • Justified - Justified.

  • Vertical Alignment

    Specifies the vertical alignment of the text object.

    • Top - Top.

    • Middle - Middle.

    • Bottom - Bottom.

  • Line Spacing

    Specifies the line spacing type.

    • Single - Single line spacing.

    • 1 and 1/2 - One and a half line spacing.

    • Double - Double line spacing.

  • Rotation

    Specifies the rotation type.

    • None - No rotation.

    • Left - Text is rotated 90 degrees counter wise.

    • Right - Text is rotated 90 degrees clock wise.

    • Upside Down - Text is rotated 180 degrees.

  • Markup

    Markup language used in the text.

    • None - No markup.

    • Styled - Styled text. Styled text can contain style information that is specified using <style> tag. <style> tag supports the following attributes : fontName, size, isBold, isItalic, isUnderline, isStrikeThrough, pdfFontName, pdfEncoding, isPdfEmbedded, forecolor, backcolor.

    • HTML - HyperText Markup Language.

    • RTF - Rich Text Format.

  • Box

    Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globally for all sides.

6.12.6.2. Static Text

Static Text object represents a text element whose value is known at the report design time.

Static Text Properties

  • Text

    Specifies the object's text.

6.12.6.3. Text Field

Text Field object represents a text element that can present dynamic values that are calculated at the time of report execution. The most frequent use of this object is for printing text values obtained from a data source.

Text Field Properties

  • Expression

    Expression that determines the Text Field's value. The class of the value can be one of the following:

    • java.lang.Boolean

    • java.lang.Byte

    • java.util.Date

    • java.sql.Timestamp

    • java.sql.Time

    • java.lang.Double

    • java.lang.Float

    • java.lang.Integer

    • java.lang.Long

    • java.lang.Short

    • java.math.BigDecimal

    • java.lang.Number

    • java.lang.String

  • Evaluation Time

    Determines the moment of the Text Field's expression evaluation.

    • Now - The expression is evaluated at the section fill time.

    • Report - The expression is evaluated when the end of the report is reached.

    • Page - The expression is evaluated when the end of the current page is reached

    • Column - The expression is evaluated when the end of the current column is reached.

    • Group - The expression is evaluated when the group specified by the Evaluation Group property changes.

    • Band - The expression is evaluated after the element's parent band has finished rendering all the other elements.

    • Auto - The expression is evaluated at the time that is deduced automatically by the engine. This is useful when the expression combines values evaluated at different times (e.g. percentage out of a total).

  • Evaluation Group

    Specifies the group required by the Evaluation Time property when its value is Group.

  • Pattern

    Specifies the pattern that is used to format the value of the Text Field's expression. For date type values the pattern is defined by the java.text.SimpleDateFormat class. For numerical type values the pattern is defined by the java.text.DecimalFormat.

  • Blank When Null

    Flag that indicates whether the blank character instead of null should be displayed when the Text Field's expression evaluates to a null value.

  • Stretch With Overflow

    Flag that indicates whether the height of the object should be increased when the text does not fit the specified object height.

  • Anchor Name Expression

    Expression that determines the name of the local anchor that will mark the Text Field object. This anchor name can be later referred to in document hyperlinks.

  • Bookmark Level

    Specifies the level of the bookmark corresponding to the anchor. This value is used to generate bookmarks in the exported PDF document.

  • Hyperlink Type

    Specifies the type of the hyperlink associated with the Text Field object.

    • None - No hyperlink.

    • Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.

    • Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.

    • Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.

    • Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.

    • Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.

  • Hyperlink Anchor Expression

    Expression that determines the document anchor to which points the hyperlink associated with the Text Field object.

  • Hyperlink Page Expression

    Expression that determines the document page to which points the hyperlink associated with the Text Field object.

  • Hyperlink Reference Expression

    Expression that determines the external document or resource to which points the hyperlink associated with the Text Field object.

  • Hyperlink Tooltip Expression

    Expression that determines the tooltip to be displayed when hovering the mouse over the hyperlink.

  • Hyperlink Target

    Specifies the target of the hyperlink associated with the Text Field object.

    • Self - The hyperlink destination document is opened in the same window.

    • Blank - The hyperlink destination document is opened in a new window.

    • Parent - The hyperlink destination document is opened in the parent frame.

    • Top - The hyperlink destination document is opened in the top frame.

6.12.7. Subreport

Subreport object is used for inserting a report within report. This report nesting mechanism allows the creation of complex reports and also adds the possibility of report fragments reuse. A frequent use of sub-reports is for creating master-detail type of reports.

Nested reports usually require a number of parameters. These parameters can be passed in using the Parameters Map Expression property. Parameters can also be specified individually by right-clicking on the Subreport/Parameters node in the Outline View and selecting the Add Parameter action.

Since JasperReports 1.0.0, values can be returned by subreports to the master report. Return values can be specified by right-clicking on the Subreport/ReturnValues node in the Outline View and selecting the Add Return Value action.

Subreport Properties

  • Expression

    Expression that determines the source of the sub-report. Type of the sub-report source is determined by the expression's value class:

    • java.lang.String - Subreport location. First, the report engine tries to determine whether the String represents an URL. If not, it tries to interpret the String as a disk file path. Finally, if the String does not represent a file path, the subreport is searched in the CLASSPATH using the String as a resource path.

    • java.io.File - Subreport is loaded from the java.io.File object that represent a file on disk.

    • java.net.URL - Subreport is loaded from the location represented by the java.net.URL object.

    • java.io.InputStream - Subreport is loaded from a java.io.InputStream object.

    • net.sf.jasperreports.engine.JasperReport - Subreport is supplied directly by the expression as a net.sf.jasperreports.engine.JasperReport object.

  • Using Cache

    Flag indicating whether the sub-reports that are loaded from the same location should be cached.

  • Connection Expression

    Optional expression that supplies the JDBC connection (an instance of java.sql.Connection) for the sub-report. This property is used in conjunction with a JDBC data source. Most of the time, expression specifies the connection used by the master report. This is done by using a built-in parameter $P{REPORT_CONNECTION}.

  • Data Source Expression

    Optional expression that supplies an instance of net.sf.jasperreports.engine.JRDataSource to the sub-report.

  • Parameters Map Expression

    Optional expression that supplies the sub-report parameters that are passed in as an instance of java.util.Map. The most frequent use of this expression is to propagate to the sub-report the parameters that have been received by the master report. This is achieved by using a built-in parameter $P{REPORT_PARAMETERS_MAP}.

Subreport Parameter Properties

  • Name

    Name of the parameter as declared by the nested report.

  • Expression

    Expression that determines the value of the parameter.

Subreport Return Value Properties

  • To Variable

    Name of the master report variable to which the value is returned. This should be a variable with System calculation type.

  • Subreport Variable

    Name of the subreport variable whose value will be returned to the master report.

  • Calculation

    Specifies the calculation to perform on the master report variable when returning the value from the subreport.

    • Nothing - No calculation is performed.

    • Count - The variable calculates the number of the not null values obtained as the result of Variable's expression evaluation.

    • Distinct Count - The variable calculates the number of the distinct not null values obtained as the result of Variable's expression evaluation.

    • Sum - The variable calculates the sum of the not null values obtained as the result of Variable's expression evaluation. This type is only valid for numerical variables.

    • Average - The variable calculates the average of the not null values obtained as the result of Variable's expression evaluation. This type is only valid for numerical variables.

    • Lowest - The variable calculates the lowest value obtained as the result of Variable's expression evaluation.

    • Highest - The variable calculates the highest value obtained as the result of Variable's expression evaluation.

    • Standard Deviation - The variable calculates the standard deviation of the not null values obtained as the result of Variable's expression evaluation. This type is only valid for numerical variables.

    • Variance - The variable calculates the variance of the not null values obtained as the result of Variable's expression evaluation. This type is only valid for numerical variables.

    • First - The variable calculates the first encountered value. All the subsequent values are ignored.

  • Incrementer Factory Class

    The name of a class that implements the net.sf.jasperreports.engine.fill.JRIncrementerFactory interface to use to handle values returned from the subreport.

6.12.8. Chart

Chart object represents a graphical chart. Chart data is obtained by using the configuration specified in the chart's dataset.

Chart's type and the type of its dataset can be configured when adding a chart element from the Palette. The type can be changed later by selecting the Change Chart Type... action from the context menu.

Chart Properties

  • Show Legend

    Flag that indicates whether the chart's legend should be shown or not.

  • Evaluation Time

    Determines the moment of the Chart's evaluation.

    • Now - The chart is evaluated at the section fill time.

    • Report - The chart is evaluated when the end of the report is reached.

    • Page - The chart is evaluated when the end of the current page is reached

    • Column - The chart is evaluated when the end of the current column is reached.

    • Group - The chart is evaluated when the group specified by the Evaluation Group property changes.

    • Band - The chart is evaluated after the element's parent band has finished rendering all the other elements.

  • Evaluation Group

    Specifies the group required by the Evaluation Time property when its value is Group.

  • Anchor Name Expression

    Expression that determines the name of the local anchor that will mark the Chart object. This anchor name can be later referred to in document hyperlinks.

  • Bookmark Level

    Specifies the level of the bookmark corresponding to the anchor. This value is used to generate bookmarks in the exported PDF document.

  • Hyperlink Type

    Specifies the type of the hyperlink associated with the Chart object.

    • None - No hyperlink.

    • Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.

    • Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.

    • Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.

    • Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.

    • Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.

  • Hyperlink Anchor Expression

    Expression that determines the document anchor to which points the hyperlink associated with the Chart object.

  • Hyperlink Page Expression

    Expression that determines the document page to which points the hyperlink associated with the Chart object.

  • Hyperlink Reference Expression

    Expression that determines the external document or resource to which points the hyperlink associated with the Chart object.

  • Hyperlink Tooltip Expression

    Expression that determines the tooltip to be displayed when hovering the mouse over the hyperlink.

  • Hyperlink Target

    Specifies the target of the hyperlink associated with the Chart object.

    • Self - The hyperlink destination document is opened in the same window.

    • Blank - The hyperlink destination document is opened in a new window.

    • Parent - The hyperlink destination document is opened in the parent frame.

    • Top - The hyperlink destination document is opened in the top frame.

  • Box

    Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globally for all sides.

  • Title Position

    Specifies the relative position of the Chart's title.

    • Top - Title is positioned at the top.

    • Bottom - Title is positioned at the bottom.

    • Left - Title is positioned at the left.

    • Right - Title is positioned at the right.

  • Title Color

    Specifies the color of the Chart's title.

  • Title Font

    Specifies the font for the Chart's title. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Title Expression

    Specifies the expression that provides the text of the Chart's title.

  • Subtitle Color

    Specifies the color of the Chart's subtitle.

  • Subtitle Font

    Specifies the font for the Chart's subtitle. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Subtitle Expression

    Specifies the expression that provides the text of the Chart's subtitle.

  • Customizer Class

    The name of a class that implements the net.sf.jasperreports.engine.JRChartCustomizer interface to use to perform additional chart configuration.

  • Legend Color

    Specifies the foreground color of the Chart's legend.

  • Legend Background Color

    Specifies the background color of the Chart's legend.

  • Legend Font

    Specifies the font for the Chart's legend. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Legend Position

    Specifies the relative position of the Chart's legend.

    • Top - Legend is positioned at the top.

    • Bottom - Legend is positioned at the bottom.

    • Left - Legend is positioned at the left.

    • Right - Legend is positioned at the right.

  • Render Type

    Specifies the rendering method to be used for chart.

6.12.8.1. Plots

Plot properties allow to configure type specific aspects of chart appearance.

6.12.8.1.1. Common Plot Properties

Different chart types share a set of common plot properties.

Common Plot Properties

  • Plot Backcolor

    Specifies the background color of the Chart.

  • Plot Background Alpha

    Specifies the alpha transparency coefficient for the background. Values between 0.0 and 1.0 are allowed.

  • Plot Foreground Alpha

    Specifies the alpha transparency coefficient for the foreground. Values between 0.0 and 1.0 are allowed.

  • Plot Orientation

    Specifies the orientation of the Chart.

    • Horizontal - horizontal orientation.

    • Vertical - vertical orientation.

  • Label Rotation

    Degrees to rotate the text labels for the x axis of the Chart.

Most of the chart types have axes, of which presentation can be customized using axis format properties.

Axis Format Properties

  • Axis Label Font

    Specifies the font that is used to draw axis label. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Axis Tick Label Font

    Specifies the font that is used to draw axis tick labels. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Axis Label Color

    Specifies the foreground color that is used to draw axis label.

  • Axis Tick Label Color

    Specifies the foreground color that is used to draw axis tick labels.

  • Axis Tick Label Mask

    Specifies the pattern that is used to format tick values. For date type values the pattern is defined by the java.text.SimpleDateFormat class. For numerical type values the pattern is defined by the java.text.DecimalFormat.

  • Axis Line Color

    Specifies the foreground color that is used to draw axis line.

6.12.8.1.2. Area Plot Properties

Area Plot is used by Area, XYArea and ScatterArea chart types.

Area Plot Properties

  • Category Axis Expression

    Specifies the expression that provides the label for category axis.

  • Value Axis Expression

    Specifies the expression that provides the label for value axis.

6.12.8.1.3. Bar Plot Properties

Bar Plot is used by Bar, StackedBar, Gantt and XYBar chart types.

Bar Plot Properties

  • Category Axis Expression

    Specifies the expression that provides the label for category axis.

  • Value Axis Expression

    Specifies the expression that provides the label for value axis.

  • Show Tick Marks

    Flag that indicates whether the tick marks should be shown or not.

  • Show Tick Labels

    Flag that indicates whether the tick labels should be shown or not.

  • Show Labels

    Flag that indicates whether the labels should be shown or not.

6.12.8.1.4. Bar3D Plot Properties

Bar3D Plot is used by Bar3D and StackedBar3D chart types.

Bar3D Plot Properties

  • Category Axis Expression

    Specifies the expression that provides the label for category axis.

  • Value Axis Expression

    Specifies the expression that provides the label for value axis.

  • X Offset

    X-offset for the 3D effect.

  • Y Offset

    Y-offset for the 3D effect.

  • Show Labels

    Flag that indicates whether the labels should be shown or not.

6.12.8.1.5. Bubble Plot Properties

Bubble Plot is used by the Bubble chart type.

Bubble Plot Properties

  • X Axis Expression

    Specifies the expression that provides the label for the X axis of the chart.

  • Y Axis Expression

    Specifies the expression that provides the label for the Y axis of the chart.

  • Scale Type

    Specifies the scale type of the Bubble chart items.

    • Both Axes - bubble items scale on both axes.

    • Domain Axis - bubble items scale on domain axis.

    • Range Axis - bubble items scale on range axis.

6.12.8.1.6. Candlestick Plot Properties

Candlestick Plot is used by the Candlestick chart type.

Candlestick Plot Properties

  • Time Axis Expression

    Specifies the expression that provides the label for the time axis of the chart.

  • Value Axis Expression

    Specifies the expression that provides the label for the value axis of the chart.

  • Show Volume

    Flag that indicates whether the volume values should be shown or not.

6.12.8.1.7. HighLow Plot Properties

HighLow Plot is used by the HighLow chart type.

HighLow Plot Properties

  • Time Axis Expression

    Specifies the expression that provides the label for the time axis of the chart.

  • Value Axis Expression

    Specifies the expression that provides the label for the value axis of the chart.

  • Show Open Ticks

    Flag that indicates whether open ticks should be shown or not.

  • Show Close Ticks

    Flag that indicates whether close ticks should be shown or not.

6.12.8.1.8. Line Plot Properties

Line Plot is used by Line and XYLine chart types.

Line Plot Properties

  • Category Axis Expression

    Specifies the expression that provides the label for category axis.

  • Value Axis Expression

    Specifies the expression that provides the label for value axis.

  • Show Lines

    Flag that indicates whether lines should be shown or not.

  • Show Shapes

    Flag that indicates whether shapes should be shown or not.

6.12.8.1.9. Pie3D Plot Properties

Pie3D Plot is used by the Pie3D chart type.

Pie3D Plot Properties

  • Depth Factor

    Depth factor for the pie chart plot represents as a percentage of the height of the plot area. Allowed values are between 0.0 and 1.0.

  • Circular

    Flag that indicates whether the pie chart is circular or stretched into an elliptical shape.

  • Legend Format

    Pattern used to format pie section labels.

  • Legend Legend Format

    Pattern used to format pie section labels in chart's legend.

6.12.8.1.10. Pie Plot Properties

Pie Plot is used by the Pie chart type.

Pie Plot Properties

  • Circular

    Flag that indicates whether the pie chart is circular or stretched into an elliptical shape.

  • Legend Format

    Pattern used to format pie section labels.

  • Legend Legend Format

    Pattern used to format pie section labels in chart's legend.

6.12.8.1.11. Scatter Plot Properties

Scatter Plot is used by the Scatter chart type.

Scatter Plot Properties

  • X Axis Expression

    Specifies the expression that provides the label for the X axis of the chart.

  • Y Axis Expression

    Specifies the expression that provides the label for the Y axis of the chart.

  • Show Lines

    Flag that indicates whether lines should be shown or not.

  • Show Shapes

    Flag that indicates whether shapes should be shown or not.

6.12.8.1.12. TimeSeries Plot Properties

TimeSeries Plot is used by the TimeSeries chart type.

TimeSeries Plot Properties

  • Time Axis Expression

    Specifies the expression that provides the label for the time axis of the chart.

  • Value Axis Expression

    Specifies the expression that provides the label for the value axis of the chart.

  • Show Lines

    Flag that indicates whether lines should be shown or not.

  • Show Shapes

    Flag that indicates whether shapes should be shown or not.

6.12.8.1.13. Meter Plot Properties

Meter Plot is used by the Meter chart type.

Meter Plot Properties

  • Meter Shape

    Specifies the shape of the meter.

  • Angle

    Specifies the angle that determines the extent of the meter.

  • Units

    An optional unit string that will be appended to the value.

  • Tick interval

    Specifies the distance between tick values.

  • Meter Color

    Specifies the background color that is used to fill the meter.

  • Needle Color

    Specifies the color that is used to draw the needle of the meter.

  • Tick Color

    Specifies the color that is used to draw the ticks of the meter.

  • Value Display Color

    Specifies the color that is used to draw the meter value.

  • Value Display Mask

    Specifies the pattern that is used to format the meter value. For date type values the pattern is defined by the java.text.SimpleDateFormat class. For numerical type values the pattern is defined by the java.text.DecimalFormat.

  • Value Display Font

    Specifies the font that is used to draw the meter value. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Data Range Low Expression

    Specifies the expression that provides the low value of the data range that the meter can display.

  • Data Range High Expression

    Specifies the expression that provides the high value of the data range that the meter can display.

Meter Plot can be further configured by specifying a list of Meter Intervals. A Meter Interval can be added by right-clicking on the Chart/Meter Intervals node in the Outline View and selecting the Add Meter Interval option.

Meter Interval Properties

  • Alpha

    Specifies the alpha transparency coefficient for the background. Values between 0.0 and 1.0 are allowed.

  • Background Color

    Specifies the color that is used to fill region identified by the interval.

  • Label

    Specifies the label that will be displayed in chart's legend.

  • Data Range Low Expression

    Specifies the expression that provides the low value of the data range that defines the interval.

  • Data Range High Expression

    Specifies the expression that provides the the high value of the data range that defines the interval.

6.12.8.1.14. Thermometer Plot Properties

Thermometer Plot is used by the Thermometer chart type.

Thermometer Plot Properties

  • Value Location

    Specifies the relative location of the displayed value.

  • Show Value Lines

    Flag that indicates whether value line is drawn or not on the thermometer.

  • Mercury Color

    Specifies the background color that is used to fill the thermometer.

  • Value Display Color

    Specifies the color that is used to draw the thermometer value.

  • Value Display Mask

    Specifies the pattern that is used to format the thermometer value. For date type values the pattern is defined by the java.text.SimpleDateFormat class. For numerical type values the pattern is defined by the java.text.DecimalFormat.

  • Value Display Font

    Specifies the font that is used to draw the thermometer value. The font property is defined through a number of sub-properties. These sub-properties are the same as used by the report font definition (Section 6.5, “Fonts”). A special Report Font sub-property allows to specify a report font that is used as the base font for the font definition. If not specified, then the default report font is used for this scope. By specifying other sub-properties, the font definition basically overrides the properties of the corresponding base font.

  • Data Range Low Expression

    Specifies the expression that provides the low value of the data range that the meter can display.

  • Data Range High Expression

    Specifies the expression that provides the the high value of the data range that the meter can display.

  • Low Range Low Expression

    Specifies the expression that provides the low value of the low range that the meter can display.

  • Low Range High Expression

    Specifies the expression that provides the the high value of the low range that the meter can display.

  • Medium Range Low Expression

    Specifies the expression that provides the low value of the medium range that the meter can display.

  • Medium Range High Expression

    Specifies the expression that provides the the high value of the medium range that the meter can display.

  • High Range Low Expression

    Specifies the expression that provides the low value of the high range that the meter can display.

  • High Range High Expression

    Specifies the expression that provides the the high value of the high range that the meter can display.

6.12.8.1.15. MultiAxis Plot

MultiAxis Plot is used by the MultiAxis chart type. MultiAxis Plot is configured by specifying a list of Axes. An Axis can be added by right-clicking on the Chart/Axes node in the Outline View and selecting the Add Axis option.

Each Axis must specify a Chart object that provides the properties for the axis. A chart can be specified by selecting Chart entry in the Palette View and then clicking one the Axis node in the Outline View.

Axis Properties

  • Position

    Specifies the relative position of the axis.

    • Left Or Top - axis is positioned to the left (for charts with a Vertical orientation) or top (for charts with a Horizontal orientation.)

    • Right Or Bottom - axis is positioned to the right (for charts with a Vertical orientation) or bottom (for charts with a Horizontal orientation.)

6.12.8.2. Datasets

Datasets allow to configure the access to data that is used for chart rendering.

6.12.8.2.1. Common Dataset Properties

Different chart dataset types share a set of common dataset properties.

Common Dataset Properties

  • Reset Type

    Indicates the moment of report execution at which the dataset is reinitialized.

    • Report - Dataset is initialized once, at the beginning of the report.

    • Page - Dataset is initialized at the beginning of each page.

    • Column - Dataset is initialized at the beginning of each column.

    • Group - Dataset is initialized each time the group specified by the Reset Group property changes its value.

    • None - Dataset is never reinitialized.

  • Reset Group

    Name of the group at which the dataset is reinitialized, when the Reset Type property is set to Group.

  • Increment Type

    Indicates the moment of report execution at which the dataset is incremented.

    • Report - Dataset is incremented only once, at the end of the report.

    • Page - Dataset is incremented at the end of each page.

    • Column - Dataset is incremented at the end of each column.

    • Group - Dataset is incremented when the group specified by the Increment Group attribute changes.

    • None - Dataset is incremented with every record in the data source.

  • Increment Group

    Name of the group at which the dataset is incremented, when the Increment Type property is set to Group.

  • Increment When Expression

    Specifies a boolean expression that determines whether the dataset is incremented or not.

A chart dataset can instantiate and use a predefined sub-dataset. To do this, the SubDataset property must be set to the desired sub-dataset. Setting this property activates additional sub-dataset properties including sub-dataset parameters that allow to specify parameter values for the sub-dataset that is being instantiated.

Sub-dataset Properties

  • SubDataset

    Name of the dataset that should be instantiated and used to provide the data for chart's dataset.

  • Connection Expression

    Optional expression that supplies the JDBC connection (an instance of java.sql.Connection) for the sub-dataset.

  • Data Source Expression

    Optional expression that supplies an instance of net.sf.jasperreports.engine.JRDataSource to the sub-dataset.

  • Parameters Map Expression

    Optional expression that supplies the sub-dataset parameters that are passed in as an instance of java.util.Map.

Datasets that support dataset series allow to define item hyperlinks that are used to generate drill-down links on items generated by the series.

Item Hyperlink Properties

  • Hyperlink Type

    Specifies the type of the hyperlink associated with the item.

    • None - No hyperlink.

    • Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.

    • Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.

    • Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.

    • Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.

    • Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.

  • Hyperlink Anchor Expression

    Expression that determines the document anchor to which points the hyperlink associated with the item.

  • Hyperlink Page Expression

    Expression that determines the document page to which points the hyperlink associated with the item.

  • Hyperlink Reference Expression

    Expression that determines the external document or resource to which points the hyperlink associated with the item.

  • Hyperlink Tooltip Expression

    Expression that determines the tooltip to be displayed when hovering the mouse over the hyperlink.

  • Hyperlink Target

    Specifies the target of the hyperlink associated with the item.

    • Self - The hyperlink destination document is opened in the same window.

    • Blank - The hyperlink destination document is opened in a new window.

    • Parent - The hyperlink destination document is opened in the parent frame.

    • Top - The hyperlink destination document is opened in the top frame.

6.12.8.2.2. Pie Dataset

Pie Dataset is used by the Pie and Pie3D chart types.

Pie Dataset Properties

  • Key Expression

    Expression that provides a key for the pie dataset.

  • Value Expression

    Expression that provides a value for the pie dataset.

  • Label Expression

    Expression that provides a label for the pie dataset.

Pie Dataset also supports section hyperlinks that are used to generate drill-down links on pie sections.

Section Hyperlink Properties

  • Hyperlink Type

    Specifies the type of the hyperlink associated with the pie section.

    • None - No hyperlink.

    • Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.

    • Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.

    • Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.

    • Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.

    • Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.

  • Hyperlink Anchor Expression

    Expression that determines the document anchor to which points the hyperlink associated with the pie section.

  • Hyperlink Page Expression

    Expression that determines the document page to which points the hyperlink associated with the pie section.

  • Hyperlink Reference Expression

    Expression that determines the external document or resource to which points the hyperlink associated with the pie section.

  • Hyperlink Tooltip Expression

    Expression that determines the tooltip to be displayed when hovering the mouse over the hyperlink.

  • Hyperlink Target

    Specifies the target of the hyperlink associated with the pie section.

    • Self - The hyperlink destination document is opened in the same window.

    • Blank - The hyperlink destination document is opened in a new window.

    • Parent - The hyperlink destination document is opened in the parent frame.

    • Top - The hyperlink destination document is opened in the top frame.

6.12.8.2.3. Category Dataset

Category Dataset is used by Area, StackedArea, Bar, Bar3D, Line, StackedBar and StackedBar3D chart types.

A Category Dataset is configured by specifying a list of Category Series. Category Series can be added by right-clicking on the Chart/Category Dataset node in the Outline View and selecting the Add Category Series option.

Category Series Properties

  • Series Expression

    Expression that provides the series value for the category dataset series.

  • Category Expression

    Expression that provides the category for the category dataset series.

  • Value Expression

    Expression that provides the value for the category dataset series.

  • Label Expression

    Expression that provides the label for the category dataset series.

For hyperlink properties please see Item Hyperlink Properties

6.12.8.2.4. XY Dataset

XY Dataset is used by Scatter, XYArea, XYBar and XYLine chart types.

An XY Dataset is configured by specifying a list of XY Series. XY Series can be added by right-clicking on the Chart/XY Dataset node in the Outline View and selecting the Add XY Series option.

XY Series Properties

  • Series Expression

    Expression that provides the series value for the XY dataset series.

  • X Value Expression

    Expression that provides the X value for the XY dataset series.

  • Y Value Expression

    Expression that provides the Y value for the XY dataset series.

  • Label Expression

    Expression that provides the label for the XY dataset series.

For hyperlink properties please see Item Hyperlink Properties

6.12.8.2.5. XYZ Dataset

XYZ Dataset is used by the Bubble chart type.

An XYZ Dataset is configured by specifying a list of XYZ Series. XYZ Series can be added by right-clicking on the Chart/XYZ Dataset node in the Outline View and selecting the Add XYZ Series option.

XYZ Series Properties

  • Series Expression

    Expression that provides the series value for the XYZ dataset series.

  • X Value Expression

    Expression that provides the X value for the XYZ dataset series.

  • Y Value Expression

    Expression that provides the Y value for the XYZ dataset series.

  • Z Value Expression

    Expression that provides the Z value for the XYZ dataset series.

For hyperlink properties please see Item Hyperlink Properties

6.12.8.2.6. TimePeriod Dataset

TimePeriod Dataset is used by the XYBar chart type.

A TimePeriod Dataset is configured by specifying a list of TimePeriod Series. TimePeriod Series can be added by right-clicking on the Chart/TimePeriod Dataset node in the Outline View and selecting the Add TimePeriod Series option.

TimePeriod Series Properties

  • Series Expression

    Expression that provides the series value for the timeperiod dataset series.

  • Start Date Expression

    Expression that provides the start date for the timeperiod dataset series.

  • End Date Expression

    Expression that provides the end date for the timeperiod dataset series.

  • Value Expression

    Expression that provides the value for the timeperiod dataset series.

  • Label Expression

    Expression that provides the label for the timeperiod dataset series.

For hyperlink properties please see Item Hyperlink Properties

6.12.8.2.7. TimeSeries Dataset

TimeSeries Dataset is used by TimeSeries and XYBar chart types.

TimeSeries Dataset Properties

  • Time Period

    Specified the time period for the dataset.

    • Year - year time period.

    • Quarter - quarter time period.

    • Month - month time period.

    • Week - week time period.

    • Day - day time period.

    • Hour - hour time period.

    • Minute - minute time period.

    • Second - second time period.

    • Millisecond - millisecond time period.

A TimeSeries Dataset is configured by specifying a list of Time Series. Time Series can be added by right-clicking on the Chart/TimeSeries Dataset node in the Outline View and selecting the Add Time Series option.

Time Series Properties

  • Series Expression

    Expression that provides the series value for the timeseries dataset series.

  • Time Period Expression

    Expression that provides the time period for the timeseries dataset series.

  • Value Expression

    Expression that provides the value for the timeseries dataset series.

  • Label Expression

    Expression that provides the label for the timeseries dataset series.

For hyperlink properties please see Item Hyperlink Properties

6.12.8.2.8. HighLow Dataset

HighLow Dataset is used by Candlestick and HighLow chart types.

HighLow Dataset Properties

  • Series Expression

    Expression that provides series in a highlow dataset.

  • Date Expression

    Expression that provides dates in a highlow dataset.

  • High Expression

    Expression that provides high values in a highlow dataset.

  • Low Expression

    Expression that provides low values in a highlow dataset.

  • Open Expression

    Expression that provides open values in a highlow dataset.

  • Close Expression

    Expression that provides close values in a highlow dataset.

  • Volume Expression

    Expression that provides volume values in a highlow dataset.

HighLow Dataset also supports item hyperlinks that are used to generate drill-down links on chart items.

Item Hyperlink Properties

  • Hyperlink Type

    Specifies the type of the hyperlink associated with the item.

    • None - No hyperlink.

    • Reference - The hyperlink points to an external resource specified by the Hyperlink Reference Expression property. This is usually a URL.

    • Local Anchor - The hyperlink points to a local anchor (same document) specified by the Hyperlink Anchor Expression property.

    • Local Page - The hyperlink points to a local page (same document) specified by the Hyperlink Page Expression property. The page number is 1 based.

    • Remote Anchor - The hyperlink points to an anchor (external document) specified by the Hyperlink Anchor Expression property. The external document is specified by the Hyperlink Reference Expression property.

    • Remote Page - The hyperlink points to a page (external document) specified by the Hyperlink Page Expression property. The external document is specified by the Hyperlink Reference Expression property. The page number is 1 based.

  • Hyperlink Anchor Expression

    Expression that determines the document anchor to which points the hyperlink associated with the item.

  • Hyperlink Page Expression

    Expression that determines the document page to which points the hyperlink associated with the item.

  • Hyperlink Reference Expression

    Expression that determines the external document or resource to which points the hyperlink associated with the item.

  • Hyperlink Tooltip Expression

    Expression that determines the tooltip to be displayed when hovering the mouse over the hyperlink.

  • Hyperlink Target

    Specifies the target of the hyperlink associated with the item.

    • Self - The hyperlink destination document is opened in the same window.

    • Blank - The hyperlink destination document is opened in a new window.

    • Parent - The hyperlink destination document is opened in the parent frame.

    • Top - The hyperlink destination document is opened in the top frame.

6.12.8.2.9. Value Dataset

Value Dataset is used by Meter and Thermometer chart types.

Value Dataset Properties

  • Value Expression

    Expression that provides the value for this dataset.

6.12.8.2.10. Gantt Dataset

Gantt Dataset is used by Gantt chart type.

A Gantt Dataset is configured by specifying a list of Gantt Series. Gantt Series can be added by right-clicking on the Chart/GanttDataset node in the Outline View and selecting the Add Gantt Series option.

Gantt Series Properties

  • Series Expression

    Expression that provides the series value for the gantt dataset series.

  • Task Expression

    Expression that provides the name of the task for the gantt dataset series.

  • Subtask Expression

    Expression that provides the name of the subtask for the gantt dataset series.

  • Start Date Expression

    Expression that provides the start date for the gantt dataset series.

  • End Date Expression

    Expression that provides the end date for the gantt dataset series.

  • Percent Expression

    Expression that provides the percent value for the gantt dataset series.

6.12.9. Element Group

Element Group object is used for grouping other objects on the report. This is useful for relating the height stretching behavior of a report object to other object's height.

6.12.10. Frame

Frame object is a container that can host other report objects. The position properties, such as location, of contained objects are relative to the frame instead of the band.

Frame Properties

  • Box

    Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globally for all sides.

6.12.11. Crosstab

Crosstab object is used for inserting a crosstab report within the main report. Crosstab reports are used to display the summary of multi-dimensional data in a two-dimensional layout.

A crosstab report consists of a set of rows and columns at intersection of which the summarized data is displayed. Each intersection represents a cell that has a free-form layout and can contain almost any report element. Additional cells are provided for row and column headers, total headers and total cells.

Crosstab Properties

  • Repeat Row Headers

    Flag that determines whether the row headers should be reprinted after a crosstab column break.

  • Repeat Column Headers

    Flag that determines whether the column headers should be reprinted after a page break.

  • Column Break Offset

    Offset used when a column break occurs and the filling is continued on the same page.

  • Parameters Map Expression

    Optional expression that supplies the crosstab parameters that are passed in as an instance of java.util.Map. The most frequent use of this expression is to propagate to the crosstab the parameters that have been received by the master report. This is achieved by using a built-in parameter $P{REPORT_PARAMETERS_MAP}

  • Run Direction

    Specifies the rendering direction.

    • Left To Right - Crosstab is rendered from left to right.

    • Right To Left - Crosstab is rendered from right to left.

Crosstab Dataset Properties

  • Data Presorted

    Flag that indicates whether the crosstab data is already sorted according to the row bucket expressions and group bucket expressions.

  • Reset Type

    Indicates the moment of report execution at which the dataset is reinitialized.

    • Report - Dataset is initialized once, at the beginning of the report.

    • Page - Dataset is initialized at the beginning of each page.

    • Column - Dataset is initialized at the beginning of each column.

    • Group - Dataset is initialized each time the group specified by the Reset Group property changes its value.

    • None - Dataset is never reinitialized.

  • Reset Group

    Name of the group at which the dataset is reinitialized, when the Reset Type property is set to Group.

  • Increment Type

    Indicates the moment of report execution at which the dataset is incremented.

    • Report - Dataset is incremented only once, at the end of the report.

    • Page - Dataset is incremented at the end of each page.

    • Column - Dataset is incremented at the end of each column.

    • Group - Dataset is incremented when the group specified by the Increment Group attribute changes.

    • None - Dataset is incremented with every record in the data source.

  • Increment Group

    Name of the group at which the dataset is incremented, when the Increment Type property is set to Group.

  • Increment When Expression

    Specifies a boolean expression that determines whether the dataset is incremented or not.

A crosstab dataset can instantiate and use a predefined sub-dataset. To do this, the SubDataset property must be set to the desired sub-dataset. Setting this property activates additional sub-dataset properties including sub-dataset parameters that allow to specify parameter values for the sub-dataset that is being instantiated.

Crosstab Sub-dataset Properties

  • SubDataset

    Name of the dataset that should be instantiated and used to provide the data for crosstab's dataset.

  • Connection Expression

    Optional expression that supplies the JDBC connection (an instance of java.sql.Connection) for the sub-dataset.

  • Data Source Expression

    Optional expression that supplies an instance of net.sf.jasperreports.engine.JRDataSource to the sub-dataset.

  • Parameters Map Expression

    Optional expression that supplies the sub-dataset parameters that are passed in as an instance of java.util.Map.

6.12.11.1. Parameters

A crosstab can define a number of parameters. Parameters provide a way for crosstab to access data from the master report, which is not possible otherwise.

Parameter Properties

  • Name

    Name of the crosstab parameter.

  • Value Expression

    Expression that specifies parameter's value.

  • Value Class

    Class of the parameter values.

6.12.11.2. Measures

A crosstab must define at least one measure. Measures are used to perform aggregate calculations on crosstab data.

Values calculated by a measure can be accessed using dedicated variables:

Measure variables

  • <Measure>_<RowGroup>_ALL

    Provides a row group total.

  • <Measure>_<ColumnGroup>_ALL

    Provides a column group total.

  • <Measure>_<RowGroup>_<ColumnGroup>_ALL

    Provides a combined column and group total.

Measure Properties

  • Name

    Name of the crosstab measure.

  • Value Expression

    Expression that determines the value that is used to perform calculations.

  • Value Class

    Class of the values as obtained by evaluating the Measure's value expression.

  • Initial Value Expression

    Expression that determines the Variable's initial value.

  • Incrementer Factory Class

    The name of a class that implements the net.sf.jasperreports.engine.fill.JRIncrementerFactory interface to use when creating the incrementer instance for the measure. Incrementers are objects that implement the net.sf.jasperreports.engine.fill.JRIncrementer interface and handle the incremental calculation performed on the measure's current value with every iteration in the data source.

  • Calculation

    Specifies the calculation type to perform on the Measure's expression.

    • Nothing - No calculation is performed.

    • Count - The measure calculates the number of the not null values obtained as the result of Measure's expression evaluation.

    • Distinct Count - The measure calculates the number of the distinct not null values obtained as the result of Measure's expression evaluation.

    • Sum - The measure calculates the sum of the not null values obtained as the result of Measure's expression evaluation. This type is only valid for numerical measures.

    • Average - The measure calculates the average of the not null values obtained as the result of Measure's expression evaluation. This type is only valid for numerical measures.

    • Lowest - The measure calculates the lowest value obtained as the result of Measure's expression evaluation.

    • Highest - The measure calculates the highest value obtained as the result of Measure's expression evaluation.

    • Standard Deviation - The measure calculates the standard deviation of the not null values obtained as the result of Measure's expression evaluation. This type is only valid for numerical measures.

    • Variance - The measure calculates the variance of the not null values obtained as the result of Measure's expression evaluation. This type is only valid for numerical measures.

    • First - The measure calculates the first encountered value that is obtained as the result of Measure's expression evaluation. All the subsequent values are ignored.

  • Percentage Of

    Specifies the percentage calculation type to perform on the Measure's expression.

    • None - No percentage is calculated.

    • Grand Total - The value calculates the percentage of the grand total value.

  • Percentage Calculator Class

    The name of a class that implements the net.sf.jasperreports.crosstabs.fill.JRPercentageCalculator. This property must be specified when a non-standard Value Class is used.

6.12.11.3. Crosstab Cells

The crosstab's presentation is specified using crosstab cells. Cells are portions of the crosstab that have a specified width and height and that can contain report objects like lines, rectangles, images, and text fields.

There are several types of cells each of them serving a specific purpose.

Cell Types

  • Header

    The header cell. This cell appears in the upper-left corner of the crosstab.

  • When No Data

    The when no data cell. This cell is only displayed if there is no data in crosstab's data source.

  • Row Header

    The row header cell. This cell appears as a row header on the left side of the crosstab.

  • Row Total Header

    The total row header cell. This cell appears as a total row header on the left side of the crosstab.

  • Column Header

    The column header cell. This cell appears as a column header in the top area of the crosstab.

  • Column Total Header

    The total column header cell. This cell appears as a total column header in the top area of the crosstab.

  • Detail

    The detail cell. This type of cells appear on the intersection of rows and columns. It allows to display the crosstab data such as column and row totals, grand total and base crosstab data.

Cell Properties

  • Background

    The background color of the cell.

  • Mode

    Determines whether the background of the cell is transparent or opaque.

  • Box

    Specifies the box properties such as border type, border color and padding. Each property can be set individually for each box side or globally for all sides.

  • Style

    The report style to be used as the base configuration for various visual aspects of the cell.

  • Width

    The cell width specified in report units.

  • Height

    The cell height specified in report units.

6.12.11.4. Row and Column Groups

A crosstab must define at least one row group and one column group. Row and column groups are used to specify the way crosstab data is grouped to perform the desired aggregations.

The crosstab data grouping is specified using bucket expressions. A bucket expression provides values that are used to group the base crosstab data. Bucket expression values can be accessed in crosstab cells using the group variable: $V{GROUP_NAME}

When declaring a group, two additional crosstab cells become available, a group header and a group total header.

Common Group Properties

  • Name

    The name of the group. This is the same name that is used to access the group variable.

  • Bucket Expression

    Expression that provides bucket values used for data grouping.

  • Comparator Expression

    Optional comparator expression that can be used to specify a custom comparator used to sort bucket values. When specified, this expression must provide values of type java.lang.Comparator.

  • Order

    Specifies the order for bucket value sorting.

    • Ascending - Bucket values are sorted in ascending order.

    • Descending - Bucket values are sorted in descending order.

Row Group Properties

  • Header Width

    Specifies the width of the header cell in report units

  • Header Position

    Specifies the position header cell contents on cell span.

    • Top - The contents will be displayed on the top of the cell.

    • Middle - The contents will be displayed in the middle of the cell.

    • Bottom - The contents will be displayed on the bottom of the cell.

    • Stretch - The contents will be stretched to occupy the entire height of the cell.

  • Total Position

    Specifies the position of the total row.

    • Start - The total row will be displayed before the data row.

    • End - The total row will be displayed after the data row.

    • None - The total row won't be displayed.

Column Group Properties

  • Header Height

    Specifies the height of the header cell in report units

  • Header Position

    Specifies the position header cell contents on cell span.

    • Left - The contents will be displayed on the left side of the cell.

    • Center - The contents will be displayed in the center of the cell.

    • Right - The contents will be displayed on the right side of the cell.

    • Stretch - The contents will be stretched to occupy the entire width of the cell.

  • Total Position

    Specifies the position of the total column.

    • Start - The total column will be displayed before the data column.

    • End - The total column will be displayed after the data column.

    • None - The total column won't be displayed.

6.12.12. Break

Break object is used to force a page or column break.

Break Properties

  • Type

    Specifies the break type.

    • Page - A page break.

    • Column - A column break.