JasperReports 4.0.1 - Templates Sample

Sample Reference - Schema Reference - Configuration Reference - API (Javadoc)

JasperReports - Templates Sample (version 4.0.1)

Shows how to work with style templates.

Download All Sample Source Files
Browse Sample Source Files on SVN


Main Features in This Sample
	Style Templates


top

	Style Templates		Documented by Sanda Zaharia

	Description / Goal	How to reuse report style definitions from external style templates.
	Since	2.0.0

	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 style `style` - a reference to the parent style `mode` - sets the element's transparency. Possible values are `Opaque` and `Transparent`. `forecolor` - the foreground color `backcolor` - the background color `fill` - 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 texts `fontName` - sets the font name `fontSize` - sets the font size `isBold` - indicates if the font style is bold `isItalic` - indicates if the font style is italic `isUnderline` - indicates if the font style is underline `isStrikeThrough` - indicates if the font style is strikethrough `pdfFontName` - sets the related PDF font name `pdfEncoding` - sets the character encoding for the PDF output format `isPdfEmbedded` - indicates if the PDF font is embedded `pattern` - sets the format pattern for formatted texts `isBlankWhenNull` - 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: <?xml version="1.0"?> <!DOCTYPE jasperTemplate PUBLIC "-//JasperReports//DTD Template//EN" "http://jasperreports.sourceforge.net/dtds/jaspertemplate.dtd"> <jasperTemplate> <template><![CDATA[base_styles.jrtx]]></template> <!-- Override the default font from base_styles.xml --> <style name="Regular" style="Base" isDefault="true" fontSize="12"/> <style name="Special Emphasis" style="Emphasis" fontSize="12" forecolor="red"/> <!-- Override the Strong style from base_styles.xml. Note that the Very Strong style from base_styles.xml will still inherit the original Strong style. --> <style name="Strong" style="Base" isUnderline="true" fontSize="14"/> <style name="Serif" style="Base" fontSize="12" fontName="DejaVu Serif"/> <style name="Serif Note" style="Serif" isUnderline="true"/> </jasperTemplate> 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: <jasperReport ...> <template>”report_styles.jrtx”</template> <!-- parameters can be used in style template expressions --> <template>$P{BaseTemplateLocation} + ”report_styles.jrtx”</template> <template class=”java.net.URL”>$P{StyleTemplateURL}</template> <parameter name=”BaseTemplateLocation”/> <parameter name=”StyleTemplateURL” class=”java.net.URL”/> ... 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.String` `java.io.File` `java.net.URL` `java.io.InputStream` `net.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.