Styles in JasperReports
In a given report, elements can have different appearances. They can have borders, foreground and background colors,
alignments, text decorations, etc. JasperReports provides the <style /> element in order to manage all these appearance characteristics.
A <style /> element is defined by the following attributes:
isDefault - indicates whether this style is the document's default stylestyle - a reference to the parent stylemode - sets the element's transparency. Possible values are Opaque and Transparent.forecolor - the foreground colorbackcolor - the background colorfill - sets the fill mode. At the moment the single value allowed is Solid.radius - sets the radius value, if necessary.scaleImage - sets the scale for images only. Possible values: Clip, FillFrame, RetainShape, RealHeight, RealSize.hAlign - sets the horizontal alignment. Possible values: Left, Center, Right, Justified.vAlign - sets the vertical alignment. Possible values: Top, Middle, Bottom.rotation - sets the element's rotation. Possible values: None, Left, Right, UpsideDown.lineSpacing - sets the line spacing for text elements only. Possible values: Single, 1_1_2, Double.markup - sets the markup style for styled textsfontName - sets the font namefontSize - sets the font sizeisBold - indicates if the font style is boldisItalic - indicates if the font style is italicisUnderline - indicates if the font style is underlineisStrikeThrough - indicates if the font style is strikethroughpdfFontName - sets the related PDF font namepdfEncoding - sets the character encoding for the PDF output formatisPdfEmbedded - indicates if the PDF font is embeddedpattern - sets the format pattern for formatted textsisBlankWhenNull - indicates if a white space should be shown if the text is not present
In a style element can be set also the element's <box /> and <pen /> styles.
In some situations, a style should be applied only if a certain condition is met. For example, consecutive rows in a table should alternate their background colors.
JasperReports provides conditional styles in order to manage conditions for styles.
Style Templates
Any type of report element can reference a report style definition using its style
attribute. By doing so, all the style properties declared by the style definition that are
applicable to the current element will be inherited. Style properties specified at the report
element level can be used to override the inherited values.
But what if there are several reports that require the same report style to be applied? One can write the same report style definition in each report, but this is not an optimized approach.
Better than that, and recommended, is to use style templates instead.
Report styles can also be defined in external style template files that are referenced by
report templates. This allows report designers to define in a single place a common look
for a set of reports.
A style template is an XML file that contains one or more style definitions. A template
can include references to other style template files, hence one can organize a style library
as a hierarchical set of style template files.
Style template files use by convention the *.jrtx extension, but this is not mandatory.
The <jasperTemplate /> element is the root of a style template file. The <template />
element is used to include references to other template files; the contents of this element
is interpreted as the location of the referred template file.
The <style /> element is identical to the element with the same name from report design
templates (JRXML files), with the exception that a style in a style template cannot
contain conditional styles. This limitation is caused by the fact that conditional styles
involve report expressions, and expressions can only be interpreted in the context of a
single report definition. Each style must specify a name, and the style names have to be
unique inside a style template.
The following is an example of a styles template file which refers a base template file named base_styles.jrtx, overrides 2 parent styles and defines other 3 own styles:
]]>
A report can use style templates by explicitly referring them in its definition. References
to a style templates are included in JRXML reports as <template /> elements. Such an
element contains an expression that is resolved at fill time to a style template instance.
The template expression can only use constants/literals and report parameters. Variables
and fields cannot be used because the template expressions are evaluated before the
report calculation engine is initialized. If the template expression evaluates to null, the
engine ignores the template reference.
Below is an example of how to reference a style template in a report:
”report_styles.jrtx”
$P{BaseTemplateLocation} + ”report_styles.jrtx”
$P{StyleTemplateURL}
...
]]>
Style template locations are interpreted in the same manner as image or subreport
locations, that is, the engine attempts to load the location as an URL, a disk file or a
classpath resource. The class attribute in the <template /> element represents the class for the style template source expression. Possible values are:
java.lang.Stringjava.io.Filejava.net.URLjava.io.InputStreamnet.sf.jasperreports.engine.JRTemplate
Running the Sample
Running the sample requires the Apache Ant library. Make sure that ant is already installed on your system (version 1.5 or later).
In a command prompt/terminal window set the current folder to demo/samples/templates within the JasperReports source project and run the > ant test view command.
It will generate all supported document types containing the sample report in the demo/samples/templates/build/reports directory.
Then the report will open in the JasperReports internal viewer.